system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-10-02 22:37:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
systemd/docs/ARCHITECTURE.md

174 lines
7 KiB
Markdown
Raw Normal View History

docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
---
docs: use uppercase letters in title We usually do it that way, do so here, too.
2021-06-04 08:34:56 +00:00
title: systemd Repository Architecture
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
category: Contributing
layout: default
docs: add spdx tags to all .md files I have no idea if this is going to cause rendering problems, and it is fairly hard to check. So let's just merge this, and if it github markdown processor doesn't like it, revert.
2021-09-14 14:05:21 +00:00
SPDX-License-Identifier: LGPL-2.1-or-later
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
---
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
# The systemd Repository Architecture
## Code Map
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
This section will attempt to provide a high-level overview of the various
components of the systemd repository.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
## Source Code
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
Directories in `src/` provide the implementation of all daemons, libraries and
command-line tools shipped by the project. There are many, and more are
docs/ARCHITECTURE: more markup and unicode
2021-06-04 08:50:33 +00:00
constantly added, so we will not enumerate them all here — the directory
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
names are self-explanatory.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### Shared Code
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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
docs/ARCHITECTURE: more markup and unicode
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/`.
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
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/`
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### PID 1
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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/`.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
#### Implementing Unit Settings
docs: generic info about adding directives in ARCHITECTURE.md
2021-09-13 14:57:54 +00:00
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/`.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### systemd-udev
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
Sources for the udev daemon and command-line tool (single binary) can be found under
`src/udev/`.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### Unit Tests
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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
docs: use lowercase "qemu" and other minor tweaks to test docs We used both "qemu" and "QEMU", let's use the lower-case version everywhere since it's also the name of the binary and the version that people are most familiar with. The stuff under test/ is not only for the integeration tests, but also for various other test-related stuff, so adjust the docs a bit.
2022-05-04 10:29:31 +00:00
corresponding module. While most of the tests can be run by any user, some
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
require privileges, and will attempt to clearly log about what they need
(mostly in the form of effective capabilities). These tests are self-contained,
docs/ARCHITECTURE: more markup and unicode
2021-06-04 08:50:33 +00:00
and generally safe to run on the host without side effects.
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
docs/ARCHITECTURE: more markup and unicode
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.
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### Fuzzing
docs/ARCHITECTURE: describe fuzzer locations and use
2022-05-05 16:35:10 +00:00
Fuzzers are a type of unit tests that execute code on an externally-supplied
input sample. Fuzzers are called `fuzz-*`. Fuzzers for `src/basic/` and
`src/shared` live under `src/fuzz/`, and those for other parts of the codebase
should be located next to the code they test.
docs: say that fuzzer input samples should have short names
2022-05-04 10:21:42 +00:00
Files under `test/fuzz/` contain input data for fuzzers, one subdirectory for
each fuzzer. Some of the files are "seed corpora", i.e. files that contain
lists of settings and input values intended to generate initial coverage, and
other files are samples saved by the fuzzing engines when they find an issue.
When adding new input samples under `test/fuzz/*/`, please use some
short-but-meaningful names. Names of meson tests include the input file name
and output looks awkward if they are too long.
docs/ARCHITECTURE: describe fuzzer locations and use
2022-05-05 16:35:10 +00:00
Fuzzers are invoked primarily in three ways: firstly, each fuzzer is compiled
as a normal executable and executed for each of the input samples under
`test/fuzz/` as part of the test suite. Secondly, fuzzers may be instrumented
with sanitizers and invoked as part of the test suite (if `-Dfuzz-tests=true`
is configured). Thirdly, fuzzers are executed through fuzzing engines that try
to find new "interesting" inputs through coverage feedback and massive
docs: use relative links Allows for links to work both on systemd.io (or forks) and when viewed on https://github.com/systemd/systemd/tree/main/docs Note that the markdown links are converted by jekyll-relative-links[1] to html. This plugin is enabled by default on github pages[2][3]. Due to a bug in jekyll-relative-links – see https://github.com/benbalter/jekyll-relative-links/issues/61 – we need to avoid line-wrapped links when using relative markdown links. [1] https://github.com/benbalter/jekyll-relative-links [2] https://github.blog/2016-12-05-relative-links-for-github-pages/ [3] https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins
2022-05-17 22:05:38 +00:00
parallelization; see the links for oss-fuzz in [Code quality](CODE_QUALITY.md).
For testing and debugging, fuzzers can be executed as any other program,
including under `valgrind` or `gdb`.
docs/ARCHITECTURE: describe fuzzer locations and use
2022-05-05 16:35:10 +00:00
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
## Integration Tests
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
docs: use lowercase "qemu" and other minor tweaks to test docs We used both "qemu" and "QEMU", let's use the lower-case version everywhere since it's also the name of the binary and the version that people are most familiar with. The stuff under test/ is not only for the integeration tests, but also for various other test-related stuff, so adjust the docs a bit.
2022-05-04 10:29:31 +00:00
Sources in `test/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`.
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
docs: use lowercase "qemu" and other minor tweaks to test docs We used both "qemu" and "QEMU", let's use the lower-case version everywhere since it's also the name of the binary and the version that people are most familiar with. The stuff under test/ is not only for the integeration tests, but also for various other test-related stuff, so adjust the docs a bit.
2022-05-04 10:29:31 +00:00
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.
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
See `test/README.testsuite` for more specific details.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
## hwdb
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
docs: use lowercase "qemu" and other minor tweaks to test docs We used both "qemu" and "QEMU", let's use the lower-case version everywhere since it's also the name of the binary and the version that people are most familiar with. The stuff under test/ is not only for the integeration tests, but also for various other test-related stuff, so adjust the docs a bit.
2022-05-04 10:29:31 +00:00
Rules built in the static hardware database shipped by the project can be found
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
under `hwdb.d/`. Some of these files are updated automatically, some are filled
by contributors.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
## Documentation
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### systemd.io
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### Man pages
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
### Translations
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
## System Configuration files and presets
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
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/`.
docs: avoid multiple first-level headlines One document should only contain one main headline, both for structuring and for visual reasons. Relevant cases found via: git grep -A2 '^# ' docs/
2022-05-17 13:54:46 +00:00
## Utilities for Developers
docs: add ARCHITECTURE.md with code map Initial and coarse version of a code map, useful for people getting started and looking at the repository for the first time.
2021-06-03 14:37:17 +00:00
`tools/`, `coccinelle/`, `.github/`, `.semaphore/`, `.lgtm/`, `.mkosi/` host various
utilities and scripts that are used by maintainers and developers. They are not
shipped or installed.
Reference in a new issue Copy permalink