SWIG: difference between %import and %include

Question

The SWIG docs explain these two directives as follows:

• %include: "To include another file into a SWIG interface, use the %include directive ... 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."

• %import: "SWIG provides another file inclusion directive with the %import directive ... 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. "

My question is what are the differences between these two directives and what are the pros/cons of using each?

---

P.S. Just for some background info. I have a simple C++ - python extension that builds and works when I use either of the above directives. One, however (%import) gives fewer warnings when I call swig -c++ -python my_file.i.

Answer 1

The way SWIG works is that it assumes that any valid C++ declarations you provide are to be exposed to the target language. Therefore, any C++ code that SWIG is provided will be used to generate an interface.

%import is an inclusion mechanism that prevents the generation of the interface for the code it includes. That's the difference. So the question you ask when including a header is, "Do I want all of the stuff in this header to be exposed to the target language?" If the answer is "no", then you use %import.