2026-03-12 00:52:47 -04:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-06-13 02:10:56 -04:00
|
|
|
|
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.
|
|
|
|
|
|
|
2026-03-12 00:52:47 -04:00
|
|
|
|
Build Options
|
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
|
|
.. list-table::
|
|
|
|
|
|
:header-rows: 1
|
|
|
|
|
|
:widths: 30 15 55
|
|
|
|
|
|
|
|
|
|
|
|
* - Option
|
|
|
|
|
|
- Default
|
|
|
|
|
|
- Description
|
|
|
|
|
|
* - ``UC2_BUILD_TESTS``
|
|
|
|
|
|
- ``ON``
|
|
|
|
|
|
- Build test programs
|
2026-06-13 02:10:56 -04:00
|
|
|
|
* - ``UC2_BUILD_LIBARCHIVE_PLUGIN``
|
|
|
|
|
|
- ``OFF``
|
|
|
|
|
|
- Build the libarchive read handler (needs ``LIBARCHIVE_SOURCE_DIR``)
|
2026-03-12 00:52:47 -04:00
|
|
|
|
* - ``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)
|
