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