SWIG: difference between %import and %include
Question: The [SWIG docs](http://www.swig.org/Doc2.0/Preprocessor.html) 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: 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`.

