docs/spatch.1

   1 .\"  -*- nroff -*-
   2 .\" Please adjust this date whenever revising the manpage.
   3 .TH SPATCH 1 "December 30, 2008"
   4
   5 .\" see http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html
   6 .\" see http://www.linuxjournal.com/article/1158
   7 .\" see http://www.schweikhardt.net/man_page_howto.html
   8 .\" groff -Tascii -man ./spatch.1 | more
   9 .\"
  10 .\" Some roff macros, for reference:
  11 .\" .nh        disable hyphenation
  12 .\" .hy        enable hyphenation
  13 .\" .ad l      left justify
  14 .\" .ad b      justify to both left and right margins
  15 .\" .nf        disable filling
  16 .\" .fi        enable filling
  17 .\" .br        insert line break
  18 .\" .sp <n>    insert n+1 empty lines
  19 .\" for manpage-specific macros, see man(7)
  20 .\"
  21 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
  22 .\" \fI<whatever>\fP escape sequences to invode bold face and italics,
  23 .\" respectively. Also \fR for roman.
  24 .\" pad: src: deputy man page
  25 .SH NAME
  26 spatch \- apply a semantic patch file to a set of C files
  27
  28 .SH SYNOPSIS
  29 .B spatch
  30 .B -sp_file
  31 .I <SP>
  32 .I <files>
  33 .B [-o
  34 .I <outfile>
  35 .B ]
  36 .B [-iso_file
  37 .I <iso>
  38 .B ]
  39 .B [
  40 .I options
  41 .B ]
  42 .\"
  43 .SH DESCRIPTION
  44 \fBspatch\fP is a program matching and transformation tool for C.
  45 The programmer describes the code to match and the transformation to
  46 perform as a semantic patch, which looks like a standard patch, but can
  47 transform multiple files at any number of code sites.
  48
  49 .PP
  50 Further information about spatch is available at
  51 \fBhttp://www.emn.fr/x-info/coccinelle\fP.
  52
  53 .SH OPTIONS
  54 Here is a summary of the most commonly used options:
  55
  56 .TP
  57 .B -sp_file \fI<file>\fP
  58 the semantic patch file
  59 .TP
  60 .B -dir                 \fI<dir>\fP
  61 process all files in directory recursively
  62 .TP
  63 .B -iso_file            \fI<file>\fP
  64 (default=/usr/local/share/coccinelle/standard.iso)
  65 .TP
  66 .B -macro_file          \fI<file>\fP
  67 (default=/usr/local/share/coccinelle/standard.h)
  68 .TP
  69 .B -debug
  70 print some information to help debug the matching process
  71 .TP
  72 .B -all_includes
  73 causes all available include files to be used
  74 .TP
  75 .B -no_includes
  76 causes not even local include files to be used
  77 .TP
  78 .B -I                   \fI<dir>\fP
  79 the directory containing the include files
  80 .TP
  81 .B -include_headers
  82 process header files independently
  83 .TP
  84 .B -use_glimpse
  85 works with -dir, use information generated by glimpseindex
  86 .TP
  87 .B -o                   \fI<file>\fP
  88 the output file. If none is specified, a patch is generated on the standard
  89 output
  90 .TP
  91 .B -inplace
  92 do the modification on the file directly
  93 .TP
  94 .B -outplace
  95 store modifications in a .cocci_res file
  96 .TP
  97 .B -version
  98 show the version of spatch
  99 .TP
 100 .B -date
 101 show the date on which spatch was compiled
 102 .TP
 103 .B -shorthelp
 104 see short list of options
 105 .TP
 106 .B -longhelp
 107 see all the available options in different categories
 108 .TP
 109 .B \-help, \-\-help
 110 show summary of options.
 111
 112
 113
 114 .SH EXAMPLES
 115
 116   ./spatch -sp_file foo.cocci foo.c
 117
 118 Apply the semantic patch foo.cocci to the C file foo.c.  The semantic patch
 119 is applied modulo a set of isomorphisms contained in standard.iso
 120 (standard.iso is by default located in
 121 /usr/local/share/coccinelle/standard.iso).  A patch showing the effect of
 122 the application, if any, will be generated on the standard output.
 123
 124   ./spatch -sp_file foo.cocci foo.c -o /tmp/newfoo.c
 125
 126 The same as the above, except that a modified version of foo.c is stored in
 127 /tmp/newfoo.c.
 128
 129 It is also possible to apply spatch to all of the C files in
 130 a directory:
 131
 132   ./spatch -cocci_file foo.cocci -dir foodir .
 133
 134 If the semantic patch is not working as expected, the option -debug
 135 shows selection of information about the application of
 136 a semantic patch to a file or directory.
 137
 138 .SH FILES
 139 .I /usr/local/share/coccinelle/standard.iso
 140 .RS
 141 This file contains the default set of isomorphisms.
 142 .RE
 143 .I /usr/local/share/coccinelle/standard.h
 144 .RS
 145 This file contains the default set of macro hints.
 146
 147 .SH ENVIRONMENT
 148 .IP COCCINELLE_HOME
 149 The path to coccinelle share directory. Defaut is
 150 .I /usr/local/share/coccinelle
 151
 152 .SH REFERENCES
 153 Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller
 154 "Documenting and Automating Collateral Evolutions in Linux Device Driver"
 155 .I EuroSys 2008,
 156 Glasgow, Scotland (April 2008) pp. 247-260.
 157
 158 .SH AUTHOR
 159 \fBspatch\fP was written by Julia Lawall <julia@diku.dk>, Yoann Padioleau
 160 <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrhansen@diku.dk> and
 161 Henrik Stuart <henrik@hstuart.dk>.
 162 .PP
 163 This manual page was written by Yoann Padioleau <yoann.padioleau@gmail.com>
 164 and Julia Lawall <julia@diku.dk>.
 165
 166 .SH REPORTING BUGS
 167 Send a mail to <cocci@diku.dk>
 168
 169 .SH COPYRIGHT
 170 Copyright 2005-2009, Ecole des Mines de Nantes, University of Copenhagen.
 171 spatch is free software: you can redistribute it and/or modify
 172 it under the terms of the GNU General Public License as published by
 173 the Free Software Foundation, according to version 2 of the License.
 174
 175 .SH SEE ALSO
 176 .BR patch (1).
 177