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 | ||
faf9a90c C |
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 | ||
708f4980 C |
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 | |
faf9a90c C |
161 | rightmost directory specified is used. |
162 | ||
faf9a90c C |
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 | ||
c3e37e97 C |
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.} | |
708f4980 | 184 | |
faf9a90c C |
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 | ||
708f4980 C |
209 | \developer{-expected\_score\_file $\langle$file$\rangle$}{ |
210 | which score file to compare with in the testall run} | |
211 | ||
faf9a90c C |
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 | ||
ae4735db C |
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 | ||
faf9a90c C |
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 | ||
708f4980 C |
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 | ||
002099fc C |
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 | ||
faf9a90c C |
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 | ||
708f4980 | 264 | \normal{-macro\_file $\langle$file$\rangle$}{ |
faf9a90c | 265 | Extra macro definitions to be taken into account when parsing the C |
18b1275a C |
266 | files. This uses the provided macro definitions in addition to those in |
267 | the default macro file.} | |
faf9a90c | 268 | |
708f4980 C |
269 | \normal{-macro\_file\_builtins $\langle$file$\rangle$}{ |
270 | Builtin macro definitions to be taken into account when parsing the C | |
18b1275a C |
271 | files. This causes the macro definitions provided in the default macro |
272 | file to be ignored and the ones in the specified file to be used instead.} | |
708f4980 C |
273 | |
274 | \rare{-ifdef\_to\_if,-no\_ifdef\_to\_if}{ | |
275 | The option {\bf -ifdef\_to\_if} | |
276 | represents an {\tt \#ifdef} in the source code as a conditional in the | |
277 | control-flow graph when doing so represents valid code. {\bf | |
278 | -no\_ifdef\_to\_if} disables this feature. {\bf -ifdef\_to\_if} is the | |
279 | default. | |
280 | } | |
faf9a90c C |
281 | |
282 | \rare{-use\_if0\_code}{ Normally code under \#if 0 is ignored. If this | |
283 | option is set then the code is considered, just like the code under any | |
284 | other \#ifdef.} | |
285 | ||
286 | \developer{-noadd\_typedef\_root}{This seems to reduce the scope of a | |
287 | typedef declaration found in the C code.} | |
288 | ||
289 | \subsubsection*{Include files} | |
290 | ||
291 | \normal{-all\_includes, -local\_includes, -no\_includes}{ | |
292 | These options control which include files mentioned in a C file are taken into | |
293 | account. {\bf -all\_includes} indicates that all included files will be | |
294 | processed. {\bf -local\_includes} indicates that only included files in | |
295 | the current directory will be processed. {\bf -no\_includes} indicates | |
296 | that no included files will be processed. If the semantic patch contains | |
297 | type specifications on expression metavariables, then the default is {\bf | |
298 | -local\_includes}. Otherwise the default is {\bf -no\_includes}. At most | |
299 | one of these options can be specified.} | |
300 | ||
5636bb2c C |
301 | \normal{-I $\langle$path$\rangle$}{ This option specifies a directory |
302 | in which to find non-local include files. This option can be used | |
303 | several times.} | |
faf9a90c | 304 | |
7f004419 C |
305 | \rare{-relax\_include\_path}{This option when combined with -all\_includes |
306 | causes the search for local | |
aba5c457 C |
307 | include files to consider the current directory, even if the include |
308 | patch specifies a subdirectory. This is really only useful for testing, | |
309 | eg with the option {\bf -testall}} | |
faf9a90c C |
310 | |
311 | \section{Application of the semantic patch to the C code} | |
312 | ||
313 | \subsection{Feedback at the rule level during the application of the | |
314 | semantic patch} | |
315 | ||
316 | \normal{-show\_bindings}{ | |
317 | Show the environments with respect to which each rule is applied and the | |
318 | bindings that result from each such application.} | |
319 | ||
320 | \normal{-show\_dependencies}{ Show the status (matched or unmatched) of the | |
321 | rules on which a given rule depends. {\bf -show\_dependencies} implicitly | |
322 | sets {\bf -show\_bindings}, as the values of the dependencies are | |
323 | environment-specific.} | |
324 | ||
325 | \normal{-show\_trying}{ | |
326 | Show the name of each program element to which each rule is applied.} | |
327 | ||
328 | \normal{-show\_transinfo}{ | |
329 | Show information about each transformation that is performed. | |
330 | The node numbers that are referenced are the number of the nodes in the | |
331 | control-flow graph, which can be seen using the option {\bf -control\_flow} | |
332 | (the initial control-flow graph only) or the option {\bf -show\_flow} (the | |
333 | control-flow graph before and after each rule application).} | |
334 | ||
335 | \normal{-show\_misc}{Show some miscellaneous information.} | |
336 | ||
337 | \rare{-show\_flow $\langle$file$\rangle$, -show\_flow | |
338 | $\langle$file$\rangle$:$\langle$function$\rangle$} Show the control-flow | |
339 | graph before and after the application of each rule. | |
340 | ||
341 | \developer{-show\_before\_fixed\_flow}{This is similar to {\bf | |
342 | -show\_flow}, but shows a preliminary version of the control-flow graph.} | |
343 | ||
344 | \subsection{Feedback at the CTL level during the application of the | |
345 | semantic patch} | |
346 | ||
347 | \normal{-verbose\_engine}{Show a trace of the matching of atomic terms to C | |
348 | code.} | |
349 | ||
350 | \rare{-verbose\_ctl\_engine}{Show a trace of the CTL matching process. | |
351 | This is unfortunately rather voluminous and not so helpful for someone | |
352 | who is not familiar with CTL in general and the translation of SmPL into | |
353 | CTL specifically. This option implicitly sets the option {\bf | |
354 | -show\_ctl\_text}.} | |
355 | ||
356 | \rare{-graphical\_trace}{Create a pdf file containing the control flow | |
357 | graph annotated with the various nodes matched during the CTL matching | |
358 | process. Unfortunately, except for the most simple examples, the output | |
359 | is voluminous, and so the option is not really practical for most | |
360 | examples. This requires {\tt dot} (http://www.graphviz.org/) and {\tt | |
361 | pdftk}.} | |
362 | ||
363 | \rare{-gt\_without\_label}{The same as {\bf -graphical\_trace}, but the PDF | |
364 | file does not contain the CTL code.} | |
365 | ||
366 | \rare{-partial\_match}{ | |
367 | Report partial matches of the semantic patch on the C file. This can | |
368 | be substantially slower than normal matching.} | |
369 | ||
370 | \rare{-verbose\_match}{ | |
371 | Report on when CTL matching is not applied to a function or other program | |
372 | unit because it does not contain some required atomic pattern. | |
373 | This can be viewed as a simpler, more efficient, but less informative | |
374 | version of {\bf -partial\_match}.} | |
375 | ||
376 | \subsection{Actions during the application of the semantic patch} | |
377 | ||
ae4735db C |
378 | \normal{-D rulename}{Run the patch considering that the virtual rule |
379 | ``rulename'' is satisfied. Virtual rules should be declared at the | |
380 | beginning of the semantic patch in a comma separated list following the | |
381 | keyword virtual. Other rules can depend on the satisfaction or non | |
382 | satifaction of these rules using the keyword {\tt depends on} in the | |
383 | usual way.} | |
384 | ||
385 | \normal{-D variable=value}{Run the patch considering that the virtual | |
386 | identifier metavariable ``variable'' is bound to ``value''. Any | |
387 | identifier metavariable can be designated as being virtual by giving it | |
388 | the rule name {\tt virtual}. An example is in demos/vm.coci} | |
389 | ||
faf9a90c C |
390 | \rare{-allow\_inconsistent\_paths}{Normally, a term that is transformed |
391 | should only be accessible from other terms that are matched by the | |
392 | semantic patch. This option removes this constraint. Doing so, is | |
393 | unsafe, however, because the properties that hold along the matched path | |
394 | might not hold at all along the unmatched path.} | |
395 | ||
396 | \rare{-disallow\_nested\_exps}{In an expression that contains repeated | |
397 | nested subterms, {\em e.g.} of the form {\tt f(f(x))}, a pattern can | |
398 | match a single expression in multiple ways, some nested inside others. | |
399 | This option causes the matching process to stop immediately at the | |
400 | outermost match. Thus, in the example {\tt f(f(x))}, the possibility | |
401 | that the pattern {\tt f(E)}, with metavariable {\tt E}, matches with {\tt | |
402 | E} as {\tt x} will not be considered.} | |
403 | ||
978fd7e5 C |
404 | \rare{-no\_safe\_expressions}{normally, we check that an expression does |
405 | not match something earlier in the disjunction. But for large | |
406 | disjunctions, this can result in a very big CTL formula. So this | |
407 | option give the user the option to say he doesn't want this feature, | |
408 | if that is the case.} | |
409 | ||
faf9a90c C |
410 | \rare{-pyoutput coccilib.output.Gtk, -pyoutput coccilib.output.Console}{ |
411 | This controls whether Python output is sent to Gtk or to the console. {\bf | |
412 | -pyoutput coccilib.output.Console} is the default. The Gtk option is | |
413 | currently not well supported.} | |
414 | ||
415 | \developer{-loop}{When there is ``{\tt{\ldots}}'' in the semantic patch, | |
416 | the CTL operator {\sf AU} is used if the current function does not | |
417 | contain a loop, and {\sf AW} may be used if it does. This option causes | |
418 | {\sf AW} always to be used.} | |
419 | ||
420 | \developer{-steps $\langle$int$\rangle$}{ | |
421 | This limits the number of steps performed by the CTL engine to the | |
422 | specified number. This option is unsafe as it might cause a rule to fail | |
423 | due to running out of steps rather than due to not matching.} | |
424 | ||
425 | \developer{-bench $\langle$int$\rangle$}{This collects various information | |
426 | about the operations performed during the CTL matching process.} | |
427 | ||
428 | \developer{-popl, -popl\_mark\_all, -popl\_keep\_all\_wits}{ | |
429 | These options use a simplified version of the SmPL language. {\bf | |
430 | -popl\_mark\_all} and {\bf -popl\_keep\_all\_wits} implicitly set {\bf | |
431 | -popl}.} | |
432 | ||
433 | \section{Generation of the result} | |
434 | ||
435 | Normally, the only output is a diff printed to standard output. | |
436 | ||
7f004419 C |
437 | \normal{-keep\_comments}{Don't remove comments adjacent to removed code.} |
438 | ||
708f4980 C |
439 | \normal{-linux\_spacing, -smpl\_spacing}{Control the spacing within the code |
440 | added by the semantic patch. The option {\bf -linux\_spacing} causes | |
441 | spatch to follow the conventions of Linux, regardless of the spacing in | |
442 | the semantic patch. This is the default. The option {\bf | |
443 | -smpl\_spacing} causes spatch to follow the spacing given in the semantic | |
444 | patch, within individual lines.} | |
445 | ||
faf9a90c C |
446 | \rare{-o $\langle$file$\rangle$}{ The output file.} |
447 | ||
5636bb2c C |
448 | \rare{-in\_place}{ Modify the input file. By default, the input file is |
449 | overwritten, with no backup.} | |
faf9a90c | 450 | |
5636bb2c C |
451 | \rare{-backup\_suffix}{The suffix of the file to use in making a backup of |
452 | the original file(s). This suffix should include the leading ``.'', if | |
453 | one is desired. This option only has an effect when the option | |
454 | {\tt -in\_place} is also used.} | |
455 | ||
456 | \rare{-out\_place}{ Store modifications in a .cocci\_res file.} | |
faf9a90c C |
457 | |
458 | \rare{-no\_show\_diff}{ Normally, a diff between the original and transformed | |
459 | code is printed on the standard output. This option causes this not to be | |
460 | done.} | |
461 | ||
462 | \rare{-U}{ Set number of diff context lines.} | |
463 | ||
c3e37e97 C |
464 | \rare{-patch $\langle$path$\rangle$}{The prefix of the pathname of the |
465 | directory or file name that should dropped from the diff line in the | |
466 | generated patch. This is useful if you want to apply a patch only to a | |
467 | subdirectory of a source code tree but want to create a patch that can be | |
468 | applied at the root of the source code tree. An example could be {\tt | |
469 | spatch -sp\_file foo.cocci -dir /var/linuxes/linux-next/drivers -patch | |
470 | /var/linuxes/linux-next}. A trailing {\tt /} is permitted on the | |
471 | directory name and has no impact on the result.} | |
472 | ||
faf9a90c C |
473 | \rare{-save\_tmp\_files}{Coccinelle creates some temporary |
474 | files in {\tt /tmp} that it deletes after use. This option causes these | |
475 | files to be saved.} | |
476 | ||
477 | \developer{-debug\_unparsing}{Show some debugging information about the | |
478 | generation of the transformed code. This has the side-effect of | |
479 | deleting the transformed code.} | |
480 | ||
faf9a90c C |
481 | |
482 | \section{Other options} | |
483 | ||
484 | \subsection{Version information} | |
485 | ||
486 | \normal{-version}{ The version of Coccinelle. No other options are | |
487 | allowed.} | |
488 | ||
489 | \normal{-date}{ The date of the current version of Coccinelle. No other | |
490 | options are allowed.} | |
491 | ||
492 | \subsection{Help} | |
493 | ||
494 | \minimum{-h, -shorthelp}{ The most useful commands.} | |
495 | ||
496 | \minimum{-help, --help, -longhelp}{ A complete listing of the available | |
497 | commands.} | |
498 | ||
499 | \subsection{Controlling the execution of Coccinelle} | |
500 | ||
501 | \normal{-timeout $\langle$int$\rangle$}{ The maximum time in seconds for | |
502 | processing a single file.} | |
503 | ||
504 | \rare{-max $\langle$int$\rangle$}{This option informs Coccinelle of the | |
505 | number of instances of Coccinelle that will be run concurrently. This | |
506 | option requires {\bf -index}. It is usually used with {\bf -dir}.} | |
507 | ||
508 | \rare{-index $\langle$int$\rangle$}{This option informs Coccinelle of | |
509 | which of the concurrent instances is the current one. This option | |
510 | requires {\bf -max}.} | |
511 | ||
512 | \rare{-mod\_distrib}{When multiple instances of Coccinelle are run in | |
513 | parallel, normally the first instance processes the first $n$ files, the | |
514 | second instance the second $n$ files, etc. With this option, the files | |
515 | are distributed among the instances in a round-robin fashion.} | |
516 | ||
517 | \developer{-debugger}{Option for running Coccinelle from within the OCaml | |
518 | debugger.} | |
519 | ||
520 | \developer{-profile}{ Gather timing information about the main Coccinelle | |
521 | functions.} | |
522 | ||
523 | \developer{-disable\_once}{Print various warning messages every time some | |
524 | condition occurs, rather than only once.} | |
525 | ||
526 | \subsection{Miscellaneous} | |
527 | ||
528 | \rare{-quiet}{Suppress most output. This is the default.} | |
529 | ||
530 | \developer{-pad, -hrule $\langle$dir$\rangle$, -xxx, -l1}{} | |
531 | ||
5636bb2c C |
532 | |
533 | %%% Local Variables: | |
534 | %%% mode: LaTeX | |
535 | %%% TeX-master: "main_options" | |
536 | %%% coding: utf-8 | |
537 | %%% TeX-PDF-mode: t | |
538 | %%% ispell-local-dictionary: "american" | |
539 | %%% End: |