Building and installation

Use the root CMakeLists.txt for all builds. CMake discovers installed
dependencies; configuration does not download libraries.

Dependencies

CMake 3.28+, Ninja 1.11+, upstream Clang 16+ with clang-scan-deps (plus a C compiler for Cubiomes)

OpenCV: core, imgproc, imgcodecs

OpenSSL 3.0+ Crypto/SSL, Crypto++ 8.9+, zlib, libpng, libzip, and pkg-config

Catch2 3 and Python 3.9+ when BUILD_TESTING is enabled (the default)

macOS with Homebrew:

brew install cmake ninja llvm pkgconf opencv openssl@3 cryptopp libpng libzip catch2
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release

Ubuntu 24.04 (also used by CI):

sudo apt-get update
sudo apt-get install build-essential clang-18 clang-tools-18 cmake ninja-build pkg-config \
  libopencv-dev libssl-dev zlib1g-dev libpng-dev libcrypto++-dev libzip-dev catch2 zip python3
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++-18

For dependencies in another prefix, pass -DCMAKE_PREFIX_PATH=/path/to/prefix.
The CLI uses POSIX APIs; macOS and Linux are the supported build environments.

Build and test

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

CTest runs 12 groups; see Testing for coverage and optional checks:

Test	Scope
`csha_cipher_unit`	Shared C++20 interface, all ciphers, known-answer vectors, tampering and capacity
`csha_core_cli`	All 21 CLI modes and derived-seed/ZIP regressions
`csha_cipher_cli`	Ten new cipher choices through public CLI workflows
`csha_docker_unit`	Archive boundaries, metadata and digest validation
`csha_blob_protocol`	Relay protocol rejection, fragmentation and timeout recovery
`csha_unit`	Core image, map, data-URL, and image-pair Catch2 tests
`csha_blob_unit`	TLS session and authentication behavior
`csha_blob_live`	Two-process direct TCP and paired relay flows on loopback
`csha_docker_cli`	Real archive/PNG codec with a deterministic Docker subprocess fixture
`csha_pair_data_url`	Image-pair file recovery through PNG data URLs
`csha_help`	Top-level help output
`csha_version`	Executable version output

Core cases share temporary filenames and are kept serial where required. The
Blob process tests require permission to open loopback sockets. Default Docker
tests do not need a real daemon or download an image.
A JUnit report can be requested with --output-junit junit.xml on CTest 3.21+.

For a CLI-only build without Catch2:

cmake -S . -B build-cli -G Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
cmake --build build-cli --parallel

On macOS, CMake asks Homebrew for its OpenSSL prefix if normal discovery fails.
An explicit -DOPENSSL_ROOT_DIR=/path/to/openssl or OPENSSL_ROOT_DIR
environment variable takes precedence.

Install

cmake --install build --prefix "$HOME/.local"
"$HOME/.local/bin/csha" --version

Only the csha executable is installed. Its shared dependencies must remain
installed on the destination system.

CLion

Open the repository root as a CMake project. Select the csha run target or
csha_tests test target. Homebrew OpenSSL is discovered automatically, including
when CLion is launched from Finder. For a custom installation, add
-DOPENSSL_ROOT_DIR=/path/to/openssl to the CMake profile. Keep generated build
files in build/ or CLion's cmake-build-* directories.

C++20 encryption module

src/crypto/encoder.ixx exports csha.encoder: Encoder,
StreamingEncoder, cipher IDs, key types, and configuration. AES and the added
ciphers implement this shared contract through make_encoder in
crypto/encoder_factory.h; Docker uses the streaming contract. CMake registers
the interface as a public CXX_MODULES file set and tracks imports with Ninja.

Use CMake 3.28+, Ninja 1.11+, and upstream Clang 16+ with clang-scan-deps.
AppleClang does not support this named-module build. A fresh macOS configuration
automatically selects Homebrew LLVM when installed; for CLion select that LLVM
toolchain and Ninja. If an existing build cached AppleClang or Make, configure a
new build directory rather than reusing it. For an explicit macOS selection:

cmake -S . -B build-modules -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++"
cmake --build build-modules --parallel
ctest --test-dir build-modules --output-on-failure

Debug builds and generators

Keep Debug and Release outputs in separate directories:

cmake -S . -B build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build-debug --parallel
ctest --test-dir build-debug --output-on-failure

Use -G Ninja on the first configuration of a new build directory for module
dependency scanning. CMake generates the build system; no handwritten Makefile is
required. Do not change generators inside an existing build directory.

What each dependency is used for

Dependency	Use
OpenCV	Image matrices, PNG I/O, and map/image operations
OpenSSL Crypto	AES, hashes, random keys, and image credentials
Crypto++	Added authenticated ciphers and streaming archive encryption
OpenSSL SSL	Blob Streams TLS sessions
libpng	Row-by-row Docker archive PNG codec
zlib and libzip	Compression and ZIP-related helpers
Cubiomes	Bundled biome generation; built as C with wrapping signed arithmetic
Catch2 and Python	Unit and CLI integration tests
Docker CLI and daemon	Runtime dependency only for Docker `pack`, `load`, and `run`
System `zip`	Preparing ZIP examples and the legacy `mtz` metadata export

A successful build does not imply Docker is installed, a peer is reachable,
or a registry image exists. These are runtime prerequisites of those commands.

CI and install checks

The GitLab pipeline configures a Release Ninja build on Ubuntu 24.04, builds the
application and tests, runs CTest, installs to a temporary prefix, and checks
the installed executable's version. It retains the binary and JUnit report as
artifacts. This is build and fixture coverage, not a deployed network or
real-container integration check.

To repeat the install portion locally without modifying system directories:

cmake --install build --prefix "$PWD/build/install"
./build/install/bin/csha --version

If discovery fails, see Troubleshooting. After a successful
build, continue with Quick start.

Building and installation

Dependencies#

Build and test#

Install#

CLion#

C++20 encryption module#

Debug builds and generators#

What each dependency is used for#

CI and install checks#