permit multiline comments and strings in macros

[bpt/coccinelle.git] / docs / spatch.1.in

.\"  -*- nroff -*-
.\" Please adjust this date whenever revising the manpage.
.TH SPATCH 1 "aug 02, 2012"

.\" see http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html
.\" see http://www.linuxjournal.com/article/1158
.\" see http://www.schweikhardt.net/man_page_howto.html
.\" groff -Tascii -man ./spatch.1 | more
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\"
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
.\" respectively. Also \fR for roman.
.\" pad: src: deputy man page
.SH NAME
spatch \- apply a semantic patch file to a set of C files

.SH SYNOPSIS
.B spatch
.B -sp_file
.I <SP>
.I <files>
.B [-o 
.I <outfile>
.B ] 
.B [-iso_file 
.I <iso>
.B ] 
.B [
.I options
.B ]
.\"
.SH DESCRIPTION
\fBspatch\fP is a program matching and transformation tool for C.
The programmer describes the code to match and the transformation to
perform as a semantic patch, which looks like a standard patch, but can
transform multiple files at any number of code sites.

.PP
Further information about spatch is available at
\fBhttp://coccinelle.lip6.fr/\fP.

.SH OPTIONS
Here is a summary of the most commonly used options:

.TP
.B -sp_file \fI<file>\fP
the semantic patch file
.TP
.B -dir                 \fI<dir>\fP
process all files in directory recursively
.TP
.B -iso_file            \fI<file>\fP
(default=@SHAREDIR@/standard.iso)
.TP
.B -macro_file          \fI<file>\fP
(default=@SHAREDIR@/standard.h)
.TP
.B -debug        
print some information to help debug the matching process
.TP
.B -all_includes        
causes all available include files to be used
.TP
.B -no_includes         
causes not even local include files to be used
.TP
.B -I                   \fI<dir>\fP
the directory containing the include files
.TP 
.B -include_headers     
process header files independently
.TP
.B -use_glimpse         
works with -dir, use information generated by glimpseindex
.TP
.B -o                   \fI<file>\fP
the output file. If none is specified, a patch is generated on the standard
output
.TP
.B -in_place             
do the modification on the file directly
.TP
.B -out_place            
store modifications in a .cocci_res file
.TP
.B -version             
show the version of spatch
.TP
.B -date                
show the date on which spatch was compiled
.TP
.B -shorthelp           
see short list of options
.TP
.B -longhelp            
see all the available options in different categories
.TP 
.B \-help, \-\-help             
show summary of options.

.SH EXAMPLES

  ./spatch -sp_file foo.cocci foo.c

Apply the semantic patch foo.cocci to the C file foo.c.  The semantic patch
is applied modulo a set of isomorphisms contained in standard.iso
(standard.iso is by default located in
@SHAREDIR@/standard.iso).  A patch showing the effect of
the application, if any, will be generated on the standard output.

  ./spatch -sp_file foo.cocci foo.c -o /tmp/newfoo.c

The same as the above, except that a modified version of foo.c is stored in
/tmp/newfoo.c.

It is also possible to apply spatch to all of the C files in
a directory: 

  ./spatch -cocci_file foo.cocci -dir foodir

If the semantic patch is not working as expected, the option -debug
shows selection of information about the application of
a semantic patch to a file or directory.

