diff options
author | Benjamin Franzke <benjaminfranzke@googlemail.com> | 2022-05-17 15:54:46 +0200 |
---|---|---|
committer | Benjamin Franzke <benjaminfranzke@googlemail.com> | 2022-05-17 23:00:18 +0200 |
commit | 818e46ae7c3159ef3026930c1a4330f66344b2d1 (patch) | |
tree | 417aaf5acf0f2ba950df2e719c07ff8ca7927ecb /docs | |
parent | 85b5930b7b3c2099f450438ab02260b41cb3bef3 (diff) | |
download | systemd-818e46ae7c3159ef3026930c1a4330f66344b2d1.tar.gz |
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/
Diffstat (limited to 'docs')
-rw-r--r-- | docs/ARCHITECTURE.md | 34 | ||||
-rw-r--r-- | docs/HACKING.md | 2 | ||||
-rw-r--r-- | docs/RESOLVED-VPNS.md | 10 |
3 files changed, 24 insertions, 22 deletions
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4559f7c7e5..2ae2ac98e3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -5,19 +5,21 @@ layout: default SPDX-License-Identifier: LGPL-2.1-or-later --- -# Code Map +# The systemd Repository Architecture + +## Code Map This section will attempt to provide a high-level overview of the various components of the systemd repository. -# Source Code +## 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 constantly added, so we will not enumerate them all here — the directory names are self-explanatory. -## Shared Code +### 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 @@ -44,14 +46,14 @@ To summarize: `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 +### 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/`. -### Implementing Unit Settings +#### Implementing Unit Settings The system and session manager supports a large number of unit settings. These can generally be configured in three ways: @@ -73,12 +75,12 @@ 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/`. -## systemd-udev +### systemd-udev Sources for the udev daemon and command-line tool (single binary) can be found under `src/udev/`. -## Unit Tests +### 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 @@ -91,7 +93,7 @@ and generally safe to run on the host without side effects. Ideally, every module in `src/basic/` and `src/shared/` should have a corresponding unit test under `src/test/`, exercising every helper function. -## Fuzzing +### Fuzzing 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 @@ -117,7 +119,7 @@ parallelization; see the links for oss-fuzz in [Code quality](https://systemd.io/CODE_QUALITY). For testing and debugging, fuzzers can be executed as any other program, including under `valgrind` or `gdb`. -# Integration Tests +## Integration Tests Sources in `test/TEST-*` implement system-level testing for executables, libraries and daemons that are shipped by the project. They require privileges @@ -131,40 +133,40 @@ is the case. See `test/README.testsuite` for more specific details. -# hwdb +## hwdb Rules built in the static hardware database shipped by the project can be found under `hwdb.d/`. Some of these files are updated automatically, some are filled by contributors. -# Documentation +## Documentation -## systemd.io +### 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 +### 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 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 +## 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 +## Utilities for Developers `tools/`, `coccinelle/`, `.github/`, `.semaphore/`, `.lgtm/`, `.mkosi/` host various utilities and scripts that are used by maintainers and developers. They are not diff --git a/docs/HACKING.md b/docs/HACKING.md index 3f6838cfd0..9d938769ab 100644 --- a/docs/HACKING.md +++ b/docs/HACKING.md @@ -331,7 +331,7 @@ debug and set "processId" to "${command:pickProcess}". Now, when starting the de the PID of the process you want to debug. Run `systemctl show --property MainPID --value <component>` in the container to figure out the PID and enter it when asked and VSCode will attach to that process instead. -# Debugging systemd-boot +## Debugging systemd-boot During boot, systemd-boot and the stub loader will output a message like `systemd-boot@0x0A,0x0B`, providing the location of the text and data sections. These location can then be used to attach diff --git a/docs/RESOLVED-VPNS.md b/docs/RESOLVED-VPNS.md index e06fbc3d2f..97c1125242 100644 --- a/docs/RESOLVED-VPNS.md +++ b/docs/RESOLVED-VPNS.md @@ -112,7 +112,7 @@ and another one with `~corp.company.example` — both suffixes match a lookup fo `foo.corp.company.example`, but the latter interface wins, since the match is for four labels, while the other is for zero labels. -# Putting it Together +## Putting it Together Let's discuss how the three DNS routing concepts above are best used for a reasonably complex scenario consisting of: @@ -159,7 +159,7 @@ else. If `privacy0` is then downed again, `wifi0` will get the regular DNS traffic again, and `company0` will still get the company's internal domain and IP subnet traffic and nothing else. Everything hence works as intended. -# How to Implement this in Your VPN Software +## How to Implement this in Your VPN Software Most likely you want to expose a boolean in some way that declares whether a specific VPN is of the *corporate* or the *privacy* kind: @@ -177,7 +177,7 @@ specific VPN is of the *corporate* or the *privacy* kind: traditional, i.e. with any search domains as acquired, do not set `~.` though, and do not disable `default-route`.) -# The APIs +## The APIs Now we determined how we want to configure things, but how do you actually get the configuration to `systemd-resolved.service`? There are three relevant @@ -222,7 +222,7 @@ interfaces: propagate the `default-route` boolean, nor can be used to configure the `~….in-addr.arpa` or `~.ip6.arpa` routing domains. -# Ordering +## Ordering When configuring per-interface DNS configuration settings it is wise to configure everything *before* actually upping the interface. Once the interface @@ -235,7 +235,7 @@ as the former without the latter has no effect, but the latter without the former will result in DNS traffic possibly being generated, in a non-desirable way given that the routing information is not set yet. -# Downgrading Search Domains to Routing Domains +## Downgrading Search Domains to Routing Domains Many VPN implementations provide a way how VPN servers can inform VPN clients about search domains to use. In some cases it might make sense to install those |