mirror of
https://github.com/systemd/systemd.git
synced 2024-10-31 07:51:21 +03:00
c3e270f4ee
It turns out Jekyll (the engine behind GitHub Pages) requires that pages
include a "Front Matter" snippet of YAML at the top for proper rendering.
Omitting it will still render the pages, but including it opens up new
possibilities, such as using a {% for %} loop to generate index.md instead of
requiring a separate script.
I'm hoping this will also fix the issue with some of the pages (notably
CODE_OF_CONDUCT.html) not being available under systemd.io
Tested locally by rendering the website with Jekyll. Before this change, the
*.md files were kept unchanged (so not sure how that even works?!), after this
commit, proper *.html files were generated from it.
128 lines
5.7 KiB
Markdown
128 lines
5.7 KiB
Markdown
---
|
|
title: Hacking on systemd
|
|
---
|
|
|
|
# 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) at https://github.com/systemd/systemd/pull/new.
|
|
|
|
Please make sure to follow our [Coding Style](CODING_STYLE.md) when submitting patches.
|
|
Also have a look at our [Contribution Guidelines](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 not possible, integration tests in `test/` are
|
|
encouraged.
|
|
|
|
Please also have a look at our list of [code quality tools](CODE_QUALITY.md) we have setup for systemd,
|
|
to ensure our codebase stays in good shape.
|
|
|
|
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):
|
|
|
|
```sh
|
|
$ 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
|
|
$ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi
|
|
$ 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
|
|
`tools/oss-fuzz.sh`.
|
|
|
|
The fuzzers can be built locally if you have libFuzzer installed by running
|
|
`tools/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 [CONTRIBUTING.md](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
|