1pycocci(1) General Commands Manual pycocci(1)
2
6 pycocci - Coccinelle wrapper for SmPL patch development
7 pycocci [-h | --help] [-p | --profile-cocci] [-j | --jobs <job-digit> ]
9 [-v | --verbose] [-s | --show-proof] <SmPL-patch.cocci> <target> ]
10
12 pycocci is wrapper around spatch, it enables a set of default arguments
13 and also uses a bit of heuristics to infers which arguments you likely
14 want enabled. It takes two arguments, the <SmPL-patch.cocci> and your
15 <target> which can either be a directory or file. The actual command
16 run is always displayed on standard output.
17 Coccinelle spatch is a very rich tool, it provides a large set of fea‐
19 tures for use with the Coccinelle engine. Typical day to day SmPL patch
20 development may only require a base set of features though, we can also
21 infer a set of features depending on your target. pycocci enables a set
22 of flags which over time have been determined to be required for day to
23 day Linux kernel development, for instance through a cronjob, it also
24 uses a set of heuristics to infer a set of arguments to use depending
25 on your release of Coccinelle. pycocci also checks to see which version
26 of Coccinelle you have installed and looks to enable arguments depend‐
27 ing on what version of Coccinelle you have installed.
28 pycocci can also be used to help write and verify SmPL patches when
30 replacing a regular patch series. pycocci checks the version of spatch
31 installed and based on this enables a set of features. This man page
32 will document what options it always enables by default, why it has
33 done this and it will also document the heuristics used and logic
34 behind them.
35
38 By default pycocci will always enable when running spatch:
39 --in-place
41 --recursive-includes
43 --relax-include-path
45 --timeout 120
47 --dir <target>
49 The --in-place option is enabled by default as most development these
51 days happens on version control systems and built-in version control
52 systems can typically display differences better.
53 --relax-include-path and --relax-include-path are enabled by default
55 given that at least for Linux kernel development some C files tend to
56 include headers in paths only specified by a target's Makefile through
57 utilities such as subdir-ccflags or ccflags-y making it difficult to
58 ensure all required header files are read by Coccinelle. We are aggres‐
59 sive with headers search and inclusion.
60 A default timeout of 120 seconds is used by default. Not using a time‐
62 out is typically not a good idea. The value of 120 is used by default
63 and is considered significantly large enough to support most SmPL
64 patches.
65 We make use of --dir to enable use of a target directory and its subdi‐
67 rectories recursively.
68
71 Coccinelle spatch prior to release 1.0.0 provided support for multi‐
72 threading but required the developer to spawn each thread on their own,
73 and provide an index reference number identifying each thread. Coc‐
74 cinelle would divide the amount of work required to be done and based
75 on the index grant the thread a specific set of work. Some shell
76 scripts could be used to help split the work out for you. pycocci was
77 originally written to supercede these scripts and use Python's multi‐
78 threaded support, while also enabling some sensible arguments by
79 default.
80 If you have a version of spatch older than 1.0.2 pycocci will provide
82 its own built-in multithreaded batched solution, the spatch --jobs
83 argument is enabled on spatch >= 1.0.2. The spatch --jobs arguments
84 takes advantage of Coccinelle's built-in paramap support, and perfor‐
85 mance-wise yields better results than pycocci's multithreaded solution.
86 The number of threads used will always default to the number of number
87 of CPUs on your system, this is taken from what Python multiprocess‐
88 ing.cpu_count() returns. You can override the number of threads pycocci
89 will use with the --jobs argument.
90
93 Coccinelle pycocci supports using a series of indexing alternatives:
94 --use-glimpse
96 --use-gitgrep
98 --use-coccigrep
100 Coccinelle puts the onus of which indexing feature to enable on the
102 developer. pycocci will figure things out for you and make sure that
103 only supported options are used in specific supported releases of coc‐
104 cinelle. So for instance, although --use-gitgrep has been available on
105 1.0.1 pycocci will only it on 1.0.2. The order of preference for what
106 indexing option to uses the following heuristics: If your target direc‐
107 tory has a .glimpse_index file we assume you will want to use --use-
108 glimpse. Glimpse is now released under the ISC license and performance-
109 wise is known to work as the best indexing alternative, this is why we
110 always check for a glimpse index first. This heuristic is however lim‐
111 ited, you need the target path to be the base directory where the
112 .glimpse_index file exists, otherwise pycocci will not recurse below on
113 sub-directories. If we determine glimpse cannot be used then pycocci
114 will use git rev-parse --toplevel on the specified path to determine if
115 the provided path is part of a git directory to enable --use-gitgrep.
116 Although coccinelle provides a fail-safe mechanism to enable use of
117 --use-gitgrep and fall back onto --use-coccigrep if a git tree is not
118 used, we avoid the failure case ahead of time. pycocci will be tuned
119 through each release to infer the best indexing option known to use on
120 your target path.
121 Further information about spatch is available at http://coc‐
124 cinelle.lip6.fr/.
125
128 Here is a summary of the options available on pycocci:
129
132 pycocci [-h | --help] [-p | --profile-cocci] [-j | --jobs] [-v | --ver‐
133 bose] [-s | --show-proof] <SmPL patch> <target> ]
134 -h | --help
137 print short help menu
138 -p | --profile-cocci
140 Profile the <SmPL patch> when run against <target>
141 -j | --jobs <job-digit>
143 Override the default number of jobs to use with <job-digit>. You
144 really only need this if the heuristics for the default number
145 of jobs is determined to be incorrect.
146 -v | --verbose
148 Output all possible information when run. By default pycocci
149 will provide no output unless an error is found.
150 -s | --show-proof
152 Show that the <SmPL-patch.cocci> can replace a series of
153 patches. The <SmPL-patch.cocci> must have a .cocci postfix. A
154 series of patches are expected to exist in the directory named
155 after the <SmPL-patch.cocci> with the .cocci postfix removed.
156 pycocci will use git in order to show a proof of equivalence
157 between the two. A new git branch will be created and used to
158 apply the series of patches ("pycocci-patch-8-random-chars")
159 onto the <target>, another git branch will be created and used
160 to apply the <SmPL-patch.cocci> ("pycocci-smpl-8-random-chars").
161 pycocci will display name of the newly created branches and
162 finally provide the output of git diff --stat <pycocci-
163 patch-8-random-chars>..<pycocci-smpl-8-random-chars>. You should
164 see no changes, and therefore a perfect SmPL patch equivalence,
165 when the diffstat on the output shows no changes. The way to
166 interpret a positive diffstat is that the <SmPL-patch.cocci> is
167 introducing more changes than the patch series. The way to
168 interpret a negative diffstat is that the <SmPL-patch.cocci> is
169 lacking some changes in place on the patch series. pycocci will
170 use git rev-parse --toplevel against the <target> to see if the
171 <target> is part of a git tree. If the <target> is not part of a
172 git tree a git tree is created for you on <target> if <target>
173 is a directory or on the base directory of <target> if <target>
174 is a file. pycocci will return you to the branch previously set
175 on the <target> if one was previously set, otherwise if a new
176 git tree was created for you pycocci will set the tree back to
177 the master branch. Each run of pycocci --show-proof will create
178 two new git branches. 8 random characters are postixed to each
179 new git branch created to avoid conflicts with previous runs.
180 You must run this option with a clean git tree, if you have any
182 pending changes you must commit them or discard them.
183 c | --clean-proof This does what --show-proof does but this is
185 completely silent unless an error occurs. It will also remove
186 the git branches used to test for the equivalence proof, unless
187 an error is found. If an error is found you can inspect the two
188 branches used to test for proof, refer to the documentation on
189 --show-proof for details about these branches. This option is
190 useful if you want to automate tests with proofs.
191 Note that using this method will have created and subsequently
193 if successful deleted two git branches on your git tree. As a
194 consequence of using git branches your git reflog will show
195 these branches, if you push your tree out these branches will
196 not be pushed as they were deleted, your reflog however will
197 keep these references locally until git expires them, by default
198 this is 30 days. If this is too chatty for you, you can run:
199 git reflog expire --all --expire=now
201 This will immediately clear old entries from your reflog.
203
206 pycocci and this man page was written by Luis R. Rodriguez <mcgrof@ker‐
207 nel.org>
208
211 Send a mail to <cocci@systeme.lip6.fr>
212
215 Copyright 2015, Luis R. Rodriguez pycocci is free software: you can
216 redistribute it and/or modify it under the terms of the GNU General
217 Public License as published by the Free Software Foundation, according
218 to version 2 of the License.
219
222 spatch(1), pycocci(1), diff(1)
223 July 20, 2015 pycocci(1)