Building
========

Requirements
------------

- CMake >= 3.16
- C99 compiler: GCC, Clang, or MSVC
- Optional: DJGPP cross-compiler for DOS builds

Linux / macOS
-------------

.. code-block:: sh

   cmake -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build
   ctest --test-dir build

The binary is ``build/cli/uc2`` and the library is
``build/lib/libuc2.a``.

Windows (MSVC)
--------------

.. code-block:: sh

   cmake -B build
   cmake --build build --config Release
   ctest --test-dir build -C Release

DOS (DJGPP Cross-Compilation)
-----------------------------

Cross-compile from a Linux host using the DJGPP toolchain:

.. code-block:: sh

   cmake -B build-dos -DCMAKE_TOOLCHAIN_FILE=cmake/djgpp.cmake
   cmake --build build-dos

This produces a DOS executable suitable for DOSBox or real hardware.

libarchive Read Plugin
----------------------

The optional libarchive read handler (``contrib/libarchive/``) lets any
libarchive consumer — ``bsdtar``, file managers, language bindings —
list and extract ``.uc2`` archives. It uses libarchive's internal
read-format API, so it builds against a libarchive **source tree**
rather than an installed ``-devel`` package.

Unpack a libarchive release and build a static library (a
dependency-free configuration is enough for the plugin and its test):

.. code-block:: sh

   curl -LO https://github.com/libarchive/libarchive/releases/download/v3.7.7/libarchive-3.7.7.tar.gz
   tar xzf libarchive-3.7.7.tar.gz
   cmake -S libarchive-3.7.7 -B larch-build -DCMAKE_BUILD_TYPE=Release \
         -DBUILD_SHARED_LIBS=OFF -DENABLE_TEST=OFF
   cmake --build larch-build --target archive_static

Then configure UC2 with the plugin enabled, pointing at the source tree
and the static library:

.. code-block:: sh

   cmake -B build -DCMAKE_BUILD_TYPE=Release \
         -DUC2_BUILD_LIBARCHIVE_PLUGIN=ON \
         -DLIBARCHIVE_SOURCE_DIR=$PWD/libarchive-3.7.7 \
         -DLIBARCHIVE_LIBRARY=$PWD/larch-build/libarchive/libarchive.a
   cmake --build build

This builds ``libuc2_libarchive.a`` and the ``libarchive_roundtrip``
test, which creates archives at multiple compression levels and reads
them back through libarchive's public API, verifying every byte. The
plugin handles multi-file archives with directory paths, master-block
deduplication, and Win95 long names.

Build Options
-------------

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Option
     - Default
     - Description
   * - ``UC2_BUILD_TESTS``
     - ``ON``
     - Build test programs
   * - ``UC2_BUILD_LIBARCHIVE_PLUGIN``
     - ``OFF``
     - Build the libarchive read handler (needs ``LIBARCHIVE_SOURCE_DIR``)
   * - ``CMAKE_BUILD_TYPE``
     - (none)
     - ``Release``, ``Debug``, ``RelWithDebInfo``

Running Tests
-------------

.. code-block:: sh

   ctest --test-dir build --output-on-failure

Tests include:

- **identify**: UC2 magic detection
- **extract**: decompression against reference archives
- **roundtrip**: compress → archive → decompress → verify (8 patterns
  × 4 compression levels = 32 tests)