yams/docs/developer/setup.md

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+
• CMake 3.25+ (Ninja recommended)
• Python 3.8+ and pip (for Conan)
• Conan 2.x (package/dependency manager)

Install examples:

• macOS (Homebrew)
  • brew install cmake 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 cmake ninja-build python3-pip
  • pip3 install --upgrade conan
• Fedora
  • sudo dnf groupinstall -y "Development Tools"
  • sudo dnf install -y cmake ninja-build python3-pip
  • pip3 install --upgrade conan

Initialize Conan profile (one-time):

conan profile detect --force

Quick start (Release)

# From repo root
pip3 install --upgrade conan

# Resolve deps to a dedicated build folder
conan install . --output-folder=build/yams-release -s build_type=Release --build=missing

# Configure
cmake --preset yams-release

# Build
cmake --build --preset yams-release

# Install (optional; may require sudo depending on CMAKE_INSTALL_PREFIX)
sudo cmake --install build/yams-release

Debug build

conan install . --output-folder=build/yams-debug -s build_type=Debug --build=missing
cmake --preset yams-debug   # configure preset
cmake --build --preset yams-debug  # build preset

Run unit tests

Common options:

• Run tests from the configured build directory with ctest
• Show output on failures; parallelize with -j

Examples:

# Debug (single-config Ninja default layout)
ctest --preset yams-debug --output-on-failure

# Release
ctest --preset yams-release --output-on-failure

Notes:

• If your generator uses single-config (Ninja), the inner build dir path is build/yams-*/build.
• ctest will discover tests if the project enables testing (enable_testing/add_test).

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)

Build with sanitizers for faster defect discovery:

# Example via CMake cache flags (per build directory)
cmake --preset yams-debug -DYA_ENABLE_ASAN=ON -DYA_ENABLE_UBSAN=ON
cmake --build --preset yams-debug -j
# Run tests to exercise instrumented code
ctest --preset yams-debug --output-on-failure

If your project doesn’t expose YA_ENABLE_ASAN/UBSAN, you can add compile/link flags via CMAKE_FLAGS* cache entries or a toolchain overlay.

Static analysis and formatting

• clang-format:

  find src include -name '*.[ch]pp' -o -name '*.cc' -o -name '*.hh' | xargs clang-format -i
  

• clang-tidy (example invocation):

  cmake --build --preset yams-debug --target clang-tidy
  

Adjust targets/paths to your repository layout. If a .clang-format or .clang-tidy 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 compiler/cmake/ninja.
• Link errors/missing deps: re-run conan install with --build=missing; clean the build folder if needed.
• Tests not discovered: confirm enable_testing() and add_test() are present; run ctest from the correct inner build dir.
• Install prefix: set CMAKE_INSTALL_PREFIX when configuring if you don’t want system-wide install.

Notes

• Use Release for benchmarking and production builds; Debug + sanitizers for local development.
• Keep your build trees (build/yams-debug, build/yams-release) out of version control.
• File issues with exact compiler/CMake/Conan versions and commands you ran for fast triage.