/trunk/Doc/Manual/Introduction.html
HTML | 463 lines | 382 code | 79 blank | 2 comment | 0 complexity | 50c1a175435e34e12ae7a6291c0efcf6 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <title>Introduction</title>
- <link rel="stylesheet" type="text/css" href="style.css">
- </head>
- <body bgcolor="#ffffff">
- <H1><a name="Introduction"></a>2 Introduction</H1>
- <!-- INDEX -->
- <div class="sectiontoc">
- <ul>
- <li><a href="#Introduction_nn2">What is SWIG?</a>
- <li><a href="#Introduction_nn3">Why use SWIG?</a>
- <li><a href="#Introduction_nn4">A SWIG example</a>
- <ul>
- <li><a href="#Introduction_nn5">SWIG interface file</a>
- <li><a href="#Introduction_nn6">The swig command</a>
- <li><a href="#Introduction_nn7">Building a Perl5 module</a>
- <li><a href="#Introduction_nn8">Building a Python module</a>
- <li><a href="#Introduction_nn9">Shortcuts</a>
- </ul>
- <li><a href="#Introduction_nn10">Supported C/C++ language features</a>
- <li><a href="#Introduction_nn11">Non-intrusive interface building</a>
- <li><a href="#Introduction_build_system">Incorporating SWIG into a build system</a>
- <li><a href="#Introduction_nn12">Hands off code generation</a>
- <li><a href="#Introduction_nn13">SWIG and freedom</a>
- </ul>
- </div>
- <!-- INDEX -->
- <H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2>
- <p>
- SWIG is a software development tool that simplifies the task of
- interfacing different languages to C and C++ programs. In a
- nutshell, SWIG is a compiler that takes C/C++ declarations and creates
- the wrappers needed to access those declarations from other languages including
- including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
- requires no modifications to existing code and can often be used to
- build a usable interface in only a few minutes. Possible applications
- of SWIG include:
- </p>
- <ul>
- <li>Building interpreted interfaces to existing C programs.
- <li>Rapid prototyping and application development.
- <li>Interactive debugging.
- <li>Reengineering or refactoring of legacy software into a scripting language components.
- <li>Making a graphical user interface (using Tk for example).
- <li>Testing of C libraries and programs (using scripts).
- <li>Building high performance C modules for scripting languages.
- <li>Making C programming more enjoyable (or tolerable depending on your point of view).
- <li>Impressing your friends.
- <li>Obtaining vast sums of research funding (although obviously not applicable to the author).
- </ul>
- <p>
- SWIG was originally designed to make it extremely easy for scientists
- and engineers to build extensible scientific software without having to get a
- degree in software engineering. Because of this, the use of
- SWIG tends to be somewhat informal and ad-hoc (e.g., SWIG does not
- require users to provide formal interface specifications as you would find in
- a dedicated IDL compiler). Although
- this style of development isn't appropriate for every
- project, it is particularly well suited to software development in the
- small; especially the research and development work that is commonly found
- in scientific and engineering projects. However, nowadays SWIG is known to be used in many
- large open source and commercial projects.
- <H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
- <p>
- As stated in the previous section, the primary purpose of SWIG is to simplify
- the task of integrating C/C++ with other programming languages. However, why would
- anyone want to do that? To answer that question, it is useful to list a few strengths
- of C/C++ programming:
- </p>
- <ul>
- <li>Excellent support for writing programming libraries.
- <li>High performance (number crunching, data processing, graphics, etc.).
- <li>Systems programming and systems integration.
- <li>Large user community and software base.
- </ul>
- <p>
- Next, let's list a few problems with C/C++ programming
- </p>
- <ul>
- <li>Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number
- of other libraries).
- <li>Testing is time consuming (the compile/debug cycle).
- <li>Not easy to reconfigure or customize without recompilation.
- <li>Modularization can be tricky.
- <li>Security concerns (buffer overflow for instance).
- </ul>
- <p>
- To address these limitations, many programmers have arrived at the
- conclusion that it is much easier to use different programming
- languages for different tasks. For instance, writing a graphical user
- interface may be significantly easier in a scripting language like
- Python or Tcl (consider the reasons why millions of programmers have used languages like
- Visual Basic if you need more proof). An interactive interpreter might also serve as a
- useful debugging and testing tool. Other languages like Java might
- greatly simplify the task of writing distributed computing software.
- The key point is that different programming languages offer different
- strengths and weaknesses. Moreover, it is extremely unlikely that any
- programming is ever going to be perfect. Therefore, by combining
- languages together, you can utilize the best features of each language
- and greatly simplify certain aspects of software development.
- </p>
- <p>
- From the standpoint of C/C++, a lot of people use SWIG because they want to break
- out of the traditional monolithic C programming model which usually results
- in programs that resemble this:
- <ul>
- <li>A collection of functions and variables that do something useful.
- <li>A <tt>main()</tt> program that starts everything.
- <li>A horrible collection of hacks that form some kind of user interface (but
- which no-one really wants to touch).
- </ul>
- <p>
- Instead of going down that route, incorporating C/C++ into a higher level language
- often results in a more modular design, less code, better flexibility, and increased
- programmer productivity.
- </p>
- <p>
- SWIG tries to make the problem of C/C++ integration as painless as possible.
- This allows you to focus on the underlying C
- program and using the high-level language interface, but not
- the tedious and complex chore of making the two languages talk to each
- other. At the same time, SWIG recognizes that all applications are different. Therefore,
- it provides a wide variety of customization features that let you change almost
- every aspect of the language bindings. This is the main reason why SWIG has such a large
- user manual ;-).
- <H2><a name="Introduction_nn4"></a>2.3 A SWIG example</H2>
- <p>
- The best way to illustrate SWIG is with a simple example. Consider the
- following C code:
- </p>
- <div class="code"><pre>
- /* File : example.c */
- double My_variable = 3.0;
- /* Compute factorial of n */
- int fact(int n) {
- if (n <= 1) return 1;
- else return n*fact(n-1);
- }
- /* Compute n mod m */
- int my_mod(int n, int m) {
- return(n % m);
- }
- </pre></div>
- <p>
- Suppose that you wanted to access these functions and the global
- variable <tt>My_variable</tt> from Tcl. You start by making a SWIG
- interface file as shown below (by convention, these files carry a .i
- suffix) :
- <H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3>
- <div class="code"><pre>
- /* File : example.i */
- %module example
- %{
- /* Put headers and other declarations here */
- extern double My_variable;
- extern int fact(int);
- extern int my_mod(int n, int m);
- %}
- extern double My_variable;
- extern int fact(int);
- extern int my_mod(int n, int m);
- </pre></div>
- <p>
- The interface file contains ANSI C function prototypes and variable
- declarations. The <tt>%module</tt> directive defines the name of the
- module that will be created by SWIG. The <tt>%{ %}</tt> block
- provides a location for inserting additional code, such as C header
- files or additional C declarations, into the generated C wrapper code.
- <H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3>
- <p>
- SWIG is invoked using the <tt>swig</tt> command. We can use this to
- build a Tcl module (under Linux) as follows :
- </p>
- <div class="shell"><pre>
- unix > <b>swig -tcl example.i</b>
- unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
- unix > <b>gcc -shared example.o example_wrap.o -o example.so</b>
- unix > <b>tclsh</b>
- % <b>load ./example.so</b>
- % <b>fact 4</b>
- 24
- % <b>my_mod 23 7</b>
- 2
- % <b>expr $My_variable + 4.5</b>
- 7.5
- %
- </pre></div>
- <p>
- The <tt>swig</tt> command produced a new file called
- <tt>example_wrap.c</tt> that should be compiled along with the
- <tt>example.c</tt> file. Most operating systems and scripting
- languages now support dynamic loading of modules. In our example, our
- Tcl module has been compiled into a shared library that can be loaded
- into Tcl. When loaded, Tcl can now access the functions
- and variables declared in the SWIG interface. A look at the file
- <tt>example_wrap.c</tt> reveals a hideous mess. However, you
- almost never need to worry about it.
- <H3><a name="Introduction_nn7"></a>2.3.3 Building a Perl5 module</H3>
- <p>
- Now, let's turn these functions into a Perl5 module. Without making
- any changes type the following (shown for Solaris):
- </p>
- <div class="shell"><pre>
- unix > <b>swig -perl5 example.i</b>
- unix > <b>gcc -c example.c example_wrap.c \
- -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
- unix > <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris
- unix > <b>perl5.003
- use example;
- print example::fact(4), "\n";
- print example::my_mod(23,7), "\n";
- print $example::My_variable + 4.5, "\n";
- <ctrl-d></b>
- 24
- 2
- 7.5
- unix >
- </pre></div>
- <H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3>
- <p>
- Finally, let's build a module for Python (shown for Irix).
- </p>
- <div class="shell"><pre>
- unix > <b>swig -python example.i</b>
- unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
- unix > <b>gcc -shared example.o example_wrap.o -o _example.so</b>
- unix > <b>python</b>
- Python 2.0 (#6, Feb 21 2001, 13:29:45)
- [GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
- Type "copyright", "credits" or "license" for more information.
- >>> <b>import example</b>
- >>> <b>example.fact(4)</b>
- 24
- >>> <b>example.my_mod(23,7)</b>
- 2
- >>> <b>example.cvar.My_variable + 4.5</b>
- 7.5
- </pre></div>
- <H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3>
- <p>
- To the truly lazy programmer, one may wonder why we needed the extra
- interface file at all. As it turns out, you can often do without
- it. For example, you could also build a Perl5 module by just running
- SWIG on the C header file and specifying a module name as follows
- </p>
- <div class="shell"><pre>
- unix > <b>swig -perl5 -module example example.h</b>
- unix > <b>gcc -c example.c example_wrap.c \
- -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
- unix > <b>ld -G example.o example_wrap.o -o example.so</b>
- unix > <b>perl5.003
- use example;
- print example::fact(4), "\n";
- print example::my_mod(23,7), "\n";
- print $example::My_variable + 4.5, "\n";
- <ctrl-d></b>
- 24
- 2
- 7.5
- </pre></div>
- <H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2>
- <p>
- A primary goal of the SWIG project is to make the language binding
- process extremely easy. Although a few simple examples have been shown,
- SWIG is quite capable in supporting most of C++. Some of the
- major features include:
- </p>
- <ul>
- <li>Full C99 preprocessing.
- <li>All ANSI C and C++ datatypes.
- <li>Functions, variables, and constants.
- <li>Classes.
- <li>Single and multiple inheritance.
- <li>Overloaded functions and methods.
- <li>Overloaded operators.
- <li>C++ templates (including member templates, specialization, and partial specialization).
- <li>Namespaces.
- <li>Variable length arguments.
- <li>C++ smart pointers.
- </ul>
- <p>
- Currently, the only major C++ feature not supported is nested classes--a limitation
- that should be removed in a future release, but has some workarounds for the moment.
- </p>
- <p>
- It is important to stress that SWIG is not a simplistic C++ lexing
- tool like several apparently similar wrapper generation tools. SWIG
- not only parses C++, it implements the full C++ type system and it is
- able to understand C++ semantics. SWIG generates its wrappers with
- full knowledge of this information. As a result, you will find SWIG
- to be just as capable of dealing with nasty corner cases as it is in
- wrapping simple C++ code. In fact, SWIG is able handle C++ code that
- stresses the very limits of many C++ compilers.
- <H2><a name="Introduction_nn11"></a>2.5 Non-intrusive interface building</H2>
- <p>
- When used as intended, SWIG requires minimal (if any) modification to
- existing C or C++ code. This makes SWIG extremely easy to use with existing
- packages and promotes software reuse and modularity. By making
- the C/C++ code independent of the high level interface, you can change the
- interface and reuse the code in other applications. It is also
- possible to support different types of interfaces depending on the application.
- </p>
- <H2><a name="Introduction_build_system"></a>2.6 Incorporating SWIG into a build system</H2>
- <p>
- SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers.
- SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from popular IDEs such as
- Microsoft Visual Studio.
- </p>
- <p>
- If you are using the GNU Autotools
- (<a href="http://www.gnu.org/software/autoconf/">Autoconf</a>/
- <a href="http://www.gnu.org/software/automake/">Automake</a>/
- <a href="http://www.gnu.org/software/libtool/">Libtool</a>)
- to configure SWIG use in your project, the SWIG Autoconf macros can be used.
- The primary macro is <tt>ax_pkg_swig</tt>, see
- <a href="http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
- The <tt>ax_python_devel</tt> macro is also helpful for generating Python extensions. See the
- <a href="http://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
- for further information on this and other Autoconf macros.
- </p>
- <p>
- There is growing support for SWIG in some build tools, for example <a href="http://www.cmake.org">CMake</a>
- is a cross-platform, open-source build manager with built in support for SWIG. CMake can detect the SWIG executable
- and many of the target language libraries for linking against.
- CMake knows how to build shared libraries and loadable modules on many different operating systems.
- This allows easy cross platform SWIG development. It also can generate the custom commands necessary for
- driving SWIG from IDE's and makefiles. All of this can be done from a single cross platform input file.
- The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
- </p>
- <div class="code"><pre>
- # This is a CMake example for Python
- FIND_PACKAGE(SWIG REQUIRED)
- INCLUDE(${SWIG_USE_FILE})
- FIND_PACKAGE(PythonLibs)
- INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})
- INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
- SET(CMAKE_SWIG_FLAGS "")
- SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)
- SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
- SWIG_ADD_MODULE(example python example.i example.cxx)
- SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
- </pre></div>
- <p>
- The above example will generate native build files such as makefiles, nmake files and Visual Studio projects
- which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.pyd (Windows).
- For other target languages on Windows a dll, instead of a .pyd file, is usually generated.
- </p>
- <H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>
- <p>
- SWIG is designed to produce working code that needs no
- hand-modification (in fact, if you look at the output, you probably
- won't want to modify it). You should think of your target language interface being
- defined entirely by the input to SWIG, not the resulting output
- file. While this approach may limit flexibility for hard-core hackers,
- it allows others to forget about the low-level implementation
- details.
- </p>
- <H2><a name="Introduction_nn13"></a>2.8 SWIG and freedom</H2>
- <p>
- No, this isn't a special section on the sorry state of world politics.
- However, it may be useful to know that SWIG was written with a
- certain "philosophy" about programming---namely that programmers are
- smart and that tools should just stay out of their way. Because of
- that, you will find that SWIG is extremely permissive in what it lets
- you get away with. In fact, you can use SWIG to go well beyond
- "shooting yourself in the foot" if dangerous programming is your goal.
- On the other hand, this kind of freedom may be exactly what is needed
- to work with complicated and unusual C/C++ applications.
- </p>
- <p>
- Ironically, the freedom that SWIG provides is countered by an
- extremely conservative approach to code generation. At it's core, SWIG
- tries to distill even the most advanced C++ code down to a small
- well-defined set of interface building techniques based on ANSI C
- programming. Because of this, you will find that SWIG interfaces can
- be easily compiled by virtually every C/C++ compiler and that they can
- be used on any platform. Again, this is an important part of staying out
- of the programmer's way----the last thing any developer wants to do is
- to spend their time debugging the output of a tool that relies on
- non-portable or unreliable programming features.
- </body>
- </html>