Christopher M. Punches
11aad23e80
src/documentation.cpp is the documentation loading source: it carries no code and names each document that the generated reference contains, in order, by page label. The labels are declared on each markdown file's first heading. The build configuration lists the files as Doxygen inputs and nothing more, so the structure of the documentation and the mechanics of generating it are separate. The hand-maintained document index at the end of OVERVIEW.md is gone, along with the last references to markdown files by filename in the public header. The document list exists in one place. The docs target clears its output and scratch directories on every run. Doxygen keeps output files it judges unchanged, so a run over a populated scratch directory carried pages forward from earlier ones, and removed sections survived in the generated HTML and PDF after their source was edited.
3.0 KiB
Building libdpm-core.so and the dpm Binary
Prerequisites
- GCC/G++ supporting C++20
- CMake 3.22 or later
- Make
- Doxygen (optional, for the code reference)
pdflatexandmakeindex(optional, for the PDF code reference)
The library itself depends only on libc and libstdc++, so it builds and runs on a minimal system.
Development Builds
Configure a build tree and compile it:
cmake -B <build-dir> -DCMAKE_BUILD_TYPE=Debug
cmake --build <build-dir>
Artifacts land in:
<build-dir>/bin/dpm the dpm binary
<build-dir>/lib/libdpm-core.so the library
<build-dir>/modules/info.so the bundled info module
The dpm binary built here finds the locally built libdpm-core.so on its own — an embedded library search path points it at the lib/ directory next to it in the build tree, so running it directly uses the library you just built with nothing to set up first. This is only the default: LD_LIBRARY_PATH takes precedence over the embedded path, so the binary can be pointed at any other libdpm-core, including the system-installed one.
Automated Testing
ctest --test-dir <build-dir> --output-on-failure
This runs the API test binary (which exercises the full load-time validation matrix against the fixture modules in tests/fixtures/) and the CLI end-to-end tests.
Manual Execution
The build tree plus the test fixtures form a complete self-contained environment; no installation is required. Point the dpm binary at local paths with its override flags:
<build-dir>/bin/dpm --config-dir ./tests/fixtures/conf --module-path <build-dir>/modules info version
The flags --config-dir, --module-path, --root, and --log-level each redirect the corresponding system default; --root sets the target root that package-operation modules act on.
Release Builds
One build tree carries the whole sequence, so the artifacts that get tested are the artifacts that get installed:
cmake -B <build-dir> -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
cmake --build <build-dir>
ctest --test-dir <build-dir> --output-on-failure
cmake --install <build-dir>
This is the packaging flow: configure once, build once, test what was built, install what was tested.
Automated Testing
The test suite builds and runs in any configuration, so a release tree is tested by the same command a development tree is:
ctest --test-dir <build-dir> --output-on-failure
Running it between the build and the install step is what makes the sequence above a packaging flow rather than four unrelated commands.
Installation
cmake --install <build-dir>
Omit -DCMAKE_INSTALL_PREFIX=/usr at configure time for a /usr/local install. Under the install prefix this installs:
bin/dpm the dpm binary
lib/libdpm-core.so the library
lib/dpm/modules/info.so the bundled info module
include/dpm/ the public header
The library's own configuration installs to /etc/dpm/conf.d/core.conf regardless of prefix.
