@page install Installing Rust and Just

# Installing Rust and Just

This guide covers installing Rust and the Just task runner on all supported operating systems.

## Supported Operating Systems

- **Linux**: Ubuntu/Debian, Fedora/RHEL, and other distributions
- **macOS**: Intel and Apple Silicon
- **Windows**: Windows 10 and later

---

## Installing Rust

Rust is required to build all project binaries. The recommended installation method is via `rustup`, the official Rust toolchain installer.

### Linux

```bash
# Install rustup (official Rust installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the prompts and select default installation (option 1)

# Add Rust to your current shell session
source "$HOME/.cargo/env"
```

After installation, log out and back in, or run `source ~/.cargo/env` to ensure the Rust binaries are in your PATH.

### macOS

```bash
# Install rustup (official Rust installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the prompts and select default installation (option 1)

# Add Rust to your current shell session
source "$HOME/.cargo/env"
```

Alternatively, if you use Homebrew:

```bash
# Install via Homebrew (not recommended for development)
brew install rust
```

Note: The Homebrew installation does not include `rustup` and may be outdated. Using `rustup` directly is recommended for active Rust development.

### Windows

**Option 1: Using the installer (Recommended)**

1. Download the installer from https://www.rust-lang.org/tools/install
2. Run `rustup-init.exe`
3. Follow the prompts and select default installation
4. Restart your terminal or command prompt

**Option 2: Using winget**

```powershell
winget install Rustlang.Rustup
```

**Option 3: Using PowerShell**

```powershell
# Download and run the installer
Invoke-WebRequest -Uri https://win.rustup.rs -OutFile rustup-init.exe
.\rustup-init.exe
```

**Prerequisites for Windows:**

Rust on Windows requires the Microsoft C++ Build Tools. The installer will prompt you if they are not installed. You can install them manually:

1. Download Visual Studio Build Tools from https://visualstudio.microsoft.com/visual-cpp-build-tools/
2. Run the installer and select "C++ build tools"
3. Ensure "Windows 10 SDK" is checked

### Verify Rust Installation

After installation, verify Rust is working:

```bash
# Check Rust compiler version
rustc --version

# Check Cargo (Rust package manager) version
cargo --version

# Check rustup version
rustup --version
```

Expected output:

```
rustc 1.XX.X (hash date)
cargo 1.XX.X (hash date)
rustup 1.XX.X (hash date)
```

### Updating Rust

Keep Rust up to date with:

```bash
rustup update
```

---

## Installing Just

Just is a task runner that simplifies running project commands. It reads commands from the `justfile` in the project root.

### Linux (Ubuntu/Debian)

```bash
# Using apt (Ubuntu 22.04+, Debian 12+)
sudo apt install just

# Or using the prebuilt binary
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
```

### Linux (Fedora/RHEL)

```bash
# Using dnf (Fedora)
sudo dnf install just

# Or using the prebuilt binary
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
```

### Linux (Arch)

```bash
sudo pacman -S just
```

### Linux (Generic)

For distributions without Just in their package manager:

```bash
# Install to /usr/local/bin (requires sudo for this location)
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

# Or install to ~/.local/bin (no sudo required)
mkdir -p ~/.local/bin
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

# Ensure ~/.local/bin is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### macOS

```bash
# Using Homebrew (recommended)
brew install just

# Or using the prebuilt binary
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
```

### Windows

**Option 1: Using winget (Recommended)**

```powershell
winget install Casey.Just
```

**Option 2: Using Scoop**

```powershell
scoop install just
```

**Option 3: Using Chocolatey**

```powershell
choco install just
```

**Option 4: Using Cargo**

If you have Rust installed, you can install Just via Cargo on any platform:

```bash
cargo install just
```

Note: This compiles Just from source and may take a few minutes.

### Verify Just Installation

```bash
# Check Just version
just --version

# List available commands (from project root)
just --list
```

Expected output for `just --version`:

```
just 1.X.X
```

---

## Quick Installation Summary

### Linux (Ubuntu/Debian)

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Install Just
sudo apt install just
# Or: curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
```

### Linux (Fedora/RHEL)

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Install Just
sudo dnf install just
```

### macOS

```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Install Just
brew install just
```

### Windows

```powershell
# Install Rust (download from https://www.rust-lang.org/tools/install)
# Or: winget install Rustlang.Rustup

# Install Just
winget install Casey.Just
```

---

## Troubleshooting

### Rust Issues

**Problem:** `rustc` or `cargo` command not found

Solution: Ensure Rust is in your PATH:

```bash
# Linux/macOS
source "$HOME/.cargo/env"

# Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'source "$HOME/.cargo/env"' >> ~/.bashrc
```

**Problem:** Permission denied when installing

Solution: The rustup installer does not require sudo. If you see permission errors, ensure you are not running with sudo.

**Problem:** SSL/TLS errors during installation

Solution: Ensure your system has up-to-date CA certificates:

```bash
# Ubuntu/Debian
sudo apt install ca-certificates

# Fedora/RHEL
sudo dnf install ca-certificates
```

### Just Issues

**Problem:** `just` command not found after installation

Solution: Ensure the installation directory is in your PATH:

```bash
# If installed to ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

# If installed to /usr/local/bin (should be in PATH by default)
echo $PATH | grep -q "/usr/local/bin" || export PATH="/usr/local/bin:$PATH"
```

**Problem:** Just not available in package manager

Solution: Use the prebuilt binary installer or install via Cargo:

```bash
# Prebuilt binary
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

# Or via Cargo (requires Rust)
cargo install just
```

---

## Next Steps

After installing Rust and Just, proceed to:

1. **[BUILD.md](BUILD.md)** - Install system dependencies for your platform
2. **[QUICKSTART.md](QUICKSTART.md)** - Build and run the project

### Common Just Commands

Once installed, you can use these commands from the project root:

```bash
# List all available commands
just --list

# Build Python bindings
just build

# Run tests
just test

# Build all Rust binaries
just build-all

# Run full CI checks
just ci
```

See the [justfile](../justfile) for all available commands.
