From 6b0020749d4b1711b669ba68fe74474f8241f084 Mon Sep 17 00:00:00 2001
From: Jade Lovelace <lix@jade.fyi>
Date: Sun, 17 Mar 2024 19:54:58 -0700
Subject: clang-tidy check infrastructure

This brings in infrastructure for developing new custom clang-tidy lints
and refactors for Lix.

Change-Id: I3df5f5855712ab4f97d4e84d771e5e818f81f881
---
 clang-tidy/README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 clang-tidy/README.md

(limited to 'clang-tidy/README.md')

diff --git a/clang-tidy/README.md b/clang-tidy/README.md
new file mode 100644
index 000000000..cf46c71ec
--- /dev/null
+++ b/clang-tidy/README.md
@@ -0,0 +1,56 @@
+# Clang tidy lints for Nix
+
+This is a skeleton of a clang-tidy lints library for Nix.
+
+Currently there is one check (which is already obsolete as it has served its
+goal and is there as an example), `HasPrefixSuffixCheck`.
+
+## Running fixes/checks
+
+One file:
+
+```
+ninja -C build && clang-tidy --checks='-*,nix-*' --load=build/libnix-clang-tidy.so -p ../compile_commands.json --fix ../src/libcmd/installables.cc
+```
+
+Several files, in parallel:
+
+```
+ninja -C build && run-clang-tidy -checks='-*,nix-*' -load=build/libnix-clang-tidy.so -p .. -fix ../src | tee -a clang-tidy-result
+```
+
+## Resources
+
+* https://firefox-source-docs.mozilla.org/code-quality/static-analysis/writing-new/clang-query.html
+* https://clang.llvm.org/docs/LibASTMatchersReference.html
+* https://devblogs.microsoft.com/cppblog/exploring-clang-tooling-part-3-rewriting-code-with-clang-tidy/
+
+## Developing new checks
+
+Put something like so in `myquery.txt`:
+
+```
+set traversal     IgnoreUnlessSpelledInSource
+# ^ Ignore implicit AST nodes. May need to use AsIs depending on how you are
+# working.
+set bind-root     true
+# ^ true unless you use any .bind("foo") commands
+set print-matcher true
+enable output     dump
+match callExpr(callee(functionDecl(hasName("hasPrefix"))), optionally(hasArgument( 0, cxxConstructExpr(hasDeclaration(functionDecl(hasParameter(0, parmVarDecl(hasType(asString("const char *"))).bind("meow2"))))))))
+```
+
+Then run, e.g. `clang-query --preload hasprefix.query -p compile_commands.json src/libcmd/installables.cc`.
+
+With this you can iterate a query before writing it in C++ and suffering from
+C++.
+
+### Tips and tricks for the C++
+
+There is a function `dump()` on many things that will dump to stderr. Also
+`llvm::errs()` lets you print to stderr.
+
+When I wrote `HasPrefixSuffixCheck`, I was not really able to figure out how
+the structured replacement system was supposed to work. In principle you can
+describe the replacement with a nice DSL. Look up the Stencil system in Clang
+for details.
-- 
cgit v1.2.3