]>
Commit | Line | Data |
---|---|---|
2ecce1f1 | 1 | --- |
00d06c99 | 2 | title: systemd Repository Architecture |
2ecce1f1 LB |
3 | category: Contributing |
4 | layout: default | |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
2ecce1f1 LB |
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 | |
771bdb6a | 17 | constantly added, so we will not enumerate them all here — the directory |
2ecce1f1 LB |
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 | |
771bdb6a ZJS |
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/`. | |
2ecce1f1 LB |
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 | ||
76ab98fa LB |
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 | ||
2ecce1f1 LB |
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, | |
771bdb6a | 89 | and generally safe to run on the host without side effects. |
2ecce1f1 | 90 | |
771bdb6a ZJS |
91 | Ideally, every module in `src/basic/` and `src/shared/` should have a |
92 | corresponding unit test under `src/test/`, exercising every helper function. | |
2ecce1f1 LB |
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. |