shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-21 13:34:21 +03:00
Code

docs: Simplify hacking documentation

Browse Source 
Let's use "mkosi sandbox" in the docs so that users can build systemd
without having to install anything except mkosi. Using mkosi sandbox
will use tools and dependencies from the tools tree which is also used
in CI and thus has a higher chance of working from the first try compared
to whatever tools might be installed on the host system of a new contributor.
This commit is contained in:
Daan De Meyer 2024-12-19 11:45:01 +01:00
parent ba3f148307
commit 34b5a27b0b
1 changed files with 66 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/HACKING.md
View File

@ -7,94 +7,97 @@ SPDX-License-Identifier: LGPL-2.1-or-later
# 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).
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.
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 always test your work before submitting a PR.
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.
## Hacking on systemd with mkosi
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` from the [GitHub repository](https://github.com/systemd/mkosi#running-mkosi-from-the-repository).
`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:
[mkosi](https://mkosi.systemd.io/) is our swiss army knife for hacking on
systemd. It makes sure all necessary dependencies are available to build systemd
and allows building and booting an OS image with the latest systemd installed
for testing purposes.
First, install `mkosi` from the
[GitHub repository](https://github.com/systemd/mkosi#running-mkosi-from-the-repository).
Note that it's not possible to use your distribution's packaged version of mkosi
as mkosi has to be installed outside of `/usr` for the following steps to work.
Then, you can build and run systemd executables as follows:
```sh
$ sudo mkosi boot # nspawn still needs sudo for now
$ mkosi -f sandbox meson setup build
$ mkosi -f sandbox ninja -C build
$ mkosi -f sandbox build/systemctl --version
```
or:
To build and boot an OS image with the latest systemd installed:
```sh
$ mkosi qemu
$ mkosi -f genkey # Generate signing keys once.
$ mkosi -f sandbox ninja -C build mkosi # (re-)build the OS image
$ sudo mkosi boot # Boot the image with systemd-nspawn.
$ mkosi qemu # Boot the image with qemu.
```
By default, the tools from your host system are used to build the image.
Sometimes we start using mkosi features that rely on functionality in systemd
tools that's not in an official release yet. In that case, you'll need to build
systemd from source on the host and configure mkosi to use the tools from the
systemd build directory.
To do a local build, most distributions provide very simple and convenient ways
to install most development packages necessary to build systemd:
Putting this all together, here's a series of commands for preparing a patch for
systemd:
```sh
# Fedora
$ sudo dnf builddep systemd
# Debian/Ubuntu
$ sudo apt-get build-dep systemd
# Arch
$ sudo pacman -S devtools
$ pkgctl repo clone --protocol=https systemd
$ git clone https://github.com/systemd/mkosi.git
$ ln -s $PWD/mkosi/bin/mkosi ~/.local/bin/mkosi # Make sure ~/.local/bin is in $PATH.
$ git clone https://github.com/systemd/systemd.git
$ cd systemd
$ makepkg -seoc
$ git checkout -b <BRANCH> # where BRANCH is the name of the branch
$ $EDITOR src/core/main.c # or wherever you'd like to make your changes
$ mkosi -f sandbox meson setup build # Set up meson
$ mkosi -f genkey # Generate signing keys once.
$ mkosi -f sandbox ninja -C build mkosi # (re-)build the test image
$ mkosi qemu # Boot the image in qemu
$ git add -p # interactively put together your patch
$ git commit # commit it
$ git push -u <REMOTE> # where REMOTE is your "fork" on GitHub
```
After installing the development packages, systemd can be built from source as follows:
And after that, head over to your repo on GitHub and click "Compare & pull
request"
```sh
$ meson setup build <options>
$ ninja -C build
$ meson test -C build
```
Happy hacking!
To have `mkosi` use the systemd tools from the `build/` directory, add the
following to `mkosi.local.conf`:
The following sections contain advanced topics on how to speed up development or
streamline debugging. Feel free to read them if you're interested but they're
not required to write basic patches.
## Building the OS image without a tools tree
By default, `mkosi` will first build a tools tree and use it build the image and
provide the environment for `mkosi sandbox`. To disable the tools tree and use
binaries from your host instead, write the following to `mkosi.local.conf`:
```conf
[Host]
ExtraSearchPaths=build/
[Build]
ToolsTree=
```
And if you want `mkosi` to build a tools image and use the tools from there
instead of looking for tools on the host, add the following to
`mkosi.local.conf`:
## Rebuilding systemd without rebuilding the OS image
```conf
[Host]
ToolsTree=default
```
Every time you rerun the `mkosi` command a fresh image is built, incorporating
all current changes you made to the project tree. To build the latest changes
and re-install after booting the image, run one of the following commands in
another terminal on your host (choose the right one depending on the
distribution of the container or virtual machine):
Every time the `mkosi` target is built, a fresh image is built. To build the
latest changes and re-install systemd without rebuilding the image, run one of
the following commands in another terminal on your host after booting the image
(choose the right one depending on the distribution of the container or virtual
machine):
```sh
mkosi -t none && mkosi ssh dnf upgrade --disablerepo="*" --assumeyes "/work/build/*.rpm" # CentOS/Fedora
@ -107,26 +110,6 @@ 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:
```sh
$ git clone https://github.com/systemd/mkosi.git
$ ln -s $PWD/mkosi/bin/mkosi /usr/local/bin/mkosi
$ git clone https://github.com/systemd/systemd.git
$ cd systemd
$ git checkout -b <BRANCH> # where BRANCH is the name of the branch
$ vim src/core/main.c # or wherever you'd like to make your changes
$ mkosi -f qemu # (re-)build and boot up the test image in qemu
$ mkosi -t none # Build new packages without rebuilding the image
$ git add -p # interactively put together your patch
$ git commit # commit it
$ git push -u <REMOTE> # where REMOTE is your "fork" on GitHub
```
And after that, head over to your repo on GitHub and click "Compare & pull request"
Happy hacking!
## Building distribution packages with mkosi
To build distribution packages for a specific distribution and release without