]>
Commit | Line | Data |
---|---|---|
c3e270f4 FB |
1 | --- |
2 | title: Hacking on systemd | |
4cdca0af | 3 | category: Contributing |
b41a3f66 | 4 | layout: default |
c3e270f4 FB |
5 | --- |
6 | ||
5a8a9dee FA |
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 | |
1e268f42 | 22 | strongly recommended. If that is not possible, integration tests in `test/` are |
5a8a9dee FA |
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 it is sufficient to type `mkosi` in the systemd project | |
40 | directory to generate a disk image `image.raw` you can boot either in | |
41 | `systemd-nspawn` or in an UEFI-capable VM: | |
42 | ||
43 | ``` | |
44 | # systemd-nspawn -bi image.raw | |
45 | ``` | |
46 | ||
47 | or: | |
48 | ||
49 | ``` | |
50 | # qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw | |
51 | ``` | |
52 | ||
53 | Every time you rerun the `mkosi` command a fresh image is built, incorporating | |
54 | all current changes you made to the project tree. | |
55 | ||
56 | Alternatively, you may install the systemd version from your git check-out | |
57 | directly on top of your host system's directory tree. This mostly works fine, | |
58 | but of course you should know what you are doing as you might make your system | |
59 | unbootable in case of a bug in your changes. Also, you might step into your | |
60 | package manager's territory with this. Be careful! | |
61 | ||
62 | And never forget: most distributions provide very simple and convenient ways to | |
63 | install all development packages necessary to build systemd. For example, on | |
64 | Fedora the following command line should be sufficient to install all of | |
65 | systemd's build dependencies: | |
66 | ||
67 | ``` | |
68 | # dnf builddep systemd | |
69 | ``` | |
70 | ||
71 | Putting this all together, here's a series of commands for preparing a patch | |
72 | for systemd (this example is for Fedora): | |
73 | ||
74 | ```sh | |
75 | $ sudo dnf builddep systemd # install build dependencies | |
76 | $ sudo dnf install mkosi # install tool to quickly build images | |
77 | $ git clone https://github.com/systemd/systemd.git | |
78 | $ cd systemd | |
79 | $ vim src/core/main.c # or wherever you'd like to make your changes | |
80 | $ meson build # configure the build | |
81 | $ ninja -C build # build it locally, see if everything compiles fine | |
82 | $ ninja -C build test # run some simple regression tests | |
83 | $ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi | |
84 | $ sudo mkosi # build a test image | |
85 | $ sudo systemd-nspawn -bi image.raw # boot up the test image | |
86 | $ git add -p # interactively put together your patch | |
87 | $ git commit # commit it | |
88 | $ git push REMOTE HEAD:refs/heads/BRANCH | |
89 | # where REMOTE is your "fork" on GitHub | |
90 | # and BRANCH is a branch name. | |
91 | ``` | |
92 | ||
93 | And after that, head over to your repo on GitHub and click "Compare & pull request" | |
94 | ||
95 | Happy hacking! | |
96 | ||
97 | ||
98 | ## Fuzzers | |
99 | ||
100 | systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically | |
53a42e62 JP |
101 | run by [OSS-Fuzz](https://github.com/google/oss-fuzz) and [Fuzzit](https://fuzzit.dev) with sanitizers. |
102 | To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput` | |
5a8a9dee FA |
103 | function and add it to the list in `src/fuzz/meson.build`. |
104 | ||
105 | Whenever possible, a seed corpus and a dictionary should also be added with new | |
106 | fuzz targets. The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed | |
107 | corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in | |
108 | `tools/oss-fuzz.sh`. | |
109 | ||
110 | The fuzzers can be built locally if you have libFuzzer installed by running | |
111 | `tools/oss-fuzz.sh`. You should also confirm that the fuzzer runs in the | |
112 | OSS-Fuzz environment by checking out the OSS-Fuzz repo, and then running | |
113 | commands like this: | |
114 | ||
115 | ``` | |
116 | python infra/helper.py build_image systemd | |
117 | python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd | |
118 | python infra/helper.py run_fuzzer systemd fuzz-foo | |
119 | ``` | |
120 | ||
53a42e62 JP |
121 | When you add a new target you should also add the target on [Fuzzit](https://app.fuzzit.dev/admin/RxqRpGNXquIvqrmp4iJS/dashboard) |
122 | (Please ask someone with permissions). One the target is configured on Fuzzit you need to add it to | |
123 | `travis-ci/managers/fuzzit.sh` so the new target will run sanity tests on every pull-request and periodic fuzzing jobs. | |
124 | ||
5a8a9dee FA |
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 | ||
6cec69fc LK |
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) |