.SH MORE OPTIONS
.IP "MAIN OPTIONS"
.TP
\fB\-\-sp\-file\fR
<file> the semantic patch file
.TP
\fB\-o\fR
<file> the output file
.TP
\fB\-\-in\-place\fR
do the modification on the file directly
.TP
\fB\-\-backup\-suffix\fR
suffix to use when making a backup for inplace
.TP
\fB\-\-out\-place\fR
store modifications in a .cocci_res file
.TP
\fB\-\-reverse\fR
invert the semantic patch before applying it
.TP
\fB\-U\fR
set number of diff context lines
.TP
\fB\-\-partial\-match\fR
report partial matches of the SP on the C file
.TP
\fB\-\-iso\-file\fR
<file> (default=/usr/local/share/coccinelle/standard.iso)
.TP
\fB\-\-macro\-file\fR
<file>
.TP
\fB\-\-macro\-file\-builtins\fR
<file> (default=/usr/local/share/coccinelle/standard.h)
.TP
\fB\-\-recursive\-includes\fR
causes all available include files, both those included in the C file(s) and those included in header files, to be used
.TP
\fB\-\-all\-includes\fR
causes all available include files included in the C file(s) to be used
.TP
\fB\-\-no\-includes\fR
causes not even local include files to be used
.TP
\fB\-\-local\-includes\fR
causes local include files to be used
.TP
\fB\-\-ignore\-unknown\-options\fR
For integration in a toolchain (must be set before the first unknown option)
.TP
\fB\-\-include\-headers\fR
process header files independently
.TP
\fB\-I\fR
<dir> containing the header files (optional)
.TP
\fB\-\-preprocess\fR
run the C preprocessor before applying the semantic match
.TP
\fB\-c\fR
gcc/cpp compatibility mode
.TP
\fB\-\-dir\fR
<dir> process all files in directory recursively
.TP
\fB\-\-use\-glimpse\fR
works with \fB\-dir\fR, use info generated by glimpseindex
.TP
\fB\-\-use\-google\fR
find relevant files using google code search
.TP
\fB\-\-use\-idutils\fR
find relevant files using id\-utils
.TP
\fB\-\-patch\fR
<dir> path name with respect to which a patch should be created
.IP
"" for a file in the current directory
.TP
\fB\-\-kbuild\-info\fR
<file> improve \fB\-dir\fR by grouping related c files
.TP
\fB\-\-pyoutput\fR
Sets output routine: Standard values: <coccilib.output.Gtk|coccilib.output.Console>
.TP
\fB\-\-version\fR
guess what
.TP
\fB\-\-date\fR
guess what
.TP
\fB\-\-shorthelp\fR
see short list of options
.TP
\fB\-\-longhelp\fR
see all the available options in different categories
.PP
.IP "ALIASES AND OBSOLETE OPTIONS"
.TP
\fB\-\-sp\fR
command line semantic patch
.TP
\fB\-\-iso\fR
short option of \fB\-\-iso\-file\fR
.TP
\fB\-\-cocci\-file\fR
<file> the semantic patch file
.PP
.IP "MOST USEFUL SHOW OPTIONS"
.HP
\fB\-\-show\-diff\fR
.HP
\fB\-\-no\-show\-diff\fR
.TP
\fB\-\-force\-diffshow\fR
diff even if only spacing changes
.HP
\fB\-\-show\-flow\fR
.HP
\fB\-\-ctl\-inline\-let\fR
.HP
\fB\-\-ctl\-show\-mcodekind\fR
.HP
\fB\-\-show\-bindings\fR
.HP
\fB\-\-show\-transinfo\fR
.HP
\fB\-\-show\-misc\fR
.TP
\fB\-\-show\-trying\fR
show the name of each function being processed
.TP
\fB\-\-show\-dependencies\fR
show the dependencies related to each rule
.PP
.IP "VERBOSE SUBSYSTEMS OPTIONS"
.HP
\fB\-\-verbose\-ctl\-engine\fR
.HP
\fB\-\-verbose\-match\fR
.HP
\fB\-\-verbose\-engine\fR
.TP
\fB\-\-graphical\-trace\fR
generate a pdf file representing the matching process
.TP
\fB\-\-gt\-without\-label\fR
remove graph label (requires option \fB\-graphical\-trace\fR)
.HP
\fB\-\-parse\-error\-msg\fR
.HP
\fB\-\-verbose\-parsing\fR
.HP
\fB\-\-type\-error\-msg\fR
.PP
.IP "OTHER SHOW OPTIONS"
.HP
\fB\-\-show\-c\fR
.HP
\fB\-\-show\-cocci\fR
.HP
\fB\-\-show\-before\-fixed\-flow\fR
.HP
\fB\-\-show\-ctl\-tex\fR
.HP
\fB\-\-show\-ctl\-text\fR
.HP
\fB\-\-show\-SP\fR
.PP
.IP "DEBUG C PARSING/UNPARSING"
.HP
\fB\-\-debug\-cpp\fR
.HP
\fB\-\-debug\-lexer\fR
.HP
\fB\-\-debug\-etdt\fR
.HP
\fB\-\-debug\-typedef\fR
.TP
\fB\-\-filter\-msg\fR
filter some cpp message when the macro is a "known" cpp construct
.HP
\fB\-\-filter\-define\-error\fR
.TP
\fB\-\-filter\-msg\-define\-error\fR
filter the error msg
.HP
\fB\-\-filter\-passed\-level\fR
.HP
\fB\-\-debug\-unparsing\fR
.PP
.IP "SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE"
.HP
\fB\-\-quiet\fR
.HP
\fB\-\-very\-quiet\fR
.HP
\fB\-\-debug\fR
.HP
\fB\-\-pad\fR
.PP
.IP "BENCH OPTIONS"
.TP
\fB\-\-profile\fR
gather timing information about the main coccinelle functions
.TP
\fB\-\-bench\fR
<level> for profiling the CTL engine
.TP
\fB\-\-timeout\fR
<sec> timeout in seconds
.TP
\fB\-\-steps\fR
max number of model checking steps per code unit
.TP
\fB\-\-iso\-limit\fR
max depth of iso application
.TP
\fB\-\-no\-iso\-limit\fR
disable limit on max depth of iso application
.TP
\fB\-\-track\-iso\fR
gather information about isomorphism usage
.TP
\fB\-\-disable\-iso\fR
disable a specific isomorphism
.TP
\fB\-\-profile\-iso\fR
gather information about the cost of isomorphism usage
.PP
.IP "CHANGE OF ALGORITHM OPTIONS"
.TP
\fB\-\-keep\-comments\fR
keep comments around removed code
.HP
\fB\-\-loop\fR
.TP
\fB\-\-no\-loops\fR
drop all back edges derived from looping constructs \- unsafe
.TP
\fB\-\-no\-gotos\fR
drop all jumps derived from gotos \- unsafe
.TP
\fB\-\-no\-saved\-typedefs\fR
drop all inferred typedefs from one parse of some code to the next
.TP
\fB\-\-ocaml\-regexps\fR
use OCaml Str regular expressions for constraints
.HP
\fB\-\-l1\fR
.TP
\fB\-\-ifdef\-to\-if\fR
convert ifdef to if (experimental)
.TP
\fB\-\-no\-ifdef\-to\-if\fR
convert ifdef to if (experimental)
.HP
\fB\-\-disable\-multi\-pass\fR
.HP
\fB\-\-noif0\-passing\fR
.HP
\fB\-\-defined\fR
.HP
\fB\-\-undefined\fR
.HP
\fB\-\-noadd\-typedef\-root\fR
.TP
\fB\-\-disallow\-nested\-exps\fR
disallow an expresion pattern from matching a term and its subterm
.HP
\fB\-\-disable\-worth\-trying\-opt\fR
.HP
\fB\-\-only\-return\-is\-error\-exitif\fR this flag is not set, then break and continue are also error exits
.TP
\fB\-\-allow\-inconsistent\-paths\fR
if this flag is set don't check for inconsistent paths; dangerous
.TP
\fB\-\-no\-safe\-expressions\fR
make an expression disjunction not prioritise the topmost disjunct
.TP
\fB\-\-int\-bits\fR
the number of bits in an unsigned int
.TP
\fB\-\-long\-bits\fR
the number of bits in an unsigned long
.TP
\fB\-\-linux\-spacing\fR
spacing of + code follows the conventions of Linux
.TP
\fB\-\-smpl\-spacing\fR
spacing of + code follows the semantic patch
.TP
\fB\-D\fR
indicate that a virtual rule should be considered to be matched
.TP
\fB\-\-c\fR++
make a small attempt to parse C++ files
.PP
.IP "MISC OPTIONS"
.TP
\fB\-\-debugger\fR
option to set if launch spatch in ocamldebug
.TP
\fB\-\-disable\-once\fR
to print more messages
.TP
\fB\-\-show\-trace\-profile\fR
show trace
.HP
\fB\-\-save\-tmp\-files\fR
.PP
.IP "CONCURRENCY"
.TP
\fB\-\-index\fR
the processor to use for this run of spatch
.TP
\fB\-\-max\fR
the number of processors available
.TP
\fB\-\-mod\-distrib\fR
use mod to distribute files among the processors
.PP
.IP "PAD OPTIONS"
.TP
\fB\-\-use\-cache\fR
use .ast_raw pre\-parsed cached C file
.TP
\fB\-\-cache\-prefix\fR
directory of cached ASTs, sets \fB\-use\-cache\fR
.TP
\fB\-\-cache\-limit\fR
maximum number of cached ASTs, sets \fB\-use\-cache\fR
.PP
.IP "TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES)"
The test options don't work with the \fB\-\-sp\-file\fR and so on.
.TP
\fB\-\-test\fR
<file> launch spatch on tests/file.[c,cocci]
.TP
\fB\-\-testall\fR
launch spatch on all files in tests/ having a .res
.TP
\fB\-\-test\-okfailed\fR
generates .{ok,failed,spatch_ok} files using .res files
.TP
\fB\-\-test\-regression\-okfailed\fR
process the .{ok,failed,spatch_ok} files in current dir
.TP
\fB\-\-compare\-with\-expected\fR
use also file.res
.TP
\fB\-\-expected\-score\-file\fR
which score file to compare with in \fB\-testall\fR
.TP
\fB\-\-no\-update\-score\-file\fR
do not update the score file when \fB\-testall\fR succeeds
.HP
\fB\-\-relax\-include\-path\fR
.PP
.IP "ACTION MODE"
The action options don't work with the \fB\-\-sp\-file\fR and so on.
It's for the other (internal) uses of the spatch program.
.TP
\fB\-\-tokens\-c\fR
<file>
.TP
\fB\-\-parse\-c\fR
<file or dir>
.TP
\fB\-\-parse\-h\fR
<file or dir>
.TP
\fB\-\-parse\-ch\fR
<file or dir>
.TP
\fB\-\-parse\-i\fR
<file or dir>
.TP
\fB\-\-parse\fR
<file or dir>
.TP
\fB\-\-show\-flow\fR
<file or file:function>
.TP
\fB\-\-control\-flow\fR
<file or file:function>
.TP
\fB\-\-control\-flow\-to\-file\fR
<file or file:function>
.TP
\fB\-\-test\-cfg\-ifdef\fR
<file>
.TP
\fB\-\-parse\-unparse\fR
<file>
.TP
\fB\-\-type\-c\fR
<file>
.TP
\fB\-\-compare\-c\fR
<file1> <file2>
.TP
\fB\-\-comment\-annotater\-c\fR
<file>
.HP
\fB\-\-compare\-c\-hardcoded\fR
.TP
\fB\-\-test\-attributes\fR
<file>
.TP
\fB\-\-test\-cpp\fR
<file>
.TP
\fB\-\-extract\-macros\fR
<file or dir>
.TP
\fB\-\-extract\-macros\-select\fR
<file or dir>
.TP
\fB\-\-xxx\fR
<file1> <>
.TP
\fB\-\-parse\-cocci\fR
<file>
.TP
\fB\-\-compare\-c\fR
<file1> <file2>

