Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>SWIG Preprocessor</title> | |
5 | <link rel="stylesheet" type="text/css" href="style.css"> | |
6 | </head> | |
7 | ||
8 | <body bgcolor="#ffffff"> | |
9 | <H1><a name="Preprocessor"></a>7 Preprocessing</H1> | |
10 | <!-- INDEX --> | |
11 | <div class="sectiontoc"> | |
12 | <ul> | |
13 | <li><a href="#Preprocessor_nn2">File inclusion</a> | |
14 | <li><a href="#Preprocessor_nn3">File imports</a> | |
15 | <li><a href="#Preprocessor_nn4">Conditional Compilation</a> | |
16 | <li><a href="#Preprocessor_nn5">Macro Expansion</a> | |
17 | <li><a href="#Preprocessor_nn6">SWIG Macros</a> | |
18 | <li><a href="#Preprocessor_nn7">C99 and GNU Extensions</a> | |
19 | <li><a href="#Preprocessor_nn8">Preprocessing and %{ ... %} blocks</a> | |
20 | <li><a href="#Preprocessor_nn9">Preprocessing and { ... }</a> | |
21 | <li><a href="#Preprocessor_nn10">Viewing preprocessor output</a> | |
22 | </ul> | |
23 | </div> | |
24 | <!-- INDEX --> | |
25 | ||
26 | ||
27 | ||
28 | <p> | |
29 | SWIG includes its own enhanced version of the C preprocessor. The preprocessor | |
30 | supports the standard preprocessor directives and macro expansion rules. | |
31 | However, a number of modifications and enhancements have been made. This | |
32 | chapter describes some of these modifications. | |
33 | </p> | |
34 | ||
35 | <H2><a name="Preprocessor_nn2"></a>7.1 File inclusion</H2> | |
36 | ||
37 | ||
38 | <p> | |
39 | To include another file into a SWIG interface, use the <tt>%include</tt> directive | |
40 | like this: | |
41 | </p> | |
42 | ||
43 | <div class="code"> | |
44 | <pre> | |
45 | %include "pointer.i" | |
46 | </pre> | |
47 | </div> | |
48 | ||
49 | <p> | |
50 | Unlike, <tt>#include</tt>, <tt>%include</tt> includes each file once (and will not | |
51 | reload the file on subsequent <tt>%include</tt> declarations). Therefore, it | |
52 | is not necessary to use include-guards in SWIG interfaces. | |
53 | </p> | |
54 | ||
55 | <p> | |
56 | By default, the <tt>#include</tt> is ignored unless you run SWIG with the | |
57 | <tt>-includeall</tt> option. The reason for ignoring traditional includes | |
58 | is that you often don't want SWIG to try and wrap everything included | |
59 | in standard header system headers and auxilliary files. | |
60 | ||
61 | <H2><a name="Preprocessor_nn3"></a>7.2 File imports</H2> | |
62 | ||
63 | ||
64 | <p> | |
65 | SWIG provides another file inclusion directive with the <tt>%import</tt> directive. | |
66 | For example: | |
67 | </p> | |
68 | ||
69 | <div class="code"> | |
70 | <pre> | |
71 | %import "foo.i" | |
72 | </pre> | |
73 | </div> | |
74 | ||
75 | <p> | |
76 | The purpose of <tt>%import</tt> is to collect certain information from another | |
77 | SWIG interface file or a header file without actually generating any wrapper code. | |
78 | Such information generally includes type declarations (e.g., <tt>typedef</tt>) as well as | |
79 | C++ classes that might be used as base-classes for class declarations in the interface. | |
80 | The use of <tt>%import</tt> is also important when SWIG is used to generate | |
81 | extensions as a collection of related modules. This is an advanced topic and is described | |
82 | in a later chapter. | |
83 | </p> | |
84 | ||
85 | <P> | |
86 | The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> statements | |
87 | as imports. This might be useful if you want to extract type definitions from system | |
88 | header files without generating any wrappers. | |
89 | ||
90 | <H2><a name="Preprocessor_nn4"></a>7.3 Conditional Compilation</H2> | |
91 | ||
92 | ||
93 | <p> | |
94 | SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>, | |
95 | <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally | |
96 | include parts of an interface. The following symbols are predefined | |
97 | by SWIG when it is parsing the interface: | |
98 | </p> | |
99 | ||
100 | <div class="code"><pre> | |
101 | SWIG Always defined when SWIG is processing a file | |
102 | SWIGIMPORTED Defined when SWIG is importing a file with <tt>%import</tt> | |
103 | SWIGMAC Defined when running SWIG on the Macintosh | |
104 | SWIGWIN Defined when running SWIG under Windows | |
105 | SWIG_VERSION Hexadecimal number containing SWIG version, | |
106 | such as 0x010311 (corresponding to SWIG-1.3.11). | |
107 | ||
108 | SWIGCHICKEN Defined when using CHICKEN | |
109 | SWIGCSHARP Defined when using C# | |
110 | SWIGGUILE Defined when using Guile | |
111 | SWIGJAVA Defined when using Java | |
112 | SWIGMZSCHEME Defined when using Mzscheme | |
113 | SWIGOCAML Defined when using Ocaml | |
114 | SWIGPERL Defined when using Perl | |
115 | SWIGPERL5 Defined when using Perl5 | |
116 | SWIGPHP Defined when using PHP | |
117 | SWIGPHP4 Defined when using PHP4 | |
118 | SWIGPYTHON Defined when using Python | |
119 | SWIGRUBY Defined when using Ruby | |
120 | SWIGSEXP Defined when using S-expressions | |
121 | SWIGTCL Defined when using Tcl | |
122 | SWIGTCL8 Defined when using Tcl8.0 | |
123 | SWIGXML Defined when using XML | |
124 | </pre></div> | |
125 | ||
126 | <p> | |
127 | In addition, SWIG defines the following set of standard C/C++ macros: | |
128 | </p> | |
129 | ||
130 | <div class="code"> | |
131 | <pre> | |
132 | __LINE__ Current line number | |
133 | __FILE__ Current file name | |
134 | __STDC__ Defined to indicate ANSI C | |
135 | __cplusplus Defined when -c++ option used | |
136 | </pre> | |
137 | </div> | |
138 | ||
139 | <p> | |
140 | Interface files can look at these symbols as necessary to change the | |
141 | way in which an interface is generated or to mix SWIG directives with | |
142 | C code. These symbols are also defined within the C code generated by | |
143 | SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined | |
144 | within the SWIG compiler). | |
145 | </p> | |
146 | ||
147 | <H2><a name="Preprocessor_nn5"></a>7.4 Macro Expansion</H2> | |
148 | ||
149 | ||
150 | <p> | |
151 | Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the <tt>#define</tt> statement | |
152 | is also used to try and detect constants. Therefore, if you have something like this in your file, | |
153 | </p> | |
154 | ||
155 | <div class="code"> | |
156 | <pre> | |
157 | #ifndef _FOO_H 1 | |
158 | #define _FOO_H 1 | |
159 | ... | |
160 | #endif | |
161 | </pre> | |
162 | </div> | |
163 | ||
164 | <p> | |
165 | you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface. | |
166 | </p> | |
167 | ||
168 | <p> | |
169 | More complex macros can be defined in the standard way. For example: | |
170 | </p> | |
171 | ||
172 | <div class="code"> | |
173 | <pre> | |
174 | #define EXTERN extern | |
175 | #ifdef __STDC__ | |
176 | #define _ANSI(args) (args) | |
177 | #else | |
178 | #define _ANSI(args) () | |
179 | #endif | |
180 | </pre> | |
181 | </div> | |
182 | ||
183 | <p> | |
184 | The following operators can appear in macro definitions: | |
185 | </p> | |
186 | ||
187 | <ul> | |
188 | <li><tt>#x</tt><br> | |
189 | Converts macro argument <tt>x</tt> to a string surrounded by double quotes ("x"). | |
190 | </li> | |
191 | ||
192 | <li><tt>x ## y</tt><br> | |
193 | Concatenates x and y together to form <tt>xy</tt>. | |
194 | </li> | |
195 | ||
196 | <li><tt>`x`</tt><br> | |
197 | If <tt>x</tt> is a string surrounded by double quotes, do nothing. Otherwise, turn into a string | |
198 | like <tt>#x</tt>. This is a non-standard SWIG extension. | |
199 | </li> | |
200 | </ul> | |
201 | ||
202 | <H2><a name="Preprocessor_nn6"></a>7.5 SWIG Macros</H2> | |
203 | ||
204 | ||
205 | <p> | |
206 | SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives. | |
207 | For example: | |
208 | </p> | |
209 | ||
210 | <div class="code"> | |
211 | <pre> | |
212 | %define ARRAYHELPER(type,name) | |
213 | %inline %{ | |
214 | type *new_ ## name (int nitems) { | |
215 | return (type *) malloc(sizeof(type)*nitems); | |
216 | } | |
217 | void delete_ ## name(type *t) { | |
218 | free(t); | |
219 | } | |
220 | type name ## _get(type *t, int index) { | |
221 | return t[index]; | |
222 | } | |
223 | void name ## _set(type *t, int index, type val) { | |
224 | t[index] = val; | |
225 | } | |
226 | %} | |
227 | %enddef | |
228 | ||
229 | ARRAYHELPER(int, IntArray) | |
230 | ARRAYHELPER(double, DoubleArray) | |
231 | </pre> | |
232 | </div> | |
233 | ||
234 | <p> | |
235 | The primary purpose of <tt>%define</tt> is to define large macros of code. Unlike normal C preprocessor | |
236 | macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition | |
237 | extends to the first occurrence of <tt>%enddef</tt>. Furthermore, when such macros are expanded, | |
238 | they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor | |
239 | directives except for nested <tt>%define</tt> statements. | |
240 | </p> | |
241 | ||
242 | <p> | |
243 | The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact, | |
244 | many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template | |
245 | support). | |
246 | </p> | |
247 | ||
248 | <H2><a name="Preprocessor_nn7"></a>7.6 C99 and GNU Extensions</H2> | |
249 | ||
250 | ||
251 | <p> | |
252 | SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example: | |
253 | </p> | |
254 | ||
255 | <div class="code"> | |
256 | <pre> | |
257 | #define DEBUGF(fmt,...) fprintf(stderr,fmt,__VA_ARGS__) | |
258 | </pre> | |
259 | </div> | |
260 | ||
261 | <p> | |
262 | When used, any extra arguments to <tt>...</tt> are placed into the | |
263 | special variable <tt>__VA_ARGS__</tt>. This also works with special SWIG | |
264 | macros defined using <tt>%define</tt>. | |
265 | </p> | |
266 | ||
267 | <p> | |
268 | SWIG allows a variable number of arguments to be empty. However, this often results | |
269 | in an extra comma (,) and syntax error in the resulting expansion. For example: | |
270 | </p> | |
271 | ||
272 | <div class="code"> | |
273 | <pre> | |
274 | DEBUGF("hello"); --> fprintf(stderr,"hello",); | |
275 | </pre> | |
276 | </div> | |
277 | ||
278 | <p> | |
279 | To get rid of the extra comma, use <tt>##</tt> like this: | |
280 | </p> | |
281 | ||
282 | <div class="code"> | |
283 | <pre> | |
284 | #define DEBUGF(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__) | |
285 | </pre> | |
286 | </div> | |
287 | ||
288 | <p> | |
289 | SWIG also supports GNU-style variadic macros. For example: | |
290 | </p> | |
291 | ||
292 | <div class="code"> | |
293 | <pre> | |
294 | #define DEBUGF(fmt, args...) fprintf(stdout,fmt,args) | |
295 | </pre> | |
296 | </div> | |
297 | ||
298 | <p> | |
299 | <b>Comment:</b> It's not entirely clear how variadic macros might be useful to | |
300 | interface building. However, they are used internally to implement a number of | |
301 | SWIG directives and are provided to make SWIG more compatible with C99 code. | |
302 | </p> | |
303 | ||
304 | <H2><a name="Preprocessor_nn8"></a>7.7 Preprocessing and %{ ... %} blocks</H2> | |
305 | ||
306 | ||
307 | <p> | |
308 | The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore, | |
309 | if you write code like this, | |
310 | </p> | |
311 | ||
312 | <div class="code"> | |
313 | <pre> | |
314 | %{ | |
315 | #ifdef NEED_BLAH | |
316 | int blah() { | |
317 | ... | |
318 | } | |
319 | #endif | |
320 | %} | |
321 | </pre> | |
322 | </div> | |
323 | ||
324 | <p> | |
325 | the contents of the <tt>%{ ... %}</tt> block are copied without | |
326 | modification to the output (including all preprocessor directives). | |
327 | </p> | |
328 | ||
329 | <H2><a name="Preprocessor_nn9"></a>7.8 Preprocessing and { ... }</H2> | |
330 | ||
331 | ||
332 | <p> | |
333 | SWIG always runs the preprocessor on text appearing inside <tt>{ ... }</tt>. However, | |
334 | sometimes it is desirable to make a preprocessor directive pass through to the output | |
335 | file. For example: | |
336 | </p> | |
337 | ||
338 | <div class="code"> | |
339 | <pre> | |
340 | %extend Foo { | |
341 | void bar() { | |
342 | #ifdef DEBUG | |
343 | printf("I'm in bar\n"); | |
344 | #endif | |
345 | } | |
346 | } | |
347 | </pre> | |
348 | </div> | |
349 | ||
350 | <p> | |
351 | By default, SWIG will interpret the <tt>#ifdef DEBUG</tt> statement. However, if you really wanted that code | |
352 | to actually go into the wrapper file, prefix the preprocessor directives with <tt>%</tt> like this: | |
353 | </p> | |
354 | ||
355 | <div class="code"> | |
356 | <pre> | |
357 | %extend Foo { | |
358 | void bar() { | |
359 | %#ifdef DEBUG | |
360 | printf("I'm in bar\n"); | |
361 | %#endif | |
362 | } | |
363 | } | |
364 | </pre> | |
365 | </div> | |
366 | ||
367 | <p> | |
368 | SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code. | |
369 | </p> | |
370 | ||
371 | <H2><a name="Preprocessor_nn10"></a>7.9 Viewing preprocessor output</H2> | |
372 | ||
373 | ||
374 | <p> | |
375 | Like many compilers, SWIG supports a <tt>-E</tt> command line option to display the output from the preprocessor. | |
376 | When the <tt>-E</tt> switch is used, SWIG will not generate any wrappers. | |
377 | Instead the results after the preprocessor has run are displayed. | |
378 | This might be useful as an aid to debugging and viewing the results of macro expansions. | |
379 | </p> | |
380 | ||
381 | </body> | |
382 | </html> |