diff options
Diffstat (limited to 'Documentation/coccinelle.txt')
| -rw-r--r-- | Documentation/coccinelle.txt | 63 |
1 files changed, 39 insertions, 24 deletions
diff --git a/Documentation/coccinelle.txt b/Documentation/coccinelle.txt index 18de78599dd4..7f773d51fdd9 100644 --- a/Documentation/coccinelle.txt +++ b/Documentation/coccinelle.txt @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |