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

# 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:

  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!

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

# 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

# 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

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:

# 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
• Cargo Documentation
• Cross-compilation Guide