syntaxis/docs/howto/how-install-works.md

How install.sh Actually Works: The Dependency Chain

The Core Question

"¿Para que se pueda usar el curl con el install.sh hay que tener instalado Cargo y Rustc?"

Answer: NO - The script installs them automatically.

---

The Bootstrap Problem

This is called the "Bootstrap Problem" or "Chicken and Egg Problem":

• To compile Rust code, you need cargo and rustc
• But cargo is part of Rust
• So how do you install Rust in the first place without Rust?

The Solution: Bootstrapping

Most languages solve this with a bootstrap compiler - a pre-compiled version that installs itself.

---

How install.sh Solves It

The 8-Phase Flow

Phase 1: Pre-Flight Checks
  ├─ Check: uname (you already have this - it's in every OS)
  ├─ Check: git (you already have this or install via package manager)
  ├─ Check: curl (you already have this or install via package manager)
  └─ NO RUST NEEDED YET

Phase 2: Install Core Dependencies  ⭐ THE KEY PHASE
  ├─ Install Rust (using rustup bootstrap):
  │   curl https://sh.rustup.rs | sh
  │   └─ Downloads pre-compiled rustc + cargo
  │   └─ Installs to: ~/.rustup/toolchains/
  │   └─ Installs binaries to: ~/.cargo/bin/
  │
  ├─ Source ~/.cargo/env
  │   └─ NOW cargo is available in PATH
  │
  ├─ Install NuShell:
  │   cargo install nu
  │   └─ Uses cargo (now available)
  │
  └─ Install Just:
      cargo install just
      └─ Uses cargo (now available)

Phase 3: Clone Repository
  └─ git clone ...
     └─ git comes from system, not from Rust

Phase 4: Build Workspace
  └─ cargo build --release --workspace
     └─ Uses cargo (installed in Phase 2)
     └─ Compiles source code from repository
     └─ Creates binaries in target/release/

Phase 5: Install Binaries
  └─ cargo install --path ...
     └─ Uses cargo (installed in Phase 2)
     └─ Installs to ~/.cargo/bin/

Phase 6: Deploy Configurations
  └─ cp and mkdir (system commands)

Phase 7: Setup Environment
  └─ Update shell rc files

Phase 8: Verify Installation
  └─ Run verification commands

---

What You Need BEFORE Running install.sh

Absolute Minimum

To run curl -sSL ... | bash, you need:

1. curl - ✅ Pre-installed on all major OSes
2. bash - ✅ Pre-installed on all major OSes
3. git - ✅ Usually pre-installed, or installable via package manager
4. Internet connection - ✅ To download Rust
5. ~2GB disk space - ✅ For Rust toolchain + dependencies + build artifacts

That's IT!

You DON'T need:

• ❌ Rust (script installs it)
• ❌ Cargo (comes with Rust)
• ❌ NuShell (script installs it)
• ❌ Just (script installs it)
• ❌ Any build tools (script installs them)

---

The Bootstrap Installation Flow

Step 1: Download and Run Script

curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash

At this point, you have:

• ✅ bash (from system)
• ✅ curl (from system)
• ❌ rustc (NOT YET)
• ❌ cargo (NOT YET)

Step 2: Script Runs Phase 2

# Inside install.sh, line 283:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain 1.75

This runs the Rust installer (rustup), which:

1. Downloads pre-compiled Rust binaries for your system
   • From: https://static.rust-lang.org/dist/
   • Downloads for your architecture (aarch64-apple-darwin, x86_64-unknown-linux-gnu, etc.)
2. Installs them to ~/.rustup/
3. Adds to PATH by creating ~/.cargo/bin/

After this, you have:

• ✅ bash (from system)
• ✅ curl (from system)
• ✅ rustc (freshly installed!)
• ✅ cargo (freshly installed!)

Step 3: Source Environment

# Line 288 in install.sh:
source "$HOME/.cargo/env"

This adds ~/.cargo/bin/ to your PATH in the current shell session.

Now:

• ✅ cargo command is available
• ✅ rustc command is available

Step 4: Use Cargo to Install Everything Else

# Line 324 in install.sh:
cargo install nu --locked

Now that cargo exists, the script uses it to:

• Install NuShell
• Install Just
• Clone the repository
• Build binaries with cargo build --release
• Install binaries with cargo install

---

The Key Insight

The script doesn't need pre-compiled binaries in the repo.

Instead, it:

1. Uses curl (from system) to download Rust
2. Installs Rust which brings cargo
3. Uses cargo to download and compile everything else from source

System binaries (curl, bash, git)
        ↓
    Downloads Rust bootstrap
        ↓
    Installs Rust + Cargo
        ↓
    Uses Cargo to get/build everything
        ↓
    Final installation complete

---

Where Does Everything Come From?

Phase 1-2: System Tools

├─ curl      → Already on your system (or install via brew/apt/dnf)
├─ bash      → Already on your system
├─ git       → System package manager or pre-installed
└─ build-tools → System package manager (gcc, make, pkg-config)

Phase 2: Rust Bootstrap

├─ rustup    ← Downloaded from: https://sh.rustup.rs
├─ rustc     ← Pre-compiled binary for your architecture
└─ cargo     ← Pre-compiled binary for your architecture
              From: https://static.rust-lang.org/dist/

Phase 2-4: Everything Else

├─ NuShell   ← cargo install nu
│            ← Source downloaded from: https://crates.io/crates/nu
│            ← Compiled locally with cargo
├─ Just      ← cargo install just
│            ← Source: https://crates.io/crates/just
│            ← Compiled locally with cargo
├─ workspace ← Source in cloned repo
│            ← Compiled locally with cargo build
└─ syntaxis-tui, syntaxis-dashboard
             ← Source in cloned repo
             ← Compiled locally with cargo build

---

No Pre-Compiled Targets in Repo Needed!

Why not?

The repository contains SOURCE CODE, not compiled binaries.

syntaxis/
├─ src/
│  ├─ main.rs
│  ├─ lib.rs
│  └─ ...
├─ Cargo.toml          ← Package definition (SOURCE)
├─ Cargo.lock          ← Dependency lock (for reproducibility)
├─ syntaxis/
│  ├─ crates/
│  │  ├─ syntaxis-cli/
│  │  │  ├─ src/
│  │  │  ├─ Cargo.toml
│  │  │  └─ ...
│  │  └─ ...
│  └─ ...
└─ target/             ← NOT in git (generated during build)
   ├─ debug/           ← Compiled during `cargo build`
   └─ release/         ← Compiled during `cargo build --release`

The Installation Doesn't Need Pre-Built Targets Because:

1. Cargo downloads dependencies from crates.io
2. Cargo compiles from source on your machine
3. Each machine compiles for its own architecture automatically

# On Mac M1:
cargo build --release
  → Cargo queries: rustc --print host-tuple
  → Returns: aarch64-apple-darwin
  → Compiles for ARM64
  → Creates: target/release/workspace (ARM64 binary)

# On Linux Intel:
cargo build --release
  → Cargo queries: rustc --print host-tuple
  → Returns: x86_64-unknown-linux-gnu
  → Compiles for x86_64
  → Creates: target/release/workspace (x86_64 binary)

---

What About the Repository Size?

The repository is small because:

syntaxis repo:    ~50-100 MB
  ├─ Source code (.rs files)  ~500 KB
  ├─ Cargo.toml/lock files    ~50 KB
  ├─ Documentation            ~500 KB
  ├─ Build artifacts (target/)  ~14 GB (NOT in repo, generated locally)
  └─ git history             ~100 MB

VS. Pre-compiled binaries would need:

Pre-built binaries:    ~500 MB+
  ├─ Mac ARM64 binary        ~50 MB
  ├─ Mac Intel binary        ~50 MB
  ├─ Linux ARM64 binary      ~50 MB
  ├─ Linux Intel binary      ~50 MB
  ├─ Windows 64-bit          ~50 MB
  ├─ Windows 32-bit          ~40 MB
  └─ ... (more architectures)

Storing pre-compiled binaries would make the repo 5-10x larger!

---

The install.sh Strategy

✅ BETTER APPROACH (What We Do)

install.sh (small, ~20 KB)
    ↓
Installs: Rust + Cargo (from official bootstrap)
    ↓
Uses Cargo to: Download dependencies from crates.io
    ↓
Uses Cargo to: Compile everything from source
    ↓
Result: Optimized binaries for your exact architecture

Advantages:

• ✅ Minimal repo size (~50-100 MB)
• ✅ Works on ANY architecture (auto-compiles)
• ✅ Latest dependencies always
• ✅ Full control over build flags
• ✅ Can optimize for your specific CPU

❌ WORSE APPROACH (Pre-compiled binaries)

Repository contains pre-compiled binaries for:
  - Mac ARM64
  - Mac Intel
  - Linux ARM64
  - Linux Intel
  - Windows 64-bit
  - BSD
  - etc...

Disadvantages:

• ❌ Repo size: 500 MB+ (huge!)
• ❌ Maintenance nightmare (rebuild for each platform)
• ❌ Compatibility issues (linked against specific glibc version)
• ❌ Security concerns (harder to audit binaries)
• ❌ Can't optimize for each user's CPU

---

Timeline: What Actually Happens

$ curl -sSL https://...install.sh | bash

00:00 ↓ Script starts
00:10 ↓ Detects macOS, arm64
00:20 ↓ Downloads rustup (5 MB)
00:30 ↓ Installs Rust (~1.2 GB)
        └─ rustc, cargo, std library
01:30 ↓ Sources ~/.cargo/env
        └─ cargo is now available
01:40 ↓ Installs NuShell via cargo install nu
        └─ Compiles locally (~2 minutes)
03:40 ↓ Installs Just via cargo install just
        └─ Compiles locally (~1 minute)
04:40 ↓ Clones syntaxis repo
        └─ 50-100 MB download
05:00 ↓ cargo build --release --workspace
        └─ Compiles all 14 crates (~15-20 minutes)
20:00 ↓ cargo install --path ... (3 binaries)
        └─ Installs to ~/.cargo/bin/
21:00 ↓ Deploys configurations
21:30 ↓ Verification
22:00 ✅ DONE

Total: ~20-30 minutes (first time)
       ~5-10 minutes (subsequent runs with cache)

---

Answer to Your Exact Question

"¿Para que se pueda usar el curl con el install.sh hay que tener instalado Cargo y Rustc?"

NO. The script installs them.

But more precisely:

Tool	Before Script	What Script Does	After Script
curl	✅ Already have	Uses it to download Rust	✅ Same
bash	✅ Already have	Uses it to run script	✅ Same
git	Maybe	Installs if needed	✅ Required
Rust	❌ Don't have	Installs via rustup	✅ Installed
Cargo	❌ Don't have	Comes with Rust	✅ Installed
NuShell	❌ Don't have	Installs via cargo install	✅ Installed
Just	❌ Don't have	Installs via cargo install	✅ Installed

---

No Repository-Hosted Targets Needed

The repository does NOT need to host:

• ❌ Pre-compiled binaries
• ❌ Platform-specific artifacts
• ❌ Compiled .so/.dylib files

It only needs:

• ✅ Source code (.rs files)
• ✅ Cargo.toml / Cargo.lock
• ✅ Documentation
• ✅ Scripts (like install.sh)

Everything else is generated during installation on the user's machine.

---

Summary

┌──────────────────────────────────────────────────────────┐
│ install.sh: The Self-Bootstrapping Installer            │
├──────────────────────────────────────────────────────────┤
│                                                          │
│ Requirements (you already have):                        │
│   ✅ curl (system utility)                             │
│   ✅ bash (system shell)                               │
│   ✅ Internet connection                               │
│                                                          │
│ Installs automatically:                                 │
│   📦 Rust 1.75+ (with rustc + cargo)                   │
│   📦 NuShell                                            │
│   📦 Just task runner                                  │
│   📦 Build tools (gcc, pkg-config, etc.)              │
│   📦 workspace binaries (compiled from source)         │
│                                                          │
│ Why no pre-compiled targets in repo:                   │
│   • Repo size would be 5-10x larger                    │
│   • Cargo compiles for each user's architecture       │
│   • Works on any platform automatically               │
│                                                          │
└──────────────────────────────────────────────────────────┘

Result: One command to install everything. Pure genius! 🚀