syntaxis/docs/howto/bootstrap-explained-final.md

Bootstrap Compiler: Complete Technical Walkthrough

The Fundamental Problem: Bootstrapping Rust

The core challenge Rust faces is a circular dependency:

To compile Rust source code → You need rustc compiler
To get rustc compiler → You need to compile Rust source code

🔄 Circular dependency!

This is called the "bootstrap problem" and exists for all programming languages.

Rust's solution: Provide pre-compiled binaries so you can break the cycle.

The Solution: rustup Bootstrap Architecture

When you run:

curl https://sh.rustup.rs | bash

Here's what happens:

1. Download installer script (~50KB bash script from GitHub)
2. Execute with bash (already on all systems)
3. Detect your system using uname -s and uname -m
4. Download pre-compiled Rust for your architecture (~100MB from static.rust-lang.org)
5. Extract and install to ~/.rustup/
6. Configure PATH so rustc is available globally

Key Insight: The installer doesn't compile Rust. It downloads pre-compiled binaries.

Why Only Rust is Pre-Compiled

Approach A: Bootstrap Only (✅ What Rust Does)

• Pre-compile: rustc for 50 architectures (100MB each)
• Total size: ~150MB download
• Time: ~45 seconds
• Maintenance: Free (Rust Foundation handles it)
• Everything else compiled from source by rustc

Approach B: Pre-Compile Everything (❌ Hypothetical)

• Pre-compile: rustc, NuShell, Just, workspace for 50 architectures
• Total size: 5GB+
• Time: Hours to download
• Maintenance: Rebuild every Rust release (weekly)
• Cost: $1000s/month in infrastructure

Approach C: Compile from Source (❌ Original Approach)

• User compiles Rust from source
• Time: 3+ hours
• Requires: C compiler, CMake, GNU Make, etc.
• Result: Not suitable for end users

Conclusion: Bootstrap is the elegant sweet spot.

The Architecture Detection Process

Your system
    ↓
uname -s → "Darwin" (OS)
uname -m → "arm64" (Processor)
    ↓
Construct target triple: "aarch64-apple-darwin"
    ↓
Download from: https://static.rust-lang.org/dist/
rust-1.91.1-aarch64-apple-darwin.tar.gz
    ↓
Extract and install
    ↓
rustc is now available!

Supported Architectures (50+)

System	Target Triple	Status
M1/M2/M3 Mac	aarch64-apple-darwin	✅
Intel Mac	x86_64-apple-darwin	✅
Linux ARM 64-bit	aarch64-unknown-linux-gnu	✅
Linux Intel 64-bit	x86_64-unknown-linux-gnu	✅
Linux ARM (musl)	aarch64-unknown-linux-musl	✅
Windows Intel	x86_64-pc-windows-msvc	✅
Windows ARM	aarch64-pc-windows-msvc	✅
Plus 40+ more	Android, iOS, FreeBSD, WebAssembly, RISC-V, PowerPC, etc.	✅

How Our install.sh Uses Bootstrap

Phase 1: Detect system
         ↓
Phase 2: curl https://sh.rustup.rs | bash
         (Bootstrap installs pre-compiled Rust)
         ↓
Phase 3: cargo install nu
         (Rust compiles NuShell from source)
         ↓
Phase 4: cargo install just
         (Rust compiles Just from source)
         ↓
Phase 5: git clone syntaxis
         ↓
Phase 6: cargo build --release
         (Rust compiles all workspace binaries)
         ↓
Phase 7: Deploy configuration
         ↓
Phase 8: Verify installation
         ↓
Everything ready to use! ✅

Installation Timeline

⏱️  T+0s   Download installer script (50KB)
⏱️  T+1s   Execute bash script
⏱️  T+2s   Detect system (uname)
⏱️  T+30s  Download pre-compiled Rust (100MB)
⏱️  T+35s  Verify SHA256 checksum
⏱️  T+40s  Extract and install to ~/.rustup/
⏱️  T+45s  ✅ Rust installed and ready
→  Next: Compile NuShell (1-2 minutes)
→  Next: Compile Just (1-2 minutes)
→  Next: Build workspace (5-10 minutes)
→  Next: Deploy & verify (<1 minute)
⏱️  Total: 15-30 minutes

The Bootstrap Kernel Concept

Think of pre-compiled rustc as the "kernel" of the system:

Traditional OS Bootstrap:
    CPU powers on → BIOS → Bootloader → Kernel → OS

Rust Bootstrap:
    User runs script → sh.rustup.rs → Pre-compiled rustc → Everything else
                           ↑ (50KB)              ↑ (100MB)
                        Bash script          Pre-compiled kernel

Once you have the kernel (rustc), everything else builds from source.

FAQ

Q: Why not just download pre-compiled workspace binaries?

A: That would require 5GB+ repository, rebuilding for every Rust release (weekly), and thousands in infrastructure costs. Bootstrap solves this elegantly by only pre-compiling the minimal dependency (rustc).

Q: What happens if my architecture isn't supported?

A: You'd compile Rust from source (3+ hours). Rust Nightly supports 50+ architectures, covering 99%+ of use cases.

Q: Is downloading pre-compiled binaries safe?

A: Yes. Rust uses HTTPS, SHA256 verification, cryptographic signing, and is distributed via Amazon CloudFront. Multiple security layers.

Q: Can I compile from source instead?

A: Yes, you can clone Rust GitHub and compile from source. Takes 3+ hours and requires C/C++ compiler toolchain.

Q: How does Cargo know what architecture to build for?

A: It calls rustc --print host-tuple to detect automatically. No manual configuration needed for native builds.

Q: What gets pre-compiled in the download?

A: Only: rustc, cargo, rustfmt, clippy, and the standard library (pre-compiled for your architecture). Everything else comes from source.

Why This Matters for syntaxis

Because we use Rust's bootstrap approach, our installation:

✅ Works with one command: curl ... | bash ✅ Automatically detects your architecture (50+ supported) ✅ Installs in 15-30 minutes (not 4+ hours) ✅ Keeps repository small (~500MB, not 5GB+) ✅ Requires zero pre-compiled binaries in our repo ✅ Automatically updates when Rust updates ✅ Works on macOS, Linux, Windows, and more

All because we leverage the Rust Foundation's pre-compiled rustc bootstrap instead of trying to pre-compile everything ourselves.

Summary

The bootstrap compiler solves the circular dependency with elegance:

1. Only pre-compile one thing: rustc (the compiler itself)
2. Use rustc to build everything else from source
3. Loop broken! No more circular dependency

This is why Rust installation is so fast and so simple for end users.