syntaxis/docs/howto/bash-commands-reference.md

# Bash Commands Reference - Target Selection Investigation

Complete reference of all bash commands used to understand how syntaxis installer selects correct targets.

## Quick Start: 5 Essential Commands

```bash
# 1. See your OS and architecture
uname -s && uname -m

# 2. See what Rust target triple you have (THE KEY)
rustc --print host-tuple

# 3. See what targets you can compile for
rustup target list | grep installed

# 4. See every command cargo executes
cargo build --release -v

# 5. Verify the compiled binary matches your architecture
file target/release/workspace
```

---

## Category 1: System Detection

### `uname -s`
- **Purpose:** Detect operating system
- **Output:** `Darwin` (macOS) or `Linux`
- **Used by:** install.sh to choose how to install dependencies

### `uname -m`
- **Purpose:** Detect processor architecture
- **Output:** `arm64`, `x86_64`, `aarch64`
- **Used by:** install.sh to understand CPU type

### `uname -a`
- **Purpose:** Complete system information
- **Output:** Full kernel, hostname, architecture details
- **Used by:** Debugging, comprehensive system check

---

## Category 2: Rust Information (The Critical Ones)

### `rustc --version`
- **Purpose:** Check installed Rust version
- **Output:** `rustc 1.91.1 (ed61e7d7e 2025-11-07)`
- **Why:** Verify compatibility (needs 1.75+)

### ⭐ `rustc --print host-tuple` ⭐
- **Purpose:** Get the host target triple - THIS IS THE KEY
- **Output Examples:**
  - `aarch64-apple-darwin` (Mac M1/M2/M3)
  - `x86_64-apple-darwin` (Mac Intel)
  - `aarch64-unknown-linux-gnu` (Linux ARM64)
  - `x86_64-unknown-linux-gnu` (Linux Intel x86)
- **Why:** This is EXACTLY what Cargo uses to decide what to compile

### `rustc --print cfg`
- **Purpose:** See CPU features Rust detects
- **Output:** `target_arch="aarch64"`, `target_os="macos"`, etc.
- **Why:** Developers use `#[cfg(...)]` directives based on this

### `rustc --version --verbose`
- **Purpose:** Detailed Rust information including LLVM
- **Used by:** Debugging compatibility issues

---

## Category 3: Rustup Toolchain Manager

### `rustup default`
- **Purpose:** See default toolchain
- **Output:** `stable-aarch64-apple-darwin (default)`
- **Why:** Verify correct toolchain is active

### `rustup toolchain list`
- **Purpose:** List all installed toolchains
- **Output:** Multiple toolchain versions and variants
- **Why:** Check if you have multiple Rust versions

### `rustup target list | grep installed`
- **Purpose:** List INSTALLED targets for compilation
- **Output Examples:**
  ```
  aarch64-apple-darwin (installed)
  x86_64-apple-darwin (installed)
  x86_64-unknown-linux-gnu (installed)
  ```
- **Why:** Determines if cross-compilation is possible
  - Only `aarch64-apple-darwin` = can only compile for Mac ARM
  - Multiple targets = can cross-compile

### `rustup which rustc`
- **Purpose:** Find where rustc is installed
- **Output:** `/Users/.../stable-aarch64-apple-darwin/bin/rustc`
- **Why:** Verify installation paths are correct

### `rustup target add x86_64-unknown-linux-gnu`
- **Purpose:** Install a new target for cross-compilation
- **Used by:** Setting up cross-compilation capability

---

## Category 4: Advanced Rust Information

### `rustc --print sysroot`
- **Purpose:** Find standard library and installed targets location
- **Output:** `/Users/.../.rustup/toolchains/stable-aarch64-apple-darwin`
- **Why:** Verify library paths and installed targets

### `rustc --print sysroot | xargs -I {} ls {}/lib/rustlib/`
- **Purpose:** List all targets available in this Rust installation
- **Output:**
  ```
  aarch64-apple-darwin
  aarch64-apple-ios
  x86_64-apple-darwin
  x86_64-unknown-linux-gnu
  ```
