| 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 | |