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