2021-06-03 14:37:17 +00:00
|
|
|
---
|
2021-06-04 08:34:56 +00:00
|
|
|
title: systemd Repository Architecture
|
2021-06-03 14:37:17 +00:00
|
|
|
category: Contributing
|
|
|
|
layout: default
|
2021-09-14 14:05:21 +00:00
|
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
2021-06-03 14:37:17 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# Code Map
|
|
|
|
|
|
|
|
This section will attempt to provide a high-level overview of the various
|
|
|
|
components of the systemd repository.
|
|
|
|
|
|
|
|
# Source Code
|
|
|
|
|
|
|
|
Directories in `src/` provide the implementation of all daemons, libraries and
|
|
|
|
command-line tools shipped by the project. There are many, and more are
|
2021-06-04 08:50:33 +00:00
|
|
|
constantly added, so we will not enumerate them all here — the directory
|
2021-06-03 14:37:17 +00:00
|
|
|
names are self-explanatory.
|
|
|
|
|
|
|
|
## Shared Code
|
|
|
|
|
|
|
|
You might wonder what kind of common code belongs in `src/shared/` and what
|
|
|
|
belongs in `src/basic/`. The split is like this: anything that is used to
|
2021-06-04 08:50:33 +00:00
|
|
|
implement the public shared objects we provide (`sd-bus`, `sd-login`,
|
|
|
|
`sd-id128`, `nss-systemd`, `nss-mymachines`, `nss-resolve`, `nss-myhostname`,
|
|
|
|
`pam_systemd`), must be located in `src/basic` (those objects are not allowed
|
|
|
|
to link to `libsystemd-shared.so`). Conversely, anything which is shared
|
|
|
|
between multiple components and does not need to be in `src/basic/`, should be
|
|
|
|
in `src/shared/`.
|
2021-06-03 14:37:17 +00:00
|
|
|
|
|
|
|
To summarize:
|
|
|
|
|
|
|
|
`src/basic/`
|
|
|
|
- may be used by all code in the tree
|
|
|
|
- may not use any code outside of `src/basic/`
|
|
|
|
|
|
|
|
`src/libsystemd/`
|
|
|
|
- may be used by all code in the tree, except for code in `src/basic/`
|
|
|
|
- may not use any code outside of `src/basic/`, `src/libsystemd/`
|
|
|
|
|
|
|
|
`src/shared/`
|
|
|
|
- may be used by all code in the tree, except for code in `src/basic/`,
|
|
|
|
`src/libsystemd/`, `src/nss-*`, `src/login/pam_systemd.*`, and files under
|
|
|
|
`src/journal/` that end up in `libjournal-client.a` convenience library.
|
|
|
|
- may not use any code outside of `src/basic/`, `src/libsystemd/`, `src/shared/`
|
|
|
|
|
|
|
|
## PID 1
|
|
|
|
|
|
|
|
Code located in `src/core/` implements the main logic of the systemd system (and user)
|
|
|
|
service manager.
|
|
|
|
|
|
|
|
BPF helpers written in C and used by PID 1 can be found under `src/core/bpf/`.
|
|
|
|
|
2021-09-13 14:57:54 +00:00
|
|
|
### Implementing Unit Settings
|
|
|
|
|
|
|
|
The system and session manager supports a large number of unit settings. These can generally
|
|
|
|
be configured in three ways:
|
|
|
|
|
|
|
|
1. Via textual, INI-style configuration files called *unit* *files*
|
|
|
|
2. Via D-Bus messages to the manager
|
|
|
|
3. Via the `systemd-run` and `systemctl set-property` commands
|
|
|
|
|
|
|
|
From a user's perspective, the third is a wrapper for the second. To implement a new unit
|
|
|
|
setting, it is necessary to support all three input methods:
|
|
|
|
|
|
|
|
1. *unit* *files* are parsed in `src/core/load-fragment.c`, with many simple and fixed-type
|
|
|
|
unit settings being parsed by common helpers, with the definition in the generator file
|
|
|
|
`src/core/load-fragment-gperf.gperf.in`
|
|
|
|
2. D-Bus messages are defined and parsed in `src/core/dbus-*.c`
|
|
|
|
3. `systemd-run` and `systemctl set-property` do client-side parsing and translating into
|
|
|
|
D-Bus messages in `src/shared/bus-unit-util.c`
|
|
|
|
|
|
|
|
So that they are exercised by the fuzzing CI, new unit settings should also be listed in the
|
|
|
|
text files under `test/fuzz/fuzz-unit-file/`.
|
|
|
|
|
2021-06-03 14:37:17 +00:00
|
|
|
## UDEV
|
|
|
|
|
|
|
|
Sources for the udev daemon and command-line tool (single binary) can be found under
|
|
|
|
`src/udev/`.
|
|
|
|
|
|
|
|
## Unit Tests
|
|
|
|
|
|
|
|
Source files found under `src/test/` implement unit-level testing, mostly for
|
|
|
|
modules found in `src/basic/` and `src/shared/`, but not exclusively. Each test
|
|
|
|
file is compiled in a standalone binary that can be run to exercise the
|
|
|
|
corresponding module. While most of the tests can be ran by any user, some
|
|
|
|
require privileges, and will attempt to clearly log about what they need
|
|
|
|
(mostly in the form of effective capabilities). These tests are self-contained,
|
2021-06-04 08:50:33 +00:00
|
|
|
and generally safe to run on the host without side effects.
|
2021-06-03 14:37:17 +00:00
|
|
|
|
2021-06-04 08:50:33 +00:00
|
|
|
Ideally, every module in `src/basic/` and `src/shared/` should have a
|
|
|
|
corresponding unit test under `src/test/`, exercising every helper function.
|
2021-06-03 14:37:17 +00:00
|
|
|
|
|
|
|
# Integration Tests
|
|
|
|
|
|
|
|
Sources in `test/` implement system-level testing for executables, libraries and
|
|
|
|
daemons that are shipped by the project. They require privileges to run, and
|
|
|
|
are not safe to execute directly on a host. By default they will build an image
|
|
|
|
and run the test under it via `QEMU` or `systemd-nspawn`.
|
|
|
|
|
|
|
|
Most of those tests should be able to run via `systemd-nspawn`, which is orders of
|
|
|
|
magnitude faster than `QEMU`, but some tests require privileged operations like
|
|
|
|
using `dm-crypt` or `loopdev`. They are clearly marked if that is the case.
|
|
|
|
|
|
|
|
See `test/README.testsuite` for more specific details.
|
|
|
|
|
|
|
|
# HWDB
|
|
|
|
|
|
|
|
Rules built in the static `HWDB` database shipped by the project can be found
|
|
|
|
under `hwdb.d/`. Some of these files are updated automatically, some are filled
|
|
|
|
by contributors.
|
|
|
|
|
|
|
|
# Documentation
|
|
|
|
|
|
|
|
## systemd.io
|
|
|
|
|
|
|
|
Markdown files found under `docs/` are automatically published on the
|
|
|
|
[systemd.io](https://systemd.io) website using Github Pages. A minimal unit test
|
|
|
|
to ensure the formatting doesn't have errors is included in the
|
|
|
|
`meson test -C build/ github-pages` run as part of the CI.
|
|
|
|
|
|
|
|
## MAN pages
|
|
|
|
|
|
|
|
Manpages for binaries and libraries, and the DBUS interfaces, can be found under
|
|
|
|
`man/` and should ideally be kept in sync with changes to the corresponding
|
|
|
|
binaries and libraries.
|
|
|
|
|
|
|
|
## Translations
|
|
|
|
|
|
|
|
Translations files for binaries and daemons, provided by volunteers, can be found
|
|
|
|
under `po/` in the usual format. They are kept up to date by contributors and by
|
|
|
|
automated tools.
|
|
|
|
|
|
|
|
# System Configuration files and presets
|
|
|
|
|
|
|
|
Presets (or templates from which they are generated) for various daemons and tools
|
|
|
|
can be found under various directories such as `factory/`, `modprobe.d/`, `network/`,
|
|
|
|
`presets/`, `rules.d/`, `shell-completion/`, `sysctl.d/`, `sysusers.d/`, `tmpfiles.d/`.
|
|
|
|
|
|
|
|
# Utilities for Developers
|
|
|
|
|
|
|
|
`tools/`, `coccinelle/`, `.github/`, `.semaphore/`, `.lgtm/`, `.mkosi/` host various
|
|
|
|
utilities and scripts that are used by maintainers and developers. They are not
|
|
|
|
shipped or installed.
|