wifi-densepose/vendor/ruvector/crates/ruvector-postgres/docs/BUILD.md

Build System Documentation

This document describes the build system for the ruvector-postgres extension.

Overview

The build system supports multiple PostgreSQL versions (14-17), various SIMD optimizations, and optional features like different index types and quantization methods.

Prerequisites

• Rust 1.75 or later
• PostgreSQL 14, 15, 16, or 17
• cargo-pgrx 0.12.0
• Build essentials (gcc, make, etc.)

Quick Start

Using Make (Recommended)

# Build for PostgreSQL 16 (default)
make build

# Build with all features
make build-all

# Build with native CPU optimizations
make build-native

# Run tests
make test

# Install extension
make install

Using Cargo

# Build for PostgreSQL 16
cargo pgrx package --features pg16

# Build with specific features
cargo pgrx package --features pg16,index-all,quant-all

# Run tests
cargo pgrx test pg16

Build Features

PostgreSQL Versions

Choose one PostgreSQL version feature:

• pg14 - PostgreSQL 14
• pg15 - PostgreSQL 15
• pg16 - PostgreSQL 16 (default)
• pg17 - PostgreSQL 17

Example:

make build PGVER=15

SIMD Optimizations

SIMD features for performance optimization:

• simd-native - Use native CPU features (auto-detected at build time)
• simd-avx512 - Enable AVX-512 instructions
• simd-avx2 - Enable AVX2 instructions
• simd-neon - Enable ARM NEON instructions
• simd-auto - Runtime auto-detection (default)

Example:

# Build with native CPU optimizations
make build-native

# Build with specific SIMD
cargo build --features pg16,simd-avx512 --release

Index Types

• index-hnsw - HNSW (Hierarchical Navigable Small World) index
• index-ivfflat - IVFFlat (Inverted File with Flat compression) index
• index-all - Enable all index types

Example:

make build INDEX_ALL=1

Quantization Methods

• quantization-scalar - Scalar quantization
• quantization-product - Product quantization
• quantization-binary - Binary quantization
• quantization-all - Enable all quantization methods
• quant-all - Alias for quantization-all

Example:

make build QUANT_ALL=1

Optional Features

• hybrid-search - Hybrid search capabilities
• filtered-search - Filtered search support
• neon-compat - Neon-specific optimizations

Build Modes

Debug Mode

make build BUILD_MODE=debug

Debug builds include:

• Debug symbols
• Assertions enabled
• No optimizations
• Faster compile times

Release Mode (Default)

make build BUILD_MODE=release

Release builds include:

• Full optimizations
• No debug symbols
• Smaller binary size
• Better performance

Build Script (build.rs)

The build.rs script automatically:

1. Detects CPU features at build time
2. Configures SIMD optimizations based on target architecture
3. Prints feature status during compilation
4. Sets up PostgreSQL paths from environment

CPU Feature Detection

For x86_64 systems:

• Checks for AVX-512, AVX2, and SSE4.2 support
• Enables appropriate compiler flags
• Prints build configuration

For ARM systems:

• Enables NEON support on AArch64
• Configures appropriate SIMD features

Native Optimization

When building with simd-native, the build script adds:

RUSTFLAGS=-C target-cpu=native

This enables all CPU features available on the build machine.

Makefile Targets

Build Targets

• make build - Build for default PostgreSQL version
• make build-all - Build with all features enabled
• make build-native - Build with native CPU optimizations
• make package - Create distributable package

Test Targets

• make test - Run tests for current PostgreSQL version
• make test-all - Run tests for all PostgreSQL versions
• make bench - Run all benchmarks
• make bench-<name> - Run specific benchmark

Development Targets

• make dev - Start development server
• make pgrx-init - Initialize pgrx (first-time setup)
• make pgrx-start - Start PostgreSQL for development
• make pgrx-stop - Stop PostgreSQL
• make pgrx-connect - Connect to development database

Quality Targets

• make check - Run cargo check
• make clippy - Run clippy linter
• make fmt - Format code
• make fmt-check - Check code formatting

