Question

In SWIG, what is the difference between the “%include” directive, and the standard C “#include”?

For instance, in all the tutorials, why do they typically look something like this:

%module my_module

%{
#include "MyHeader.h"
%}

%include "MyHeader.h"

This seems redundant to me. Perhaps somebody with knowledge can clarify.

Is there a preferred method for including C++ code?

Answer 1

The stuff in %{ ... %} is passed through directly to the output; it is not itself interpreted by SWIG. So the #include is there to make sure the generated C/C++ code includes that header.

%include, by contrast, is a SWIG directive. It tells SWIG to process that header file before proceeding. This way SWIG will learn about (and generate wrappers for) the types and functions declared in that header file.

If the header is very complex, it might confuse SWIG or result in very large output (as SWIG tries to generate a wrapper for everything within). In such cases, you are better off manually declaring just the parts of the header that you need SWIG to process, and omit the %include. But you still may want the #include in order for the generated C++ to compile.

[update]

As for “preferred”, SWIG is more about what works than what is “preferred”… If you have a very clean header file declaring a nice interface for a single class, you can just %include it and have SWIG automatically generate the wrappers. If your header file is very hairy (e.g. iostream), you should manually tell SWIG what to wrap. But there is no hard and fast rule.