# Hacking on systemd
- We welcome all contributions to systemd. If you notice a bug or a missing
- feature, please feel invited to fix it, and submit your work as a
+ We welcome all contributions to systemd.
+ If you notice a bug or a missing feature, please feel invited to fix it, and submit your work as a
[GitHub Pull Request (PR)](https://github.com/systemd/systemd/pull/new).
- Please make sure to follow our [Coding Style](CODING_STYLE) when submitting
- patches. Also have a look at our [Contribution Guidelines](CONTRIBUTING).
+ Please make sure to follow our [Coding Style](CODING_STYLE) when submitting patches.
+ Also have a look at our [Contribution Guidelines](CONTRIBUTING).
- To start, run the following commands in the systemd git repository to set up
- git correctly (running `meson` will run these commands for you automatically):
+ When adding new functionality, tests should be added.
+ For shared functionality (in `src/basic/` and `src/shared/`) unit tests should be sufficient.
+ The general policy is to keep tests in matching files underneath `src/test/`,
+ e.g. `src/test/test-path-util.c` contains tests for any functions in `src/basic/path-util.c`.
+ If adding a new source file, consider adding a matching test executable.
+ For features at a higher level, tests in `src/test/` are very strongly recommended.
+ If that is not possible, integration tests in `test/` are encouraged.
-Please also have a look at our list of [code quality tools](CODE_QUALITY) we have setup for systemd, to ensure our codebase stays in good shape.
+```shell
+$ git config submodule.recurse true
+$ git config fetch.recurseSubmodules on-demand
+$ git config push.recurseSubmodules no
+$ cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
+$ cp tools/git-post-rewrite-hook.sh .git/hooks/post-rewrite
+```
- When adding new functionality, tests should be added. For shared functionality
- (in `src/basic/` and `src/shared/`) unit tests should be sufficient. The general
- policy is to keep tests in matching files underneath `src/test/`,
- e.g. `src/test/test-path-util.c` contains tests for any functions in
- `src/basic/path-util.c`. If adding a new source file, consider adding a matching
- test executable. For features at a higher level, tests in `src/test/` are very
- strongly recommended. If that is not possible, integration tests in `test/` are
- encouraged.
-
- Please also have a look at our list of [code quality tools](CODE_QUALITY) we
- have setup for systemd, to ensure our codebase stays in good shape.
-
- Please always test your work before submitting a PR. For many of the components
- of systemd testing is straightforward as you can simply compile systemd and
- run the relevant tool from the build directory.
-
- For some components (most importantly, systemd/PID 1 itself) this is not
- possible, however. In order to simplify testing for cases like this we provide
- a set of `mkosi` config files directly in the source tree.
- [mkosi](https://github.com/systemd/mkosi) is a tool for building clean OS images
- from an upstream distribution in combination with a fresh build of the project
- in the local working directory. To make use of this, please install the latest
- version of mkosi from the [GitHub repository](https://github.com/systemd/mkosi).
- `mkosi` will build an image for the host distro by default. First, run
- `mkosi genkey` to generate a key and certificate to be used for secure boot and
- verity signing. After that is done, it is sufficient to type `mkosi` in the
- systemd project directory to generate a disk image you can boot either in
- `systemd-nspawn` or in a UEFI-capable VM:
+ Please always test your work before submitting a PR.
+ For many of the components of systemd testing is straightforward as you can simply compile systemd and run the relevant tool from the build directory.
+
+ For some components (most importantly, systemd/PID 1 itself) this is not possible, however.
+ In order to simplify testing for cases like this we provide a set of `mkosi` config files directly in the source tree.
+ [mkosi](https://mkosi.systemd.io/)
+ is a tool for building clean OS images from an upstream distribution in combination with a fresh build of the project in the local working directory.
+ To make use of this, please install `mkosi` v19 or newer using your distribution's package manager or from the
+ [GitHub repository](https://github.com/systemd/mkosi).
+ `mkosi` will build an image for the host distro by default.
+ First, run `mkosi genkey` to generate a key and certificate to be used for secure boot and verity signing.
+ After that is done, it is sufficient to type `mkosi` in the systemd project directory to generate a disk image you can boot either in `systemd-nspawn` or in a UEFI-capable VM:
```sh
$ sudo mkosi boot # nspawn still needs sudo for now
QemuFirmware=uefi
```
- To avoid having to build a new image all the time when iterating on a patch, add
- the following to `mkosi.local.conf`:
++To avoid having to build a new image all the time when iterating on a patch,
++add the following to `mkosi.local.conf`:
+
+```conf
+[Host]
+RuntimeBuildSources=yes
+```
+
+After enabling this setting, the source and build directories will be mounted to
+`/work/src` and `/work/build` respectively when booting the image as a container
+or virtual machine. To build the latest changes and re-install, run
+`meson install -C /work/build --only-changed` in the container or virtual machine
+and optionally restart the daemon(s) you're working on using
+`systemctl restart <units>` or `systemctl daemon-reexec` if you're working on pid1
+or `systemctl soft-reboot` to restart everything.
+
- Putting this all together, here's a series of commands for preparing a patch
- for systemd:
+ Putting this all together, here's a series of commands for preparing a patch for systemd:
```sh
$ git clone https://github.com/systemd/mkosi.git # If mkosi v19 or newer is not packaged by your distribution
./infra/helper.py coverage --no-corpus-download systemd
```
- If you find a bug that impacts the security of systemd, please follow the
- guidance in [CONTRIBUTING.md](CONTRIBUTING) on how to report a security vulnerability.
-If you find a bug that impacts the security of systemd, please follow the guidance in [CONTRIBUTING.md](CONTRIBUTING) on how to report a security vulnerability.
++If you find a bug that impacts the security of systemd,
++please follow the guidance in [CONTRIBUTING.md](CONTRIBUTING) on how to report a security vulnerability.
For more details on building fuzzers and integrating with OSS-Fuzz, visit:
## Debugging systemd with mkosi + vscode
- To simplify debugging systemd when testing changes using mkosi, we're going to show how to attach
- [VSCode](https://code.visualstudio.com/)'s debugger to an instance of systemd running in a mkosi image using
- QEMU.
+ To simplify debugging systemd when testing changes using mkosi, we're going to show how to attach [VSCode](https://code.visualstudio.com/)'s debugger to an instance of systemd running in a mkosi image using QEMU.
- To allow VSCode's debugger to attach to systemd running in a mkosi image, we have to make sure it can access
- the virtual machine spawned by mkosi where systemd is running. After booting the image with `mkosi qemu`, you
- should now be able to connect to it by running `mkosi ssh` from the same directory in another terminal
- window.
-To allow VSCode's debugger to attach to systemd running in a mkosi image, we have to make sure it can access the virtual machine spawned by mkosi where systemd is running.
-mkosi makes this possible via a handy SSH option that makes the generated image accessible via SSH when booted.
-Thus you must build the image with `mkosi --ssh`.
-The easiest way to set the option is to create a file `mkosi.local.conf` in the root of the repository and add the following contents:
-
-```conf
-[Host]
-Ssh=yes
-RuntimeTrees=.
-```
-
-Also make sure that the SSH agent is running on your system and that you've added your SSH key to it with `ssh-add`.
-Also make sure that `virtiofsd` is installed.
-
-After rebuilding the image and booting it with `mkosi qemu`,
++To allow VSCode's debugger to attach to systemd running in a mkosi image,
++we have to make sure it can access the virtual machine spawned by mkosi where systemd is running.
++After booting the image with `mkosi qemu`,
+ you should now be able to connect to it by running `mkosi ssh` from the same directory in another terminal window.
- Now we need to configure VSCode. First, make sure the C/C++ extension is installed. If you're already using
- a different extension for code completion and other IDE features for C in VSCode, make sure to disable the
- corresponding parts of the C/C++ extension in your VSCode user settings by adding the following entries:
+ Now we need to configure VSCode.
+ First, make sure the C/C++ extension is installed.
+ If you're already using a different extension for code completion and other IDE features for C in VSCode,
+ make sure to disable the corresponding parts of the C/C++ extension in your VSCode user settings by adding the following entries:
```json
"C_Cpp.formatting": "Disabled",
The stable interfaces are:
- * **The unit configuration file format**. Unit files written now will stay compatible with future versions of systemd. Extensions to the file format will happen in a way that existing files remain compatible.
+ * **The unit configuration file format**. Unit files written now will stay compatible with future versions of systemd.
+ Extensions to the file format will happen in a way that existing files remain compatible.
- * **The command line interface** of `systemd`, `systemctl`, `loginctl`, `journalctl`, and all other command line utilities installed in `$PATH` and documented in a man page. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of `systemctl status` is not stable, but that of `systemctl show` is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page.
+ * **The command line interface** of `systemd`, `systemctl`, `loginctl`, `journalctl`, and all other command line utilities installed in `$PATH` and documented in a man page.
+ We will make sure that scripts invoking these commands will continue to work with future versions of systemd.
+ Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page.
+ Example: the output of `systemctl status` is not stable, but that of `systemctl show` is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page.
-* **The protocol spoken on the socket referred to by `$NOTIFY_SOCKET`**, as documented in [sd_notify(3)](https://www.freedesktop.org/software/systemd/man/sd_notify.html).
+* **The protocol spoken on the socket referred to by `$NOTIFY_SOCKET`**, as documented in
+ [sd_notify(3)](https://www.freedesktop.org/software/systemd/man/sd_notify.html). Note that, although using
+ libsystemd is a good choice, this protocol can also be reimplemented without external dependencies, as
+ demonstrated in the example listed in
+ [sd_notify(3)](https://www.freedesktop.org/software/systemd/man/devel/sd_notify.html#Notes)
- * Some of the **"special" unit names** and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`.
+ * Some of the **"special" unit names** and their semantics.
+ To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions.
+ To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`.
- * **The D-Bus interfaces of the main service daemon and other daemons**. We try to always preserve backwards compatibility, and intentional breakage is never introduced. Nevertheless, when we find bugs that mean that the existing interface was not useful, or when the implementation did something different than stated by the documentation and the implemented behaviour is not useful, we will fix the implementation and thus introduce a change in behaviour. But the API (parameter counts and types) is never changed, and existing attributes and methods will not be removed.
+ * **The D-Bus interfaces of the main service daemon and other daemons**. We try to always preserve backwards compatibility, and intentional breakage is never introduced.
+ Nevertheless, when we find bugs that mean that the existing interface was not useful, or when the implementation did something different than stated by the documentation and the implemented behaviour is not useful, we will fix the implementation and thus introduce a change in behaviour.
+ But the API (parameter counts and types) is never changed, and existing attributes and methods will not be removed.
* For a more comprehensive and authoritative list, consult the chart below.
projects / thirdparty / systemd.git / commitdiff
