Commit | Line | Data |
---|---|---|
faf9a90c C |
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 | |
0708f913 | 166 | Send a mail to <cocci@diku.dk> |
faf9a90c C |
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 |