Merge pull request #9222 from poettering/code-quality-docs

let's document the code quality tools we have set up

coccinelle/run-coccinelle.sh

@@ -1,5 +1,6 @@
 #!/bin/bash -e
 
+top="$(git rev-parse --show-toplevel)"
 files="$(git ls-files ':/*.[ch]')"
 args=
 
@@ -10,7 +11,7 @@ case "$1" in
                 ;;
 esac
 
-for SCRIPT in ${@-coccinelle/*.cocci} ; do
+for SCRIPT in ${@-$top/coccinelle/*.cocci} ; do
         echo "--x-- Processing $SCRIPT --x--"
         TMPFILE=`mktemp`
         echo "+ spatch --sp-file $SCRIPT $args ..."

doc/CODE_QUALITY.md

@@ -0,0 +1,54 @@
+# Code Quality Tools
+
+The systemd project has a number of code quality tools set up in the source
+tree and on the github infrastructure. Here's an incomprehensive list of the
+available functionality:
+
+1. Use `ninja -C build test` to run the unit tests. Some tests are skipped if
+   no privileges are available, hence consider also running them with `sudo
+   ninja -C build test`. A couple of unit tests are considered "unsafe" (as
+   they change system state); to run those too, build with `meson
+   -Dtests=unsafe`. Finally, some unit tests are considered to be very slow,
+   build them too with `meson -Dslow-tests=true`. (Note that there are a couple
+   of manual tests in addition to these unit tests.)
+
+2. Use `./test/run-integration-tests.sh` to run the full integration test
+   suite. This will build OS images with a number of integration tests and run
+   them in nspawn and qemu. Requires root.
+
+3. Use `./coccinelle/run-coccinelle.sh` to run all
+   [Coccinelle](http://coccinelle.lip6.fr/) semantic patch scripts we ship. The
+   output will show false positives, hence take it with a pinch of salt.
+
+4. Use `./tools/find-double-newline.sh recdiff` to find double newlines. Use
+   `./tools/find-double-newline.sh recpatch` to fix them. Take this with a grain
+   of salt, in particular as we generally leave foreign header files we include in
+   our tree unmodified, if possible.
+
+5. Similar use `./tools/find-tabs.sh recdiff` to find TABs, and
+   `./tools/find-tabs.sh recpatch` to fix them. (Again, grain of salt, foreign
+   headers should usually be left unmodified.)
+
+6. Use `ninja -C build check-api-docs` to compare the the list of exported
+   symbols of `libsystemd.so` and `libudev.so` with the list of man pages. Symbols
+   lacking documentation are highlighted.
+
+7. Use `ninja -C build hwdb-update` to automatically download and import the
+   PCI, USB and OUI databases into hwdb.
+
+8. Use `ninja -C build man/update-man-rules` to update the meson rules for
+   building man pages automatically from the docbook XML files included in
+   `man/`.
+
+9. There are multiple CI systems in use that run on every github PR submission.
+
+10. [Coverity](https://scan.coverity.com/) is analyzing systemd master in
+    regular intervals. The reports are available
+    [online](https://scan.coverity.com/projects/systemd).
+
+11. [oss-fuzz](https://oss-fuzz.com/) is continuously fuzzing the
+    codebase. Reports are available
+    [online](https://oss-fuzz.com/v2/testcases?project=systemd).
+
+Access to Coverity and oss-fuzz reports is limited. Please reach out the the
+maintainers is you need access.

doc/HACKING

@@ -20,6 +20,11 @@ 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 also have a look at our list of code quality tools we have setup for systemd,
+to ensure our codebase stays in good shape:
+
+        https://github.com/systemd/systemd/blob/master/doc/CODE_QUALITY.md
+
 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.

tools/find-double-newline.sh

@@ -1,11 +1,13 @@
 #!/bin/sh
 # SPDX-License-Identifier: LGPL-2.1+
 
+TOP=`git rev-parse --show-toplevel`
+
 case "$1" in
 
         recdiff)
                 if [ "$2" = "" ] ; then
-                        DIR="$PWD/.."
+                        DIR="$TOP"
                 else
                         DIR="$2"
                 fi
@@ -15,7 +17,7 @@ case "$1" in
 
         recpatch)
                 if [ "$2" = "" ] ; then
-                        DIR="$PWD/.."
+                        DIR="$TOP"
                 else
                         DIR="$2"
                 fi

tools/find-tabs.sh

@@ -1,11 +1,13 @@
 #!/bin/sh
 # SPDX-License-Identifier: LGPL-2.1+
 
+TOP=`git rev-parse --show-toplevel`
+
 case "$1" in
 
         recdiff)
                 if [ "$2" = "" ] ; then
-                        DIR="$PWD/.."
+                        DIR="$TOP"
                 else
                         DIR="$2"
                 fi
@@ -15,7 +17,7 @@ case "$1" in
 
         recpatch)
                 if [ "$2" = "" ] ; then
-                        DIR="$PWD/.."
+                        DIR="$TOP"
                 else
                         DIR="$2"
                 fi