|
@@ -6,15 +6,17 @@ Copyright 2010 Gilles Muller <Gilles.Muller@lip6.fr>
|
|
|
Getting Coccinelle
|
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
-The semantic patches included in the kernel use the 'virtual rule'
|
|
|
-feature which was introduced in Coccinelle version 0.1.11.
|
|
|
+The semantic patches included in the kernel use features and options
|
|
|
+which are provided by Coccinelle version 1.0.0-rc11 and above.
|
|
|
+Using earlier versions will fail as the option names used by
|
|
|
+the Coccinelle files and coccicheck have been updated.
|
|
|
|
|
|
-Coccinelle (>=0.2.0) is available through the package manager
|
|
|
+Coccinelle is available through the package manager
|
|
|
of many distributions, e.g. :
|
|
|
|
|
|
- - Debian (>=squeeze)
|
|
|
- - Fedora (>=13)
|
|
|
- - Ubuntu (>=10.04 Lucid Lynx)
|
|
|
+ - Debian
|
|
|
+ - Fedora
|
|
|
+ - Ubuntu
|
|
|
- OpenSUSE
|
|
|
- Arch Linux
|
|
|
- NetBSD
|
|
@@ -36,11 +38,6 @@ as a regular user, and install it with
|
|
|
|
|
|
sudo make install
|
|
|
|
|
|
-The semantic patches in the kernel will work best with Coccinelle version
|
|
|
-0.2.4 or later. Using earlier versions may incur some parse errors in the
|
|
|
-semantic patch code, but any results that are obtained should still be
|
|
|
-correct.
|
|
|
-
|
|
|
Using Coccinelle on the Linux kernel
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
@@ -48,7 +45,7 @@ A Coccinelle-specific target is defined in the top level
|
|
|
Makefile. This target is named 'coccicheck' and calls the 'coccicheck'
|
|
|
front-end in the 'scripts' directory.
|
|
|
|
|
|
-Four modes are defined: patch, report, context, and org. The mode to
|
|
|
+Four basic modes are defined: patch, report, context, and org. The mode to
|
|
|
use is specified by setting the MODE variable with 'MODE=<mode>'.
|
|
|
|
|
|
'patch' proposes a fix, when possible.
|
|
@@ -62,18 +59,24 @@ diff-like style.Lines of interest are indicated with '-'.
|
|
|
'org' generates a report in the Org mode format of Emacs.
|
|
|
|
|
|
Note that not all semantic patches implement all modes. For easy use
|
|
|
-of Coccinelle, the default mode is "chain" which tries the previous
|
|
|
-modes in the order above until one succeeds.
|
|
|
+of Coccinelle, the default mode is "report".
|
|
|
+
|
|
|
+Two other modes provide some common combinations of these modes.
|
|
|
|
|
|
-To make a report for every semantic patch, run the following command:
|
|
|
+'chain' tries the previous modes in the order above until one succeeds.
|
|
|
|
|
|
- make coccicheck MODE=report
|
|
|
+'rep+ctxt' runs successively the report mode and the context mode.
|
|
|
+ It should be used with the C option (described later)
|
|
|
+ which checks the code on a file basis.
|
|
|
|
|
|
-NB: The 'report' mode is the default one.
|
|
|
+Examples:
|
|
|
+ To make a report for every semantic patch, run the following command:
|
|
|
|
|
|
-To produce patches, run:
|
|
|
+ make coccicheck MODE=report
|
|
|
|
|
|
- make coccicheck MODE=patch
|
|
|
+ To produce patches, run:
|
|
|
+
|
|
|
+ make coccicheck MODE=patch
|
|
|
|
|
|
|
|
|
The coccicheck target applies every semantic patch available in the
|
|
@@ -91,6 +94,11 @@ To enable verbose messages set the V= variable, for example:
|
|
|
|
|
|
make coccicheck MODE=report V=1
|
|
|
|
|
|
+By default, coccicheck tries to run as parallel as possible. To change
|
|
|
+the parallelism, set the J= variable. For example, to run across 4 CPUs:
|
|
|
+
|
|
|
+ make coccicheck MODE=report J=4
|
|
|
+
|
|
|
|
|
|
Using Coccinelle with a single semantic patch
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
@@ -124,26 +132,33 @@ To check only newly edited code, use the value 2 for the C flag, i.e.
|
|
|
|
|
|
make C=2 CHECK="scripts/coccicheck"
|
|
|
|
|
|
+In these modes, which works on a file basis, there is no information
|
|
|
+about semantic patches displayed, and no commit message proposed.
|
|
|
+
|
|
|
This runs every semantic patch in scripts/coccinelle by default. The
|
|
|
COCCI variable may additionally be used to only apply a single
|
|
|
semantic patch as shown in the previous section.
|
|
|
|
|
|
-The "chain" mode is the default. You can select another one with the
|
|
|
+The "report" mode is the default. You can select another one with the
|
|
|
MODE variable explained above.
|
|
|
|
|
|
-In this mode, there is no information about semantic patches
|
|
|
-displayed, and no commit message proposed.
|
|
|
-
|
|
|
Additional flags
|
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
Additional flags can be passed to spatch through the SPFLAGS
|
|
|
variable.
|
|
|
|
|
|
- make SPFLAGS=--use_glimpse coccicheck
|
|
|
+ make SPFLAGS=--use-glimpse coccicheck
|
|
|
+ make SPFLAGS=--use-idutils coccicheck
|
|
|
|
|
|
See spatch --help to learn more about spatch options.
|
|
|
|
|
|
+Note that the '--use-glimpse' and '--use-idutils' options
|
|
|
+require external tools for indexing the code. None of them is
|
|
|
+thus active by default. However, by indexing the code with
|
|
|
+one of these tools, and according to the cocci file used,
|
|
|
+spatch could proceed the entire code base more quickly.
|
|
|
+
|
|
|
Proposing new semantic patches
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|