Unlike, #include, %include includes each file once (and will not reload the file on subsequent %include declarations). Therefore, it is not necessary to use include-guards in SWIG interfaces.%include "pointer.i"
By default, the #include is ignored unless you run SWIG with the -includeall option. The reason for ignoring traditional includes is that you often don't want SWIG to try and wrap everything included in standard header system headers and auxilliary files.
The purpose of %import is to collect certain information from another SWIG interface file or a header file without actually generating any wrapper code. Such information generally includes type declarations (e.g., typedef) as well as C++ classes that might be used as base-classes for class declarations in the interface. The use of %import is also important when SWIG is used to generate extensions as a collection of related modules. This is advanced topic and is described in a later chapter.%import "foo.i"
The -importall directive tells SWIG to follow all #include statements as imports. This might be useful if you want to extract type definitions from system header files without generating any wrappers.
In addition, SWIG defines the following set of standard C/C++ macros:SWIG Always defined when SWIG is processing a file SWIGMAC Defined when running SWIG on the Macintosh SWIGWIN Defined when running SWIG under Windows SWIGCHICKEN Defined when using CHICKEN SWIGCSHARP Defined when using C# SWIGGUILE Defined when using Guile SWIGJAVA Defined when using Java SWIGMZSCHEME Defined when using Mzscheme SWIGOCAML Defined when using Ocaml SWIGPERL Defined when using Perl SWIGPERL5 Defined when using Perl5 SWIGPHP Defined when using PHP SWIGPHP4 Defined when using PHP4 SWIGPYTHON Defined when using Python SWIGRUBY Defined when using Ruby SWIGSEXP Defined when using S-expressions SWIGTCL Defined when using Tcl SWIGTCL8 Defined when using Tcl8.0 SWIGXML Defined when using XML
Interface files can look at these symbols as necessary to change the way in which an interface is generated or to mix SWIG directives with C code. These symbols are also defined within the C code generated by SWIG (except for the symbol `SWIG' which is only defined within the SWIG compiler).__LINE__ Current line number __FILE__ Current file name __STDC__ Defined to indicate ANSI C __cplusplus Defined when -c++ option used
you may get some extra constants such as _FOO_H showing up in the scripting interface.#ifndef _FOO_H 1 #define _FOO_H 1 ... #endif
More complex macros can be defined in the standard way. For example:
The following operators can appear in macro definitions:#define EXTERN extern #ifdef __STDC__ #define _ANSI(args) (args) #else #define _ANSI(args) () #endif
The primary purpose of %define is to define large macros of code. Unlike normal C preprocessor macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition extends to the first occurrence of %enddef. Furthermore, when such macros are expanded, they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor directives except for nested %define statements.%define ARRAYHELPER(type,name) %inline %{ type *new_ ## name (int nitems) { return (type *) malloc(sizeof(type)*nitems); } void delete_ ## name(type *t) { free(t); } type name ## _get(type *t, int index) { return t[index]; } void name ## _set(type *t, int index, type val) { t[index] = val; } %} %enddef ARRAYHELPER(int, IntArray) ARRAYHELPER(double, DoubleArray)
The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact, many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template support).
When used, any extra arguments to ... are placed into the special variable __VA_ARGS__. This also works with special SWIG macros defined using %define.#define DEBUGF(fmt,...) fprintf(stderr,fmt,__VA_ARGS__)
SWIG allows a variable number of arguments to be empty. However, this often results in an extra comma (,) and syntax error in the resulting expansion. For example:
To get rid of the extra comma, use ## like this:DEBUGF("hello"); --> fprintf(stderr,"hello",);
#define DEBUGF(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__)
SWIG also supports GNU-style variadic macros. For example:
Comment: It's not entirely clear how variadic macros might be useful to interface building. However, they are used internally to implement a number of SWIG directives and are provided to make SWIG more compatible with C99 code.#define DEBUGF(fmt, args...) fprintf(stdout,fmt,args)
the contents of the %{ ... %} block are copied without modification to the output (including all preprocessor directives).%{ #ifdef NEED_BLAH int blah() { ... } #endif %}
By default, SWIG will interpret the #ifdef DEBUG statement. However, if you really wanted that code to actually go into the wrapper file, prefix the preprocessor directives with % like this:%extend Foo { void bar() { #ifdef DEBUG printf("I'm in bar\n"); #endif } }
SWIG will strip the extra % and leave the preprocessor directive in the code.%extend Foo { void bar() { %#ifdef DEBUG printf("I'm in bar\n"); %#endif } }