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