summaryrefslogtreecommitdiffstats
path: root/contrib/coccinelle/README
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 14:47:53 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 14:47:53 +0000
commitc8bae7493d2f2910b57f13ded012e86bdcfb0532 (patch)
tree24e09d9f84dec336720cf393e156089ca2835791 /contrib/coccinelle/README
parentInitial commit. (diff)
downloadgit-c8bae7493d2f2910b57f13ded012e86bdcfb0532.tar.xz
git-c8bae7493d2f2910b57f13ded012e86bdcfb0532.zip
Adding upstream version 1:2.39.2.upstream/1%2.39.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--contrib/coccinelle/README92
1 files changed, 92 insertions, 0 deletions
diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README
new file mode 100644
index 0000000..d1daa1f
--- /dev/null
+++ b/contrib/coccinelle/README
@@ -0,0 +1,92 @@
+This directory provides examples of Coccinelle (http://coccinelle.lip6.fr/)
+semantic patches that might be useful to developers.
+
+There are two types of semantic patches:
+
+ * Using the semantic transformation to check for bad patterns in the code;
+ The target 'make coccicheck' is designed to check for these patterns and
+ it is expected that any resulting patch indicates a regression.
+ The patches resulting from 'make coccicheck' are small and infrequent,
+ so once they are found, they can be sent to the mailing list as per usual.
+
+ Example for introducing new patterns:
+ 67947c34ae (convert "hashcmp() != 0" to "!hasheq()", 2018-08-28)
+ b84c783882 (fsck: s/++i > 1/i++/, 2018-10-24)
+
+ Example of fixes using this approach:
+ 248f66ed8e (run-command: use strbuf_addstr() for adding a string to
+ a strbuf, 2018-03-25)
+ f919ffebed (Use MOVE_ARRAY, 2018-01-22)
+
+ These types of semantic patches are usually part of testing, c.f.
+ 0860a7641b (travis-ci: fail if Coccinelle static analysis found something
+ to transform, 2018-07-23)
+
+ * Using semantic transformations in large scale refactorings throughout
+ the code base.
+
+ When applying the semantic patch into a real patch, sending it to the
+ mailing list in the usual way, such a patch would be expected to have a
+ lot of textual and semantic conflicts as such large scale refactorings
+ change function signatures that are used widely in the code base.
+ A textual conflict would arise if surrounding code near any call of such
+ function changes. A semantic conflict arises when other patch series in
+ flight introduce calls to such functions.
+
+ So to aid these large scale refactorings, semantic patches can be used.
+ However we do not want to store them in the same place as the checks for
+ bad patterns, as then automated builds would fail.
+ That is why semantic patches 'contrib/coccinelle/*.pending.cocci'
+ are ignored for checks, and can be applied using 'make coccicheck-pending'.
+
+ This allows to expose plans of pending large scale refactorings without
+ impacting the bad pattern checks.
+
+Git-specific tips & things to know about how we run "spatch":
+
+ * The "make coccicheck" will piggy-back on
+ "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file
+ the "coccicheck" target will consider its depednency to decide if
+ it needs to re-run on the corresponding source file.
+
+ This means that a "make coccicheck" will re-compile object files
+ before running. This might be unexpected, but speeds up the run in
+ the common case, as e.g. a change to "column.h" won't require all
+ coccinelle rules to be re-run against "grep.c" (or another file
+ that happens not to use "column.h").
+
+ To disable this behavior use the "SPATCH_USE_O_DEPENDENCIES=NoThanks"
+ flag.
+
+ * To speed up our rules the "make coccicheck" target will by default
+ concatenate all of the *.cocci files here into an "ALL.cocci", and
+ apply it to each source file.
+
+ This makes the run faster, as we don't need to run each rule
+ against each source file. See the Makefile for further discussion,
+ this behavior can be disabled with "SPATCH_CONCAT_COCCI=".
+
+ But since they're concatenated any <id> in the <rulname> (e.g. "@
+ my_name", v.s. anonymous "@@") needs to be unique across all our
+ *.cocci files. You should only need to name rules if other rules
+ depend on them (currently only one rule is named).
+
+ * To speed up incremental runs even more use the "spatchcache" tool
+ in this directory as your "SPATCH". It aimns to be a "ccache" for
+ coccinelle, and piggy-backs on "COMPUTE_HEADER_DEPENDENCIES".
+
+ It caches in Redis by default, see it source for a how-to.
+
+ In one setup with a primed cache "make coccicheck" followed by a
+ "make clean && make" takes around 10s to run, but 2m30s with the
+ default of "SPATCH_CONCAT_COCCI=Y".
+
+ With "SPATCH_CONCAT_COCCI=" the total runtime is around ~6m, sped
+ up to ~1m with "spatchcache".
+
+ Most of the 10s (or ~1m) being spent on re-running "spatch" on
+ files we couldn't cache, as we didn't compile them (in contrib/*
+ and compat/* mostly).
+
+ The absolute times will differ for you, but the relative speedup
+ from caching should be on that order.