docs/ARCHITECTURE.md

   1 ---
   2 title: systemd Repository Architecture
   3 category: Contributing
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # Code Map
   9
  10 This section will attempt to provide a high-level overview of the various
  11 components of the systemd repository.
  12
  13 # Source Code
  14
  15 Directories in `src/` provide the implementation of all daemons, libraries and
  16 command-line tools shipped by the project. There are many, and more are
  17 constantly added, so we will not enumerate them all here — the directory
  18 names are self-explanatory.
  19
  20 ## Shared Code
  21
  22 You might wonder what kind of common code belongs in `src/shared/` and what
  23 belongs in `src/basic/`. The split is like this: anything that is used to
  24 implement the public shared objects we provide (`sd-bus`, `sd-login`,
  25 `sd-id128`, `nss-systemd`, `nss-mymachines`, `nss-resolve`, `nss-myhostname`,
  26 `pam_systemd`), must be located in `src/basic` (those objects are not allowed
  27 to link to `libsystemd-shared.so`). Conversely, anything which is shared
  28 between multiple components and does not need to be in `src/basic/`, should be
  29 in `src/shared/`.
  30
  31 To summarize:
  32
  33 `src/basic/`
  34 - may be used by all code in the tree
  35 - may not use any code outside of `src/basic/`
  36
  37 `src/libsystemd/`
  38 - may be used by all code in the tree, except for code in `src/basic/`
  39 - may not use any code outside of `src/basic/`, `src/libsystemd/`
  40
  41 `src/shared/`
  42 - may be used by all code in the tree, except for code in `src/basic/`,
  43 `src/libsystemd/`, `src/nss-*`, `src/login/pam_systemd.*`, and files under
  44 `src/journal/` that end up in `libjournal-client.a` convenience library.
  45 - may not use any code outside of `src/basic/`, `src/libsystemd/`, `src/shared/`
  46
  47 ## PID 1
  48
  49 Code located in `src/core/` implements the main logic of the systemd system (and user)
  50 service manager.
  51
  52 BPF helpers written in C and used by PID 1 can be found under `src/core/bpf/`.
  53
  54 ### Implementing Unit Settings
  55
  56 The system and session manager supports a large number of unit settings. These can generally
  57 be configured in three ways:
  58
  59 1. Via textual, INI-style configuration files called *unit* *files*
  60 2. Via D-Bus messages to the manager
  61 3. Via the `systemd-run` and `systemctl set-property` commands
  62
  63 From a user's perspective, the third is a wrapper for the second. To implement a new unit
  64 setting, it is necessary to support all three input methods:
  65
  66 1. *unit* *files* are parsed in `src/core/load-fragment.c`, with many simple and fixed-type
  67 unit settings being parsed by common helpers, with the definition in the generator file
  68 `src/core/load-fragment-gperf.gperf.in`
  69 2. D-Bus messages are defined and parsed in `src/core/dbus-*.c`
  70 3. `systemd-run` and `systemctl set-property` do client-side parsing and translating into
  71 D-Bus messages in `src/shared/bus-unit-util.c`
  72
  73 So that they are exercised by the fuzzing CI, new unit settings should also be listed in the
  74 text files under `test/fuzz/fuzz-unit-file/`.
  75
  76 ## UDEV
  77
  78 Sources for the udev daemon and command-line tool (single binary) can be found under
  79 `src/udev/`.
  80
  81 ## Unit Tests
  82
  83 Source files found under `src/test/` implement unit-level testing, mostly for
  84 modules found in `src/basic/` and `src/shared/`, but not exclusively. Each test
  85 file is compiled in a standalone binary that can be run to exercise the
  86 corresponding module. While most of the tests can be ran by any user, some
  87 require privileges, and will attempt to clearly log about what they need
  88 (mostly in the form of effective capabilities). These tests are self-contained,
  89 and generally safe to run on the host without side effects.
  90
  91 Ideally, every module in `src/basic/` and `src/shared/` should have a
  92 corresponding unit test under `src/test/`, exercising every helper function.
  93
  94 # Integration Tests
  95
  96 Sources in `test/` implement system-level testing for executables, libraries and
  97 daemons that are shipped by the project. They require privileges to run, and
  98 are not safe to execute directly on a host. By default they will build an image
  99 and run the test under it via `QEMU` or `systemd-nspawn`.
 100
 101 Most of those tests should be able to run via `systemd-nspawn`, which is orders of
 102 magnitude faster than `QEMU`, but some tests require privileged operations like
 103 using `dm-crypt` or `loopdev`. They are clearly marked if that is the case.
 104
 105 See `test/README.testsuite` for more specific details.
 106
 107 # HWDB
 108
 109 Rules built in the static `HWDB` database shipped by the project can be found
 110 under `hwdb.d/`. Some of these files are updated automatically, some are filled
 111 by contributors.
 112
 113 # Documentation
 114
 115 ## systemd.io
 116
 117 Markdown files found under `docs/` are automatically published on the
 118 [systemd.io](https://systemd.io) website using Github Pages. A minimal unit test
 119 to ensure the formatting doesn't have errors is included in the
 120 `meson test -C build/ github-pages` run as part of the CI.
 121
 122 ## MAN pages
 123
 124 Manpages for binaries and libraries, and the DBUS interfaces, can be found under
 125 `man/` and should ideally be kept in sync with changes to the corresponding
 126 binaries and libraries.
 127
 128 ## Translations
 129
 130 Translations files for binaries and daemons, provided by volunteers, can be found
 131 under `po/` in the usual format. They are kept up to date by contributors and by
 132 automated tools.
 133
 134 # System Configuration files and presets
 135
 136 Presets (or templates from which they are generated) for various daemons and tools
 137 can be found under various directories such as `factory/`, `modprobe.d/`, `network/`,
 138 `presets/`, `rules.d/`, `shell-completion/`, `sysctl.d/`, `sysusers.d/`, `tmpfiles.d/`.
 139
 140 # Utilities for Developers
 141
 142 `tools/`, `coccinelle/`, `.github/`, `.semaphore/`, `.lgtm/`, `.mkosi/` host various
 143 utilities and scripts that are used by maintainers and developers. They are not
 144 shipped or installed.