Building YAMS¶
Cross-platform build guide for Linux, macOS, and Windows.
Quick Start¶
Linux/macOS¶
# Portable optimized build (`-O2 -g`, `NDEBUG`)
./setup.sh Release
meson compile -C build/release
Windows¶
./setup.ps1 Release
meson compile -C build/release
Prerequisites¶
Compilers¶
| Platform | Compiler | Minimum | Recommended |
|---|---|---|---|
| Linux/macOS | GCC | 11+ | 13+ |
| Linux/macOS | Clang | 14+ | 16+ |
| Windows | MSVC | 193 (VS 2022) | 193+ |
All require C++20 support.
Build Tools¶
| Tool | Required | Install |
|---|---|---|
| Meson | Yes | pip install meson |
| Ninja | Yes | pip install ninja |
| Conan | Default path only | 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+
Build Options¶
Setup Script Options¶
| Variable | Default | Description |
|---|---|---|
YAMS_OFFLINE |
false | Disable network dependency resolution; use only local Conan cache and local sources |
YAMS_USE_SYSTEM_DEPS |
false | Skip Conan and resolve dependencies from system/pkg-config/CMake paths |
YAMS_COMPILER |
auto | Force gcc or clang |
YAMS_CPPSTD |
20 | C++ standard (20 or 23) |
YAMS_DISABLE_ONNX |
false | Disable ONNX embeddings |
YAMS_DISABLE_SYMBOL_EXTRACTION |
false | Disable Tree-sitter symbol extraction |
YAMS_INSTALL_PREFIX |
/usr/local | Install location |
YAMS_PKG_CONFIG_PATH |
unset | Extra host pkg-config search path passed to Meson |
YAMS_BUILD_PKG_CONFIG_PATH |
unset | Extra build-machine pkg-config path for cross-build tools |
YAMS_CMAKE_PREFIX_PATH |
unset | Extra host CMake prefix path passed to Meson |
YAMS_BUILD_CMAKE_PREFIX_PATH |
unset | Extra build-machine CMake prefix path for cross-build tools |
YAMS_MESON_NATIVE_FILE |
unset | Use this Meson native file instead of Conan-generated metadata |
YAMS_MESON_CROSS_FILE |
unset | Use this Meson cross file instead of Conan-generated metadata |
SOURCE_DATE_EPOCH |
unset | If set, YAMS uses this timestamp for reproducible build metadata |
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-onnx |
enabled | ONNX embedding models |
plugin-symbols |
true | Tree-sitter symbol extraction plugin |
Configure after setup:
meson configure builddir -Dbuild-tests=true
Manual Build¶
GCC (Linux/macOS)¶
conan install . -of build/release -s build_type=Release \
-s compiler.cppstd=20 --build=missing
meson setup build/release \
--native-file build/release/build-release/conan/conan_meson_native.ini \
--buildtype=debugoptimized \
-Db_ndebug=true
meson compile -C build/release
Clang (Linux/macOS)¶
conan install . -of build/release -s build_type=Release \
-s compiler=clang -s compiler.cppstd=20 --build=missing
CC=clang CXX=clang++ meson setup build/release \
--native-file build/release/build-release/conan/conan_meson_native.ini \
--buildtype=debugoptimized \
-Db_ndebug=true
meson compile -C build/release
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.0
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=debugoptimized `
-Db_ndebug=true
meson compile -C build\release
Offline and System Dependency Builds¶
Conan Cache Only (no network)¶
./setup.sh Release --offline
meson compile -C build/release
This mode uses Conan only from the local cache and disables Meson wrap downloads.
System Dependencies Only (no Conan)¶
YAMS_USE_SYSTEM_DEPS=true \
YAMS_OFFLINE=true \
YAMS_PKG_CONFIG_PATH=/opt/yams-deps/lib/pkgconfig \
YAMS_CMAKE_PREFIX_PATH=/opt/yams-deps \
./setup.sh Release --system-deps --offline
meson compile -C build/release
This path is intended for distro/package-manager integration, sandboxed builders, and manually staged dependency prefixes.
Direct Meson with Manual Prefixes¶
meson setup build/release \
--buildtype=debugoptimized \
-Db_ndebug=true \
--wrap-mode=nofallback \
--pkg-config-path=/opt/yams-deps/lib/pkgconfig \
--cmake-prefix-path=/opt/yams-deps
meson compile -C build/release
CMake Bootstrap¶
cmake -S . -B build/cmake-bootstrap \
-DYAMS_PROFILE=Release \
-DYAMS_OFFLINE=ON \
-DYAMS_USE_SYSTEM_DEPS=ON
cmake --build build/cmake-bootstrap
This entrypoint is a thin wrapper around the repo’s canonical Meson setup flow. It exists so integrators can start from source with CMake while keeping Meson as the maintained build graph.
System-Deps Cross Build¶
YAMS_USE_SYSTEM_DEPS=true \
YAMS_OFFLINE=true \
YAMS_MESON_CROSS_FILE=/path/to/cross.ini \
YAMS_BUILD_PKG_CONFIG_PATH=/opt/build-tools/lib/pkgconfig \
YAMS_PKG_CONFIG_PATH=/opt/target-sysroot/usr/lib/pkgconfig \
./setup.sh Release --system-deps --offline
Testing¶
# Build with tests
./setup.sh Debug
meson configure builddir -Dbuild-tests=true
meson compile -C builddir
# Run tests
meson test -C builddir --print-errorlogs
Troubleshooting¶
qpdf: “recompile with -fPIC”¶
conan remove 'qpdf/*' -c
./setup.sh Release
Clang: “cannot find -lstdc++”¶
Install libstdc++ or use libc++:
sudo apt-get install libstdc++-13-dev
# Or switch to GCC:
YAMS_COMPILER=gcc ./setup.sh Release
Windows: Boost build failures¶
Boost 1.85 requires VS 2022 toolset (v143). If using VS 2025:
1. Install v143 toolset via Visual Studio Installer → Individual Components
2. Clean cache: conan remove 'boost/*' -c
3. Re-run: ./setup.ps1 Release
Windows: Missing recipes¶
conan export conan/qpdf --name=qpdf --version=11.9.0
conan export conan/onnxruntime --name=onnxruntime --version=1.23.0
Missing dependencies¶
pkg-config --list-all | grep -E "(sqlite|openssl|protobuf)"
Install missing development packages from Prerequisites.
Compiler Comparison¶
| Feature | GCC 13+ | Clang 16+ | MSVC 193+ |
|---|---|---|---|
| C++20 coroutines | Yes | Yes | Yes |
| std::format | Yes | Yes | Yes |
| C++20 modules | Partial | Full | Full |
| Link time | Moderate | Fast (LLD) | Moderate |
| Platform | Linux, macOS | Linux, macOS | Windows |
Advanced Options¶
Code Coverage¶
./setup.sh Debug --coverage
meson test -C builddir
gcovr --html -o builddir/coverage.html
LTO (Link Time Optimization)¶
CXXFLAGS="-flto" LDFLAGS="-flto" ./setup.sh Release
Native Optimization¶
CXXFLAGS="-march=native" ./setup.sh Release
Use this only for local benchmarking. Do not ship or package binaries built with -march=native.
Verification¶
./build/release/tools/yams-cli/yams --version
echo "test" | ./build/release/tools/yams-cli/yams add - --tags test
pkg-config --modversion yams
pkg-config --libs yams