docs/HACKING.md

   1 ---
   2 title: Hacking on systemd
   3 category: Contributing
   4 layout: default
   5 ---
   6
   7 # Hacking on systemd
   8
   9 We welcome all contributions to systemd. If you notice a bug or a missing
  10 feature, please feel invited to fix it, and submit your work as a GitHub Pull
  11 Request (PR) at https://github.com/systemd/systemd/pull/new.
  12
  13 Please make sure to follow our [Coding Style](CODING_STYLE.md) when submitting patches.
  14 Also have a look at our [Contribution Guidelines](CONTRIBUTING.md).
  15
  16 When adding new functionality, tests should be added. For shared functionality
  17 (in `src/basic/` and `src/shared/`) unit tests should be sufficient. The general
  18 policy is to keep tests in matching files underneath `src/test/`,
  19 e.g. `src/test/test-path-util.c` contains tests for any functions in
  20 `src/basic/path-util.c`. If adding a new source file, consider adding a matching
  21 test executable. For features at a higher level, tests in `src/test/` are very
  22 strongly recommended. If that is not possible, integration tests in `test/` are
  23 encouraged.
  24
  25 Please also have a look at our list of [code quality tools](CODE_QUALITY.md) we have setup for systemd,
  26 to ensure our codebase stays in good shape.
  27
  28 Please always test your work before submitting a PR. For many of the components
  29 of systemd testing is straight-forward as you can simply compile systemd and
  30 run the relevant tool from the build directory.
  31
  32 For some components (most importantly, systemd/PID1 itself) this is not
  33 possible, however. In order to simplify testing for cases like this we provide
  34 a set of `mkosi` build files directly in the source tree. `mkosi` is a tool for
  35 building clean OS images from an upstream distribution in combination with a
  36 fresh build of the project in the local working directory. To make use of this,
  37 please acquire `mkosi` from https://github.com/systemd/mkosi first, unless your
  38 distribution has packaged it already and you can get it from there. After the
  39 tool is installed, symlink the settings file for your distribution of choice from
  40 .mkosi/ to mkosi.default in the project root directory (note that the package
  41 manager for this distro needs to be installed on your host system). After doing
  42 that, it is sufficient to type `mkosi` in the systemd project directory to
  43 generate a disk image `image.raw` you can boot either in `systemd-nspawn` or in
  44 an UEFI-capable VM:
  45
  46 ```
  47 # systemd-nspawn -bi image.raw
  48 ```
  49
  50 or:
  51
  52 ```
  53 # qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw
  54 ```
  55
  56 Every time you rerun the `mkosi` command a fresh image is built, incorporating
  57 all current changes you made to the project tree.
  58
  59 Alternatively, you may install the systemd version from your git check-out
  60 directly on top of your host system's directory tree. This mostly works fine,
  61 but of course you should know what you are doing as you might make your system
  62 unbootable in case of a bug in your changes. Also, you might step into your
  63 package manager's territory with this. Be careful!
  64
  65 And never forget: most distributions provide very simple and convenient ways to
  66 install all development packages necessary to build systemd. For example, on
  67 Fedora the following command line should be sufficient to install all of
  68 systemd's build dependencies:
  69
  70 ```
  71 # dnf builddep systemd
  72 ```
  73
  74 Putting this all together, here's a series of commands for preparing a patch
  75 for systemd (this example is for Fedora):
  76
  77 ```sh
  78 $ sudo dnf builddep systemd               # install build dependencies
  79 $ sudo dnf install mkosi                  # install tool to quickly build images
  80 $ git clone https://github.com/systemd/systemd.git
  81 $ cd systemd
  82 $ vim src/core/main.c                     # or wherever you'd like to make your changes
  83 $ meson build                             # configure the build
  84 $ ninja -C build                          # build it locally, see if everything compiles fine
  85 $ ninja -C build test                     # run some simple regression tests
  86 $ ln -s .mkosi/mkosi.fedora mkosi.default # Configure mkosi to build a fedora image
  87 $ (umask 077; echo 123 > mkosi.rootpw)    # set root password used by mkosi
  88 $ sudo mkosi                              # build a test image
  89 $ sudo systemd-nspawn -bi image.raw       # boot up the test image
  90 $ git add -p                              # interactively put together your patch
  91 $ git commit                              # commit it
  92 $ git push REMOTE HEAD:refs/heads/BRANCH
  93                                           # where REMOTE is your "fork" on GitHub
  94                                           # and BRANCH is a branch name.
  95 ```
  96
  97 And after that, head over to your repo on GitHub and click "Compare & pull request"
  98
  99 Happy hacking!
 100
 101
 102 ## Fuzzers
 103
 104 systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically
 105 run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers.
 106 To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput`
 107 function and add it to the list in `src/fuzz/meson.build`.
 108
 109 Whenever possible, a seed corpus and a dictionary should also be added with new
 110 fuzz targets. The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed
 111 corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in
 112 `tools/oss-fuzz.sh`.
 113
 114 The fuzzers can be built locally if you have libFuzzer installed by running
 115 `tools/oss-fuzz.sh`. You should also confirm that the fuzzer runs in the
 116 OSS-Fuzz environment by checking out the OSS-Fuzz repo, and then running
 117 commands like this:
 118
 119 ```
 120 python infra/helper.py build_image systemd
 121 python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd
 122 python infra/helper.py run_fuzzer systemd fuzz-foo
 123 ```
 124
 125 If you find a bug that impacts the security of systemd, please follow the
 126 guidance in [CONTRIBUTING.md](CONTRIBUTING.md) on how to report a security vulnerability.
 127
 128 For more details on building fuzzers and integrating with OSS-Fuzz, visit:
 129
 130 - [Setting up a new project - OSS-Fuzz](https://google.github.io/oss-fuzz/getting-started/new-project-guide/)
 131 - [Tutorials - OSS-Fuzz](https://google.github.io/oss-fuzz/reference/useful-links/#tutorials)