| HACKING ON SYSTEMD |
| |
| We welcome all contributions to systemd. If you notice a bug or a missing |
| feature, please feel invited to fix it, and submit your work as a github Pull |
| Request (PR): |
| |
| https://github.com/systemd/systemd/pull/new |
| |
| Please make sure to follow our Coding Style when submitting patches. See |
| doc/CODING_STYLE for details. Also have a look at our Contribution Guidelines: |
| |
| https://github.com/systemd/systemd/blob/master/.github/CONTRIBUTING.md |
| |
| When adding new functionality, tests should be added. For shared functionality |
| (in src/basic and src/shared) unit tests should be sufficient. The general |
| policy is to keep tests in matching files underneath src/test, |
| e.g. src/test/test-path-util.c contains tests for any functions in |
| src/basic/path-util.c. If adding a new source file, consider adding a matching |
| test executable. For features at a higher level, tests in src/test/ are very |
| strongly recommended. If that is no possible, integration tests in test/ are |
| encouraged. |
| |
| Please always test your work before submitting a PR. For many of the components |
| of systemd testing is straight-forward as you can simply compile systemd and |
| run the relevant tool from the build directory. |
| |
| For some components (most importantly, systemd/PID1 itself) this is not |
| possible, however. In order to simplify testing for cases like this we provide |
| a set of "mkosi" build files directly in the source tree. "mkosi" is a tool for |
| building clean OS images from an upstream distribution in combination with a |
| fresh build of the project in the local working directory. To make use of this, |
| please acquire "mkosi" from https://github.com/systemd/mkosi first, unless your |
| distribution has packaged it already and you can get it from there. After the |
| tool is installed it is sufficient to type "mkosi" in the systemd project |
| directory to generate a disk image "image.raw" you can boot either in |
| systemd-nspawn or in an UEFI-capable VM: |
| |
| # systemd-nspawn -bi image.raw |
| |
| or: |
| |
| # qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw |
| |
| Every time you rerun the "mkosi" command a fresh image is built, incorporating |
| all current changes you made to the project tree. |
| |
| Alternatively, you may install the systemd version from your git check-out |
| directly on top of your host system's directory tree. This mostly works fine, |
| but of course you should know what you are doing as you might make your system |
| unbootable in case of a bug in your changes. Also, you might step into your |
| package manager's territory with this. Be careful! |
| |
| And never forget: most distributions provide very simple and convenient ways to |
| install all development packages necessary to build systemd. For example, on |
| Fedora the following command line should be sufficient to install all of |
| systemd's build dependencies: |
| |
| # dnf builddep systemd |
| |
| Putting this all together, here's a series of commands for preparing a patch |
| for systemd (this example is for Fedora): |
| |
| $ sudo dnf builddep systemd # install build dependencies |
| $ sudo dnf install mkosi # install tool to quickly build images |
| $ git clone https://github.com/systemd/systemd.git |
| $ cd systemd |
| $ vim src/core/main.c # or wherever you'd like to make your changes |
| $ meson build # configure the build |
| $ ninja -C build # build it locally, see if everything compiles fine |
| $ ninja -C build test # run some simple regression tests |
| $ sudo mkosi # build a test image |
| $ sudo systemd-nspawn -bi image.raw # boot up the test image |
| $ git add -p # interactively put together your patch |
| $ git commit # commit it |
| $ git push REMOTE HEAD:refs/heads/BRANCH |
| # where REMOTE is your "fork" on github |
| # and BRANCH is a branch name. |
| |
| And after that, head over to your repo on github and click "Compare & pull request" |
| |
| Happy hacking! |
| |
| |
| FUZZERS |
| |
| systemd includes fuzzers in src/fuzz that use libFuzzer and are automatically |
| run by OSS-Fuzz (https://github.com/google/oss-fuzz) with sanitizers. To add a |
| fuzz target, create a new src/fuzz/fuzz-foo.c file with a LLVMFuzzerTestOneInput |
| function and add it to the list in src/fuzz/meson.build. |
| |
| Whenever possible, a seed corpus and a dictionary should also be added with new |
| fuzz targets. The dictionary should be named src/fuzz/fuzz-foo.dict and the seed |
| corpus should be built and exported as $OUT/fuzz-foo_seed_corpus.zip in |
| scripts/oss-fuzz.sh. |
| |
| The fuzzers can be built locally if you have libFuzzer installed by running |
| scripts/oss-fuzz.sh. You should also confirm that the fuzzer runs in the |
| OSS-Fuzz environment by checking out the OSS-Fuzz repo, and then running |
| commands like this: |
| |
| python infra/helper.py build_image systemd |
| python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd |
| python infra/helper.py run_fuzzer systemd fuzz-foo |
| |
| If you find a bug that impacts the security of systemd, please follow the |
| guidance in .github/CONTRIBUTING.md on how to report a security vulnerability. |
| |
| For more details on building fuzzers and integrating with OSS-Fuzz, visit: |
| |
| https://github.com/google/oss-fuzz/blob/master/docs/new_project_guide.md |
| |
| https://llvm.org/docs/LibFuzzer.html |
| |
| https://github.com/google/fuzzer-test-suite/blob/master/tutorial/libFuzzerTutorial.md |
| |
| https://chromium.googlesource.com/chromium/src/testing/libfuzzer/+/HEAD/efficient_fuzzer.md |