foxhunt/LLD_SETUP_GUIDE.md

# LLD Linker Configuration - Setup Summary

## ⚠️ Action Required

**LLD is not currently installed** on this system. Sudo privileges are required for installation.

## 📋 Quick Setup (Automated)

Run the provided setup script:

```bash
sudo bash /tmp/setup_lld.sh
```

This script will:
1. Install lld package
2. Verify installation
3. Backup current .cargo/config.toml
4. Apply lld configuration
5. Test compilation

## 📋 Manual Setup (Alternative)

### Step 1: Install LLD
```bash
sudo apt-get update
sudo apt-get install -y lld
```

### Step 2: Verify Installation
```bash
ld.lld --version
```

Expected output:
```
LLD 18.x.x (compatible with GNU linkers)
```

### Step 3: Apply Configuration

The updated configuration is ready at: `/tmp/config.toml.lld`

Copy it to your project:
```bash
cp /tmp/config.toml.lld /home/jgrusewski/Work/foxhunt/.cargo/config.toml
```

Or manually edit `/home/jgrusewski/Work/foxhunt/.cargo/config.toml`:

**Change this section:**
```toml
[target.x86_64-unknown-linux-gnu]
rustflags = [
    "-C", "link-arg=-Wl,-z,relro,-z,now",
    "-C", "link-arg=-Wl,--as-needed",
    # ... rest of flags
```

**To this:**
```toml
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = [
    "-C", "link-arg=-Wl,-z,relro,-z,now",
    "-C", "link-arg=-Wl,--as-needed",
    "-C", "link-arg=-fuse-ld=lld",  # ← ADD THIS LINE
    # ... rest of flags
```

## 🧪 Testing After Setup

### 1. Clean Build Benchmark
```bash
cd /home/jgrusewski/Work/foxhunt
cargo clean
time cargo build --release
```

Record the total time (especially "Linking" phase).

### 2. Incremental Build Test
```bash
# Make a trivial change
echo "// test" >> services/trading_service/src/main.rs
time cargo build --release
```

### 3. Load Test Build
```bash
time cargo build --bin load_test --release
```

## 📊 Expected Results

### Before LLD (Baseline)
- **Clean build**: ~5-10 minutes
- **Linking phase**: 30-60 seconds
- **Incremental build**: 20-40 seconds

### After LLD (Target)
- **Clean build**: ~3-6 minutes (40-60% faster)
- **Linking phase**: 5-15 seconds (70-80% faster)
- **Incremental build**: 10-20 seconds (50% faster)

### Performance Improvements
| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Link time | 30-60s | 5-15s | 70-80% |
| Clean build | 5-10m | 3-6m | 40-60% |
| Incremental | 20-40s | 10-20s | 50% |

## ✅ Verification Checklist

After installation and configuration:

- [ ] `ld.lld --version` shows version info
- [ ] `.cargo/config.toml` includes `linker = "clang"`
- [ ] `.cargo/config.toml` includes `"-C", "link-arg=-fuse-ld=lld"`
- [ ] `cargo build --release` completes without errors
- [ ] Build time is significantly reduced
- [ ] Tests still pass: `cargo test --workspace`
- [ ] Binary size is similar to before (±5%)

## 🔍 Troubleshooting

### Issue: "ld.lld: command not found"
**Solution**: Install lld:
```bash
sudo apt-get install -y lld
```

### Issue: "error: linker `clang` not found"
**Solution**: Clang is already installed, but verify:
```bash
which clang  # Should show /usr/bin/clang
```

### Issue: Build errors after configuration change
**Solution**: Revert to backup:
```bash
cd /home/jgrusewski/Work/foxhunt
cp .cargo/config.toml.backup.* .cargo/config.toml
```

### Issue: No noticeable improvement
**Check**:
1. Verify lld is actually being used:
```bash
cargo build --release -vv 2>&1 | grep -i "link"
```
Should show clang with `-fuse-ld=lld`

2. Make sure you're testing release builds (debug builds link faster anyway)

## 📁 Files Created

1. `/tmp/lld_installation_report.md` - Detailed analysis and recommendations
2. `/tmp/config.toml.lld` - Updated configuration file
3. `/tmp/setup_lld.sh` - Automated setup script
4. `/tmp/SETUP_SUMMARY.md` - This file

## 🚀 Next Steps

1. **Install lld** (requires sudo)
2. **Apply configuration** (automated or manual)
3. **Test builds** and measure improvements
4. **Report results** with before/after timings
5. **Update CI/CD** to include lld installation
6. **Update team docs** with new setup requirements

## 💡 Additional Optimizations

If you want even more build speed:

1. **Use cargo-nextest** for parallel testing
2. **Enable sccache** for shared compilation cache
3. **Use cargo-chef** for Docker layer caching
4. **Configure ramdisk** for target directory (advanced)

## 📚 Resources

- LLD Documentation: https://lld.llvm.org/
- Rust Linker Configuration: https://doc.rust-lang.org/cargo/reference/config.html
- Foxhunt .cargo/config.toml: `/home/jgrusewski/Work/foxhunt/.cargo/config.toml`