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