wifi-densepose/crates/ruvector-postgres/docs/BUILD_QUICK_START.md

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

# Basic build
make build

# All features enabled
make build-all

# Native CPU optimizations
make build-native

# Specific PostgreSQL version
make build PGVER=15

Test

# Test current version
make test

# Test all PostgreSQL versions
make test-all

# Run benchmarks
make bench

Install

# 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

# Initialize pgrx (first time only)
make pgrx-init

# Start development server
make dev

# Connect to database
make pgrx-connect

Docker

# 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

# 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

# Enable all index types (HNSW, IVFFlat)
make build INDEX_ALL=1

# Specific index
cargo build --features pg16,index-hnsw --release

Quantization

# Enable all quantization methods
make build QUANT_ALL=1

# Specific quantization
cargo build --features pg16,quantization-scalar --release

Combine Features

# 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

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

# Set PG_CONFIG environment variable
export PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config
make build

cargo-pgrx not installed

cargo install cargo-pgrx --version 0.12.0 --locked

pgrx not initialized

make pgrx-init

Permission denied during install

make install-sudo

Performance Tips

Maximum Performance Build

# Native CPU + LTO + All optimizations
RUSTFLAGS="-C target-cpu=native -C lto=fat" \
  make build INDEX_ALL=1 QUANT_ALL=1

Faster Development Builds

# 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