[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / swig / Introduction.html

<!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 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.

<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 &lt;= 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.

<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 &gt; <b>swig -tcl example.i</b>
unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
unix &gt; <b>gcc -shared example.o example_wrap.o -o example.so</b>
unix &gt; <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 &gt; <b>swig -perl5 example.i</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b>		# This is for Solaris
unix &gt; <b>perl5.003
use example;
print example::fact(4), "\n";
print example::my_mod(23,7), "\n";
print $example::My_variable + 4.5, "\n";
&lt;ctrl-d&gt;</b>
24
2
7.5
unix &gt;
</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 &gt; <b>swig -python example.i</b>
unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
unix &gt; <b>gcc -shared example.o example_wrap.o -o _example.so</b>
unix &gt; <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.     
&gt;&gt;&gt; <b>import example</b>
&gt;&gt;&gt; <b>example.fact(4)</b>
24
&gt;&gt;&gt; <b>example.my_mod(23,7)</b>
2
&gt;&gt;&gt; <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 &gt; <b>swig -perl5 -module example example.h</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
unix &gt; <b>ld -G example.o example_wrap.o -o example.so</b>
unix &gt; <b>perl5.003
use example;
print example::fact(4), "\n";
print example::my_mod(23,7), "\n";
print $example::My_variable + 4.5, "\n";
&lt;ctrl-d&gt;</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 will be removed in a future release.
</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 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>ac_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html">http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html</a>.
The <tt>ac_python_devel</tt> macro is also helpful for generating Python extensions. See the 
<a href="http://www.gnu.org/software/ac-archive/htmldoc/index.html">Autoconf Macro 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.dll (Windows).
</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 freedoom 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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	2	<html>
	3	<head>
	4	<title>Introduction</title>
	5	<link rel="stylesheet" type="text/css" href="style.css">
	6	</head>
	7
	8	<body bgcolor="#ffffff">
	9	<H1><a name="Introduction"></a>2 Introduction</H1>
	10	<!-- INDEX -->
	11	<div class="sectiontoc">
	12	<ul>
	13	<li><a href="#Introduction_nn2">What is SWIG?</a>
	14	<li><a href="#Introduction_nn3">Why use SWIG?</a>
	15	<li><a href="#Introduction_nn4">A SWIG example</a>
	16	<ul>
	17	<li><a href="#Introduction_nn5">SWIG interface file</a>
	18	<li><a href="#Introduction_nn6">The swig command</a>
	19	<li><a href="#Introduction_nn7">Building a Perl5 module</a>
	20	<li><a href="#Introduction_nn8">Building a Python module</a>
	21	<li><a href="#Introduction_nn9">Shortcuts</a>
	22	</ul>
	23	<li><a href="#Introduction_nn10">Supported C/C++ language features</a>
	24	<li><a href="#Introduction_nn11">Non-intrusive interface building</a>
	25	<li><a href="#Introduction_build_system">Incorporating SWIG into a build system</a>
	26	<li><a href="#Introduction_nn12">Hands off code generation</a>
	27	<li><a href="#Introduction_nn13">SWIG and freedom</a>
	28	</ul>
	29	</div>
	30	<!-- INDEX -->
	31
	32
	33
	34	<H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2>
	35
	36
	37	<p>
	38	SWIG is a software development tool that simplifies the task of
	39	interfacing different languages to C and C++ programs. In a
	40	nutshell, SWIG is a compiler that takes C declarations and creates
	41	the wrappers needed to access those declarations from other languages including
	42	including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
	43	requires no modifications to existing code and can often be used to
	44	build a usable interface in only a few minutes. Possible applications
	45	of SWIG include:
	46	</p>
	47
	48	<ul>
	49	<li>Building interpreted interfaces to existing C programs.
	50	<li>Rapid prototyping and application development.
	51	<li>Interactive debugging.
	52	<li>Reengineering or refactoring of legacy software into a scripting language components.
	53	<li>Making a graphical user interface (using Tk for example).
	54	<li>Testing of C libraries and programs (using scripts).
	55	<li>Building high performance C modules for scripting languages.
	56	<li>Making C programming more enjoyable (or tolerable depending on your point of view).
	57	<li>Impressing your friends.
	58	<li>Obtaining vast sums of research funding (although obviously not applicable to the author).
	59	</ul>
	60
	61	<p>
	62	SWIG was originally designed to make it extremely easy for scientists
	63	and engineers to build extensible scientific software without having to get a
	64	degree in software engineering. Because of this, the use of
65	SWIG tends to be somewhat informal and ad-hoc (e.g., SWIG does not
66	require users to provide formal interface specifications as you would find in
67	a dedicated IDL compiler). Although
68	this style of development isn't appropriate for every
69	project, it is particularly well suited to software development in the
70	small; especially the research and development work that is commonly found
71	in scientific and engineering projects.
72
73	<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
74
75
76	<p>
77	As stated in the previous section, the primary purpose of SWIG is to simplify
78	the task of integrating C/C++ with other programming languages. However, why would
79	anyone want to do that? To answer that question, it is useful to list a few strengths
80	of C/C++ programming:
81	</p>
82
83	<ul>
84	<li>Excellent support for writing programming libraries.
85	<li>High performance (number crunching, data processing, graphics, etc.).
86	<li>Systems programming and systems integration.
87	<li>Large user community and software base.
88	</ul>
89
90	<p>
91	Next, let's list a few problems with C/C++ programming
92	</p>
93
94	<ul>
95	<li>Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number
96	of other libraries).
97	<li>Testing is time consuming (the compile/debug cycle).
98	<li>Not easy to reconfigure or customize without recompilation.
99	<li>Modularization can be tricky.
100	<li>Security concerns (buffer overflow for instance).
101	</ul>
102	<p>
103	To address these limitations, many programmers have arrived at the
104	conclusion that it is much easier to use different programming
105	languages for different tasks. For instance, writing a graphical user
106	interface may be significantly easier in a scripting language like
107	Python or Tcl (consider the reasons why millions of programmers have used languages like
108	Visual Basic if you need more proof). An interactive interpreter might also serve as a
109	useful debugging and testing tool. Other languages like Java might
110	greatly simplify the task of writing distributed computing software.
111	The key point is that different programming languages offer different
112	strengths and weaknesses. Moreover, it is extremely unlikely that any
113	programming is ever going to be perfect. Therefore, by combining
114	languages together, you can utilize the best features of each language
115	and greatly simplify certain aspects of software development.
116	</p>
117
118	<p>
119	From the standpoint of C/C++, a lot of people use SWIG because they want to break
120	out of the traditional monolithic C programming model which usually results
121	in programs that resemble this:
122
123	<ul>
124	<li>A collection of functions and variables that do something useful.
125	<li>A <tt>main()</tt> program that starts everything.
126	<li>A horrible collection of hacks that form some kind of user interface (but
127	which no-one really wants to touch).
128	</ul>
129	<p>
130	Instead of going down that route, incorporating C/C++ into a higher level language
131	often results in a more modular design, less code, better flexibility, and increased
132	programmer productivity.
133	</p>
134
135	<p>
136	SWIG tries to make the problem of C/C++ integration as painless as possible.
137	This allows you to focus on the underlying C
138	program and using the high-level language interface, but not
139	the tedious and complex chore of making the two languages talk to each
140	other. At the same time, SWIG recognizes that all applications are different. Therefore,
141	it provides a wide variety of customization features that let you change almost
142	every aspect of the language bindings. This is the main reason why SWIG has such a large
143	user manual ;-).
144
145	<H2><a name="Introduction_nn4"></a>2.3 A SWIG example</H2>
146
147
148	<p>
149	The best way to illustrate SWIG is with a simple example. Consider the
150	following C code:
151	</p>
152
153	<div class="code"><pre>
154	/* File : example.c */
155
156	double My_variable = 3.0;
157
158	/* Compute factorial of n */
159	int fact(int n) {
160	if (n <= 1) return 1;
161	else return n*fact(n-1);
162	}
163
164	/* Compute n mod m */
165	int my_mod(int n, int m) {
166	return(n % m);
167	}
168	</pre></div>
169
170	<p>
171	Suppose that you wanted to access these functions and the global
172	variable <tt>My_variable</tt> from Tcl. You start by making a SWIG
173	interface file as shown below (by convention, these files carry a .i
174	suffix) :
175
176	<H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3>
177
178
179	<div class="code"><pre>
180	/* File : example.i */
181	%module example
182	%{
183	/* Put headers and other declarations here */
184	extern double My_variable;
185	extern int fact(int);
186	extern int my_mod(int n, int m);
187	%}
188
189	extern double My_variable;
190	extern int fact(int);
191	extern int my_mod(int n, int m);
192	</pre></div>
193
194	<p>
195	The interface file contains ANSI C function prototypes and variable
196	declarations. The <tt>%module</tt> directive defines the name of the
197	module that will be created by SWIG. The <tt>%{,%}</tt> block
198	provides a location for inserting additional code such as C header
199	files or additional C declarations.
200
201	<H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3>
202
203
204	<p>
205	SWIG is invoked using the <tt>swig</tt> command. We can use this to
206	build a Tcl module (under Linux) as follows :
207	</p>
208
209	<div class="shell"><pre>
210	unix > <b>swig -tcl example.i</b>
211	unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
212	unix > <b>gcc -shared example.o example_wrap.o -o example.so</b>
213	unix > <b>tclsh</b>
214	% <b>load ./example.so</b>
215	% <b>fact 4</b>
216	24
217	% <b>my_mod 23 7</b>
218	2
219	% <b>expr $My_variable + 4.5</b>
220	7.5
221	%
222	</pre></div>
223	<p>
224
225	The <tt>swig</tt> command produced a new file called
226	<tt>example_wrap.c</tt> that should be compiled along with the
227	<tt>example.c</tt> file. Most operating systems and scripting
228	languages now support dynamic loading of modules. In our example, our
229	Tcl module has been compiled into a shared library that can be loaded
230	into Tcl. When loaded, Tcl can now access the functions
231	and variables declared in the SWIG interface. A look at the file
232	<tt>example_wrap.c</tt> reveals a hideous mess. However, you
233	almost never need to worry about it.
234
235	<H3><a name="Introduction_nn7"></a>2.3.3 Building a Perl5 module</H3>
236
237
238	<p>
239	Now, let's turn these functions into a Perl5 module. Without making
240	any changes type the following (shown for Solaris):
241	</p>
242
243	<div class="shell"><pre>
244	unix > <b>swig -perl5 example.i</b>
245	unix > <b>gcc -c example.c example_wrap.c \
246	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
247	unix > <b>ld -G example.o example_wrap.o -o example.so</b> # This is for Solaris
248	unix > <b>perl5.003
249	use example;
250	print example::fact(4), "\n";
251	print example::my_mod(23,7), "\n";
252	print $example::My_variable + 4.5, "\n";
253	<ctrl-d></b>
254	24
255	2
256	7.5
257	unix >
258	</pre></div>
259
260
261	<H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3>
262
263
264	<p>
265	Finally, let's build a module for Python (shown for Irix).
266	</p>
267
268	<div class="shell"><pre>
269	unix > <b>swig -python example.i</b>
270	unix > <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
271	unix > <b>gcc -shared example.o example_wrap.o -o _example.so</b>
272	unix > <b>python</b>
273	Python 2.0 (#6, Feb 21 2001, 13:29:45)
274	[GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
275	Type "copyright", "credits" or "license" for more information.
276	>>> <b>import example</b>
277	>>> <b>example.fact(4)</b>
278	24
279	>>> <b>example.my_mod(23,7)</b>
280	2
281	>>> <b>example.cvar.My_variable + 4.5</b>
282	7.5
283	</pre></div>
284
285	<H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3>
286
287
288	<p>
289	To the truly lazy programmer, one may wonder why we needed the extra
290	interface file at all. As it turns out, you can often do without
291	it. For example, you could also build a Perl5 module by just running
292	SWIG on the C header file and specifying a module name as follows
293	</p>
294
295	<div class="shell"><pre>
296	unix > <b>swig -perl5 -module example example.h</b>
297	unix > <b>gcc -c example.c example_wrap.c \
298	-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
299	unix > <b>ld -G example.o example_wrap.o -o example.so</b>
300	unix > <b>perl5.003
301	use example;
302	print example::fact(4), "\n";
303	print example::my_mod(23,7), "\n";
304	print $example::My_variable + 4.5, "\n";
305	<ctrl-d></b>
306	24
307	2
308	7.5
309	</pre></div>
310
311	<H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2>
312
313
314	<p>
315	A primary goal of the SWIG project is to make the language binding
316	process extremely easy. Although a few simple examples have been shown,
317	SWIG is quite capable in supporting most of C++. Some of the
318	major features include:
319	</p>
320
321	<ul>
322	<li>Full C99 preprocessing.
323	<li>All ANSI C and C++ datatypes.
324	<li>Functions, variables, and constants.
325	<li>Classes.
326	<li>Single and multiple inheritance.
327	<li>Overloaded functions and methods.
328	<li>Overloaded operators.
329	<li>C++ templates (including member templates, specialization, and partial specialization).
330	<li>Namespaces.
331	<li>Variable length arguments.
332	<li>C++ smart pointers.
333	</ul>
334
335	<p>
336	Currently, the only major C++ feature not supported is nested classes--a limitation
337	that will be removed in a future release.
338	</p>
339
340	<p>
341	It is important to stress that SWIG is not a simplistic C++ lexing
342	tool like several apparently similar wrapper generation tools. SWIG
343	not only parses C++, it implements the full C++ type system and it is
344	able to understand C++ semantics. SWIG generates its wrappers with
345	full knowledge of this information. As a result, you will find SWIG
346	to be just as capable of dealing with nasty corner cases as it is in
347	wrapping simple C++ code. In fact, SWIG is able handle C++ code that
348	stresses the very limits of many C++ compilers.
349
350
351	<H2><a name="Introduction_nn11"></a>2.5 Non-intrusive interface building</H2>
352
353
354	<p>
355	When used as intended, SWIG requires minimal (if any) modification to
356	existing C or C++ code. This makes SWIG extremely easy to use with existing
357	packages and promotes software reuse and modularity. By making
358	the C/C++ code independent of the high level interface, you can change the
359	interface and reuse the code in other applications. It is also
360	possible to support different types of interfaces depending on the application.
361	</p>
362
363	<H2><a name="Introduction_build_system"></a>2.6 Incorporating SWIG into a build system</H2>
364
365
366	<p>
367	SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers.
368	SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from from popular IDEs such as
369	Microsoft Visual Studio.
370	</p>
371
372	<p>
373	If you are using the GNU Autotools
374	(<a href="http://www.gnu.org/software/autoconf">Autoconf</a>/
375	<a href="http://www.gnu.org/software/automake">Automake</a>/
376	<a href="http://www.gnu.org/software/libtool">Libtool</a>)
377	to configure SWIG use in your project, the SWIG Autoconf macros can be used.
378	The primary macro is <tt>ac_pkg_swig</tt>, see
379	<a href="http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html">http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html</a>.
380	The <tt>ac_python_devel</tt> macro is also helpful for generating Python extensions. See the
381	<a href="http://www.gnu.org/software/ac-archive/htmldoc/index.html">Autoconf Macro Archive</a>
382	for further information on this and other Autoconf macros.
383	</p>
384
385	<p>
386	There is growing support for SWIG in some build tools, for example <a href="http://www.cmake.org">CMake</a>
387	is a cross-platform, open-source build manager with built in support for SWIG. CMake can detect the SWIG executable
388	and many of the target language libraries for linking against.
389	CMake knows how to build shared libraries and loadable modules on many different operating systems.
390	This allows easy cross platform SWIG development. It also can generate the custom commands necessary for
391	driving SWIG from IDE's and makefiles. All of this can be done from a single cross platform input file.
392	The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
393	</p>
394
395	<div class="code"><pre>
396
397	# This is a CMake example for Python
398
399	FIND_PACKAGE(SWIG REQUIRED)
400	INCLUDE(${SWIG_USE_FILE})
401
402	FIND_PACKAGE(PythonLibs)
403	INCLUDE_DIRECTORIES(${PYTHON_INCLUDE_PATH})
404
405	INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR})
406
407	SET(CMAKE_SWIG_FLAGS "")
408
409	SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES CPLUSPLUS ON)
410	SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
411	SWIG_ADD_MODULE(example python example.i example.cxx)
412	SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
413
414	</pre></div>
415	<p>
416	The above example will generate native build files such as makefiles, nmake files and Visual Studio projects
417	which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.dll (Windows).
418	</p>
419
420	<H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>
421
422
423	<p>
424	SWIG is designed to produce working code that needs no
425	hand-modification (in fact, if you look at the output, you probably
426	won't want to modify it). You should think of your target language interface being
427	defined entirely by the input to SWIG, not the resulting output
428	file. While this approach may limit flexibility for hard-core hackers,
429	it allows others to forget about the low-level implementation
430	details.
431	</p>
432
433	<H2><a name="Introduction_nn13"></a>2.8 SWIG and freedom</H2>
434
435
436	<p>
437	No, this isn't a special section on the sorry state of world politics.
438	However, it may be useful to know that SWIG was written with a
439	certain "philosophy" about programming---namely that programmers are
440	smart and that tools should just stay out of their way. Because of
441	that, you will find that SWIG is extremely permissive in what it lets
442	you get away with. In fact, you can use SWIG to go well beyond
443	"shooting yourself in the foot" if dangerous programming is your goal.
444	On the other hand, this kind of freedoom may be exactly what is needed
445	to work with complicated and unusual C/C++ applications.
446	</p>
447
448	<p>
449	Ironically, the freedom that SWIG provides is countered by an
450	extremely conservative approach to code generation. At it's core, SWIG
451	tries to distill even the most advanced C++ code down to a small
452	well-defined set of interface building techniques based on ANSI C
453	programming. Because of this, you will find that SWIG interfaces can
454	be easily compiled by virtually every C/C++ compiler and that they can
455	be used on any platform. Again, this is an important part of staying out
456	of the programmer's way----the last thing any developer wants to do is
457	to spend their time debugging the output of a tool that relies on
458	non-portable or unreliable programming features.
459
460	</body>
461	</html>