8. Building and Integration

Hadros is an independently buildable C++23 static library. It installs public headers, libhadros, command-line tools when enabled, documentation sources, example XML files, and a relocatable CMake package. Its only package dependency is xmlio.

8.1. Requirements

A normal library and tool build requires:

  • CMake 3.24 or newer;

  • a C++23 compiler;

  • an xmlio checkout or installation.

Documentation additionally requires Python 3, Doxygen, Sphinx, Breathe, MyST-Parser, the Read the Docs theme, and latexmk for PDF output. The helper script creates a package-local Python virtual environment for the Python documentation dependencies. It does not modify the user’s system Python. Set PYTHON to choose the interpreter used to create that environment, for example PYTHON=python3.13 ./scripts/build.sh --docs.

8.2. Source Tree

Public headers live in include/hadros/ and compiled library implementation files live in src/. User-facing command-line programs and their private shared support code live in the flat tools/ directory. Teaching programs remain in examples/ and tests in tests/. This separation keeps the library independent of command-line presentation code; built tools still appear directly under build/ and install under the normal bin/ path.

8.4. Custom Build Directory

Use --build-dir to select another build tree. Relative paths are interpreted from the directory in which the script is run; absolute paths may place the build anywhere writable.

$ ./scripts/build.sh --build-dir build-clang
$ ./scripts/build.sh --build-dir /tmp/hadros-build --docs

HADROS_BUILD_DIR provides the equivalent environment setting. The command-line option takes precedence when both are present. The directory is a disposable build tree; it is not the installation directory.

8.5. Choosing a Compiler

CMake selects the compiler during configuration. Set CXX when starting a fresh helper-script build:

$ CXX=clang++ ./scripts/build.sh
$ CXX=g++-14 HADROS_BUILD_DIR=build-gcc ./scripts/build.sh

For a manual build, the equivalent cache setting is:

$ cmake --fresh -S . -B build-clang \
    -DCMAKE_CXX_COMPILER=clang++

Changing compilers inside an existing CMake cache can leave incompatible compiler checks and object files behind. Use --fresh or a new build directory when switching compilers.

8.6. Manual CMake Build

The direct CMake sequence is:

$ cmake --fresh -S . -B build \
    -DHADROS_BUILD_TESTS=ON \
    -DHADROS_BUILD_TOOLS=ON \
    -DHADROS_BUILD_EXAMPLES=ON
$ cmake --build build --parallel
$ ctest --test-dir build --output-on-failure

Hadros first looks for an existing xmlio::xmlio target, then for an installed xmlio package, and finally at the sibling ../xmlio source tree. Point to another source checkout with:

$ cmake --fresh -S . -B build \
    -DHADROS_XMLIO_SOURCE_DIR=/path/to/xmlio

For an installed dependency, use the standard CMake prefix search path:

$ cmake --fresh -S . -B build \
    -DCMAKE_PREFIX_PATH=/path/to/xmlio/prefix

The helper-script equivalent is:

$ HADROS_XMLIO_PREFIX=/path/to/xmlio/prefix ./scripts/build.sh

8.7. Compiled Teaching Examples

Hadros builds three small programs that exercise only the installed public API:

$ ./build/examples/hadros_example_load_catalog \
    data/examples/sigma/hadrons.xml
$ ./build/examples/hadros_example_load_targets \
    data/examples/sigma/targets.xml
$ ./build/examples/hadros_example_channel_basis_lookup \
    data/examples/sigma/hadrons.xml data/examples/sigma/targets.xml

They demonstrate catalog loading, target loading, and structured channel-key lookup in an indexed two-body basis. CTest runs all three, so these introductory workflows fail visibly if the public API changes. Their source files are installed under share/doc/hadros/examples/cpp; the example executables are development aids and are not installed into bin.

8.8. Building Documentation Manually

After the Python documentation requirements are available, configure and build both formats with:

$ cmake --fresh -S . -B build-docs \
    -DHADROS_BUILD_DOCUMENTATION=ON
$ cmake --build build-docs --target hadros_docs

An HTML-only build avoids the LaTeX dependency:

$ cmake --fresh -S . -B build-docs \
    -DHADROS_BUILD_DOCUMENTATION=ON \
    -DHADROS_BUILD_PDF_DOCUMENTATION=OFF
$ cmake --build build-docs --target hadros_docs

Warnings from Doxygen and Sphinx are treated as errors. This keeps broken API references and malformed manual links from silently entering a release.

