.. _hadros-building: 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``. 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``. 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. Recommended Local Build ----------------------- From the Hadros source directory, run: .. code-block:: console $ ./scripts/build.sh This is the routine development check. It performs five steps: #. builds and installs the sibling ``xmlio`` dependency into a temporary stage; #. configures a fresh Hadros build with tools, tests, examples, and strict warnings; #. compiles Hadros and runs its test suite; #. installs Hadros into the temporary stage; #. builds and tests a separate consumer project using ``find_package(hadros)``. The last step catches packaging defects that an in-tree test cannot see, such as missing installed headers, incomplete exported dependencies, or a broken CMake target name. To reuse an existing XMLIO installation instead of rebuilding the sibling source tree, set ``HADROS_XMLIO_PREFIX`` to its install prefix: .. code-block:: console $ HADROS_XMLIO_PREFIX=/path/to/xmlio/install ./scripts/build.sh The prefix is the directory passed to ``cmake --install ... --prefix``. It normally contains ``lib/cmake/xmlio/xmlioConfig.cmake``. Relative paths are interpreted from the directory in which the helper is invoked; the script canonicalizes the path before configuring Hadros. When both ``HADROS_XMLIO_PREFIX`` and ``HADROS_XMLIO_SOURCE_DIR`` are set, the installed prefix takes precedence and XMLIO is not rebuilt. For a single command-line option, ``--xmlio-dir`` accepts either layout: .. code-block:: console $ ./scripts/build.sh --xmlio-dir ../xmlio $ ./scripts/build.sh --xmlio-dir "$HOME/.local" A source tree is identified by its top-level ``CMakeLists.txt`` and ``include/xmlio/xmlio.hpp``. An installation is identified by its installed ``xmlioConfig.cmake``, normally below ``lib/cmake/xmlio``. The helper reports the detected layout before building. Ambiguous or unrecognized directories are rejected rather than guessed. ``--xmlio-dir`` takes precedence over both XMLIO environment variables. Documentation is opt-in: .. code-block:: console $ ./scripts/build.sh --docs This performs the same checks and also creates: * ``build/docs/html/index.html``; * ``build/docs/latex/hadros.pdf``. Use ``./scripts/build.sh --help`` for the short command synopsis. 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. .. code-block:: console $ ./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. Choosing a Compiler ------------------- CMake selects the compiler during configuration. Set ``CXX`` when starting a fresh helper-script build: .. code-block:: console $ 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: .. code-block:: console $ 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. Manual CMake Build ------------------ The direct CMake sequence is: .. code-block:: console $ 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: .. code-block:: console $ cmake --fresh -S . -B build \ -DHADROS_XMLIO_SOURCE_DIR=/path/to/xmlio For an installed dependency, use the standard CMake prefix search path: .. code-block:: console $ cmake --fresh -S . -B build \ -DCMAKE_PREFIX_PATH=/path/to/xmlio/prefix The helper-script equivalent is: .. code-block:: console $ HADROS_XMLIO_PREFIX=/path/to/xmlio/prefix ./scripts/build.sh Compiled Teaching Examples -------------------------- Hadros builds three small programs that exercise only the installed public API: .. code-block:: console $ ./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``. Building Documentation Manually ------------------------------- After the Python documentation requirements are available, configure and build both formats with: .. code-block:: console $ 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: .. code-block:: console $ 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. Installing Hadros ----------------- The package installation helper uses ``build/`` and ``$HOME/.local`` by default: .. code-block:: console $ ./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: .. code-block:: console $ ./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: .. code-block:: console $ ./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: .. code-block:: console $ cmake --build build --parallel $ cmake --install build --prefix "$HOME/.local" Alternatively, set ``CMAKE_INSTALL_PREFIX`` while configuring: .. code-block:: console $ 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. Using an Installed Package -------------------------- A downstream ``CMakeLists.txt`` can consume Hadros through its exported target: .. code-block:: cmake 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``: .. code-block:: console $ 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. Using Hadros as Source ---------------------- A larger source-tree build may provide ``xmlio::xmlio`` and add Hadros as a subdirectory: .. code-block:: cmake 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. 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. 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.