- **Why:** See exactly what you can compile for

### `rustc --print target-list | head -20`
- **Purpose:** List ALL targets Rust theoretically supports (100+)
- **Used by:** Research, seeing all possible options

---

## Category 5: Cargo Information

### `cargo --version`
- **Purpose:** Check Cargo version
- **Output:** `cargo 1.91.1`
- **Why:** Verify compatibility

### `cargo metadata --format-version=1 --no-deps`
- **Purpose:** Get JSON information about workspace
- **Used by:** Automated scripts, parsing crate information

### `cargo build --release --dry-run`
- **Purpose:** See what would compile WITHOUT compiling
- **Used by:** Safe preview before long compilation

### `cargo build --release -v`
- **Purpose:** Verbose mode - show every command cargo executes
- **Output:** Each rustc command, linker flags, etc.
- **Used by:** Understanding exactly what cargo does

---

## Category 6: Project Investigation

### `ls -la .cargo/`
- **Purpose:** Check if custom cargo config exists
- **Why:** `.cargo/config.toml` affects how cargo compiles

### `cat .cargo/config.toml`
- **Purpose:** View custom compilation configuration
- **Contains:** Build settings, target-specific flags, cross-compilation config
- **Why:** Cargo uses this for special compilation modes

### `grep -A 10 "\[profile.release\]" Cargo.toml`
- **Purpose:** See release build optimizations
- **Output Examples:**
  ```toml
  opt-level = 3
  lto = true
  codegen-units = 1
  strip = true
  ```
- **Why:** Understand how binaries are optimized

### `cat Cargo.toml | grep resolver`
- **Purpose:** Check workspace resolver version
- **Output:** `resolver = "2"`
- **Why:** Affects dependency resolution behavior

---

## Category 7: Target Directory Inspection

### `du -sh target/debug target/release`
- **Purpose:** Compare debug vs release build sizes
- **Output:** `12G target/debug` vs `2.4G target/release`
- **Why:** Understand space usage difference

### `cat target/.rustc_info.json`
- **Purpose:** View cached host information from previous build
- **Contains:** Target triple, CPU features, compiler info
- **Why:** Understand what cargo detected

### `ls -lh target/release/deps/ | head`
- **Purpose:** View compiled artifacts (.rlib, .dylib, .o files)
- **Used by:** Verifying compilation succeeded

### `ls -lh target/release/`
- **Purpose:** List generated executables
- **Output:** `workspace`, `syntaxis-tui`, `syntaxis-dashboard`
- **Why:** Verify binaries were created

### ⭐ `file target/release/workspace` ⭐
- **Purpose:** Check architecture of compiled binary - VERIFICATION
- **Output Examples:**
  - `Mach-O 64-bit executable arm64` (Mac ARM64 - correct)
  - `ELF 64-bit LSB pie executable, x86-64` (Linux Intel - correct)
- **Why:** CONFIRM binary was compiled for correct architecture
  - If Mac shows `x86-64` = PROBLEM
  - If Linux shows `arm64` = PROBLEM

---

## Category 8: Cross-Compilation

### `rustup target add x86_64-unknown-linux-gnu`
- **Purpose:** Install capability to compile for a different target
- **Used by:** Setting up cross-compilation from macOS to Linux

### `cargo build --release --target x86_64-unknown-linux-gnu`
- **Purpose:** Explicitly compile for a different target
- **Result:** Creates `target/x86_64-unknown-linux-gnu/release/`
- **Why:** Compile binaries for different OS/architecture

### `ls -lh target/x86_64-unknown-linux-gnu/release/`
- **Purpose:** View cross-compiled binaries for different target
- **Used by:** Verify cross-compilation worked

---

## Category 9: Binary Analysis

### `file target/release/workspace`
- **Purpose:** Check binary format and architecture
- **Most Important For:** Verifying correct architecture
- **Output:**
  - macOS: `Mach-O 64-bit executable arm64`
  - Linux: `ELF 64-bit LSB pie executable, x86-64`