Other Targets

• make clean - Clean build artifacts
• make doc - Generate documentation
• make config - Show current configuration
• make help - Show all available targets

Configuration Variables

PostgreSQL Configuration

# Specify pg_config path
make build PG_CONFIG=/usr/pgsql-16/bin/pg_config

# Set PostgreSQL version
make test PGVER=15

# Set installation prefix
make install PREFIX=/opt/postgresql

Build Configuration

# Enable features via environment
make build SIMD_NATIVE=1 INDEX_ALL=1 QUANT_ALL=1

# Change build mode
make build BUILD_MODE=debug

# Combine options
make test PGVER=16 BUILD_MODE=release QUANT_ALL=1

CI/CD Integration

The GitHub Actions workflow (postgres-extension-ci.yml) provides:

Test Matrix

• Tests on Ubuntu and macOS
• PostgreSQL versions 14, 15, 16, 17
• Stable Rust toolchain

Build Steps

1. Install PostgreSQL and development headers
2. Set up Rust toolchain with caching
3. Install and initialize cargo-pgrx
4. Run formatting and linting checks
5. Build extension
6. Run tests
7. Package artifacts

Additional Checks

• Security audit with cargo-audit
• Benchmark comparison on pull requests
• Integration tests with Docker
• Package creation for releases

Docker Build

Building Docker Image

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

Multi-stage Build

The Dockerfile uses multi-stage builds:

1. Builder stage: Compiles extension with all features
2. Runtime stage: Creates minimal PostgreSQL image with extension

Docker Features

• Based on official PostgreSQL 16 image
• Extension pre-installed and ready to use
• Automatic extension creation on startup
• Health checks configured
• Optimized layer caching

Troubleshooting

Common Issues

Issue: pg_config not found

# Solution: Set PG_CONFIG
export PG_CONFIG=/usr/lib/postgresql/16/bin/pg_config
make build

Issue: cargo-pgrx not installed

# Solution: Install cargo-pgrx
cargo install cargo-pgrx --version 0.12.0 --locked

Issue: pgrx not initialized

# Solution: Initialize pgrx
make pgrx-init

Issue: Build fails with SIMD errors

# Solution: Build without SIMD optimizations
cargo build --features pg16 --release

Debug Build Issues

Enable verbose output:

cargo build --features pg16 --release --verbose

Check build configuration:

make config

Test Failures

Run tests with output:

cargo pgrx test pg16 -- --nocapture

Run specific test:

cargo test --features pg16 test_name

Performance Optimization

Compile-time Optimizations

# Native CPU features
make build-native

# Link-time optimization (slower build, faster runtime)
RUSTFLAGS="-C lto=fat" make build

# Combine optimizations
RUSTFLAGS="-C target-cpu=native -C lto=fat" make build

Profile-guided Optimization (PGO)

# 1. Build with instrumentation
RUSTFLAGS="-C profile-generate=/tmp/pgo-data" make build

# 2. Run benchmarks to collect profiles
make bench

# 3. Build with profile data
RUSTFLAGS="-C profile-use=/tmp/pgo-data" make build

Cross-compilation

For ARM64

# Add target
rustup target add aarch64-unknown-linux-gnu

# Build
cargo build --target aarch64-unknown-linux-gnu \
  --features pg16,simd-neon \
  --release

For Different PostgreSQL Versions

# Build for all versions
for pgver in 14 15 16 17; do
  make build PGVER=$pgver
done

Distribution

Creating Packages

# Create package for distribution
make package

# Package location
ls target/release/ruvector-postgres-pg16/

Installation from Package

# Copy files
sudo cp target/release/ruvector-postgres-pg16/usr/lib/postgresql/16/lib/*.so \
  /usr/lib/postgresql/16/lib/
sudo cp target/release/ruvector-postgres-pg16/usr/share/postgresql/16/extension/* \
  /usr/share/postgresql/16/extension/

# Verify installation
psql -c "CREATE EXTENSION ruvector;"

References

• pgrx Documentation
• PostgreSQL Extension Building
• Rust Performance Book