Building
========

Prerequisites
-------------

The project uses Nix for reproducible development environments::

   # Enter the development shell (installs all dependencies)
   nix develop

Or install manually:

- GCC 14+ (C++26 support)
- Meson + Ninja
- Valgrind (for memory checking)
- gcovr / lcov (for coverage)
- Doxygen (for API documentation)
- Python 3 with Sphinx, Breathe, Exhale (for documentation)
- cppcheck, cpplint, clang-format (for linting)

Build Targets
-------------

The project provides a ``Makefile`` with convenience targets:

.. code-block:: sh

   make build-debug      # Debug build with ASan, UBSan, and coverage
   make build-release    # Optimized release build with LTO
   make install          # Install release build to system
   make test             # Run tests, valgrind, and coverage analysis
   make lint             # Auto-format, static analysis, style checks
   make docs             # Generate HTML and man page documentation
   make clean            # Remove build directories

Test Suites
-----------

Tests are organized into suites:

- **Default suite**: Unit tests that run without .mo files
- **mo suite**: Tests requiring compiled .mo files (needs ``msgfmt``)
- **valgrind suite**: Memory checking under Valgrind

.. code-block:: sh

   # Run all non-MO tests
   meson test -C builddir --no-suite mo --no-suite valgrind

   # Run valgrind checks
   meson test -C builddir --suite valgrind

   # Run MO-dependent tests (requires working msgfmt)
   meson test -C builddir --suite mo

Coverage
--------

Build with coverage instrumentation and generate reports:

.. code-block:: sh

   make test
   # Reports are generated automatically:
   # - Branch coverage (gcovr --branches)
   # - Condition/MC/DC coverage (gcovr --decisions)
   # - Line coverage
   # - HTML report at builddir-debug/coverage.html