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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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! 🚀**