d26791bfbd
The read handler now composes full directory paths from the cdir's directory ids rather than emitting bare leaf names: build_dir_path walks the parent chain (root dirid 0, depth-capped against cyclic cdirs), so multi-file archives with subdirectories list correctly. Master-block resolution (M4) and tagged long names (M6) already work through libuc2's extract and tag paths; this adds a libarchive round-trip test that creates archives at Huffman and rANS levels and verifies every byte back through libarchive's public API. Documents the plugin build recipe (libarchive source tree + static lib). Verified against libarchive 3.7.7; round-trip clean under valgrind.
114 lines
3.0 KiB
ReStructuredText
114 lines
3.0 KiB
ReStructuredText
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)
|