test: document how to run CodeQL/LGTM stuff manually

Let's have this documented somewhere so I don't have to relearn all this
stuff every time I need it.

1 files changed, 54 insertions, 0 deletions

diff --git a/test/README.testsuite b/test/README.testsuite
index b943d00bb3..24b98f78cd 100644
--- a/test/README.testsuite
+++ b/test/README.testsuite
@@ -208,3 +208,57 @@ And finally run the autopkgtest itself:
 where --test-name= is the name of the test you want to run/debug. The
 --shell-fail option will pause the execution in case the test fails and shows
 you the information how to connect to the testbed for further debugging.
+
+Manually running LGTM/CodeQL analysis
+=====================================
+
+This is mostly useful for debugging various CodeQL/LGTM quirks.
+
+Download the CodeQL Bundle from https://github.com/github/codeql-action/releases
+and unpack it somewhere. From now the 'tutorial' assumes you have the `codeql`
+binary from the unpacked archive in $PATH for brevity.
+
+Switch to the systemd repository if not already:
+
+$ cd <systemd-repo>
+
+Create an initial CodeQL database:
+
+$ CCACHE_DISABLE=1 codeql database create codeqldb --language=cpp -vvv
+
+Disabling ccache is important, otherwise you might see CodeQL complaining:
+
+No source code was seen and extracted to /home/mrc0mmand/repos/@ci-incubator/systemd/codeqldb.
+This can occur if the specified build commands failed to compile or process any code.
+ - Confirm that there is some source code for the specified language in the project.
+ - For codebases written in Go, JavaScript, TypeScript, and Python, do not specify
+   an explicit --command.
+ - For other languages, the --command must specify a "clean" build which compiles
+   all the source code files without reusing existing build artefacts.
+
+If you want to run all queries systemd uses in LGTM/CodeQL, run:
+
+$ codeql database analyze codeqldb/ --format csv --output results.csv .github/codeql-custom.qls .lgtm/cpp-queries/*.ql -vvv
+
+Note: this will take a while.
+
+If you're interested in a specific check, the easiest way (without hunting down
+the specific CodeQL query file) is to create a custom query suite. For example:
+
+$ cat >test.qls <<EOF
+- queries: .
+  from: codeql/cpp-queries
+- include:
+    id:
+        - cpp/missing-return
+EOF
+
+And then execute it in the same way as above:
+
+$ codeql database analyze codeqldb/ --format csv --output results.csv test.qls -vvv
+
+More about query suites here: https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/
+
+The results are then located in the `results.csv` file as a comma separated
+values list (obviously), which is the most human-friendly output format the
+CodeQL utility provides (so far).