Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
391
vendor/ruvector/docs/optimization/BUILD_OPTIMIZATION.md
vendored
Normal file
391
vendor/ruvector/docs/optimization/BUILD_OPTIMIZATION.md
vendored
Normal file
@@ -0,0 +1,391 @@
|
||||
# Build Optimization Guide
|
||||
|
||||
Comprehensive guide for optimizing Ruvector builds for maximum performance.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Maximum Performance Build
|
||||
|
||||
```bash
|
||||
# One-command optimized build
|
||||
RUSTFLAGS="-C target-cpu=native -C target-feature=+avx2,+fma -C link-arg=-fuse-ld=lld" \
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
## Compiler Flags
|
||||
|
||||
### Target CPU Optimization
|
||||
|
||||
```bash
|
||||
# Native CPU (recommended for production)
|
||||
RUSTFLAGS="-C target-cpu=native" cargo build --release
|
||||
|
||||
# Specific CPUs
|
||||
RUSTFLAGS="-C target-cpu=skylake" cargo build --release
|
||||
RUSTFLAGS="-C target-cpu=znver3" cargo build --release
|
||||
RUSTFLAGS="-C target-cpu=neoverse-v1" cargo build --release
|
||||
```
|
||||
|
||||
### SIMD Features
|
||||
|
||||
```bash
|
||||
# AVX2 + FMA
|
||||
RUSTFLAGS="-C target-feature=+avx2,+fma" cargo build --release
|
||||
|
||||
# AVX-512 (if supported)
|
||||
RUSTFLAGS="-C target-feature=+avx512f,+avx512dq,+avx512vl" cargo build --release
|
||||
|
||||
# List available features
|
||||
rustc --print target-features
|
||||
```
|
||||
|
||||
### Link-Time Optimization
|
||||
|
||||
Already configured in Cargo.toml:
|
||||
|
||||
```toml
|
||||
[profile.release]
|
||||
lto = "fat" # Maximum LTO
|
||||
codegen-units = 1 # Single codegen unit
|
||||
```
|
||||
|
||||
Alternatives:
|
||||
|
||||
```toml
|
||||
lto = "thin" # Faster builds, slightly less optimization
|
||||
codegen-units = 4 # Parallel codegen (faster builds)
|
||||
```
|
||||
|
||||
### Linker Selection
|
||||
|
||||
Use faster linkers:
|
||||
|
||||
```bash
|
||||
# LLD (LLVM linker) - recommended
|
||||
RUSTFLAGS="-C link-arg=-fuse-ld=lld" cargo build --release
|
||||
|
||||
# Mold (fastest)
|
||||
RUSTFLAGS="-C link-arg=-fuse-ld=mold" cargo build --release
|
||||
|
||||
# Gold
|
||||
RUSTFLAGS="-C link-arg=-fuse-ld=gold" cargo build --release
|
||||
```
|
||||
|
||||
## Profile-Guided Optimization (PGO)
|
||||
|
||||
### Step-by-Step PGO
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# pgo_build.sh
|
||||
|
||||
set -e
|
||||
|
||||
# 1. Clean previous builds
|
||||
cargo clean
|
||||
|
||||
# 2. Build instrumented binary
|
||||
echo "Building instrumented binary..."
|
||||
mkdir -p /tmp/pgo-data
|
||||
RUSTFLAGS="-Cprofile-generate=/tmp/pgo-data" \
|
||||
cargo build --release --bin ruvector-bench
|
||||
|
||||
# 3. Run representative workload
|
||||
echo "Running profiling workload..."
|
||||
./target/release/ruvector-bench \
|
||||
--workload mixed \
|
||||
--vectors 1000000 \
|
||||
--queries 10000 \
|
||||
--dimensions 384
|
||||
|
||||
# You can run multiple workloads to cover different scenarios
|
||||
./target/release/ruvector-bench \
|
||||
--workload search-heavy \
|
||||
--vectors 500000 \
|
||||
--queries 50000
|
||||
|
||||
# 4. Merge profiling data
|
||||
echo "Merging profile data..."
|
||||
llvm-profdata merge -o /tmp/pgo-data/merged.profdata /tmp/pgo-data/*.profraw
|
||||
|
||||
# 5. Build optimized binary
|
||||
echo "Building PGO-optimized binary..."
|
||||
RUSTFLAGS="-Cprofile-use=/tmp/pgo-data/merged.profdata -C target-cpu=native" \
|
||||
cargo build --release
|
||||
|
||||
echo "PGO build complete!"
|
||||
echo "Binary: ./target/release/ruvector-bench"
|
||||
```
|
||||
|
||||
### Expected PGO Gains
|
||||
|
||||
- **Throughput**: +10-15%
|
||||
- **Latency**: -10-15%
|
||||
- **Binary Size**: +5-10% (due to profiling data)
|
||||
|
||||
## Optimization Levels
|
||||
|
||||
### Cargo Profile Configurations
|
||||
|
||||
```toml
|
||||
# Maximum performance (default)
|
||||
[profile.release]
|
||||
opt-level = 3
|
||||
lto = "fat"
|
||||
codegen-units = 1
|
||||
panic = "abort"
|
||||
strip = true
|
||||
|
||||
# Fast compilation, good performance
|
||||
[profile.release-fast]
|
||||
inherits = "release"
|
||||
lto = "thin"
|
||||
codegen-units = 16
|
||||
|
||||
# Debug with optimizations
|
||||
[profile.dev-optimized]
|
||||
inherits = "dev"
|
||||
opt-level = 2
|
||||
```
|
||||
|
||||
Build with custom profile:
|
||||
|
||||
```bash
|
||||
cargo build --profile release-fast
|
||||
```
|
||||
|
||||
## CPU-Specific Builds
|
||||
|
||||
### Intel CPUs
|
||||
|
||||
```bash
|
||||
# Haswell (AVX2)
|
||||
RUSTFLAGS="-C target-cpu=haswell" cargo build --release
|
||||
|
||||
# Skylake (AVX2 + better)
|
||||
RUSTFLAGS="-C target-cpu=skylake" cargo build --release
|
||||
|
||||
# Cascade Lake (AVX-512)
|
||||
RUSTFLAGS="-C target-cpu=cascadelake" cargo build --release
|
||||
|
||||
# Ice Lake (AVX-512 + more)
|
||||
RUSTFLAGS="-C target-cpu=icelake-server" cargo build --release
|
||||
```
|
||||
|
||||
### AMD CPUs
|
||||
|
||||
```bash
|
||||
# Zen 2
|
||||
RUSTFLAGS="-C target-cpu=znver2" cargo build --release
|
||||
|
||||
# Zen 3
|
||||
RUSTFLAGS="-C target-cpu=znver3" cargo build --release
|
||||
|
||||
# Zen 4
|
||||
RUSTFLAGS="-C target-cpu=znver4" cargo build --release
|
||||
```
|
||||
|
||||
### ARM CPUs
|
||||
|
||||
```bash
|
||||
# Neoverse N1
|
||||
RUSTFLAGS="-C target-cpu=neoverse-n1" cargo build --release
|
||||
|
||||
# Neoverse V1
|
||||
RUSTFLAGS="-C target-cpu=neoverse-v1" cargo build --release
|
||||
|
||||
# Apple Silicon
|
||||
RUSTFLAGS="-C target-cpu=apple-m1" cargo build --release
|
||||
```
|
||||
|
||||
## Dependency Optimization
|
||||
|
||||
### Optimize Dependencies
|
||||
|
||||
Add to Cargo.toml:
|
||||
|
||||
```toml
|
||||
[profile.release.package."*"]
|
||||
opt-level = 3
|
||||
```
|
||||
|
||||
### Feature Selection
|
||||
|
||||
Disable unused features:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tokio = { version = "1", default-features = false, features = ["rt-multi-thread"] }
|
||||
```
|
||||
|
||||
## Cross-Compilation
|
||||
|
||||
### Building for Different Targets
|
||||
|
||||
```bash
|
||||
# Add target
|
||||
rustup target add x86_64-unknown-linux-musl
|
||||
|
||||
# Build for target
|
||||
cargo build --release --target x86_64-unknown-linux-musl
|
||||
|
||||
# With optimizations
|
||||
RUSTFLAGS="-C target-cpu=generic" \
|
||||
cargo build --release --target x86_64-unknown-linux-musl
|
||||
```
|
||||
|
||||
## Build Scripts
|
||||
|
||||
### Automated Optimized Build
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build_optimized.sh
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Detect CPU
|
||||
CPU_ARCH=$(lscpu | grep "Model name" | sed 's/Model name: *//')
|
||||
echo "Detected CPU: $CPU_ARCH"
|
||||
|
||||
# Set optimal flags
|
||||
if [[ $CPU_ARCH == *"Intel"* ]]; then
|
||||
if [[ $CPU_ARCH == *"Ice Lake"* ]] || [[ $CPU_ARCH == *"Cascade Lake"* ]]; then
|
||||
TARGET_CPU="icelake-server"
|
||||
TARGET_FEATURES="+avx512f,+avx512dq"
|
||||
else
|
||||
TARGET_CPU="skylake"
|
||||
TARGET_FEATURES="+avx2,+fma"
|
||||
fi
|
||||
elif [[ $CPU_ARCH == *"AMD"* ]]; then
|
||||
if [[ $CPU_ARCH == *"Zen 3"* ]]; then
|
||||
TARGET_CPU="znver3"
|
||||
elif [[ $CPU_ARCH == *"Zen 4"* ]]; then
|
||||
TARGET_CPU="znver4"
|
||||
else
|
||||
TARGET_CPU="znver2"
|
||||
fi
|
||||
TARGET_FEATURES="+avx2,+fma"
|
||||
else
|
||||
TARGET_CPU="native"
|
||||
TARGET_FEATURES="+avx2,+fma"
|
||||
fi
|
||||
|
||||
echo "Using target-cpu: $TARGET_CPU"
|
||||
echo "Using target-features: $TARGET_FEATURES"
|
||||
|
||||
# Build
|
||||
RUSTFLAGS="-C target-cpu=$TARGET_CPU -C target-feature=$TARGET_FEATURES -C link-arg=-fuse-ld=lld" \
|
||||
cargo build --release
|
||||
|
||||
echo "Build complete!"
|
||||
ls -lh target/release/
|
||||
```
|
||||
|
||||
## Benchmarking Builds
|
||||
|
||||
### Compare Optimization Levels
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# benchmark_builds.sh
|
||||
|
||||
echo "Building and benchmarking different optimization levels..."
|
||||
|
||||
# Baseline
|
||||
cargo clean
|
||||
cargo build --release
|
||||
hyperfine --warmup 3 './target/release/ruvector-bench' --export-json baseline.json
|
||||
|
||||
# With target-cpu=native
|
||||
cargo clean
|
||||
RUSTFLAGS="-C target-cpu=native" cargo build --release
|
||||
hyperfine --warmup 3 './target/release/ruvector-bench' --export-json native.json
|
||||
|
||||
# With AVX2
|
||||
cargo clean
|
||||
RUSTFLAGS="-C target-feature=+avx2,+fma" cargo build --release
|
||||
hyperfine --warmup 3 './target/release/ruvector-bench' --export-json avx2.json
|
||||
|
||||
# Compare
|
||||
echo "Comparing results..."
|
||||
hyperfine --warmup 3 \
|
||||
-n "baseline" './target/release-baseline/ruvector-bench' \
|
||||
-n "native" './target/release-native/ruvector-bench' \
|
||||
-n "avx2" './target/release-avx2/ruvector-bench'
|
||||
```
|
||||
|
||||
## Production Build Checklist
|
||||
|
||||
- [ ] Use `target-cpu=native` or specific CPU
|
||||
- [ ] Enable LTO (`lto = "fat"`)
|
||||
- [ ] Set `codegen-units = 1`
|
||||
- [ ] Enable `panic = "abort"`
|
||||
- [ ] Strip symbols (`strip = true`)
|
||||
- [ ] Use fast linker (lld or mold)
|
||||
- [ ] Run PGO if possible
|
||||
- [ ] Test on production-like workload
|
||||
- [ ] Verify SIMD instructions with `objdump`
|
||||
- [ ] Benchmark before deployment
|
||||
|
||||
## Verification
|
||||
|
||||
### Check SIMD Instructions
|
||||
|
||||
```bash
|
||||
# Check for AVX2
|
||||
objdump -d target/release/ruvector-bench | grep vfmadd
|
||||
|
||||
# Check for AVX-512
|
||||
objdump -d target/release/ruvector-bench | grep vfmadd512
|
||||
|
||||
# Check all SIMD instructions
|
||||
objdump -d target/release/ruvector-bench | grep -E "vmovups|vfmadd|vaddps"
|
||||
```
|
||||
|
||||
### Verify Optimizations
|
||||
|
||||
```bash
|
||||
# Check optimization level
|
||||
readelf -p .comment target/release/ruvector-bench
|
||||
|
||||
# Check binary size
|
||||
ls -lh target/release/ruvector-bench
|
||||
|
||||
# Check linked libraries
|
||||
ldd target/release/ruvector-bench
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Errors
|
||||
|
||||
**Problem**: AVX-512 not supported
|
||||
|
||||
```bash
|
||||
# Fall back to AVX2
|
||||
RUSTFLAGS="-C target-feature=+avx2,+fma" cargo build --release
|
||||
```
|
||||
|
||||
**Problem**: Linker errors
|
||||
|
||||
```bash
|
||||
# Use system linker
|
||||
cargo build --release
|
||||
# No RUSTFLAGS needed
|
||||
```
|
||||
|
||||
**Problem**: Slow builds
|
||||
|
||||
```bash
|
||||
# Use thin LTO and parallel codegen
|
||||
[profile.release]
|
||||
lto = "thin"
|
||||
codegen-units = 16
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [rustc Codegen Options](https://doc.rust-lang.org/rustc/codegen-options/)
|
||||
- [Cargo Profiles](https://doc.rust-lang.org/cargo/reference/profiles.html)
|
||||
- [PGO Guide](https://doc.rust-lang.org/rustc/profile-guided-optimization.html)
|
||||
Reference in New Issue
Block a user