39d92e49b2
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@5776 626c5289-ae23-0410-ae9c-e8d60b6d4f22
378 lines
No EOL
14 KiB
HTML
378 lines
No EOL
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Introduction</title>
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<a name="n1"></a><H1>1 Introduction</H1>
|
|
<!-- INDEX -->
|
|
<ul>
|
|
<li><a href="#n2">What is SWIG?</a>
|
|
<li><a href="#n3">Why use SWIG?</a>
|
|
<li><a href="#n4">A SWIG example</a>
|
|
<ul>
|
|
<li><a href="#n5">SWIG interface file</a>
|
|
<li><a href="#n6">The swig command</a>
|
|
<li><a href="#n7">Building a Perl5 module</a>
|
|
<li><a href="#n8">Building a Python module</a>
|
|
<li><a href="#n9">Shortcuts</a>
|
|
</ul>
|
|
<li><a href="#n10">Supported C/C++ language features</a>
|
|
<li><a href="#n11">Non-intrusive interface building</a>
|
|
<li><a href="#n12">Hands off code generation</a>
|
|
<li><a href="#n13">SWIG and freedom</a>
|
|
</ul>
|
|
<!-- INDEX -->
|
|
|
|
|
|
|
|
<a name="n2"></a><H2>1.1 What is SWIG?</H2>
|
|
|
|
|
|
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 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.
|
|
|
|
<a name="n3"></a><H2>1.2 Why use SWIG?</H2>
|
|
|
|
|
|
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:
|
|
|
|
<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>
|
|
|
|
Next, let's list a few problems with C/C++ programming
|
|
|
|
<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>
|
|
|
|
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>
|
|
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:
|
|
|
|
<p>
|
|
<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>
|
|
|
|
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>
|
|
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 ;-).
|
|
<p>
|
|
|
|
<a name="n4"></a><H2>1.3 A SWIG example</H2>
|
|
|
|
|
|
The best way to illustrate SWIG is with a simple example. Consider the
|
|
following C code: <p>
|
|
|
|
<p>
|
|
<blockquote><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></blockquote>
|
|
|
|
<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) : <p>
|
|
|
|
<a name="n5"></a><H3>1.3.1 SWIG interface file</H3>
|
|
|
|
|
|
<blockquote><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);
|
|
</pre></blockquote>
|
|
|
|
<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. <p>
|
|
|
|
<a name="n6"></a><H3>1.3.2 The swig command</H3>
|
|
|
|
|
|
SWIG is invoked using the <tt>swig</tt> command. We can use this to
|
|
build a Tcl module (under Linux) as follows :<p>
|
|
|
|
<p>
|
|
<blockquote><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></blockquote>
|
|
<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.<p>
|
|
|
|
<a name="n7"></a><H3>1.3.3 Building a Perl5 module</H3>
|
|
|
|
|
|
Now, let's turn these functions into a Perl5 module. Without making
|
|
any changes type the following (shown for Solaris):<p>
|
|
|
|
<p>
|
|
<p>
|
|
<blockquote><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></blockquote>
|
|
|
|
|
|
<a name="n8"></a><H3>1.3.4 Building a Python module</H3>
|
|
|
|
|
|
Finally, let's build a module for Python (shown for Irix).<p>
|
|
|
|
<p>
|
|
<blockquote><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></blockquote>
|
|
|
|
<a name="n9"></a><H3>1.3.5 Shortcuts</H3>
|
|
|
|
|
|
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>
|
|
|
|
<p>
|
|
<blockquote><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></blockquote>
|
|
|
|
<a name="n10"></a><H2>1.4 Supported C/C++ language features</H2>
|
|
|
|
|
|
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:
|
|
|
|
<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>
|
|
|
|
Currently, the only major C++ feature not supported is nested classes--a limitation
|
|
that will be removed in a future release.
|
|
|
|
<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.
|
|
|
|
|
|
<a name="n11"></a><H2>1.5 Non-intrusive interface building</H2>
|
|
|
|
|
|
When used as intended, SWIG requires minimal (if any) modification to
|
|
existing C code. This makes SWIG extremely easy to use with existing
|
|
packages and promotes software reuse and modularity. By making
|
|
the 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.
|
|
|
|
<a name="n12"></a><H2>1.6 Hands off code generation</H2>
|
|
|
|
|
|
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). Ideally, SWIG should be invoked
|
|
automatically inside a Makefile just as one would call the C
|
|
compiler. You should think of your scripting 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.
|
|
|
|
<a name="n13"></a><H2>1.7 SWIG and freedom</H2>
|
|
|
|
|
|
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 freedoom may be exactly what is needed
|
|
to work with complicated and unusual C/C++ applications.
|
|
|
|
<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.
|
|
|
|
<p><hr>
|
|
|
|
<address>SWIG 1.3 - Last Modified : August 10, 2002</address>
|
|
</body>
|
|
</html> |