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

Compilers

Platform	Compiler	Minimum	Recommended
Linux/macOS	GCC	11+	13+
Linux/macOS	Clang	14+	16+
Windows	MSVC	193 (VS 2022)	194+ (VS 2022 17.10+)

All require C++20 support.

Build Tools

Tool	Required	Install
Meson	Yes	pip install meson
Ninja	Yes	pip install ninja
Conan	Yes	pip install conan
CMake	Yes	Package manager
pkg-config	Linux/macOS	Package manager

System Libraries

Ubuntu/Debian:

sudo apt-get install -y build-essential cmake meson ninja-build pkg-config \
    libssl-dev libcurl4-openssl-dev libsqlite3-dev \
    protobuf-compiler libprotobuf-dev zlib1g-dev

Fedora:

sudo dnf install -y gcc-c++ cmake meson ninja-build pkg-config \
    openssl-devel libcurl-devel sqlite-devel protobuf-devel zlib-devel

macOS:

brew install cmake meson ninja pkg-config openssl sqlite protobuf

Windows: - Visual Studio 2022 with “Desktop development with C++” workload - Python 3.10+ (for Conan, Meson) - CMake 3.23+

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

Manual Build

GCC/Clang (Linux/macOS)

# Release
conan install . -of build/release -s build_type=Release -b missing
meson setup build/release \
  --prefix /usr/local \
  --native-file build/release/build-release/conan/conan_meson_native.ini \
  --buildtype=release
meson compile -C build/release

# Debug
conan install . -of build/debug -s build_type=Debug -b missing
meson setup build/debug \
  --prefix /usr/local \
  --native-file build/debug/build-debug/conan/conan_meson_native.ini \
  --buildtype=debug
meson compile -C build/debug

MSVC (Windows)

# Export local Conan recipes (required once)
conan export conan/qpdf --name=qpdf --version=11.9.0
conan export conan/onnxruntime --name=onnxruntime --version=1.23.2

# Release
conan install . -of build\release `
  -pr:h conan/profiles/host-windows-msvc -pr:b default `
  -s build_type=Release --build=missing

meson setup build\release `
  --native-file build\release\build-release\conan\conan_meson_native.ini `
  --buildtype=release

meson compile -C build\release

Build Options

Environment Variables

Variable	Default	Description
YAMS_COMPILER	auto	Force gcc or clang
YAMS_CPPSTD	20	C++ standard (20 or 23)
YAMS_DISABLE_ONNX	false	Disable ONNX embeddings
YAMS_DISABLE_PDF	false	Disable PDF extraction
YAMS_INSTALL_PREFIX	/usr/local	Install location
FAST_MODE	0	Disable ONNX and tests for quick iteration

Meson Options

Option	Default	Description
build-cli	true	Build CLI binary
build-mcp-server	true	Build MCP server
build-tests	false	Build test suite
enable-pdf	enabled	PDF extraction plugin
enable-onnx	enabled	ONNX embedding models

Configure after setup:

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

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