Building YAMS¶
Cross-platform build guide for Linux, macOS, and Windows.
Quick Start¶
Linux/macOS¶
./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 | 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+
Build Options¶
Setup Script Options¶
| 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 |
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
Manual Build¶
GCC (Linux/macOS)¶
conan install . -of build/release -s build_type=Release \
-s compiler.cppstd=20 -b missing
meson setup build/release \
--native-file build/release/build-release/conan/conan_meson_native.ini \
--buildtype=release
meson compile -C build/release
Clang (Linux/macOS)¶
conan install . -of build/release -s build_type=Release \
-s compiler=clang -s compiler.cppstd=20 -b missing
CC=clang CXX=clang++ meson setup build/release \
--native-file build/release/build-release/conan/conan_meson_native.ini \
--buildtype=release
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.2
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
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.2
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
Note: Binary not portable to other CPUs.
Verification¶
./build/release/tools/yams-cli/yams --version
echo "test" | ./build/release/tools/yams-cli/yams add - --tags test