Developer Setup¶

Concise instructions to build, test, and develop YAMS locally.

Supported Platforms¶

Platform	Architecture	Status
Linux	x86_64, arm64	Primary
macOS	Apple Silicon, x86_64	Primary
Windows	x86_64	Supported

Prerequisites¶

See ../BUILD.md#prerequisites for compilers, build tools, and system package installs.

Initialize Conan (one-time)¶

conan profile detect --force

Quick Start¶

Linux/macOS¶

# Release build
./setup.sh Release
meson compile -C build/release

# Debug build (includes tests)
./setup.sh Debug
meson compile -C builddir

Windows¶

# Release build
./setup.ps1 Release
meson compile -C build/release

# Debug build (includes tests)
./setup.ps1 Debug
meson compile -C builddir

For manual (Conan + Meson) commands, see ../BUILD.md.

Build Options¶

For the full list of build variables and Meson options, see ../BUILD.md#build-options.

Developer convenience variables¶

Variable	Default	Description
`YAMS_ONNX_GPU`	auto	GPU provider: `auto`, `cuda`, `coreml`, `directml`, `none`
`FAST_MODE`	0	Disable ONNX and tests for quick iteration

Common post-setup tweak:

meson configure builddir -Dbuild-tests=true

Testing¶

# Build with tests
./setup.sh Debug
meson configure builddir -Dbuild-tests=true
meson compile -C builddir

# Run all tests
meson test -C builddir --print-errorlogs

# Run specific suites
meson test -C builddir --suite unit:smoke      # Quick smoke tests
meson test -C builddir --suite unit            # All unit tests
meson test -C builddir --suite integration     # Integration tests

Developer Loop¶

# Edit code, then rebuild (incremental)
meson compile -C builddir

# Smoke test CLI
./builddir/tools/yams-cli/yams --version

# Use temporary data directory
mkdir -p /tmp/yams-dev && export YAMS_STORAGE=/tmp/yams-dev
yams init --non-interactive
echo "test" | yams add - --tags test
yams search test

Sanitizers (Debug)¶

CFLAGS='-fsanitize=address,undefined' CXXFLAGS='-fsanitize=address,undefined' \
  meson setup builddir --reconfigure
meson compile -C builddir
meson test -C builddir

Static Analysis and Formatting¶

# clang-format
find src include -name '*.[ch]pp' -o -name '*.cc' -o -name '*.hh' | xargs clang-format -i

# clang-tidy (integrate via editor or invoke directly)

CCache (optional)¶

Speed up rebuilds:

# Install
brew install ccache  # macOS
sudo apt install ccache  # Ubuntu

# Export wrappers
export CC="ccache gcc"
export CXX="ccache g++"

Docker (optional)¶

# Quick CLI check
docker run --rm -it ghcr.io/trvon/yams:latest --version

# Persistent data
mkdir -p $HOME/yams-data
docker run --rm -it -v $HOME/yams-data:/var/lib/yams ghcr.io/trvon/yams:latest yams init --non-interactive

GPU Acceleration¶

The ONNX plugin supports GPU acceleration for embedding generation. GPU support is auto-detected during build based on platform and available hardware.

Supported Providers¶

Platform	Provider	Hardware	Detection
macOS	CoreML	Apple Neural Engine + GPU	Always enabled (built into ONNX Runtime)
Linux	CUDA	NVIDIA GPUs	Detected via `nvidia-smi`
Windows	DirectML	Any DirectX 12 GPU	Detected via Win32 API
Windows	CUDA	NVIDIA GPUs	Preferred over DirectML if detected

Build Configuration¶

# Auto-detect (default) - recommended
./setup.sh Release

# Force specific provider
YAMS_ONNX_GPU=cuda ./setup.sh Release      # NVIDIA CUDA
YAMS_ONNX_GPU=coreml ./setup.sh Release    # macOS CoreML
YAMS_ONNX_GPU=directml ./setup.ps1         # Windows DirectML

# Disable GPU (CPU-only)
YAMS_ONNX_GPU=none ./setup.sh Release

Runtime Configuration¶

GPU is used automatically when the plugin loads. To enable/disable at runtime:

# ~/.config/yams/config.toml
[embeddings]
enable_gpu = true   # Use GPU if available (default)
# enable_gpu = false  # Force CPU-only

Prerequisites¶

CUDA (Linux/Windows): - NVIDIA GPU with CUDA Compute Capability 5.0+ - CUDA Toolkit 11.8+ and cuDNN 8.6+ - Driver version 525.60+

DirectML (Windows): - Any DirectX 12 capable GPU (no additional drivers needed)

CoreML (macOS): - macOS 11+ (Big Sur or later) - No additional setup required; Neural Engine used on Apple Silicon

Verification¶

# Check build configuration
yams plugin health

# Check ONNX provider in logs
yams daemon log | grep -i "execution provider"
# Should show: "[ONNX] CoreML execution provider enabled" or similar

Troubleshooting¶

Symptom	Fix
Missing native file	Re-run Conan install
Link errors after dep change	Delete builddir and reconfigure
Tests not found	Ensure `-Dbuild-tests=true` and recompile
qpdf: “recompile with -fPIC”	`conan remove 'qpdf/*' -c` then re-setup
Clang: “cannot find -lstdc++”	Install libstdc++ or use `YAMS_COMPILER=gcc`
Windows: Boost build failures	Install v143 toolset, clean cache
Windows: Missing recipes	Export qpdf and onnxruntime recipes

Notes¶

Use Release for benchmarking; Debug + sanitizers for development
Keep build trees out of version control
mediainfo/libmediainfo-dev enables richer video metadata
Provide exact versions and commands when filing issues