Installation and Setup

This chapter will guide you through installing Beamline and setting up your development environment. Beamline is written in Rust, so we weill cover both building from source and using pre-built binaries when available.

Prerequisites

Before installing Beamline, ensure you have the following prerequisites:

Required

• Rust Toolchain: Beamline requires Rust 1.70 or later
• Git: For cloning the repository
• Command Line Access: Terminal or command prompt

Optional but Recommended

• Text Editor: For editing Ion scripts (VS Code, vim, emacs, etc.)
• JSON/Ion Viewer: Use jq and/or ion-cli tools for examining generated data

Installing Rust

Read the following for more details on installing Rust on your machine: https://rust-lang.org/tools/install/

If you don’t have Rust installed, follow these steps:

On macOS, Linux, or WSL

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

On Windows

1. Download and run rustup-init.exe
2. Follow the installation prompts
3. Restart your command prompt

Verify Rust Installation

rustc --version
cargo --version

You should see version information for both rustc and cargo.

Installing Beamline

Method 1: Building from Source (Recommended)

This is currently the primary method for installing Beamline:

1. Clone the Repository

   git clone https://github.com/partiql/partiql-beamline.git
   cd partiql-beamline
   

2. Build the Project

   cargo build --release
   

   This will compile Beamline in release mode, which provides better performance for data generation.

3. Verify the Installation

   ./target/release/beamline --version
   

   You should see version information for Beamline.

4. Optional: Add to PATH

   For easier access, you can add the binary to your PATH or create a symlink:

   On macOS/Linux:

   # Option 1: Copy to a directory in your PATH
   sudo cp target/release/beamline /usr/local/bin/
   
   # Option 2: Create a symlink
   ln -s $(pwd)/target/release/beamline ~/.local/bin/beamline
   
   # Option 3: Add to your shell profile
   echo 'export PATH="'$(pwd)'/target/release:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

   On Windows:

   # Add the target/release directory to your PATH environment variable
   # Or copy the .exe file to a directory already in your PATH
   

Method 2: Using Cargo Install (Not available yet)

Once Beamline is published to crates.io, you’ll be able to install it directly:

# This will be available in the future
cargo install beamline

Verifying Your Installation

Let’s verify that Beamline is installed correctly by running a few basic commands:

1. Check Version

beamline --version

2. View Help

beamline --help

You should see output similar to:

Beamline CLI

Usage: beamline <COMMAND>

Commands:
  gen          Run the generator
  infer-shape  Run the script shape inference
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

3. Test Data Generation

Let’s run a simple test to ensure data generation works:

beamline gen data --help

This should display the help for the data generation command, confirming that the core functionality is available.

Development Environment Setup

Setting Up Your Workspace

Create a directory for your Beamline projects:

mkdir ~/partiql-beamline-workspace
cd ~/partiql-beamline-workspace

Editor Configuration

VS Code

If you’re using VS Code, consider installing these extensions for better Ion support:

1. Rust Analyzer: For Rust syntax highlighting if you plan to contribute
2. ion-vscode-plugin: For Syntax Highlighting, Error Reporting, and Formatting of Beamline scripts
3. JSON: For viewing generated JSON output
4. Better TOML: For configuration files

Shell Aliases (Optional)

For convenience, you might want to create shell aliases:

# Add to your ~/.bashrc, ~/.zshrc, or equivalent
alias pql-gen='beamline gen data'
alias pql-query='beamline query'
alias pql-shape='beamline infer-shape'

Troubleshooting Installation

Common Issues

Rust Version Too Old

Error: error: package requires rustc 1.70 or newer

Solution: Update Rust:

rustup update

Build Failures

Error: Compilation errors during cargo build

Solutions:

1. Ensure you have the latest Rust version
2. Clean and rebuild:

   cargo clean
   cargo build --release
   

3. Check for system-specific dependencies

Permission Issues

Error: Permission denied when copying to /usr/local/bin

Solution: Use sudo or choose a different installation location:

# Install to user directory instead
mkdir -p ~/.local/bin
cp target/release/beamline ~/.local/bin/

PATH Issues

Error: command not found: beamline

Solution: Verify the binary is in your PATH:

which beamline
echo $PATH

Getting Help

If you encounter issues not covered here:

1. Check the Troubleshooting section
2. Review the GitHub Issues
3. Create a new issue with:
   • Your operating system
   • Rust version (rustc --version)
   • Complete error messages
   • Steps to reproduce

Performance Considerations

Release vs Debug Builds

Always use release builds for actual data generation:

# Debug build (slower, for development)
cargo build

# Release build (faster, for production use)
cargo build --release

Release builds can be 10-100x faster than debug builds for data generation tasks.

System Resources

Beamline is designed to be memory-efficient, but consider your system resources:

• RAM: 4GB minimum, 8GB+ recommended for large datasets
• Storage: Ensure adequate disk space for generated data
• CPU: Multi-core processors will benefit from parallel processing features

Next Steps

Now that you have Beamline installed and verified, you’re ready to generate your first dataset! In the next section, we’ll walk through creating your first data generation script and producing some sample data.