1pycocci(1)                  General Commands Manual                 pycocci(1)
2
3
4

NAME

6       pycocci - Coccinelle wrapper for SmPL patch development
7
8       pycocci [-h | --help] [-p | --profile-cocci] [-j | --jobs <job-digit> ]
9       [-v | --verbose] [-s | --show-proof] <SmPL-patch.cocci> <target> ]
10

DESCRIPTION

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
18       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
29       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
36

DEFAULT ARGUMENTS

38       By default pycocci will always enable when running spatch:
39
40       --in-place
41
42       --recursive-includes
43
44       --relax-include-path
45
46       --timeout 120
47
48       --dir <target>
49
50       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
54       --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
61       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
66       We make use of --dir to enable use of a target directory and its subdi‐
67       rectories recursively.
68
69

MULTITHREAD ARGUMENT HEURISTICS

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
81       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
91

INDEXING ARGUMENT HEURISTICS

93       Coccinelle pycocci supports using a series of indexing alternatives:
94
95       --use-glimpse
96
97       --use-gitgrep
98
99       --use-coccigrep
100
101       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
122
123       Further  information  about  spatch   is   available   at   http://coc
124       cinelle.lip6.fr/.
125
126

OPTIONS

128       Here is a summary of the options available on pycocci:
129
130

SYNOPSIS

132       pycocci [-h | --help] [-p | --profile-cocci] [-j | --jobs] [-v | --ver‐
133       bose] [-s | --show-proof] <SmPL patch> <target> ]
134
135
136       -h | --help
137              print short help menu
138
139       -p | --profile-cocci
140              Profile the <SmPL patch> when run against <target>
141
142       -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
147       -v | --verbose
148              Output all possible information when  run.  By  default  pycocci
149              will provide no output unless an error is found.
150
151       -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
181              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
184              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
192              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
200                   git reflog expire --all --expire=now
201
202              This will immediately clear old entries from your reflog.
203
204

AUTHOR

206       pycocci and this man page was written by Luis R. Rodriguez <mcgrof@ker‐
207       nel.org>
208
209

REPORTING BUGS

211       Send a mail to <cocci@systeme.lip6.fr>
212
213
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
220

SEE ALSO

222       spatch(1), pycocci(1), diff(1)
223
224
225
226                                 July 20, 2015                      pycocci(1)
Impressum