.SH FILES
.I @SHAREDIR@/standard.iso
.RS
This file contains the default set of isomorphisms.
.RE
.I @SHAREDIR@/standard.h
.RS
This file contains the default set of macro hints.

.SH ENVIRONMENT
.IP COCCINELLE_HOME
The path to the Coccinelle share directory. Default is 
.I @SHAREDIR@

.SH REFERENCES
Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller
"Documenting and Automating Collateral Evolutions in Linux Device Driver"
.I EuroSys 2008, 
Glasgow, Scotland (April 2008) pp. 247-260.

.SH AUTHOR
\fBspatch\fP was written by Julia Lawall <julia@diku.dk>, Yoann Padioleau
<yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrhansen@diku.dk> and
Henrik Stuart <henrik@hstuart.dk>.
.PP
This manual page was written by Yoann Padioleau <yoann.padioleau@gmail.com>
and Julia Lawall <julia@diku.dk>.

.SH REPORTING BUGS
Send a mail to <cocci@diku.dk>

.SH COPYRIGHT
Copyright 2010, 2011, University of Copenhagen DIKU and INRIA.
Copyright 2005-2009, Ecole des Mines de Nantes, University of Copenhagen.
spatch is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, according to version 2 of the License.

.SH SEE ALSO
\fIpatch\fP(1), \fIdiff\fP(1)