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