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 # Hacking on systemd
We welcome all contributions to systemd. We welcome all contributions to systemd. If you notice a bug or a missing
If you notice a bug or a missing feature, please feel invited to fix it, and submit your work as a feature, please feel invited to fix it, and submit your work as a
[GitHub Pull Request (PR)](https://github.com/systemd/systemd/pull/new). [GitHub Pull Request (PR)](https://github.com/systemd/systemd/pull/new).
Please make sure to follow our [Coding Style](/CODING_STYLE) when submitting patches. Please make sure to follow our [Coding Style](/CODING_STYLE) when submitting
Also have a look at our [Contribution Guidelines](/CONTRIBUTING). patches. Also have a look at our [Contribution Guidelines](/CONTRIBUTING).
When adding new functionality, tests should be added. When adding new functionality, tests should be added. For shared functionality
For shared functionality (in `src/basic/` and `src/shared/`) unit tests should be sufficient. (in `src/basic/` and `src/shared/`) unit tests should be sufficient. The general
The general policy is to keep tests in matching files underneath `src/test/`, policy is to keep tests in matching files underneath `src/test/`, e.g.
e.g. `src/test/test-path-util.c` contains tests for any functions in `src/basic/path-util.c`. `src/test/test-path-util.c` contains tests for any functions in
If adding a new source file, consider adding a matching test executable. `src/basic/path-util.c`. If adding a new source file, consider adding a matching
For features at a higher level, tests in `src/test/` are very strongly recommended. test executable. For features at a higher level, tests in `src/test/` are very
If that is not possible, integration tests in `test/` are encouraged. 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. ## Hacking on systemd with mkosi
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. [mkosi](https://mkosi.systemd.io/) is our swiss army knife for hacking on
In order to simplify testing for cases like this we provide a set of `mkosi` config files directly in the source tree. systemd. It makes sure all necessary dependencies are available to build systemd
[mkosi](https://mkosi.systemd.io/) and allows building and booting an OS image with the latest systemd installed
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. for testing purposes.
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, install `mkosi` from the
First, run `mkosi genkey` to generate a key and certificate to be used for secure boot and verity signing. [GitHub repository](https://github.com/systemd/mkosi#running-mkosi-from-the-repository).
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: 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 ```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 ```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. Putting this all together, here's a series of commands for preparing a patch for
Sometimes we start using mkosi features that rely on functionality in systemd 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:
```sh ```sh
# Fedora $ git clone https://github.com/systemd/mkosi.git
$ sudo dnf builddep systemd $ ln -s $PWD/mkosi/bin/mkosi ~/.local/bin/mkosi # Make sure ~/.local/bin is in $PATH.
# Debian/Ubuntu $ git clone https://github.com/systemd/systemd.git
$ sudo apt-get build-dep systemd
# Arch
$ sudo pacman -S devtools
$ pkgctl repo clone --protocol=https systemd
$ cd systemd $ 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 Happy hacking!
$ meson setup build <options>
$ ninja -C build
$ meson test -C build
```
To have `mkosi` use the systemd tools from the `build/` directory, add the The following sections contain advanced topics on how to speed up development or
following to `mkosi.local.conf`: 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 ```conf
[Host] [Build]
ExtraSearchPaths=build/ ToolsTree=
``` ```
And if you want `mkosi` to build a tools image and use the tools from there ## Rebuilding systemd without rebuilding the OS image
instead of looking for tools on the host, add the following to
`mkosi.local.conf`:
```conf Every time the `mkosi` target is built, a fresh image is built. To build the
[Host] latest changes and re-install systemd without rebuilding the image, run one of
ToolsTree=default 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):
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):
```sh ```sh
mkosi -t none && mkosi ssh dnf upgrade --disablerepo="*" --assumeyes "/work/build/*.rpm" # CentOS/Fedora 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 `systemctl restart <units>` or `systemctl daemon-reexec` if you're working on
pid1 or `systemctl soft-reboot` to restart everything. 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 ## Building distribution packages with mkosi
To build distribution packages for a specific distribution and release without To build distribution packages for a specific distribution and release without