| SWIG Myths |
| |
| <p> |
| <h2>SWIG Myths</h2> |
| |
| <p> |
| Here are some common misconceptions about SWIG that have occasionally |
| appeared on other web pages and in articles--especially those that |
| describe older SWIG versions. |
| |
| <font color="#ff0000"><h4>Myth: SWIG only really works with ANSI C</h4></font> |
| |
| <h4>Fact:</h4> |
| |
| SWIG <em>does</em> provide wrapping support for all of ANSI C. However, SWIG has |
| also included C++ support since its initial release in 1996. To be fair, early |
| SWIG releases had limitations, but C++ support has continually improved with |
| each SWIG release. |
| |
| <p> |
| C++ support in current SWIG releases is quite advanced--providing support for nearly |
| every C++ feature including templates, namespaces, operators, overloaded methods, |
| and more. The only major C++ feature not supported is nested classes---and we're |
| working on that. See the <a href="compare.html">Features</a> page for more information. |
| |
| <font color="#ff0000"><h4>Myth: SWIG wraps C++ into this unusable |
| low-level "C-tran" interface.</h4></font> |
| |
| <h4>Fact:</h4> |
| |
| When wrapping C++, SWIG <em>does</em> generate a set of low-level procedural |
| wrappers. However, these are only used as building blocks for |
| creating a more advanced high-level wrappers (in fact, users rarely |
| interact with this layer directly). In nearly all target languages, |
| SWIG wraps C++ classes into a nice object-oriented interface that |
| mirrors the underlying C++ code. In Python, C++ classes |
| are wrapped as Python classes, in Perl, C++ classes are wrapped as |
| Perl classes, and so forth. The existence of procedural wrappers is |
| only an artifact of SWIG's layered approach to wrapper code generation. |
| |
| <font color="#ff0000"><h4>Myth: SWIG doesn't support overloaded methods/functions</h4></font> |
| |
| <h4>Fact:</h4> |
| |
| SWIG provides full support for C++ overloaded methods and functions. |
| For example, if you have declarations like this: |
| |
| <blockquote> |
| <pre> |
| class Foo { |
| public: |
| Foo(); |
| Foo(const Foo &); |
| void spam(int x); |
| void spam(double x); |
| void spam(char *x, int n); |
| }; |
| </pre> |
| </blockquote> |
| |
| They can be used in a completely natural way from most SWIG language modules. For example, |
| in Python: |
| |
| <blockquote> |
| <pre> |
| >>> f = Foo() |
| >>> f.spam(3) |
| >>> f.spam(3.5) |
| >>> f.spam("hello",5) |
| >>> g = Foo(f) # Make a copy |
| </pre> |
| </blockquote> |
| |
| Or in Tcl: |
| |
| <blockquote> |
| <pre> |
| % Foo f |
| % f spam 3 |
| % f spam 3.5 |
| % f spam "hello" 5 |
| % Foo g f |
| </pre> |
| </blockquote> |
| |
| The SWIG implementation of overloading utilizes type categories and a |
| type precedence scheme that results in the generation of dynamic |
| dispatch functions. The order in which declarations appear does not matter nor |
| does SWIG rely on unreliable mechanisms like trial execution (i.e., trying methods |
| one by one until one happens to execute successfully). Overloading support in SWIG |
| is more advanced than that. |
| |
| <P> |
| Due to the dynamic nature of scripting languages, it is not possible to |
| fully disambiguate overloaded methods to the same degree as in C++. |
| For example, you might have declarations like this: |
| |
| <blockquote> |
| <pre> |
| int foo(int); |
| long foo(long); |
| </pre> |
| </blockquote> |
| |
| In this case, SWIG provides a number of directives to either rename or ignore |
| one of the declarations. For example: |
| |
| <blockquote> |
| <pre> |
| %ignore foo(long); |
| </pre> |
| </blockquote> |
| |
| or |
| |
| <blockquote> |
| <pre> |
| %rename(foo_long) foo(long); |
| </pre> |
| </blockquote> |
| |
| <font color="#ff0000"><h4>Myth: SWIG doesn't support basic idiomatic C++ constructs like templates and smart pointers</h4></font> |
| |
| <h4>Fact:</h4> |
| |
| SWIG fully supports templates. However, to wrap a template class, you have to |
| tell SWIG about a particular instantiation. This is easy, just make sure SWIG |
| knows about the template definition and include a special directive like this: |
| |
| <blockquote> |
| <pre> |
| %template(deque_int) std::deque<int>; |
| </pre> |
| </blockquote> |
| |
| In this case, "deque_int" becomes the target language name for the wrapped object. |
| You would use it just like a normal class in the extension module: |
| |
| <blockquote> |
| <pre> |
| >>> d = deque_int(100) |
| >>> d.size() |
| 100 |
| >>> |
| </pre> |
| </blockquote> |
| |
| On the subject of smart-pointers, those are supported too. For example, suppose |
| you had some code like this: |
| |
| <blockquote> |
| <pre> |
| class Foo { |
| public: |
| int x; |
| int spam(int x); |
| }; |
| |
| template<class T> class SmartPtr { |
| public: |
| ... |
| T *operator->(); |
| ... |
| }; |
| |
| typedef SmartPtr<Foo> FooPtr; |
| |
| FooPtr make_Foo(); |
| </pre> |
| </blockquote> |
| |
| To wrap this with SWIG, just tell it about a template instantiation. For example: |
| |
| <blockquote> |
| <pre> |
| %template(FooPtr) SmartPtr<Foo>; |
| </pre> |
| </blockquote> |
| |
| Now, in the target language, the wrapper object works just like you would expect: |
| |
| <blockquote> |
| <pre> |
| >>> f = make_Foo() |
| >>> f.x = 3 |
| >>> f.spam(42) |
| </pre> |
| </blockquote> |
| |
| |
| <font color="#ff0000"><h4>Myth: SWIG is just too confusing to use</h4></font> |
| |
| <h4>Fact:</h4> |
| |
| Most users find SWIG to be relatively easy to use. However, confusion can arise |
| from the following: |
| |
| <ul> |
| <li>C programming. To effectively use SWIG, you should have a good grasp of |
| basic C programming concepts like pointers, arrays, memory management, data structures, |
| functions, parameter passing semantics, and so forth. SWIG tries to make it easy for |
| C programmers to build extension modules, but it does not try to make C programming |
| easy. |
| |
| <p> |
| <li>C++. This language is so large and complicated that certain parts of SWIG |
| may not make any sense unless you are also familiar with the underlying C++ concepts. |
| |
| <P> |
| <li>Dynamic linking and shared libraries. To build extension modules, you usually |
| have to create DLLs. If you've never done this before, there is a small |
| learning curve associated with finding the right compiler and linker options. |
| |
| <p> |
| <li>Customization features. SWIG provides a large number of customization features and |
| options that can be used to control almost all parts of the wrapper generation |
| process. These are provided to better support power users and to provide the |
| flexibility needed to solve difficult real-world wrapping problems. However, |
| none of this is needed to get started. |
| |
| </ul> |
| |
| |
| |