| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <title>Preface</title> |
| 5 | <link rel="stylesheet" type="text/css" href="style.css"> |
| 6 | </head> |
| 7 | |
| 8 | <body bgcolor="#ffffff"> |
| 9 | <H1><a name="Preface"></a>1 Preface</H1> |
| 10 | <!-- INDEX --> |
| 11 | <div class="sectiontoc"> |
| 12 | <ul> |
| 13 | <li><a href="#Preface_nn2">Introduction</a> |
| 14 | <li><a href="#Preface_nn3">Special Introduction for Version 1.3</a> |
| 15 | <li><a href="#Preface_nn4">SWIG Versions</a> |
| 16 | <li><a href="#Preface_nn5">SWIG resources</a> |
| 17 | <li><a href="#Preface_nn6">Prerequisites</a> |
| 18 | <li><a href="#Preface_nn7">Organization of this manual</a> |
| 19 | <li><a href="#Preface_nn8">How to avoid reading the manual</a> |
| 20 | <li><a href="#Preface_nn9">Backwards Compatibility</a> |
| 21 | <li><a href="#Preface_nn10">Credits</a> |
| 22 | <li><a href="#Preface_nn11">Bug reports</a> |
| 23 | </ul> |
| 24 | </div> |
| 25 | <!-- INDEX --> |
| 26 | |
| 27 | |
| 28 | |
| 29 | <H2><a name="Preface_nn2"></a>1.1 Introduction</H2> |
| 30 | |
| 31 | |
| 32 | <p> |
| 33 | SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language |
| 34 | interfaces to C and C++ programs. Originally developed in 1995, SWIG was |
| 35 | first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for |
| 36 | building user interfaces to simulation codes running on the Connection |
| 37 | Machine 5 supercomputer. In this environment, scientists needed to |
| 38 | work with huge amounts of simulation data, complex hardware, and a |
| 39 | constantly changing code base. The use of a scripting language |
| 40 | interface provided a simple yet highly flexible foundation for solving these |
| 41 | types of problems. SWIG simplifies development by largely automating |
| 42 | the task of scripting language integration--allowing developers and users |
| 43 | to focus on more important problems. |
| 44 | </p> |
| 45 | |
| 46 | <p> |
| 47 | Although SWIG was originally developed for scientific applications, it |
| 48 | has since evolved into a general purpose tool that is used in a wide |
| 49 | variety of applications--in fact almost anything where C/C++ programming |
| 50 | is involved. |
| 51 | |
| 52 | <H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2> |
| 53 | |
| 54 | |
| 55 | <p> |
| 56 | Since SWIG was released in 1996, its user base and applicability has |
| 57 | continued to grow. Although its rate of development has varied, an |
| 58 | active development effort has continued to make improvements to the |
| 59 | system. Today, nearly a dozen developers are working to create |
| 60 | SWIG-2.0---a system that aims to provide wrapping support for nearly |
| 61 | all of the ANSI C++ standard and approximately ten target languages |
| 62 | including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby, |
| 63 | and Tcl. |
| 64 | </p> |
| 65 | |
| 66 | <H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2> |
| 67 | |
| 68 | |
| 69 | <p> |
| 70 | For several years, the most stable version of SWIG has been release |
| 71 | 1.1p5. Starting with version 1.3, a new version numbering scheme has |
| 72 | been adopted. Odd version numbers (1.3, 1.5, etc.) represent |
| 73 | development versions of SWIG. Even version numbers (1.4, 1.6, etc.) |
| 74 | represent stable releases. Currently, developers are working to |
| 75 | create a stable SWIG-2.0 release. Don't let the development status |
| 76 | of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5. |
| 77 | </p> |
| 78 | |
| 79 | <H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2> |
| 80 | |
| 81 | |
| 82 | <p> |
| 83 | The official location of SWIG related material is |
| 84 | </p> |
| 85 | |
| 86 | <div class="shell"><pre> |
| 87 | <a href="http://www.swig.org">http://www.swig.org</a> |
| 88 | </pre></div> |
| 89 | |
| 90 | <p> |
| 91 | This site contains the latest version of the software, users guide, |
| 92 | and information regarding bugs, installation problems, and |
| 93 | implementation tricks. |
| 94 | |
| 95 | <p> |
| 96 | You can also subscribe to the SWIG mailing list by visiting the page |
| 97 | </p> |
| 98 | |
| 99 | <div class="shell"><pre> |
| 100 | <a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a> |
| 101 | </pre></div> |
| 102 | |
| 103 | <p> |
| 104 | The mailing list often discusses some of the more technical aspects of |
| 105 | SWIG along with information about beta releases and future work. |
| 106 | </p> |
| 107 | |
| 108 | <p> |
| 109 | CVS access to the latest version of SWIG is also available. More information |
| 110 | about this can be obtained at: |
| 111 | </p> |
| 112 | |
| 113 | <div class="shell"><pre> |
| 114 | <a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a> |
| 115 | </pre></div> |
| 116 | |
| 117 | |
| 118 | <H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2> |
| 119 | |
| 120 | |
| 121 | <p> |
| 122 | This manual assumes that you know how to write C/C++ programs and that you |
| 123 | have at least heard of scripting languages such as |
| 124 | Tcl, Python, and Perl. A detailed knowledge of these scripting |
| 125 | languages is not required although some familiarity won't |
| 126 | hurt. No prior experience with building C extensions to these |
| 127 | languages is required---after all, this is what SWIG does automatically. |
| 128 | However, you should be reasonably familiar with the use of |
| 129 | compilers, linkers, and makefiles since making |
| 130 | scripting language extensions is somewhat more complicated than |
| 131 | writing a normal C program. |
| 132 | </p> |
| 133 | |
| 134 | <p> |
| 135 | Recent SWIG releases have become significantly more capable in |
| 136 | their C++ handling--especially support for advanced features like |
| 137 | namespaces, overloaded operators, and templates. Whenever possible, |
| 138 | this manual tries to cover the technicalities of this interface. |
| 139 | However, this isn't meant to be a tutorial on C++ programming. For many |
| 140 | of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program |
| 141 | in C++, you may just want to skip those parts of the manual. |
| 142 | |
| 143 | <H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2> |
| 144 | |
| 145 | |
| 146 | <p> |
| 147 | The first few chapters of this manual describe SWIG in general and |
| 148 | provide an overview of its capabilities. The remaining chapters are |
| 149 | devoted to specific SWIG language modules and are self |
| 150 | contained. Thus, if you are using SWIG to build Python interfaces, you |
| 151 | can probably skip to that chapter and find almost everything you need |
| 152 | to know. Caveat: we are currently working on a documentation rewrite and many |
| 153 | of the older language module chapters are still somewhat out of date. |
| 154 | </p> |
| 155 | |
| 156 | <H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2> |
| 157 | |
| 158 | |
| 159 | <p> |
| 160 | If you hate reading manuals, glance at the "Introduction" which |
| 161 | contains a few simple examples. These |
| 162 | examples contain about 95% of everything you need to know to use |
| 163 | SWIG. After that, simply use the language-specific chapters as a reference. |
| 164 | The SWIG distribution also comes with a large directory of |
| 165 | examples that illustrate different topics. |
| 166 | </p> |
| 167 | |
| 168 | <H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2> |
| 169 | |
| 170 | |
| 171 | <p> |
| 172 | If you are a previous user of SWIG, don't expect recent versions of |
| 173 | SWIG to provide backwards compatibility. In fact, backwards |
| 174 | compatibility issues may arise even between successive 1.3.x releases. |
| 175 | Although these incompatibilities are regrettable, SWIG-1.3 is an active |
| 176 | development project. The primary goal of this effort is to make SWIG |
| 177 | better---a process that would simply be impossible if the developers |
| 178 | are constantly bogged down with backwards compatibility issues. |
| 179 | </p> |
| 180 | |
| 181 | <p> |
| 182 | On a positive note, a few incompatibilities are a small price to pay |
| 183 | for the large number of new features that have been |
| 184 | added---namespaces, templates, smart pointers, overloaded methods, |
| 185 | operators, and more. |
| 186 | </p> |
| 187 | |
| 188 | |
| 189 | <p> |
| 190 | If you need to work with different versions of SWIG and backwards |
| 191 | compatibility is an issue, you can use the SWIG_VERSION preprocessor |
| 192 | symbol which holds the version of SWIG being executed. |
| 193 | SWIG_VERSION is a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11). |
| 194 | This can be used in an interface file to define different typemaps, take |
| 195 | advantage of different features etc: |
| 196 | </p> |
| 197 | |
| 198 | <div class="code"><pre> |
| 199 | #if SWIG_VERSION >= 0x010311 |
| 200 | /* Use some fancy new feature */ |
| 201 | #endif |
| 202 | </pre></div> |
| 203 | |
| 204 | <p> |
| 205 | Note: The version symbol is not defined in the generated SWIG |
| 206 | wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11. |
| 207 | </p> |
| 208 | |
| 209 | <H2><a name="Preface_nn10"></a>1.9 Credits</H2> |
| 210 | |
| 211 | |
| 212 | <p> |
| 213 | SWIG is an unfunded project that would not be possible without the |
| 214 | contributions of many people. Most recent SWIG development has been |
| 215 | supported by Matthias Köppe, William Fulton, Lyle Johnson, |
| 216 | Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki |
| 217 | Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus, |
| 218 | Harco de Hilster, John Lenz, and Surendra Singhi. |
| 219 | </p> |
| 220 | |
| 221 | <p> |
| 222 | Historically, the following people contributed to early versions of SWIG. |
| 223 | Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann |
| 224 | at Los Alamos National Laboratory were the first users. Patrick |
| 225 | Tullmann at the University of Utah suggested the idea of automatic |
| 226 | documentation generation. John Schmidt and Kurtis Bleeker at the |
| 227 | University of Utah tested out the early versions. Chris Johnson |
| 228 | supported SWIG's developed at the University of Utah. John Buckman, |
| 229 | Larry Virden, and Tom Schwaller provided valuable input on the first |
| 230 | releases and improving the portability of SWIG. David Fletcher and |
| 231 | Gary Holt have provided a great deal of input on improving SWIG's |
| 232 | Perl5 implementation. Kevin Butler contributed the first Windows NT |
| 233 | port. |
| 234 | |
| 235 | <H2><a name="Preface_nn11"></a>1.10 Bug reports</H2> |
| 236 | |
| 237 | |
| 238 | <p> |
| 239 | Although every attempt has been made to make SWIG bug-free, we are also trying |
| 240 | to make feature improvements that may introduce bugs. |
| 241 | To report a bug, either send mail to the SWIG developer |
| 242 | list at the <a href="http://www.swig.org/mail.html">swig-dev mailing list</a> or report a bug |
| 243 | at the <a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as |
| 244 | possible, including (if applicable), error messages, tracebacks (if a |
| 245 | core dump occurred), corresponding portions of the SWIG interface file |
| 246 | used, and any important pieces of the SWIG generated wrapper code. We |
| 247 | can only fix bugs if we know about them. |
| 248 | </p> |
| 249 | |
| 250 | </body> |
| 251 | </html> |