8.9. Installing Hadros

The package installation helper uses build/ and $HOME/.local by default:

$ ./scripts/install.sh

If the selected build contains a compiled Hadros library from this source tree, the helper installs it immediately without rebuilding or rerunning tests. If the build is absent or incomplete, the helper first runs the complete build.sh workflow and only installs after that succeeds.

Generated Hadros documentation remains opt-in during installation:

$ ./scripts/install.sh --docs

If both HTML and PDF already exist, they are installed immediately. Otherwise the helper preserves the build’s XMLIO dependency choice, runs build.sh --docs, and verifies both formats before installing. This option generates Hadros documentation only; XMLIO’s generated manuals remain the responsibility of XMLIO’s own scripts.

Select both locations explicitly with:

$ ./scripts/install.sh \
    --build-dir build-clang \
    --install-dir "$HOME/.local/hadros" \
    --xmlio-dir "$HOME/.local"

HADROS_BUILD_DIR and HADROS_INSTALL_DIR provide equivalent environment settings; command-line options take precedence. --xmlio-dir is passed to build.sh when the selected Hadros build is missing or incomplete.

When the Hadros build staged XMLIO from source, install.sh installs that XMLIO build into the same destination before installing Hadros. When Hadros was built against HADROS_XMLIO_PREFIX, the helper leaves that independent XMLIO installation in place. Downstream projects must then search both installation directories when they differ.

For a manual installation, the build directory and install prefix are independent. Configure and compile normally, then select the destination:

$ cmake --build build --parallel
$ cmake --install build --prefix "$HOME/.local"

Alternatively, set CMAKE_INSTALL_PREFIX while configuring:

$ cmake --fresh -S . -B build \
    -DCMAKE_INSTALL_PREFIX="$HOME/.local"
$ cmake --build build --parallel
$ cmake --install build

The install contains the static library, public headers, CMake package files, the built tools, authored documentation, and example XML inputs. Generated HTML and PDF manuals are installed only if documentation was enabled and built.

8.10. Using an Installed Package

A downstream CMakeLists.txt can consume Hadros through its exported target:

cmake_minimum_required(VERSION 3.24)
project(my_analysis LANGUAGES CXX)

find_package(hadros 0.1 CONFIG REQUIRED)

add_executable(my_analysis main.cpp)
target_link_libraries(my_analysis PRIVATE hadros::hadros)

Configure the consumer with the prefix containing both Hadros and xmlio:

$ cmake -S . -B build \
    -DCMAKE_PREFIX_PATH="$HOME/.local"

Linking hadros::hadros propagates the public include directory, C++23 requirement, and xmlio::xmlio dependency. Consumers should not reproduce Hadros compiler flags or guess archive paths.

8.11. Using Hadros as Source

A larger source-tree build may provide xmlio::xmlio and add Hadros as a subdirectory:

add_subdirectory(path/to/xmlio)
add_subdirectory(path/to/hadros)
target_link_libraries(my_analysis PRIVATE hadros::hadros)

When Hadros is not the top-level project, its tests and tools default to off. Set the corresponding options before add_subdirectory when a combined developer build should include them.

8.12. CMake Options

HADROS_BUILD_TESTS

Build and register the unit and command-line tests. Defaults to on only when Hadros is the top-level project.

HADROS_BUILD_TOOLS

Build the command-line catalog and channel utilities. Defaults to on only when Hadros is the top-level project.

HADROS_BUILD_EXAMPLES

Build the compiled teaching examples and register them with CTest when tests are enabled. Defaults to on only when Hadros is the top-level project.

HADROS_BUILD_DOCUMENTATION

Enable Doxygen and Sphinx targets. Defaults to off.

HADROS_BUILD_PDF_DOCUMENTATION

Add PDF generation when documentation is enabled. Defaults to on. Set it to off for an HTML-only documentation build.

HADROS_WARNINGS_AS_ERRORS

Promote Hadros’ own compiler warnings to errors. Defaults to off and does not impose warning flags on downstream targets.

HADROS_XMLIO_SOURCE_DIR

Fallback source checkout for xmlio. Defaults to the sibling ../xmlio directory.

8.13. Version Compatibility

Hadros is currently pre-1.0. Its generated CMake version file uses same-minor compatibility: a request for 0.1 accepts compatible 0.1.x releases but does not silently cross into 0.2. API compatibility policy can be widened when the package reaches a stable 1.x interface.