| 1 | \section{Introduction} |
| 2 | |
| 3 | This document describes the options provided by Coccinelle. The options |
| 4 | have an impact on various phases of the semantic patch application |
| 5 | process. These are: |
| 6 | |
| 7 | \begin{enumerate} |
| 8 | \item Selecting and parsing the semantic patch. |
| 9 | \item Selecting and parsing the C code. |
| 10 | \item Application of the semantic patch to the C code. |
| 11 | \item Transformation. |
| 12 | \item Generation of the result. |
| 13 | \end{enumerate} |
| 14 | |
| 15 | \noindent |
| 16 | One can either initiate the complete process from step 1, or |
| 17 | to perform step 1 or step 2 individually. |
| 18 | |
| 19 | Coccinelle has quite a lot of options. The most common usages are as |
| 20 | follows, for a semantic match {\tt foo.cocci}, a C file {\tt foo.c}, and a |
| 21 | directory {\tt foodir}: |
| 22 | |
| 23 | \begin{itemize} |
| 24 | \item {\tt spatch -parse\_cocci foo.cocci}: Check that the semantic patch |
| 25 | is syntactically correct. |
| 26 | \item {\tt spatch -parse\_c foo.c}: Check that the C file |
| 27 | is syntactically correct. The Coccinelle C parser tries to recover |
| 28 | during the parsing process, so if one function does not parse, it will |
| 29 | start up again with the next one. Thus, a parse error is often not a |
| 30 | cause for concern, unless it occurs in a function that is relevant to the |
| 31 | semantic patch. |
| 32 | \item {\tt spatch -sp\_file foo.cocci foo.c}: Apply the semantic patch {\tt |
| 33 | foo.cocci} to the file {\tt foo.c} and print out any transformations as a |
| 34 | diff. |
| 35 | \item {\tt spatch -sp\_file foo.cocci foo.c -debug}: The same as the |
| 36 | previous case, but print out some information about the matching process. |
| 37 | \item {\tt spatch -sp\_file foo.cocci -dir foodir}: Apply the semantic |
| 38 | patch {\tt foo.cocci} to all of the C files in the directory {\tt foodir}. |
| 39 | \item {\tt spatch -sp\_file foo.cocci -dir foodir -include\_headers}: Apply |
| 40 | the semantic patch {\tt foo.cocci} to all of the C files and header files |
| 41 | in the directory {\tt foodir}. |
| 42 | \end{itemize} |
| 43 | |
| 44 | In the rest of this document, the options are annotated as follows: |
| 45 | \begin{itemize} |
| 46 | \item \FilledBigDiamondshape: a basic option, that is most likely of |
| 47 | interest to all users. |
| 48 | \item \BigLowerDiamond: an option that is frequently used, often for better |
| 49 | understanding the effect of a semantic patch. |
| 50 | \item \BigDiamondshape: an option that is likely to be rarely used, but |
| 51 | whose effect is still comprehensible to a user. |
| 52 | \item An option with no annotation is likely of interest only to |
| 53 | developers. |
| 54 | \end{itemize} |
| 55 | |
| 56 | \section{Selecting and parsing the semantic patch} |
| 57 | |
| 58 | \subsection{Standalone options} |
| 59 | |
| 60 | \normal{-parse\_cocci $\langle$file$\rangle$}{ Parse a semantic |
| 61 | patch file and print out some information about it.} |
| 62 | |
| 63 | \subsection{The semantic patch} |
| 64 | |
| 65 | \minimum{-sp\_file $\langle$file$\rangle$, -c $\langle$file$\rangle$, |
| 66 | -cocci\_file $\langle$file$\rangle$}{ Specify the name of the file |
| 67 | containing the semantic patch. The file name should end in {\tt .cocci}. |
| 68 | All three options do the same thing; the last two are deprecated.} |
| 69 | |
| 70 | \subsection{Isomorphisms} |
| 71 | |
| 72 | \rare{-iso, -iso\_file}{ Specify a file containing isomorphisms to be used in |
| 73 | place of the standard one. Normally one should use the {\tt using} |
| 74 | construct within a semantic patch to specify isomorphisms to be used {\em |
| 75 | in addition to} the standard ones.} |
| 76 | |
| 77 | \rare{-iso\_limit $\langle$int$\rangle$} Limit the depth of application of |
| 78 | isomorphisms to the specified integer. |
| 79 | |
| 80 | \rare{-no\_iso\_limit} Put no limit on the number of times that |
| 81 | isomorphisms can be applied. This is the default. |
| 82 | |
| 83 | \developer{-track\_iso}{ Gather information about isomorphism usage.} |
| 84 | |
| 85 | \developer{-profile\_iso}{ Gather information about the time required for |
| 86 | isomorphism expansion.} |
| 87 | |
| 88 | \subsection{Display options} |
| 89 | |
| 90 | \rare{-show\_cocci}{Show the semantic patch that is being processed before |
| 91 | expanding isomorphisms.} |
| 92 | |
| 93 | \rare{-show\_SP}{Show the semantic patch that is being processed after |
| 94 | expanding isomorphisms.} |
| 95 | |
| 96 | \rare{-show\_ctl\_text}{ Show the representation |
| 97 | of the semantic patch in CTL.} |
| 98 | |
| 99 | \rare{-ctl\_inline\_let}{ Sometimes {\tt let} is used to name |
| 100 | intermediate terms CTL representation. This option causes the let-bound |
| 101 | terms to be inlined at the point of their reference. |
| 102 | This option implicitly sets {\bf -show\_ctl\_text}.} |
| 103 | |
| 104 | \rare{-ctl\_show\_mcodekind}{ Show |
| 105 | transformation information within the CTL representation |
| 106 | of the semantic patch. This option implicitly sets {\bf -show\_ctl\_text}.} |
| 107 | |
| 108 | \rare{-show\_ctl\_tex}{ Create a LaTeX files showing the representation |
| 109 | of the semantic patch in CTL.} |
| 110 | |
| 111 | \section{Selecting and parsing the C files} |
| 112 | |
| 113 | \subsection{Standalone options} |
| 114 | |
| 115 | \normal{-parse\_c $\langle$file/dir$\rangle$}{ Parse a {\tt .c} file or all |
| 116 | of the {\tt .c} files in a directory. This generates information about |
| 117 | any parse errors encountered.} |
| 118 | |
| 119 | \normal{-parse\_h $\langle$file/dir$\rangle$}{ Parse a {\tt .h} file or all |
| 120 | of the {\tt .h} files in a directory. This generates information about |
| 121 | any parse errors encountered.} |
| 122 | |
| 123 | \normal{-parse\_ch $\langle$file/dir$\rangle$}{ Parse a {\tt .c} or {\tt |
| 124 | .h} file or all of the {\tt .c} or {\tt .h} files in a directory. This |
| 125 | generates information about any parse errors encountered.} |
| 126 | |
| 127 | \normal{-control\_flow $\langle$file$\rangle$, -control\_flow |
| 128 | $\langle$file$\rangle$:$\langle$function$\rangle$}{ Print a control-flow |
| 129 | graph for all of the functions in a file or for a specific function in a |
| 130 | file. This requires {\tt dot} (http://www.graphviz.org/) and {\tt gv}.} |
| 131 | |
| 132 | \rare{-type\_c $\langle$file$\rangle$}{ Parse a C file and pretty-print a |
| 133 | version including type information.} |
| 134 | |
| 135 | \developer{-tokens\_c $\langle$file$\rangle$}{Prints the tokens in a C |
| 136 | file.} |
| 137 | |
| 138 | \developer{-parse\_unparse $\langle$file$\rangle$}{Parse and then reconstruct |
| 139 | a C file.} |
| 140 | |
| 141 | \developer{-compare\_c $\langle$file$\rangle$ $\langle$file$\rangle$, |
| 142 | -compare\_c\_hardcoded}{Compares one C file to another, or compare the |
| 143 | file tests/compare1.c to the file tests/compare2.c.} |
| 144 | |
| 145 | \developer{-test\_cfg\_ifdef $\langle$file$\rangle$}{Do some special |
| 146 | processing of \#ifdef and display the resulting control-flow graph. This |
| 147 | requires {\tt dot} and {\tt gv}.} |
| 148 | |
| 149 | \developer{-test\_attributes $\langle$file$\rangle$, |
| 150 | -test\_cpp $\langle$file$\rangle$}{ |
| 151 | Test the parsing of cpp code and attributes, respectively.} |
| 152 | |
| 153 | \subsection{Selecting C files} |
| 154 | |
| 155 | An argument that ends in {\tt .c} is assumed to be a C file to process. |
| 156 | Normally, only one C file or one directory is specified. If multiple C |
| 157 | files are specified, they are treated in parallel, {\em i.e.}, the first |
| 158 | semantic patch rule is applied to all functions in all files, then the |
| 159 | second semantic patch rule is applied to all functions in all files, etc. |
| 160 | If a directory is specified then no files may be specified and only the |
| 161 | rightmost directory specified is used. |
| 162 | |
| 163 | \normal{-include\_headers}{ This option causes header files to be processed |
| 164 | independently. This option only makes sense if a directory is specified |
| 165 | using {\bf -dir}.} |
| 166 | |
| 167 | \normal{-use\_glimpse}{ Use a glimpse index to select the files to which |
| 168 | a semantic patch may be relevant. This option requires that a directory is |
| 169 | specified. The index may be created using the script {\tt |
| 170 | coccinelle/scripts/ glimpseindex\_cocci.sh}. Glimpse is available at |
| 171 | http://webglimpse.net/. In conjunction with the option {\bf -patch\_cocci} |
| 172 | this option prints the regular expression that will be passed to glimpse.} |
| 173 | |
| 174 | \rare{-dir}{ Specify a directory containing C files to process. A trailing |
| 175 | {\tt /} is permitted on the directory name and has no impact on the |
| 176 | result. By default, the include path will be set to the ``include'' |
| 177 | subdirectory of this directory. A different include path can be |
| 178 | specified using the option {\bf -I}. {\bf -dir} only considers the |
| 179 | rightmost directory in the argument list. This behavior is convenient |
| 180 | for creating a script that always works on a single directory, but allows |
| 181 | the user of the script to override the provided directory with another |
| 182 | one. Spatch collects the files in the directory using {\tt find} and |
| 183 | does not follow symbolic links.} |
| 184 | |
| 185 | \developer{-kbuild\_info $\langle$file$\rangle$}{ The specified file |
| 186 | contains information about which sets of files should be considered in |
| 187 | parallel.} |
| 188 | |
| 189 | \developer{-disable\_worth\_trying\_opt}{Normally, a C file is only |
| 190 | processed if it contains some keywords that have been determined to be |
| 191 | essential for the semantic patch to match somewhere in the file. This |
| 192 | option disables this optimization and tries the semantic patch on all files.} |
| 193 | |
| 194 | \developer{-test $\langle$file$\rangle$}{ A shortcut for running Coccinelle |
| 195 | on the semantic patch ``file{\tt{.cocci}}'' and the C file ``file{\tt{.c}}''.} |
| 196 | |
| 197 | \developer{-testall}{A shortcut for running Coccinelle on all files in a |
| 198 | subdirectory {\tt tests} such that there are all of a {\tt .cocci} file, a {\tt |
| 199 | .c} file, and a {\tt .res} file, where the {\tt .res} contains the |
| 200 | expected result.} |
| 201 | |
| 202 | \developer{-test\_okfailed, -test\_regression\_okfailed} Other options for |
| 203 | keeping track of tests that have succeeded and failed. |
| 204 | |
| 205 | \developer{-compare\_with\_expected}{Compare the result of applying |
| 206 | Coccinelle to file{\tt{.c}} to the file file{\tt{.res}} representing the |
| 207 | expected result.} |
| 208 | |
| 209 | \developer{-expected\_score\_file $\langle$file$\rangle$}{ |
| 210 | which score file to compare with in the testall run} |
| 211 | |
| 212 | \subsection{Parsing C files} |
| 213 | |
| 214 | \rare{-show\_c}{Show the C code that is being processed.} |
| 215 | |
| 216 | \rare{-parse\_error\_msg}{Show parsing errors in the C file.} |
| 217 | |
| 218 | \rare{-verbose\_parsing}{Show parsing errors in the C file, as well as |
| 219 | information about attempts to accomodate such errors. This implicitly |
| 220 | sets -parse\_error\_msg.} |
| 221 | |
| 222 | \rare{-type\_error\_msg}{Show information about where the C type checker |
| 223 | was not able to determine the type of an expression.} |
| 224 | |
| 225 | \rare{-int\_bits $\langle$n$\rangle$, -long\_bits |
| 226 | $\langle$n$\rangle$}{Provide integer size information. n is the number of |
| 227 | bits in an unsigned integer or unsigned long, respectively. If only the |
| 228 | option {\bf -int\_bits} is used, unsigned longs will be assumed to have |
| 229 | twice as many bits as unsigned integers. If only the option {\bf |
| 230 | -long\_bits} is used, unsigned ints will be assumed to have half as many |
| 231 | bits as unsigned integers. This information is only used in determining |
| 232 | the types of integer constants, according to the ANSI C standard (C89). If |
| 233 | neither is provided, the type of an integer constant is determined by the |
| 234 | sequence of ``u'' and ``l'' annotations following the constant. If there |
| 235 | is none, the constant is assumed to be a signed integer. If there is only |
| 236 | ``u'', the constant is assumed to be an unsigned integer, etc.} |
| 237 | |
| 238 | \rare{-no\_loops}{Drop back edges for loops. This may make a semantic |
| 239 | patch/match run faster, at the cost of not finding matches that wrap |
| 240 | around loops.} |
| 241 | |
| 242 | \developer{-use\_cache} Use preparsed versions of the C files that are |
| 243 | stored in a cache. |
| 244 | |
| 245 | \developer{-debug\_cpp, -debug\_lexer, -debug\_etdt, |
| 246 | -debug\_typedef}{Various options for debugging the C parser.} |
| 247 | |
| 248 | \developer{-filter\_msg, -filter\_define\_error, |
| 249 | -filter\_passed\_level}{Various options for debugging the C parser.} |
| 250 | |
| 251 | \developer{-only\_return\_is\_error\_exit}{In matching ``{\tt{\ldots}}'' in |
| 252 | a semantic patch or when forall is specified, a rule must match all |
| 253 | control-flow paths starting from a node matching the beginning of the |
| 254 | rule. This is relaxed, however, for error handling code. Normally, error |
| 255 | handling code is considered to be a conditional with only a then branch |
| 256 | that ends in goto, break, continue, or return. If this option is set, |
| 257 | then only a then branch ending in a return is considered to be error |
| 258 | handling code. Usually a better strategy is to use {\tt when strict} in |
| 259 | the semantic patch, and then match explicitly the case where there is a |
| 260 | conditional whose then branch ends in a return.} |
| 261 | |
| 262 | \subsubsection*{Macros and other preprocessor code} |
| 263 | |
| 264 | \normal{-macro\_file $\langle$file$\rangle$}{ |
| 265 | Extra macro definitions to be taken into account when parsing the C |
| 266 | files.} |
| 267 | |
| 268 | \normal{-macro\_file\_builtins $\langle$file$\rangle$}{ |
| 269 | Builtin macro definitions to be taken into account when parsing the C |
| 270 | files.} |
| 271 | |
| 272 | \rare{-ifdef\_to\_if,-no\_ifdef\_to\_if}{ |
| 273 | The option {\bf -ifdef\_to\_if} |
| 274 | represents an {\tt \#ifdef} in the source code as a conditional in the |
| 275 | control-flow graph when doing so represents valid code. {\bf |
| 276 | -no\_ifdef\_to\_if} disables this feature. {\bf -ifdef\_to\_if} is the |
| 277 | default. |
| 278 | } |
| 279 | |
| 280 | \rare{-use\_if0\_code}{ Normally code under \#if 0 is ignored. If this |
| 281 | option is set then the code is considered, just like the code under any |
| 282 | other \#ifdef.} |
| 283 | |
| 284 | \developer{-noadd\_typedef\_root}{This seems to reduce the scope of a |
| 285 | typedef declaration found in the C code.} |
| 286 | |
| 287 | \subsubsection*{Include files} |
| 288 | |
| 289 | \normal{-all\_includes, -local\_includes, -no\_includes}{ |
| 290 | These options control which include files mentioned in a C file are taken into |
| 291 | account. {\bf -all\_includes} indicates that all included files will be |
| 292 | processed. {\bf -local\_includes} indicates that only included files in |
| 293 | the current directory will be processed. {\bf -no\_includes} indicates |
| 294 | that no included files will be processed. If the semantic patch contains |
| 295 | type specifications on expression metavariables, then the default is {\bf |
| 296 | -local\_includes}. Otherwise the default is {\bf -no\_includes}. At most |
| 297 | one of these options can be specified.} |
| 298 | |
| 299 | \normal{-I $\langle$path$\rangle$}{ This option specifies the directory in |
| 300 | which to find non-local include files. This option should be used only |
| 301 | once, as each use will overwrite the preceding one.} |
| 302 | |
| 303 | \rare{-relax\_include\_path}{This option when combined with -all\_includes |
| 304 | causes the search for local |
| 305 | include files to consider the directory specified using {\bf -I} if the |
| 306 | included file is not found in the current directory.} |
| 307 | |
| 308 | \section{Application of the semantic patch to the C code} |
| 309 | |
| 310 | \subsection{Feedback at the rule level during the application of the |
| 311 | semantic patch} |
| 312 | |
| 313 | \normal{-show\_bindings}{ |
| 314 | Show the environments with respect to which each rule is applied and the |
| 315 | bindings that result from each such application.} |
| 316 | |
| 317 | \normal{-show\_dependencies}{ Show the status (matched or unmatched) of the |
| 318 | rules on which a given rule depends. {\bf -show\_dependencies} implicitly |
| 319 | sets {\bf -show\_bindings}, as the values of the dependencies are |
| 320 | environment-specific.} |
| 321 | |
| 322 | \normal{-show\_trying}{ |
| 323 | Show the name of each program element to which each rule is applied.} |
| 324 | |
| 325 | \normal{-show\_transinfo}{ |
| 326 | Show information about each transformation that is performed. |
| 327 | The node numbers that are referenced are the number of the nodes in the |
| 328 | control-flow graph, which can be seen using the option {\bf -control\_flow} |
| 329 | (the initial control-flow graph only) or the option {\bf -show\_flow} (the |
| 330 | control-flow graph before and after each rule application).} |
| 331 | |
| 332 | \normal{-show\_misc}{Show some miscellaneous information.} |
| 333 | |
| 334 | \rare{-show\_flow $\langle$file$\rangle$, -show\_flow |
| 335 | $\langle$file$\rangle$:$\langle$function$\rangle$} Show the control-flow |
| 336 | graph before and after the application of each rule. |
| 337 | |
| 338 | \developer{-show\_before\_fixed\_flow}{This is similar to {\bf |
| 339 | -show\_flow}, but shows a preliminary version of the control-flow graph.} |
| 340 | |
| 341 | \subsection{Feedback at the CTL level during the application of the |
| 342 | semantic patch} |
| 343 | |
| 344 | \normal{-verbose\_engine}{Show a trace of the matching of atomic terms to C |
| 345 | code.} |
| 346 | |
| 347 | \rare{-verbose\_ctl\_engine}{Show a trace of the CTL matching process. |
| 348 | This is unfortunately rather voluminous and not so helpful for someone |
| 349 | who is not familiar with CTL in general and the translation of SmPL into |
| 350 | CTL specifically. This option implicitly sets the option {\bf |
| 351 | -show\_ctl\_text}.} |
| 352 | |
| 353 | \rare{-graphical\_trace}{Create a pdf file containing the control flow |
| 354 | graph annotated with the various nodes matched during the CTL matching |
| 355 | process. Unfortunately, except for the most simple examples, the output |
| 356 | is voluminous, and so the option is not really practical for most |
| 357 | examples. This requires {\tt dot} (http://www.graphviz.org/) and {\tt |
| 358 | pdftk}.} |
| 359 | |
| 360 | \rare{-gt\_without\_label}{The same as {\bf -graphical\_trace}, but the PDF |
| 361 | file does not contain the CTL code.} |
| 362 | |
| 363 | \rare{-partial\_match}{ |
| 364 | Report partial matches of the semantic patch on the C file. This can |
| 365 | be substantially slower than normal matching.} |
| 366 | |
| 367 | \rare{-verbose\_match}{ |
| 368 | Report on when CTL matching is not applied to a function or other program |
| 369 | unit because it does not contain some required atomic pattern. |
| 370 | This can be viewed as a simpler, more efficient, but less informative |
| 371 | version of {\bf -partial\_match}.} |
| 372 | |
| 373 | \subsection{Actions during the application of the semantic patch} |
| 374 | |
| 375 | \normal{-D rulename}{Run the patch considering that the virtual rule |
| 376 | ``rulename'' is satisfied. Virtual rules should be declared at the |
| 377 | beginning of the semantic patch in a comma separated list following the |
| 378 | keyword virtual. Other rules can depend on the satisfaction or non |
| 379 | satifaction of these rules using the keyword {\tt depends on} in the |
| 380 | usual way.} |
| 381 | |
| 382 | \normal{-D variable=value}{Run the patch considering that the virtual |
| 383 | identifier metavariable ``variable'' is bound to ``value''. Any |
| 384 | identifier metavariable can be designated as being virtual by giving it |
| 385 | the rule name {\tt virtual}. An example is in demos/vm.coci} |
| 386 | |
| 387 | \rare{-allow\_inconsistent\_paths}{Normally, a term that is transformed |
| 388 | should only be accessible from other terms that are matched by the |
| 389 | semantic patch. This option removes this constraint. Doing so, is |
| 390 | unsafe, however, because the properties that hold along the matched path |
| 391 | might not hold at all along the unmatched path.} |
| 392 | |
| 393 | \rare{-disallow\_nested\_exps}{In an expression that contains repeated |
| 394 | nested subterms, {\em e.g.} of the form {\tt f(f(x))}, a pattern can |
| 395 | match a single expression in multiple ways, some nested inside others. |
| 396 | This option causes the matching process to stop immediately at the |
| 397 | outermost match. Thus, in the example {\tt f(f(x))}, the possibility |
| 398 | that the pattern {\tt f(E)}, with metavariable {\tt E}, matches with {\tt |
| 399 | E} as {\tt x} will not be considered.} |
| 400 | |
| 401 | \rare{-no\_safe\_expressions}{normally, we check that an expression does |
| 402 | not match something earlier in the disjunction. But for large |
| 403 | disjunctions, this can result in a very big CTL formula. So this |
| 404 | option give the user the option to say he doesn't want this feature, |
| 405 | if that is the case.} |
| 406 | |
| 407 | \rare{-pyoutput coccilib.output.Gtk, -pyoutput coccilib.output.Console}{ |
| 408 | This controls whether Python output is sent to Gtk or to the console. {\bf |
| 409 | -pyoutput coccilib.output.Console} is the default. The Gtk option is |
| 410 | currently not well supported.} |
| 411 | |
| 412 | \developer{-loop}{When there is ``{\tt{\ldots}}'' in the semantic patch, |
| 413 | the CTL operator {\sf AU} is used if the current function does not |
| 414 | contain a loop, and {\sf AW} may be used if it does. This option causes |
| 415 | {\sf AW} always to be used.} |
| 416 | |
| 417 | \developer{-steps $\langle$int$\rangle$}{ |
| 418 | This limits the number of steps performed by the CTL engine to the |
| 419 | specified number. This option is unsafe as it might cause a rule to fail |
| 420 | due to running out of steps rather than due to not matching.} |
| 421 | |
| 422 | \developer{-bench $\langle$int$\rangle$}{This collects various information |
| 423 | about the operations performed during the CTL matching process.} |
| 424 | |
| 425 | \developer{-popl, -popl\_mark\_all, -popl\_keep\_all\_wits}{ |
| 426 | These options use a simplified version of the SmPL language. {\bf |
| 427 | -popl\_mark\_all} and {\bf -popl\_keep\_all\_wits} implicitly set {\bf |
| 428 | -popl}.} |
| 429 | |
| 430 | \section{Generation of the result} |
| 431 | |
| 432 | Normally, the only output is a diff printed to standard output. |
| 433 | |
| 434 | \normal{-keep\_comments}{Don't remove comments adjacent to removed code.} |
| 435 | |
| 436 | \normal{-linux\_spacing, -smpl\_spacing}{Control the spacing within the code |
| 437 | added by the semantic patch. The option {\bf -linux\_spacing} causes |
| 438 | spatch to follow the conventions of Linux, regardless of the spacing in |
| 439 | the semantic patch. This is the default. The option {\bf |
| 440 | -smpl\_spacing} causes spatch to follow the spacing given in the semantic |
| 441 | patch, within individual lines.} |
| 442 | |
| 443 | \rare{-o $\langle$file$\rangle$}{ The output file.} |
| 444 | |
| 445 | \rare{-inplace}{ Modify the input file.} |
| 446 | |
| 447 | \rare{-outplace}{ Store modifications in a .cocci\_res file.} |
| 448 | |
| 449 | \rare{-no\_show\_diff}{ Normally, a diff between the original and transformed |
| 450 | code is printed on the standard output. This option causes this not to be |
| 451 | done.} |
| 452 | |
| 453 | \rare{-U}{ Set number of diff context lines.} |
| 454 | |
| 455 | \rare{-patch $\langle$path$\rangle$}{The prefix of the pathname of the |
| 456 | directory or file name that should dropped from the diff line in the |
| 457 | generated patch. This is useful if you want to apply a patch only to a |
| 458 | subdirectory of a source code tree but want to create a patch that can be |
| 459 | applied at the root of the source code tree. An example could be {\tt |
| 460 | spatch -sp\_file foo.cocci -dir /var/linuxes/linux-next/drivers -patch |
| 461 | /var/linuxes/linux-next}. A trailing {\tt /} is permitted on the |
| 462 | directory name and has no impact on the result.} |
| 463 | |
| 464 | \rare{-save\_tmp\_files}{Coccinelle creates some temporary |
| 465 | files in {\tt /tmp} that it deletes after use. This option causes these |
| 466 | files to be saved.} |
| 467 | |
| 468 | \developer{-debug\_unparsing}{Show some debugging information about the |
| 469 | generation of the transformed code. This has the side-effect of |
| 470 | deleting the transformed code.} |
| 471 | |
| 472 | |
| 473 | \section{Other options} |
| 474 | |
| 475 | \subsection{Version information} |
| 476 | |
| 477 | \normal{-version}{ The version of Coccinelle. No other options are |
| 478 | allowed.} |
| 479 | |
| 480 | \normal{-date}{ The date of the current version of Coccinelle. No other |
| 481 | options are allowed.} |
| 482 | |
| 483 | \subsection{Help} |
| 484 | |
| 485 | \minimum{-h, -shorthelp}{ The most useful commands.} |
| 486 | |
| 487 | \minimum{-help, --help, -longhelp}{ A complete listing of the available |
| 488 | commands.} |
| 489 | |
| 490 | \subsection{Controlling the execution of Coccinelle} |
| 491 | |
| 492 | \normal{-timeout $\langle$int$\rangle$}{ The maximum time in seconds for |
| 493 | processing a single file.} |
| 494 | |
| 495 | \rare{-max $\langle$int$\rangle$}{This option informs Coccinelle of the |
| 496 | number of instances of Coccinelle that will be run concurrently. This |
| 497 | option requires {\bf -index}. It is usually used with {\bf -dir}.} |
| 498 | |
| 499 | \rare{-index $\langle$int$\rangle$}{This option informs Coccinelle of |
| 500 | which of the concurrent instances is the current one. This option |
| 501 | requires {\bf -max}.} |
| 502 | |
| 503 | \rare{-mod\_distrib}{When multiple instances of Coccinelle are run in |
| 504 | parallel, normally the first instance processes the first $n$ files, the |
| 505 | second instance the second $n$ files, etc. With this option, the files |
| 506 | are distributed among the instances in a round-robin fashion.} |
| 507 | |
| 508 | \developer{-debugger}{Option for running Coccinelle from within the OCaml |
| 509 | debugger.} |
| 510 | |
| 511 | \developer{-profile}{ Gather timing information about the main Coccinelle |
| 512 | functions.} |
| 513 | |
| 514 | \developer{-disable\_once}{Print various warning messages every time some |
| 515 | condition occurs, rather than only once.} |
| 516 | |
| 517 | \subsection{Miscellaneous} |
| 518 | |
| 519 | \rare{-quiet}{Suppress most output. This is the default.} |
| 520 | |
| 521 | \developer{-pad, -hrule $\langle$dir$\rangle$, -xxx, -l1}{} |
| 522 | |