rpms/systemd
5
0
Fork 0
Code Issues Pull Requests Releases Activity
changed/a10s/systemd-257-3.el10.alma.1
systemd/0065-docs-Simplify-hacking-documentation.patch
Jan Macku e20fafc72a systemd-257-3 
Resolves: RHEL-44417, RHEL-71409, RHEL-72798
2025-01-08 09:25:36 +01:00

211 lines
9.8 KiB
Diff
Raw Permalink Blame History

From c96a642764e3ceb23c43eff0a49d132caf58bee7 Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Thu, 19 Dec 2024 11:45:01 +0100
Subject: [PATCH] docs: Simplify hacking documentation
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.
(cherry picked from commit 34b5a27b0bfd1b0b35bf67c70d1f8bf5c6795b7d)
---
docs/HACKING.md | 153 +++++++++++++++++++++---------------------------
1 file changed, 68 insertions(+), 85 deletions(-)
diff --git a/docs/HACKING.md b/docs/HACKING.md
index cedf35fef0..2203c32640 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -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).
-
-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.
-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` 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:
+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. Please always test your work before submitting a PR.
+
+## Hacking on systemd with mkosi
+
+[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.
-```conf
-[Host]
-ExtraSearchPaths=build/
-```
+## Building the OS image without a tools tree
-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`:
+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]
-ToolsTree=default
+[Build]
+ToolsTree=
```
-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):
+## Rebuilding systemd without rebuilding the OS image
+
+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
Reference in New Issue View Git Blame Copy Permalink