HACKING

   1 HACKING ON SYSTEMD
   2
   3 We welcome all contributions to systemd. If you notice a bug or a missing
   4 feature, please feel invited to fix it, and submit your work as a github Pull
   5 Request (PR):
   6
   7         https://github.com/systemd/systemd/pull/new
   8
   9 Please make sure to follow our Coding Style when submitting patches. See
  10 CODING_STYLE for details. Also have a look at our Contribution Guidelines:
  11
  12         https://github.com/systemd/systemd/blob/master/.github/CONTRIBUTING.md
  13
  14 When adding new functionality, tests should be added. For shared functionality
  15 (in src/basic and src/shared) unit tests should be sufficient. The general
  16 policy is to keep tests in matching files underneath src/test,
  17 e.g. src/test/test-path-util.c contains tests for any functions in
  18 src/basic/path-util.c. If adding a new source file, consider adding a matching
  19 test executable. For features at a higher level, tests in src/test/ are very
  20 strongly recommended. If that is no possible, integration tests in test/ are
  21 encouraged.
  22
  23 Please always test your work before submitting a PR. For many of the components
  24 of systemd testing is straight-forward as you can simply compile systemd and
  25 run the relevant tool from the build directory.
  26
  27 For some components (most importantly, systemd/PID1 itself) this is not
  28 possible, however. In order to simplify testing for cases like this we provide
  29 a set of "mkosi" build files directly in the source tree. "mkosi" is a tool for
  30 building clean OS images from an upstream distribution in combination with a
  31 fresh build of the project in the local working directory. To make use of this,
  32 please acquire "mkosi" from https://github.com/systemd/mkosi first, unless your
  33 distribution has packaged it already and you can get it from there. After the
  34 tool is installed it is sufficient to type "mkosi" in the systemd project
  35 directory to generate a disk image "image.raw" you can boot either in
  36 systemd-nspawn or in an UEFI-capable VM:
  37
  38         # systemd-nspawn -bi image.raw
  39
  40 or:
  41
  42         # qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw
  43
  44 Every time you rerun the "mkosi" command a fresh image is built, incorporating
  45 all current changes you made to the project tree.
  46
  47 Alternatively, you may install the systemd version from your git check-out
  48 directly on top of your host system's directory tree. This mostly works fine,
  49 but of course you should know what you are doing as you might make your system
  50 unbootable in case of a bug in your changes. Also, you might step into your
  51 package manager's territory with this. Be careful!
  52
  53 And never forget: most distributions provide very simple and convenient ways to
  54 install all development packages necessary to build systemd. For example, on
  55 Fedora the following command line should be sufficient to install all of
  56 systemd's build dependencies:
  57
  58         # dnf builddep systemd
  59
  60 Putting this all together, here's a series of commands for preparing a patch
  61 for systemd (this example is for Fedora):
  62
  63         $ sudo dnf builddep systemd            # install build dependencies
  64         $ sudo dnf install mkosi               # install tool to quickly build images
  65         $ git clone https://github.com/systemd/systemd.git
  66         $ cd systemd
  67         $ vim src/core/main.c                  # or wherever you'd like to make your changes
  68         $ meson build                          # configure the build
  69         $ ninja -C build                       # build it locally, see if everything compiles fine
  70         $ ninja -C build test                  # run some simple regression tests
  71         $ sudo mkosi                           # build a test image
  72         $ sudo systemd-nspawn -bi image.raw    # boot up the test image
  73         $ git add -p                           # interactively put together your patch
  74         $ git commit                           # commit it
  75         $ git push REMOTE HEAD:refs/heads/BRANCH
  76                                                # where REMOTE is your "fork" on github
  77                                                # and BRANCH is a branch name.
  78
  79 And after that, head over to your repo on github and click "Compare & pull request"
  80
  81 Happy hacking!