mirror of
https://github.com/systemd/systemd.git
synced 2024-10-26 17:27:41 +03: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/
This commit is contained in:
parent
85b5930b7b
commit
818e46ae7c
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user