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