8. Building and Integration

8.1. CMake options

Package options
Option	Default	Purpose
`XMLIO_BUILD_TESTS`	Top-level builds	Build and register the unit tests.
`XMLIO_BUILD_EXAMPLES`	Top-level builds	Build the examples included in this manual.
`XMLIO_BUILD_DOCUMENTATION`	Off	Add Doxygen, HTML, and PDF documentation targets.
`XMLIO_BUILD_PDF_DOCUMENTATION`	On	Include the PDF target when documentation is enabled.
`XMLIO_WARNINGS_AS_ERRORS`	Off	Promote compiler warnings from xmlio targets to errors.

Tests and examples default on when xmlio is configured directly and off when it is included with add_subdirectory.

8.2. Complete developer build

The package script creates a fresh build, maintains a package-local Python environment for Sphinx, compiles with warnings as errors, runs all tests and examples, and generates both manuals:

./scripts/build.sh

Set XMLIO_BUILD_DIR to choose another build directory or PYTHON to select the interpreter used to create .venv-docs.

The generated manuals are:

build/docs/html/index.html
build/docs/latex/xmlio.pdf

Individual xmlio_docs_html and xmlio_docs_pdf targets are available when only one format is needed.

8.3. Choosing a compiler and build directory

The compiler and build directory are independent choices. CXX selects the C++ compiler, while XMLIO_BUILD_DIR selects where CMake places generated files, object files, executables, tests, and manuals. Neither changes where the library is eventually installed.

For example, build with Clang in a directory named build-clang:

CXX=clang++ XMLIO_BUILD_DIR=build-clang ./scripts/build.sh

Or build with an installed GNU compiler in a separate directory:

CXX=g++-VERSION XMLIO_BUILD_DIR=build-gcc ./scripts/build.sh

Replace g++-VERSION with the executable available on the system, such as a versioned compiler installed by a package manager. On macOS, the unversioned g++ command may invoke Apple Clang rather than GNU GCC. The CMake configure output reports The CXX compiler identification and should always be checked when comparing compilers.

Separate build directories allow Clang and GCC builds to coexist without overwriting one another. The package script configures with cmake --fresh, so each invocation selects the compiler from scratch. For a manual CMake build, the equivalent configuration is:

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

Without --fresh, CMake retains the compiler previously selected for an existing build directory. Starting with a new build directory is therefore the simplest and least surprising way to change compilers.

8.4. HTML-only builds

Hosted documentation does not need a LaTeX installation. Configure an HTML-only build with:

cmake -S . -B build \
  -DXMLIO_BUILD_DOCUMENTATION=ON \
  -DXMLIO_BUILD_PDF_DOCUMENTATION=OFF
cmake --build build --target xmlio_docs_html

This mode remains useful for hosts that build the HTML manual directly. The Publish Documentation GitHub Actions workflow instead builds both the HTML and PDF manuals, copies xmlio.pdf beside the HTML files, and force-updates a generated docs-site branch after each push to main. Static hosting services should publish that branch without another framework build step. For Cloudflare Pages, set the build command to exit 0 and the output directory to ..

8.5. Example programs

The examples are ordinary clients linked only to xmlio::xmlio:

Compiled examples
Source	Focus
`quick_start.cpp`	Minimal in-memory write and read.
`custom_types.cpp`	Argument-dependent serialization of records.
`xpath_queries.cpp`	Predicates, namespaces, attributes, and optional values.
`catalog_merge.cpp`	Explicit map collision policies.
`composition.cpp`	Deferred groups and input provenance.
`error_handling.cpp`	Schema versions and typed exceptions.

When tests are enabled, CTest also executes every example.

8.6. Installation

The install prefix is different from the build directory. The build directory contains intermediate and generated files; the install prefix receives the finished library, headers, CMake package files, and source documentation.

After building in the default build directory, choose an install prefix with:

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

Match the install command to a custom build directory when one was used:

cmake --install build-clang --prefix "$HOME/.local/xmlio"

--prefix applies only to this installation and overrides the configured CMAKE_INSTALL_PREFIX. Installing into a system-owned location may require administrator permission; a directory below $HOME generally does not.

When the optional documentation targets have been built, installation also includes the generated HTML and PDF manuals.

8.7. Consuming the package

An installed-package consumer uses:

find_package(xmlio CONFIG REQUIRED)
target_link_libraries(my_program PRIVATE xmlio::xmlio)

Add the chosen prefix to CMAKE_PREFIX_PATH when CMake cannot otherwise find xmlioConfig.cmake.

For a source-tree dependency:

add_subdirectory(path/to/xmlio)
target_link_libraries(my_program PRIVATE xmlio::xmlio)

The public target requests C++23 and exports the required include paths. libxml2 remains an implementation detail of the C++ interface.