docs/CODE_QUALITY.md

   1 ---
   2 title: Code Quality Tools
   3 category: Contributing
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # Code Quality Tools
   9
  10 The systemd project has a number of code quality tools set up in the source
  11 tree and on the github infrastructure. Here's an incomprehensive list of the
  12 available functionality:
  13
  14 1. Use `meson test -C build` to run the unit tests. Some tests are skipped if
  15    no privileges are available, hence consider also running them with `sudo
  16    meson test -C build`. A couple of unit tests are considered "unsafe" (as
  17    they change system state); to run those too, build with `meson setup
  18    -Dtests=unsafe`. Finally, some unit tests are considered to be very slow,
  19    build them too with `meson setup -Dslow-tests=true`. (Note that there are a
  20    couple of manual tests in addition to these unit tests.) (Also note: you can
  21    change these flags for an already set up build tree, too, with "meson
  22    configure -C build -D…".)
  23
  24 2. Use `./test/run-integration-tests.sh` to run the full integration test
  25    suite. This will build OS images with a number of integration tests and run
  26    them using `systemd-nspawn` and `qemu`. Requires root.
  27
  28 3. Use `./coccinelle/run-coccinelle.sh` to run all
  29    [Coccinelle](http://coccinelle.lip6.fr/) semantic patch scripts we ship. The
  30    output will show false positives, hence take it with a pinch of salt.
  31
  32 4. Use `./tools/find-double-newline.sh recdiff` to find double newlines. Use
  33    `./tools/find-double-newline.sh recpatch` to fix them. Take this with a grain
  34    of salt, in particular as we generally leave foreign header files we include in
  35    our tree unmodified, if possible.
  36
  37 5. Similar use `./tools/find-tabs.sh recdiff` to find TABs, and
  38    `./tools/find-tabs.sh recpatch` to fix them. (Again, grain of salt, foreign
  39    headers should usually be left unmodified.)
  40
  41 6. Use `ninja -C build check-api-docs` to compare the list of exported symbols
  42    of `libsystemd.so` and `libudev.so` with the list of man pages. Symbols
  43    lacking documentation are highlighted.
  44
  45 7. Use `ninja -C build update-hwdb` and `ninja -C build update-hwdb-autosuspend`
  46    to automatically download and import the PCI, USB, and OUI databases and the
  47    autosuspend quirks into the hwdb.
  48
  49 8. Use `ninja -C build update-man-rules` to update the meson rules for building
  50    man pages automatically from the docbook XML files included in `man/`.
  51
  52 9. There are multiple CI systems in use that run on every github pull request
  53    submission or update.
  54
  55 10. [Coverity](https://scan.coverity.com/) is analyzing systemd `main` branch
  56     in regular intervals. The reports are available
  57     [online](https://scan.coverity.com/projects/systemd).
  58
  59 11. [OSS-Fuzz](https://github.com/google/oss-fuzz) is continuously fuzzing the
  60     codebase. Reports are available
  61     [online](https://oss-fuzz.com/testcases?project=systemd&open=yes).
  62     It also builds
  63     [coverage reports](https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_systemd/latest)
  64     daily.
  65
  66 12. Our tree includes `.editorconfig`, `.dir-locals.el` and `.vimrc` files, to
  67     ensure that editors follow the right indentiation styles automatically.
  68
  69 13. When building systemd from a git checkout the build scripts will
  70     automatically enable a git commit hook that ensures whitespace cleanliness.
  71
  72 14. [CodeQL](https://codeql.github.com/) analyzes each PR and every commit
  73     pushed to `main`. The list of active alerts can be found
  74     [here](https://github.com/systemd/systemd/security/code-scanning).
  75
  76 15. Each PR is automatically tested with [Address Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html)
  77     and [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).
  78     See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS)
  79     for more information.
  80
  81 16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell).
  82     The systemd report can be found [here](https://fossies.org/linux/misc/systemd/codespell.html).
  83
  84 Access to Coverity and oss-fuzz reports is limited. Please reach out to the
  85 maintainers if you need access.