1--- 2title: systemd Repository Architecture 3category: Contributing 4layout: default 5SPDX-License-Identifier: LGPL-2.1-or-later 6--- 7 8# The systemd Repository Architecture 9 10## Code Map 11 12This section will attempt to provide a high-level overview of the various 13components of the systemd repository. 14 15## Source Code 16 17Directories in `src/` provide the implementation of all daemons, libraries and 18command-line tools shipped by the project. There are many, and more are 19constantly added, so we will not enumerate them all here — the directory 20names are self-explanatory. 21 22### Shared Code 23 24You might wonder what kind of common code belongs in `src/shared/` and what 25belongs in `src/basic/`. The split is like this: anything that is used to 26implement the public shared objects we provide (`sd-bus`, `sd-login`, 27`sd-id128`, `nss-systemd`, `nss-mymachines`, `nss-resolve`, `nss-myhostname`, 28`pam_systemd`), must be located in `src/basic` (those objects are not allowed 29to link to `libsystemd-shared.so`). Conversely, anything which is shared 30between multiple components and does not need to be in `src/basic/`, should be 31in `src/shared/`. 32 33To summarize: 34 35`src/basic/` 36- may be used by all code in the tree 37- may not use any code outside of `src/basic/` 38 39`src/libsystemd/` 40- may be used by all code in the tree, except for code in `src/basic/` 41- may not use any code outside of `src/basic/`, `src/libsystemd/` 42 43`src/shared/` 44- may be used by all code in the tree, except for code in `src/basic/`, 45`src/libsystemd/`, `src/nss-*`, `src/login/pam_systemd.*`, and files under 46`src/journal/` that end up in `libjournal-client.a` convenience library. 47- may not use any code outside of `src/basic/`, `src/libsystemd/`, `src/shared/` 48 49### PID 1 50 51Code located in `src/core/` implements the main logic of the systemd system (and user) 52service manager. 53 54BPF helpers written in C and used by PID 1 can be found under `src/core/bpf/`. 55 56#### Implementing Unit Settings 57 58The system and session manager supports a large number of unit settings. These can generally 59be configured in three ways: 60 611. Via textual, INI-style configuration files called *unit* *files* 622. Via D-Bus messages to the manager 633. Via the `systemd-run` and `systemctl set-property` commands 64 65From a user's perspective, the third is a wrapper for the second. To implement a new unit 66setting, it is necessary to support all three input methods: 67 681. *unit* *files* are parsed in `src/core/load-fragment.c`, with many simple and fixed-type 69unit settings being parsed by common helpers, with the definition in the generator file 70`src/core/load-fragment-gperf.gperf.in` 712. D-Bus messages are defined and parsed in `src/core/dbus-*.c` 723. `systemd-run` and `systemctl set-property` do client-side parsing and translating into 73D-Bus messages in `src/shared/bus-unit-util.c` 74 75So that they are exercised by the fuzzing CI, new unit settings should also be listed in the 76text files under `test/fuzz/fuzz-unit-file/`. 77 78### systemd-udev 79 80Sources for the udev daemon and command-line tool (single binary) can be found under 81`src/udev/`. 82 83### Unit Tests 84 85Source files found under `src/test/` implement unit-level testing, mostly for 86modules found in `src/basic/` and `src/shared/`, but not exclusively. Each test 87file is compiled in a standalone binary that can be run to exercise the 88corresponding module. While most of the tests can be run by any user, some 89require privileges, and will attempt to clearly log about what they need 90(mostly in the form of effective capabilities). These tests are self-contained, 91and generally safe to run on the host without side effects. 92 93Ideally, every module in `src/basic/` and `src/shared/` should have a 94corresponding unit test under `src/test/`, exercising every helper function. 95 96### Fuzzing 97 98Fuzzers are a type of unit tests that execute code on an externally-supplied 99input sample. Fuzzers are called `fuzz-*`. Fuzzers for `src/basic/` and 100`src/shared` live under `src/fuzz/`, and those for other parts of the codebase 101should be located next to the code they test. 102 103Files under `test/fuzz/` contain input data for fuzzers, one subdirectory for 104each fuzzer. Some of the files are "seed corpora", i.e. files that contain 105lists of settings and input values intended to generate initial coverage, and 106other files are samples saved by the fuzzing engines when they find an issue. 107 108When adding new input samples under `test/fuzz/*/`, please use some 109short-but-meaningful names. Names of meson tests include the input file name 110and output looks awkward if they are too long. 111 112Fuzzers are invoked primarily in three ways: firstly, each fuzzer is compiled 113as a normal executable and executed for each of the input samples under 114`test/fuzz/` as part of the test suite. Secondly, fuzzers may be instrumented 115with sanitizers and invoked as part of the test suite (if `-Dfuzz-tests=true` 116is configured). Thirdly, fuzzers are executed through fuzzing engines that try 117to find new "interesting" inputs through coverage feedback and massive 118parallelization; see the links for oss-fuzz in [Code quality](CODE_QUALITY.md). 119For testing and debugging, fuzzers can be executed as any other program, 120including under `valgrind` or `gdb`. 121 122## Integration Tests 123 124Sources in `test/TEST-*` implement system-level testing for executables, 125libraries and daemons that are shipped by the project. They require privileges 126to run, and are not safe to execute directly on a host. By default they will 127build an image and run the test under it via `qemu` or `systemd-nspawn`. 128 129Most of those tests should be able to run via `systemd-nspawn`, which is 130orders-of-magnitude faster than `qemu`, but some tests require privileged 131operations like using `dm-crypt` or `loopdev`. They are clearly marked if that 132is the case. 133 134See `test/README.testsuite` for more specific details. 135 136## hwdb 137 138Rules built in the static hardware database shipped by the project can be found 139under `hwdb.d/`. Some of these files are updated automatically, some are filled 140by contributors. 141 142## Documentation 143 144### systemd.io 145 146Markdown files found under `docs/` are automatically published on the 147[systemd.io](https://systemd.io) website using Github Pages. A minimal unit test 148to ensure the formatting doesn't have errors is included in the 149`meson test -C build/ github-pages` run as part of the CI. 150 151### Man pages 152 153Manpages for binaries and libraries, and the DBUS interfaces, can be found under 154`man/` and should ideally be kept in sync with changes to the corresponding 155binaries and libraries. 156 157### Translations 158 159Translations files for binaries and daemons, provided by volunteers, can be found 160under `po/` in the usual format. They are kept up to date by contributors and by 161automated tools. 162 163## System Configuration files and presets 164 165Presets (or templates from which they are generated) for various daemons and tools 166can be found under various directories such as `factory/`, `modprobe.d/`, `network/`, 167`presets/`, `rules.d/`, `shell-completion/`, `sysctl.d/`, `sysusers.d/`, `tmpfiles.d/`. 168 169## Utilities for Developers 170 171`tools/`, `coccinelle/`, `.github/`, `.semaphore/`, `.lgtm/`, `.mkosi/` host various 172utilities and scripts that are used by maintainers and developers. They are not 173shipped or installed. 174