Skip to content

Building YAMS with GCC or Clang

Quick reference for building YAMS with either GCC or Clang toolchains.

Quick Start

Recommended: Use the setup.sh script (auto-detects compiler, handles Conan + Meson):

# Release build (default: Clang if available, else GCC)
./setup.sh Release

# Debug build with tests
./setup.sh Debug

# Force specific compiler
YAMS_COMPILER=gcc ./setup.sh Release
YAMS_COMPILER=clang ./setup.sh Release

Then compile: 

meson compile -C build/release  # or builddir for Debug

Prerequisites

Compiler (choose one): - GCC 13+ (recommended) or GCC 11+ (C++20 minimum) - Clang 16+ (recommended) or Clang 14+ (C++20 minimum)

Build tools: 

# Ubuntu/Debian
sudo apt-get install -y build-essential cmake meson ninja-build pkg-config

# Optional but recommended for faster builds
sudo apt-get install -y ccache lld clang clang-tidy

System dependencies: 

# Ubuntu/Debian
sudo apt-get install -y libssl-dev libcurl4-openssl-dev libsqlite3-dev \
    protobuf-compiler libprotobuf-dev zlib1g-dev

# Fedora
sudo dnf install -y openssl-devel libcurl-devel sqlite-devel protobuf-devel zlib-devel

# Arch
sudo pacman -S openssl curl sqlite protobuf zlib

Conan: 

pip install conan
conan profile detect --force

Manual Build (without setup.sh)

GCC

conan install . -of build/release -s build_type=Release \
  -s compiler.cppstd=20 -b missing --build=qpdf/*
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

Clang

conan install . -of build/release -s build_type=Release \
  -s compiler=clang -s compiler.version=18 -s compiler.libcxx=libstdc++11 \
  -s compiler.cppstd=20 -b missing --build=qpdf/*
CC=clang CXX=clang++ 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

Note: Clang automatically uses LLD linker if available (faster linking).

Common Options

Enable tests: 

./setup.sh Debug
meson configure builddir -Dbuild-tests=true
meson test -C builddir

Disable optional features: 

YAMS_DISABLE_ONNX=true ./setup.sh Release
YAMS_DISABLE_PDF=true ./setup.sh Release
YAMS_DISABLE_SYMBOL_EXTRACTION=true ./setup.sh Release

Code coverage: 

./setup.sh Debug --coverage
meson test -C builddir
gcovr --html --html-details -o builddir/coverage.html

libc++ hardening (Clang only): 

YAMS_LIBCXX_HARDENING=fast ./setup.sh Debug    # ~5% overhead, recommended
YAMS_LIBCXX_HARDENING=extensive ./setup.sh Debug  # ~10-20% overhead

Troubleshooting

qpdf linking error: “recompile with -fPIC”

Error: 

/usr/bin/ld: libqpdf.a(...): relocation R_X86_64_PC32 against symbol `...` can not be used when making a shared object; recompile with -fPIC

Cause: Cached qpdf package was built without -fPIC (required for plugins).

Fix: 

# Remove cached qpdf packages
conan remove 'qpdf/*' -c

# Rebuild with forced qpdf rebuild
./setup.sh Release
# or manually:
conan install . -of build/release -s build_type=Release \
  -s compiler.cppstd=20 -b missing --build=qpdf/*

Clang: “cannot find -lstdc++”

Error: 

/usr/bin/ld: cannot find -lstdc++: No such file or directory

Cause: Clang trying to use libstdc++ but missing development files.

Fix (choose one):

  1. Switch to GCC: 

    YAMS_COMPILER=gcc ./setup.sh Release

  2. Use Clang’s libc++ instead: 

    sudo apt-get install libc++-dev libc++abi-dev
# Edit ~/.conan2/profiles/default:
# Change: compiler.libcxx=libstdc++11 → compiler.libcxx=libc++

  3. Install libstdc++ dev files: 

    sudo apt-get install libstdc++-13-dev

See: Conan Profiles

Missing dependencies

pkg-config errors: 

pkg-config --list-all | grep -E "(sqlite|openssl|protobuf|libcurl)"

If missing, install development packages (see Prerequisites).

Old compiler version

GCC < 11 or Clang < 14:

Upgrade your compiler: 

# Ubuntu
sudo apt-get install gcc-13 g++-13 clang-18

# Update alternatives (optional)
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-13 100

ONNX disabled

Check configure output for “ONNX Runtime found”. If disabled:

# Enable in build
./setup.sh Release  # ONNX enabled by default

# Or explicitly
conan install . -of build/release -s build_type=Release \
  -o yams/*:enable_onnx=True -b missing

Compiler Comparison

Feature GCC 13+ Clang 16+
C++20 coroutines ✓ ✓
std::format ✓ ✓
Default linker GNU ld LLD (faster)
Hardening -D_GLIBCXX_DEBUG libc++ modes
Diagnostics Good Better

Both work equally well. Clang + LLD gives faster link times.

Advanced

Custom C++ standard: 

# C++20 (default, widely supported)
YAMS_CPPSTD=20 ./setup.sh Release

# C++23 (optional, for constexpr containers - requires GCC 13+ or Clang 16+)
YAMS_CPPSTD=23 ./setup.sh Release

Note: YAMS detects C++23 features at compile-time via cpp23_features.hpp and uses them when available. C++20 is the baseline requirement.

Custom install prefix: 

YAMS_INSTALL_PREFIX=/opt/yams ./setup.sh Release

LTO (Link Time Optimization): 

# GCC
CC=gcc CXX=g++ CXXFLAGS="-flto" LDFLAGS="-flto" ./setup.sh Release

# Clang (ThinLTO)
CC=clang CXX=clang++ CXXFLAGS="-flto=thin" LDFLAGS="-flto=thin" ./setup.sh Release

Machine-specific optimizations: 

CXXFLAGS="-march=native -mtune=native" ./setup.sh Release
⚠️ Binary won’t be portable to other CPUs.

Verification

# Check version
./build/release/tools/yams-cli/yams --version

# Quick test
echo "Hello, YAMS!" | ./build/release/tools/yams-cli/yams add -

# After install
yams --version

References