Developer Setup¶

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

Supported platforms¶

macOS 12+ (Apple Silicon and x86_64)
Linux x86_64 (glibc-based)
Windows is not a primary target for development (WSL2 recommended)

Prerequisites¶

Git
C++ compiler: Clang 14+ or GCC 11+
Meson 1.4+ and Ninja
Python 3.8+ and pip (for Conan)
Conan 2.x (package/dependency manager)

Install examples: - macOS (Homebrew) - brew install meson ninja python - pip3 install –upgrade conan - xcode-select –install (ensure Command Line Tools present) - Ubuntu/Debian - sudo apt-get update - sudo apt-get install -y build-essential meson ninja-build python3-pip - pip3 install –upgrade conan - Fedora - sudo dnf groupinstall -y “Development Tools” - sudo dnf install -y meson ninja-build python3-pip - pip3 install –upgrade conan

Initialize Conan profile (one-time):

conan profile detect --force

Quick start¶

Using setup script (recommended):

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

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

Manual Conan + Meson:

# 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

See setup.sh for environment variables (compiler override, C++ standard, cross-compilation, etc.).

Fast Mode¶

For quicker iteration (disables ONNX plugin/features & tests):

FAST_MODE=1 meson setup build/debug --reconfigure \
  --native-file build/debug/build-debug/conan/conan_meson_native.ini

or set FAST_MODE=1 in CI (SourceHut manifest already respects it).

Overriding Display Version¶

Inject a runtime/display version distinct from the static project version:

meson setup build/release --reconfigure \
  -Dyams-version="$(git describe --tags --always)" \
  --native-file build/release/build-release/conan/conan_meson_native.ini

The generated header yams/version_generated.h provides YAMS_EFFECTIVE_VERSION, git describe, and build timestamp.

Run tests (Meson)¶

In Debug builds, tests are now enabled by default. For Release builds, pass -Dbuild-tests=true if you want to build tests.

meson compile -C build/debug
meson test -C build/debug                 # all suites
meson test -C build/debug -t unit         # unit only
meson test -C build/debug -t integration  # integration only

You can enable tests for Release builds by configuring that build dir with -Dbuild-tests=true.

Strict local builds (warnings-as-errors)¶

To stabilize warnings locally without blocking CI, use the helper script (strict by default):

# Debug strict build (no tests compiled or run)
bash scripts/dev/tidy_build.sh --no-test

# If you already ran `conan install` and want to skip it:
bash scripts/dev/tidy_build.sh --no-conan --no-test

# Release strict build
bash scripts/dev/tidy_build.sh --release --no-test

# Disable strict (temporarily)
bash scripts/dev/tidy_build.sh --no-strict --no-test

Notes: - CI remains non-strict for now; strict gating will be enabled once local builds are clean (see PBI 027). - The script auto-detects the Conan Meson native file location.

Developer loop¶

Edit code
Rebuild (incremental):
cmake –build –preset yams-debug -j
Smoke test CLI (example):
./yams –version (from install location) or from the built binary path inside the build tree
Use a temporary data directory while developing:
mkdir -p /tmp/yams-dev && export YAMS_STORAGE=/tmp/yams-dev
yams init –non-interactive
echo “dev” | yams add - –tags dev
yams search dev

If YAMS_STORAGE is not supported in your version, run yams from a working directory you control (see docs for configuration and default paths).

Address/UB Sanitizers (Debug)¶

You can inject sanitizer flags via environment or Meson options if/when exposed. Example with environment flags:

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

If dedicated Meson options are added later, prefer those over raw flags.

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 your editor or invoke directly on changed files. Adjust targets/paths to your repository layout. If a .clang-format exists at repo root, it will be used.

CCache (optional)¶

Speed up rebuilds: - Install ccache (brew install ccache or apt/dnf install ccache) - Export CC/CXX wrappers or configure via CMake toolchain/profile as preferred

Docker (optional)¶

Use the published image for quick CLI checks or isolation:

docker run --rm -it ghcr.io/trvon/yams:latest --version

Bind mount a host directory to persist 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

Documentation (MkDocs)¶

If you need to preview docs locally:

# Requires Python 3 and mkdocs-material
pip3 install mkdocs mkdocs-material
mkdocs serve -f yams/mkdocs.yml

Troubleshooting¶

Compiler/toolchain not found: verify conan profile detect and PATH for meson/ninja.
Link errors/missing deps: re-run conan install with --build=missing; clean the build folder if needed.
Tests not found: ensure you configured with -Dbuild-tests=true and recompiled; list tests with meson test -C build/debug -l.
Install prefix: use meson install -C build/<dir> and Meson install options as needed.

Notes¶

Use Release for benchmarking and production builds; Debug + sanitizers for local development.
Keep your build trees (build/debug, build/release) out of version control.
mediainfo + libmediainfo-dev (or distro equivalent) enables richer video metadata (YAMS_HAVE_MEDIAINFO).
ffprobe (from FFmpeg) similarly enables YAMS_HAVE_FFPROBE; either tool enables video handler compilation.
Provide exact compiler/Meson/Conan versions and commands you ran when filing issues for fast triage.