In order to develop the project you need to install following dependencies.
To build the project on CentOS Stream 9 you need to enable CodeReady Build repository:
sudo dnf install dnf-plugin-config-manager
sudo dnf config-manager --set-enabled crb
sudo dnf install -y epel-releasesudo dnf install clang-tools-extra gcc make meson systemd-devel selinux-policy-develmarkdownlint-cli2 can be used for static analysis of markdown files. Check the installation guide and use the most appropriate way of installation for your setup.
clang-format is used to enforce a uniform code style. The formatting of all source files can be checked via:
# only check for formatting
make check-fmt
# apply formatting to files
make fmtFor the most part, this project follows systemd coding style:
systemd-coding-style. Also, this project borrows
some of the coding conventions from systemd. For example, function names pertaining to D-Bus services look like
bus_service_set_property().
clang-tidy is used for static analysis of C source codes. markdownlint-cli2 is used for static analysis of markdown files. flake8 is used for format checking and linting of python code.
The following make targets simplify the usage of the different linting tools:
# using clang-tidy, lint all C source files
make lint-c
# same as lint-c target, but auto-fix errors if possible
make lint-c-fix
# using markdownlint-cli2, lint all markdown files
make lint-markdown
# combines lint-c and lint-markdown
make lintThe project is using meson as its primary build system.
The binaries and other artifacts (such as the man pages) can be built via:
meson setup builddir
meson compile -C builddirAfter successfully compiling the binaries, they can be installed into a destination directory (by default
/usr/local/bin) using:
meson install -C builddirTo install it into builddir/bin use:
meson install -C builddir --destdir binAfter building, the following binaries are available:
hirte: the systemd service controller which is run on the main machine, sending commands to the agents and monitoring the progresshirte-agent: the node agent unit which connects with the controller and executes commands on the node machinehirte-proxy: an internally used application to resolve cross-node dependencieshirtectl: a helper (CLI) program to send an commands to the controller
Bindings for the D-Bus API of hirte are located in src/bindings. Please refer to the
README.md for more details.
A complete set of typed python bindings for the D-Bus API is auto-generated. On any change to any of the interfaces, these need to be re-generated via
bash build-scripts/generate-bindings.sh pythonIn some cases, developers might need a debug session with tools like gdb, here an example:
First, make sure meson.build contains debug=true.
Rebuild the hirte project with debug symbols included:
hirte> make clean
hirte> meson install -C builddir --dest=bin
hirte> gdb --args ./builddir/bin/usr/local/bin/hirte -c /etc/hirte/hirte.confUnit tests can be executed using following commands:
meson setup builddir
meson configure -Db_coverage=true builddir # if you want to collect coverage data
meson compile -C builddir
meson test -C builddir
ninja coverage-html -C builddir # if you want to generate coverage reportwill produce a coverage report in builddir/meson-logs/coveragereport/index.html
All files related to the integration tests are located in tests and are organized via tmt. How to get started with running and developing integration tests for hirte is described in tests/README.
The following sections describe how to run the built application(s) locally on one machine. For this, the assumed setup used is described in the first section.
The project has been build with the following command sequence:
meson setup builddir
meson compile -C builddir
meson install -C builddir --destdir binMeson will output the artifacts to ./builddir/bin/usr/local/. This directory is referred to in the following sections
simply as <builddir>.
To allow hirte and hirte-agent to own a name on the local system D-Bus, the provided configuration
files need to be copied (if not already existing):
cp <builddir>/share/dbus-1/system.d/org.containers.hirte.Agent.conf /etc/dbus-1/system.d/
cp <builddir>/share/dbus-1/system.d/org.containers.hirte.conf /etc/dbus-1/system.d/Note: Make sure to reload the dbus service so these changes take effect: systemctl reload dbus-broker.service (or
systemctl reload dbus.service)
The newly built controller can simply be run via ./<builddir>/bin/hirte, but it is recommended to use a specific
configuration for development. This file can be passed in with the -c CLI option:
./<builddir>/bin/hirte -c <path-to-cfg-file>Before starting the agent, it is best to have the hirte controller already running. However, hirte-agent will
try to reconnect in the configured heartbeat interval.
Similar to hirte, it is recommended to use a dedicated configuration file for development:
./<builddir>/bin/hirte -c <path-to-cfg-file>The newly built hirtectl can be used via:
./<builddir>/bin/hirtectl COMMANDSFiles for documentation of this project are located in the doc directory comprising:
- api examples: directory containing python files that use the D-Bus API of hirte, e.g. for starting a systemd unit
- man: directory containing the markdown files for generating the man pages (see Building MAN pages for more information)
- readthedocs files for building the documentation website of hirte (see the README for further information)
- diagrams.drawio file containing all diagrams used for hirte
The source markdown files for building the MAN pages are located in doc/man. For generating the MAN pages from the markdown files go-md2man is being used. Install it via:
sudo dnf install golang-github-cpuguy83-md2manAfter executing a meson install the MAN pages are located in the man/man* directories.
Hirte is packaged as an RPM. The scripts used to create the SRPM and RPM may be found in .build-scripts.
The RPM creation script requires one environment variable:
ARTIFACTS_DIR- full path to a directory where the RPMs will be saved. The script will create the directory if it does not exist
Please note that the RPM creation script also installs all build dependencies and therefore requires running with root privileges
In order to build an RPM locally use the following command:
sudo ARTIFACTS_DIR=${PWD}/output ./build-scripts/build-rpm.shAlternatively, by setting the environment variable SKIP_BUILDDEP=yes,
the installation process is skipped, allowing regular user permissions
SKIP_BUILDDEP=yes ARTIFACTS_DIR=${PWD}/output ./build-scripts/build-rpm.sh