Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

crates/ruvector-postgres/docs/BUILD_QUICK_START.md

@@ -0,0 +1,239 @@
+# Build System Quick Start
+
+## Files Created
+
+### Core Build Files
+- **`build.rs`** - SIMD feature detection and build configuration
+- **`Makefile`** - Common build operations and shortcuts
+- **`Dockerfile`** - Multi-stage Docker build for distribution
+- **`.dockerignore`** - Docker build optimization
+
+### CI/CD
+- **`.github/workflows/postgres-extension-ci.yml`** - GitHub Actions workflow
+
+### Documentation
+- **`docs/BUILD.md`** - Comprehensive build system documentation
+- **`docs/BUILD_QUICK_START.md`** - This file
+
+## Updated Files
+- **`Cargo.toml`** - Added new features: `simd-native`, `index-all`, `quant-all`
+
+## Quick Commands
+
+### Build
+```bash
+# Basic build
+make build
+
+# All features enabled
+make build-all
+
+# Native CPU optimizations
+make build-native
+
+# Specific PostgreSQL version
+make build PGVER=15
+```
+
+### Test
+```bash
+# Test current version
+make test
+
+# Test all PostgreSQL versions
+make test-all
+
+# Run benchmarks
+make bench
+```
+
+### Install
+```bash
+# Install to default location
+make install
+
+# Install with sudo
+make install-sudo
+
+# Install to custom location
+make install PG_CONFIG=/custom/path/pg_config
+```
+
+### Development
+```bash
+# Initialize pgrx (first time only)
+make pgrx-init
+
+# Start development server
+make dev
+
+# Connect to database
+make pgrx-connect
+```
+
+### Docker
+```bash
+# Build Docker image
+docker build -t ruvector-postgres:latest \
+  -f crates/ruvector-postgres/Dockerfile .
+
+# Run container
+docker run -d \
+  -e POSTGRES_PASSWORD=postgres \
+  -p 5432:5432 \
+  ruvector-postgres:latest
+
+# Test extension
+docker exec -it <container> psql -U postgres -c "CREATE EXTENSION ruvector;"
+```
+
+## Feature Flags
+
+### SIMD Optimization
+```bash
+# Auto-detect and use native CPU features
+make build SIMD_NATIVE=1
+
+# Specific SIMD instruction set
+cargo build --features pg16,simd-avx512 --release
+```
+
+### Index Types
+```bash
+# Enable all index types (HNSW, IVFFlat)
+make build INDEX_ALL=1
+
+# Specific index
+cargo build --features pg16,index-hnsw --release
+```
+
+### Quantization
+```bash
+# Enable all quantization methods
+make build QUANT_ALL=1
+
+# Specific quantization
+cargo build --features pg16,quantization-scalar --release
+```
+
+### Combine Features
+```bash
+# Kitchen sink build
+make build-native INDEX_ALL=1 QUANT_ALL=1
+
+# Or with cargo
+cargo build --features pg16,simd-native,index-all,quant-all --release
+```
+
+## CI/CD Pipeline
+
+The GitHub Actions workflow automatically:
+
+1. **Tests** on PostgreSQL 14, 15, 16, 17
+2. **Builds** on Ubuntu and macOS
+3. **Runs** security audits
+4. **Checks** code formatting and linting
+5. **Benchmarks** on pull requests
+6. **Packages** artifacts for releases
+7. **Tests** Docker integration
+
+Triggered on:
+- Push to `main`, `develop`, or `claude/**` branches
+- Pull requests to `main` or `develop`
+- Manual workflow dispatch
+
+## Build Output
+
+### Makefile Status
+The build.rs script reports detected features:
+```
+cargo:warning=Building with SSE4.2 support
+cargo:warning=Feature Status:
+cargo:warning=  ✓ HNSW index enabled
+cargo:warning=  ✓ IVFFlat index enabled
+```
+
+### Artifacts
+Built extension is located at:
+```
+target/release/ruvector-postgres-pg16/
+├── usr/
+│   ├── lib/postgresql/16/lib/
+│   │   └── ruvector.so
+│   └── share/postgresql/16/extension/
+│       ├── ruvector.control
+│       └── ruvector--*.sql
+```
+
+## Configuration
+
+### View Current Config
+```bash
+make config
+```
+
+Output example:
+```
+Configuration:
+  PG_CONFIG:     pg_config
+  PGVER:         16
+  PREFIX:        /usr
+  PKGLIBDIR:     /usr/lib/postgresql/16/lib
+  EXTENSION_DIR: /usr/share/postgresql/16/extension
+  BUILD_MODE:    release
+  FEATURES:      pg16
+  CARGO_FLAGS:   --features pg16 --release
+```
+
+## Troubleshooting
+
+### pg_config not found
+```bash
+# Set PG_CONFIG environment variable
+export PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config
+make build
+```
+
+### cargo-pgrx not installed
+```bash
+cargo install cargo-pgrx --version 0.12.0 --locked
+```
+
+### pgrx not initialized
+```bash
+make pgrx-init
+```
+
+### Permission denied during install
+```bash
+make install-sudo
+```
+
+## Performance Tips
+
+### Maximum Performance Build
+```bash
+# Native CPU + LTO + All optimizations
+RUSTFLAGS="-C target-cpu=native -C lto=fat" \
+  make build INDEX_ALL=1 QUANT_ALL=1
+```
+
+### Faster Development Builds
+```bash
+# Debug mode for faster compilation
+make build BUILD_MODE=debug
+```
+
+## Next Steps
+
+1. Read full documentation: `docs/BUILD.md`
+2. Run tests: `make test`
+3. Try Docker: Build and run containerized version
+4. Benchmark: `make bench` to measure performance
+5. Install: `make install` to deploy extension
+
+## Support
+
+- Build Issues: Check `docs/BUILD.md` troubleshooting section
+- Feature Requests: Open GitHub issue
+- CI/CD: Review `.github/workflows/postgres-extension-ci.yml`