yams/docs/developer/setup.md

Developer Quick Start (Minimal)

A concise guide to get you building, running, and verifying YAMS quickly.

Requirements

• C++20 compiler (Clang 14+/GCC 11+/MSVC 2022)
• CMake 3.20+
• Git
• OpenSSL 3.x headers/libs
• SQLite3 headers/libs
• Optional (recommended): Protocol Buffers 3.x (headers/libs)
• Optional (for docs/manpages + embedded verbose --help): Pandoc

Platform setup examples:

• macOS: brew install cmake openssl@3 sqlite3 protobuf pandoc and export OPENSSL_ROOT_DIR="$(brew --prefix openssl@3)"
• Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y build-essential cmake git libssl-dev libsqlite3-dev protobuf-compiler pandoc
• Fedora: sudo dnf install -y cmake gcc-c++ git openssl-devel sqlite-devel protobuf-compiler pandoc

TL;DR

# Clone
git clone https://github.com/trvon/yams.git
cd yams

# Configure (Development profile: tests, debug info, docs)
cmake -S . -B build \
  -DYAMS_BUILD_PROFILE=dev \
  -DYAMS_BUILD_DOCS=ON

# Build
cmake --build build -j

# Test (if enabled by profile)
ctest --test-dir build --output-on-failure

# (Optional) Install to a local prefix
cmake --install build --prefix "$PWD/.local"

# Initialize storage (after adding .local/bin to PATH)
export PATH="$PWD/.local/bin:$PATH"
yams init --non-interactive

# Verify
yams --version
yams --help
yams --help-all
yams search "test" --limit 1

Build Profiles

• -DYAMS_BUILD_PROFILE=release
  • Lean build focused on runtime; CLI + MCP server on; tests off
• -DYAMS_BUILD_PROFILE=dev (recommended while developing)
  • CLI, MCP server, tests, benchmarks ON; Debug/RelWithDebInfo; sanitizers on in Debug
• -DYAMS_BUILD_PROFILE=custom
  • Mix your own flags (see common options below)

Common CMake Options

• -DYAMS_BUILD_CLI=ON|OFF Build CLI tools
• -DYAMS_BUILD_MCP_SERVER=ON|OFF Build MCP server
• -DYAMS_BUILD_TESTS=ON|OFF Unit/integration tests
• -DYAMS_BUILD_BENCHMARKS=ON|OFF Benchmarks
• -DYAMS_ENABLE_SANITIZERS=ON|OFF ASan/UBSan in Debug
• -DYAMS_ENABLE_COVERAGE=ON|OFF Coverage instrumentation
• -DYAMS_BUILD_DOCS=ON|OFF Generate manpages and embed verbose --help
• -DYAMS_VERSION=MAJOR.MINOR.PATCH Override tag‑derived version

Tip: Prefer generator‑agnostic usage:

cmake -S . -B build -DYAMS_BUILD_PROFILE=dev
cmake --build build -j

Docs & Manpages (Optional)

• If YAMS_BUILD_DOCS=ON and Pandoc is installed:
  • Generates yams(1) manpage at install
  • Embeds verbose help into the CLI for:
    • yams --help-all
    • yams --help --verbose
    • yams <command> --help --verbose
• If Pandoc is missing, build proceeds; verbose help falls back with a clear note.

Run From Build or Install

• From install prefix:
  • Add bin to PATH: export PATH="$PREFIX/bin:$PATH"
  • Then yams ...
• From build tree (if your generator places executables there):
  • ./build/<subdir>/yams ...
  • Or install to a staging prefix (recommended): cmake --install build --prefix "$PWD/.local" and use PATH as above.

Storage & Config (XDG‑aligned)

Defaults:

• Data: $XDG_DATA_HOME/yams or ~/.local/share/yams
• Config: $XDG_CONFIG_HOME/yams or ~/.config/yams

Override:

• --storage <path> or export YAMS_STORAGE="<path>"

Initialize:

yams init --non-interactive

Troubleshooting (Fast)

• OpenSSL not found (macOS):
  • export OPENSSL_ROOT_DIR="$(brew --prefix openssl@3)"
• Reconfigure clean:
  • rm -rf build && cmake -S . -B build ...
• Manpages/verbose help missing:
  • Ensure Pandoc is installed and -DYAMS_BUILD_DOCS=ON, reconfigure, rebuild
• Permissions:
  • Ensure your chosen --storage path is user‑writable (avoid sudo at runtime)

Next Steps

• CLI Reference: docs/user_guide/cli.md
• Search guides: docs/user_guide/search_guide.md, docs/user_guide/vector_search_guide.md
• Admin/config: docs/admin/configuration.md
• Manpage (if built): man yams