### `nm target/release/workspace | head`
- **Purpose:** View symbols in binary
- **Output:** Function names (empty if stripped)
- **Used by:** Debug if suspicious of compilation issues

### `ldd target/release/workspace` (Linux only)
- **Purpose:** Show dynamic library dependencies
- **Output:** `libstdc++.so.6`, `libc.so.6`, etc.
- **Why:** Verify runtime dependencies

---

## Category 10: Build and Compilation

### `cargo build --workspace`
- **Purpose:** Quick debug build for development
- **Speed:** Fast (no optimizations)

### `cargo build --release --workspace`
- **Purpose:** Optimized production build
- **Speed:** Slow (maximum optimization with LTO)

### `cargo check --workspace`
- **Purpose:** Fast error checking without generating binaries
- **Speed:** Fastest (no codegen)
- **Used by:** Quick feedback during development

### `cargo test --workspace --lib --release`
- **Purpose:** Run tests with optimized binaries
- **Used by:** Validation before release

---

## How The System Works

### The Selection Flow

```
1. User runs: cargo build --release
   ↓
2. Cargo queries: rustc --print host-tuple
   ↓
3. Rustc responds: aarch64-apple-darwin
   ↓
4. Cargo creates: target/release/
   ↓
5. For each source file:
   - rustc compiles → .o file (object file for aarch64)
   - Links .o files → .rlib or executable
   ↓
6. Result: Binary for aarch64-apple-darwin
```

### Key Insight

**Cargo automatically detects the correct target.** No manual configuration needed for native compilation!

```bash
cargo build --release
# ✓ On Mac M1: automatically compiles for aarch64-apple-darwin
# ✓ On Mac Intel: automatically compiles for x86_64-apple-darwin
# ✓ On Linux ARM: automatically compiles for aarch64-unknown-linux-gnu
```

---

## Troubleshooting Guide

### Problem: "Binary won't run on my system"
**Solution:** Check architecture
```bash
# See what target your system is
rustc --print host-tuple

# Check what was compiled
file target/release/workspace

# They must match!
```

### Problem: "Want to compile for a different OS"
**Solution:** Use cross-compilation
```bash
# Check available targets
rustup target list | grep installed

# Install new target if needed
rustup target add x86_64-unknown-linux-gnu

# Build for specific target
cargo build --release --target x86_64-unknown-linux-gnu

# Verify
file target/x86_64-unknown-linux-gnu/release/workspace
```

### Problem: "Build seems wrong or slow"
**Solution:** Check with verbose mode
```bash
cargo build --release -v
```

---

## Summary Table

| Command | Purpose | Critical? |
|---------|---------|-----------|
| `uname -s && uname -m` | See your system | Yes |
| `rustc --print host-tuple` | See your target | **YES** |
| `rustup target list \| grep installed` | See possible targets | Yes |
| `cargo build --release -v` | See build details | No |
| `file target/release/workspace` | Verify architecture | **YES** |
| `rustup target add TARGET` | Install new target | Only for cross-compile |
| `cargo build --target TARGET` | Build for different target | Only for cross-compile |

---

## For install.sh Context

The `install.sh` script uses:

```bash
# Phase 1: Detect system
OS=$(detect_os)        # Uses: uname -s
ARCH=$(detect_arch)    # Uses: uname -m

# Phase 2-7: Install and build
cargo build --release --workspace
# Cargo internally uses: rustc --print host-tuple
# Result: Builds for detected target automatically

# Phase 5: Install binaries
cargo install --path core/crates/syntaxis-cli
# Installs to ~/.cargo/bin/workspace
# Binary is for the target detected in Phase 4
```

**The key:** Once Cargo knows the host target (via rustc), it handles everything automatically!

---

## References

- [Rust Platform Support](https://forge.rust-lang.org/release/platform-support.html)
- [Cargo Documentation](https://doc.rust-lang.org/cargo/)
- [Cross-compilation Guide](https://rust-lang.github.io/rustup/cross-compilation.html)