.. _xmlio-building: Building and Integration ======================== CMake options ------------- .. list-table:: Package options :header-rows: 1 :widths: 36 20 44 * - 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``. 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: .. code-block:: console ./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: .. code-block:: text 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. 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``: .. code-block:: console CXX=clang++ XMLIO_BUILD_DIR=build-clang ./scripts/build.sh Or build with an installed GNU compiler in a separate directory: .. code-block:: console 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: .. code-block:: console 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. HTML-only builds ---------------- Hosted documentation does not need a LaTeX installation. Configure an HTML-only build with: .. code-block:: console 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 ``.``. Example programs ---------------- The examples are ordinary clients linked only to ``xmlio::xmlio``: .. list-table:: Compiled examples :header-rows: 1 :widths: 34 66 * - 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. 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: .. code-block:: console cmake --install build --prefix "$HOME/.local" Match the install command to a custom build directory when one was used: .. code-block:: console 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. Consuming the package --------------------- An installed-package consumer uses: .. code-block:: cmake 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: .. code-block:: cmake 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.