Release coccinelle-0.1.7

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

.\"  -*- nroff -*-
.\" Please adjust this date whenever revising the manpage.
.TH SPATCH 1 "December 30, 2008"

.\" 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.
.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://www.emn.fr/x-info/coccinelle\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=/usr/local/share/coccinelle/standard.iso)
.TP
.B -macro_file          \fI<file>\fP
(default=/usr/local/share/coccinelle/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 -inplace             
do the modification on the file directly
.TP
.B -outplace            
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
/usr/local/share/coccinelle/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 FILES
.I /usr/local/share/coccinelle/standard.iso
.RS
This file contains the default set of isomorphisms.
.RE
.I /usr/local/share/coccinelle/standard.h
.RS
This file contains the default set of macro hints.

.SH ENVIRONMENT
.IP COCCINELLE_HOME
The path to coccinelle share directory. Defaut is 
.I /usr/local/share/coccinelle

.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 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
.BR patch (1).