# Developer Setup

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

## Supported Platforms

| Platform | Architecture | Status |
|----------|--------------|--------|
| Linux | x86_64, arm64 | Primary |
| macOS | Apple Silicon, x86_64 | Primary |
| Windows | x86_64 | Supported |

## Prerequisites

### Compilers

| Platform | Compiler | Minimum | Recommended |
|----------|----------|---------|-------------|
| Linux/macOS | GCC | 11+ | 13+ |
| Linux/macOS | Clang | 14+ | 16+ |
| Windows | MSVC | 193 (VS 2022) | 194+ (VS 2022 17.10+) |

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:**
```bash
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:**
```bash
sudo dnf install -y gcc-c++ cmake meson ninja-build pkg-config \
    openssl-devel libcurl-devel sqlite-devel protobuf-devel zlib-devel
```

**macOS:**
```bash
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+

### Initialize Conan (one-time)

```bash
conan profile detect --force
```

## Quick Start

### Linux/macOS

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

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

### Windows

```pwsh
# Release build
./setup.ps1 Release
meson compile -C build/release

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

## Manual Build

### GCC/Clang (Linux/macOS)

```bash
# 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
```

### MSVC (Windows)

```pwsh
# 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

# Release
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
```

## Build Options

### Environment Variables

| 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 |
| `FAST_MODE` | 0 | Disable ONNX and tests for quick iteration |

### 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:
```bash
meson configure builddir -Dbuild-tests=true
```

## Testing

```bash
# Build with tests
./setup.sh Debug
meson configure builddir -Dbuild-tests=true
meson compile -C builddir

# Run all tests
meson test -C builddir --print-errorlogs

# Run specific suites
meson test -C builddir --suite unit:smoke      # Quick smoke tests
meson test -C builddir --suite unit            # All unit tests
meson test -C builddir --suite integration     # Integration tests
```

## Developer Loop

```bash
# Edit code, then rebuild (incremental)
meson compile -C builddir

# Smoke test CLI
./builddir/tools/yams-cli/yams --version

# Use temporary data directory
mkdir -p /tmp/yams-dev && export YAMS_STORAGE=/tmp/yams-dev
yams init --non-interactive
echo "test" | yams add - --tags test
yams search test
```

## Sanitizers (Debug)

```bash
CFLAGS='-fsanitize=address,undefined' CXXFLAGS='-fsanitize=address,undefined' \
  meson setup builddir --reconfigure
meson compile -C builddir
meson test -C builddir
```

## Static Analysis and Formatting

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

# clang-tidy (integrate via editor or invoke directly)
```

## CCache (optional)

Speed up rebuilds:
```bash
# Install
brew install ccache  # macOS
sudo apt install ccache  # Ubuntu

# Export wrappers
export CC="ccache gcc"
export CXX="ccache g++"
```

## Docker (optional)

```bash
# Quick CLI check
docker run --rm -it ghcr.io/trvon/yams:latest --version

# Persistent 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
```

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Missing native file | Re-run Conan install |
| Link errors after dep change | Delete builddir and reconfigure |
| Tests not found | Ensure `-Dbuild-tests=true` and recompile |
| qpdf: "recompile with -fPIC" | `conan remove 'qpdf/*' -c` then re-setup |
| Clang: "cannot find -lstdc++" | Install libstdc++ or use `YAMS_COMPILER=gcc` |
| Windows: Boost build failures | Install v143 toolset, clean cache |
| Windows: Missing recipes | Export qpdf and onnxruntime recipes |

## Notes

- Use Release for benchmarking; Debug + sanitizers for development
- Keep build trees out of version control
- `mediainfo`/`libmediainfo-dev` enables richer video metadata
- Provide exact versions and commands when filing issues