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