]>
Commit | Line | Data |
---|---|---|
e4a3e122 LP |
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 | |
9e825ebf | 10 | docs/CODING_STYLE for details. Also have a look at our Contribution Guidelines: |
e4a3e122 | 11 | |
c2beadcd | 12 | https://github.com/systemd/systemd/blob/master/docs/CONTRIBUTING.md |
e4a3e122 | 13 | |
8f8dc208 ZJS |
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 | ||
ecb462db LP |
23 | Please also have a look at our list of code quality tools we have setup for systemd, |
24 | to ensure our codebase stays in good shape: | |
25 | ||
9e825ebf | 26 | https://github.com/systemd/systemd/blob/master/docs/CODE_QUALITY.md |
ecb462db | 27 | |
e4a3e122 LP |
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 | # systemd-nspawn -bi image.raw | |
44 | ||
45 | or: | |
46 | ||
676a0406 | 47 | # qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw |
e4a3e122 LP |
48 | |
49 | Every time you rerun the "mkosi" command a fresh image is built, incorporating | |
50 | all current changes you made to the project tree. | |
51 | ||
52 | Alternatively, you may install the systemd version from your git check-out | |
53 | directly on top of your host system's directory tree. This mostly works fine, | |
54 | but of course you should know what you are doing as you might make your system | |
55 | unbootable in case of a bug in your changes. Also, you might step into your | |
56 | package manager's territory with this. Be careful! | |
57 | ||
58 | And never forget: most distributions provide very simple and convenient ways to | |
59 | install all development packages necessary to build systemd. For example, on | |
60 | Fedora the following command line should be sufficient to install all of | |
61 | systemd's build dependencies: | |
62 | ||
63 | # dnf builddep systemd | |
64 | ||
65 | Putting this all together, here's a series of commands for preparing a patch | |
66 | for systemd (this example is for Fedora): | |
67 | ||
39988d11 ZJS |
68 | $ sudo dnf builddep systemd # install build dependencies |
69 | $ sudo dnf install mkosi # install tool to quickly build images | |
e4a3e122 LP |
70 | $ git clone https://github.com/systemd/systemd.git |
71 | $ cd systemd | |
72 | $ vim src/core/main.c # or wherever you'd like to make your changes | |
02263eb7 ZJS |
73 | $ meson build # configure the build |
74 | $ ninja -C build # build it locally, see if everything compiles fine | |
75 | $ ninja -C build test # run some simple regression tests | |
c8475a8f | 76 | $ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi |
e4a3e122 LP |
77 | $ sudo mkosi # build a test image |
78 | $ sudo systemd-nspawn -bi image.raw # boot up the test image | |
79 | $ git add -p # interactively put together your patch | |
80 | $ git commit # commit it | |
02263eb7 ZJS |
81 | $ git push REMOTE HEAD:refs/heads/BRANCH |
82 | # where REMOTE is your "fork" on github | |
83 | # and BRANCH is a branch name. | |
e4a3e122 | 84 | |
02263eb7 | 85 | And after that, head over to your repo on github and click "Compare & pull request" |
e4a3e122 LP |
86 | |
87 | Happy hacking! | |
8b53eb4d JR |
88 | |
89 | ||
90 | FUZZERS | |
91 | ||
92 | systemd includes fuzzers in src/fuzz that use libFuzzer and are automatically | |
93 | run by OSS-Fuzz (https://github.com/google/oss-fuzz) with sanitizers. To add a | |
94 | fuzz target, create a new src/fuzz/fuzz-foo.c file with a LLVMFuzzerTestOneInput | |
95 | function and add it to the list in src/fuzz/meson.build. | |
96 | ||
97 | Whenever possible, a seed corpus and a dictionary should also be added with new | |
98 | fuzz targets. The dictionary should be named src/fuzz/fuzz-foo.dict and the seed | |
99 | corpus should be built and exported as $OUT/fuzz-foo_seed_corpus.zip in | |
9037a0e0 | 100 | tools/oss-fuzz.sh. |
8b53eb4d JR |
101 | |
102 | The fuzzers can be built locally if you have libFuzzer installed by running | |
9037a0e0 | 103 | tools/oss-fuzz.sh. You should also confirm that the fuzzer runs in the |
33d62eba JR |
104 | OSS-Fuzz environment by checking out the OSS-Fuzz repo, and then running |
105 | commands like this: | |
8b53eb4d JR |
106 | |
107 | python infra/helper.py build_image systemd | |
33d62eba | 108 | python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd |
8b53eb4d JR |
109 | python infra/helper.py run_fuzzer systemd fuzz-foo |
110 | ||
d385cd0c | 111 | If you find a bug that impacts the security of systemd, please follow the |
7fe96758 | 112 | guidance in CONTRIBUTING.md on how to report a security vulnerability. |
d385cd0c | 113 | |
8b53eb4d JR |
114 | For more details on building fuzzers and integrating with OSS-Fuzz, visit: |
115 | ||
116 | https://github.com/google/oss-fuzz/blob/master/docs/new_project_guide.md | |
117 | ||
118 | https://llvm.org/docs/LibFuzzer.html | |
119 | ||
120 | https://github.com/google/fuzzer-test-suite/blob/master/tutorial/libFuzzerTutorial.md | |
121 | ||
122 | https://chromium.googlesource.com/chromium/src/testing/libfuzzer/+/HEAD/efficient_fuzzer.md |