diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CODING_STYLE.md | 14 | ||||
| -rw-r--r-- | docs/ENVIRONMENT.md | 4 | ||||
| -rw-r--r-- | docs/HACKING.md | 102 | ||||
| -rw-r--r-- | docs/MEMORY_PRESSURE.md | 2 | ||||
| -rw-r--r-- | docs/RELEASE.md | 5 |
5 files changed, 80 insertions, 47 deletions
diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md index 309436a..82ed0a5 100644 --- a/docs/CODING_STYLE.md +++ b/docs/CODING_STYLE.md @@ -54,6 +54,18 @@ SPDX-License-Identifier: LGPL-2.1-or-later } ``` +- Function return types should be seen/written as whole, i.e. write this: + + ```c + const char* foo(const char *input); + ``` + + instead of this: + + ```c + const char *foo(const char *input); + ``` + - Single-line `if` blocks should not be enclosed in `{}`. Write this: ```c @@ -182,7 +194,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later ```c static int foobar_frobnicate( - Foobar* object, /* the associated mutable object */ + Foobar *object, /* the associated mutable object */ const char *input, /* immutable input parameter */ char **ret_frobnicated, /* return parameter on success */ unsigned *reterr_line, /* return parameter on failure */ diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index fd8aa0c..b661f18 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -713,3 +713,7 @@ Tools using the Varlink protocol (such as `varlinkctl`) or sd-bus (such as and `run0` invocations is turned off. Note that this environment variable has no effect if the background color is explicitly selected via the relevant `--background=` switch of the tool. + +* `$SYSTEMD_ADJUST_TERMINAL_TITLE` – Takes a boolean. When false the terminal + window title will not be updated for interactive invocation of the mentioned + tools. diff --git a/docs/HACKING.md b/docs/HACKING.md index 51499d7..5b1e355 100644 --- a/docs/HACKING.md +++ b/docs/HACKING.md @@ -45,27 +45,10 @@ or: $ mkosi qemu ``` -Every time you rerun the `mkosi` command a fresh image is built, -incorporating all current changes you made to the project tree. - -By default a directory image is built. -This requires `virtiofsd` to be installed on the host. -To build a disk image instead which does not require `virtiofsd`, add the following to `mkosi.local.conf`: - -```conf -[Output] -Format=disk -``` - -To boot in UEFI mode instead of using QEMU's direct kernel boot, add the following to `mkosi.local.conf`: - -```conf -[Host] -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`: +Every time you rerun the `mkosi` command a fresh image is built, incorporating +all current changes you made to the project tree. 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] @@ -74,31 +57,21 @@ 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. - -Aside from the image, the `mkosi.output` directory will also be populated with a -set of distribution packages. Assuming you're running the same distribution and -release as the mkosi image, you can install these rpms on your host or test -system as well for any testing or debugging that cannot easily be performed in a -VM or container. - -By default, no debuginfo packages are produced. To produce debuginfo packages, -run mkosi with the `WITH_DEBUG` environment variable set to `1`: +or virtual machine. To build the latest changes and re-install after booting the +image, run `mkosi -t none` in another terminal on the host and run one of the +following commands in the container or virtual machine depending on the +distribution: ```sh -$ mkosi -E WITH_DEBUG=1 -f +dnf upgrade --disablerepo="*" /work/build/*.rpm # CentOS/Fedora +apt install --reinstall /work/build/*.deb # Debian/Ubuntu +pacman -U /work/build/*.pkg.tar # Arch Linux +zypper install --allow-unsigned-rpm /work/build/*.rpm # OpenSUSE ``` -or configure it in `mkosi.local.conf`: - -```conf -[Content] -Environment=WITH_DEBUG=1 -``` +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: @@ -110,6 +83,7 @@ $ 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 @@ -142,6 +116,50 @@ $ meson test -C build Happy hacking! +## Building distribution packages with mkosi + +To build distribution packages for a specific distribution and release without +building an actual image, the following command can be used: + +```sh +mkosi -d <distribution> -r <release> -t none -f +``` + +Afterwards the distribution packages will be located in `build/mkosi.output`. To +also build debuginfo packages, the following command can be used: + +```sh +mkosi -d <distribution> -r <release> -E WITH_DEBUG=1 -t none -f +``` + +To upgrade the systemd packages on the host system to the newer versions built +by mkosi, run the following: + +```sh +dnf upgrade build/mkosi.output/*.rpm # Fedora/CentOS +# TODO: Other distributions +``` + +To downgrade back to the old version shipped by the distribution, run the +following: + +```sh +dnf downgrade "systemd*" # Fedora/CentOS +# TODO: Other distributions +``` + +Additionally, for each pull request, the built distribution packages are +attached as CI artifacts to the pull request CI jobs, which means that users can +download and install them to test out if a pull request fixes the issue that +they reported. To download the packages from a pull request, click on the +`Checks` tab. Then click on the `mkosi` workflow in the list of workflows on the +left of the `Checks` page. Finally, scroll down to find the list of CI +artifacts. In this list of artifacts you can find artifacts containing +distribution packages. To install these, download the artifact which is a zip +archive, extract the zip archive to access the individual packages, and install +them with your package manager in the same way as described above for packages +that were built locally. + ## Templating engines in .in files Some source files are generated during build. We use two templating engines: diff --git a/docs/MEMORY_PRESSURE.md b/docs/MEMORY_PRESSURE.md index da1c9b2..532f894 100644 --- a/docs/MEMORY_PRESSURE.md +++ b/docs/MEMORY_PRESSURE.md @@ -227,7 +227,7 @@ handling, it's typically sufficient to add a line such as: Other programming environments might have native APIs to watch memory pressure/low memory events. Most notable is probably GLib's -[GMemoryMonitor](https://developer-old.gnome.org/gio/stable/GMemoryMonitor.html). It +[GMemoryMonitor](https://docs.gtk.org/gio/iface.MemoryMonitor.html). It currently uses the per-system Linux PSI interface as the backend, but operates differently than the above: memory pressure events are picked up by a system service, which then propagates this through D-Bus to the applications. This is diff --git a/docs/RELEASE.md b/docs/RELEASE.md index f299c62..0d8c0b9 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -23,8 +23,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later 14. "Draft" a new release on github (https://github.com/systemd/systemd/releases/new), mark "This is a pre-release" if appropriate. 15. Check that announcement to systemd-devel, with a copy&paste from NEWS, was sent. This should happen automatically. 16. Update IRC topic (`/msg chanserv TOPIC #systemd Version NNN released | Online resources https://systemd.io/`) -17. [FINAL] Push commits to stable, create an empty -stable branch: `git push systemd-stable --atomic origin/main:main origin/main:refs/heads/${version}-stable`. +17. [FINAL] Create an empty -stable branch: `git push systemd origin/main:refs/heads/v${version}-stable`. 18. [FINAL] Build and upload the documentation (on the -stable branch): `ninja -C build doc-sync` -19. [FINAL] Change the default branch to latest release (https://github.com/systemd/systemd-stable/settings/branches). -20. [FINAL] Change the Github Pages branch in the stable repository to the newly created branch (https://github.com/systemd/systemd-stable/settings/pages) and set the 'Custom domain' to 'systemd.io' +20. [FINAL] Change the Github Pages branch to the newly created branch (https://github.com/systemd/systemd/settings/pages) and set the 'Custom domain' to 'systemd.io' 21. [FINAL] Update version number in `meson.version` to the devel version of the next release (e.g. from `v256` to `v257~devel`) |