| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>Preface</title> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| <H1><a name="Preface"></a>1 Preface</H1> |
| <!-- INDEX --> |
| <div class="sectiontoc"> |
| <ul> |
| <li><a href="#Preface_nn2">Introduction</a> |
| <li><a href="#Preface_nn4">SWIG Versions</a> |
| <li><a href="#Preface_license">SWIG License</a> |
| <li><a href="#Preface_nn5">SWIG resources</a> |
| <li><a href="#Preface_nn6">Prerequisites</a> |
| <li><a href="#Preface_nn7">Organization of this manual</a> |
| <li><a href="#Preface_nn8">How to avoid reading the manual</a> |
| <li><a href="#Preface_nn9">Backwards compatibility</a> |
| <li><a href="#Preface_release_notes">Release notes</a> |
| <li><a href="#Preface_nn10">Credits</a> |
| <li><a href="#Preface_nn11">Bug reports</a> |
| <li><a href="#Preface_installation">Installation</a> |
| <ul> |
| <li><a href="#Preface_windows_installation">Windows installation</a> |
| <li><a href="#Preface_unix_installation">Unix installation</a> |
| <li><a href="#Preface_osx_installation">Macintosh OS X installation</a> |
| <li><a href="#Preface_testing">Testing</a> |
| <li><a href="#Preface_examples">Examples</a> |
| </ul> |
| </ul> |
| </div> |
| <!-- INDEX --> |
| |
| |
| |
| <H2><a name="Preface_nn2"></a>1.1 Introduction</H2> |
| |
| |
| <p> |
| SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language |
| interfaces to C and C++ programs. Originally developed in 1995, SWIG was |
| first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for |
| building user interfaces to simulation codes running on the Connection |
| Machine 5 supercomputer. In this environment, scientists needed to |
| work with huge amounts of simulation data, complex hardware, and a |
| constantly changing code base. The use of a scripting language |
| interface provided a simple yet highly flexible foundation for solving these |
| types of problems. SWIG simplifies development by largely automating |
| the task of scripting language integration--allowing developers and users |
| to focus on more important problems. |
| </p> |
| |
| <p> |
| Although SWIG was originally developed for scientific applications, it |
| has since evolved into a general purpose tool that is used in a wide |
| variety of applications--in fact almost anything where C/C++ programming |
| is involved. |
| |
| <H2><a name="Preface_nn4"></a>1.2 SWIG Versions</H2> |
| |
| |
| <p> |
| In the late 1990's, the most stable version of SWIG was release |
| 1.1p5. Versions 1.3.x were officially development versions and these were released |
| over a period of 10 years starting from the year 2000. The final version in the 1.3.x |
| series was 1.3.40, but in truth the 1.3.x series had been stable for many years. |
| An official stable version was released along with the decision to make SWIG |
| license changes and this gave rise to version 2.0.0 in 2010. |
| </p> |
| |
| <H2><a name="Preface_license"></a>1.3 SWIG License</H2> |
| |
| |
| <p> |
| The LICENSE file shipped with SWIG in the top level directory contains the SWIG license. |
| For further insight into the license including the license of SWIG's output code, please visit |
| the SWIG legal page - <a href="http://www.swig.org/legal.html">http://www.swig.org/legal.html</a>. |
| </p> |
| |
| <p> |
| The license was clarified in version 2.0.0 |
| so that the code that SWIG generated could be distributed |
| under license terms of the user's choice/requirements and at the same time the SWIG |
| source was placed under the GNU General Public License version 3. |
| </p> |
| |
| <H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2> |
| |
| |
| <p> |
| The official location of SWIG related material is |
| </p> |
| |
| <div class="shell"><pre> |
| <a href="http://www.swig.org">http://www.swig.org</a> |
| </pre></div> |
| |
| <p> |
| This site contains the latest version of the software, users guide, |
| and information regarding bugs, installation problems, and |
| implementation tricks. |
| |
| <p> |
| You can also subscribe to the swig-user mailing list by visiting the page |
| </p> |
| |
| <div class="shell"><pre> |
| <a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a> |
| </pre></div> |
| |
| <p> |
| The mailing list often discusses some of the more technical aspects of |
| SWIG along with information about beta releases and future work. |
| </p> |
| |
| <p> |
| Git and Subversion access to the latest version of SWIG is also available. More information |
| about this can be obtained at: |
| </p> |
| |
| <div class="shell"><pre> |
| <a href="http://www.swig.org/svn.html">SWIG Bleeding Edge</a> |
| </pre></div> |
| |
| |
| |
| <H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2> |
| |
| |
| <p> |
| This manual assumes that you know how to write C/C++ programs and that you |
| have at least heard of scripting languages such as |
| Tcl, Python, and Perl. A detailed knowledge of these scripting |
| languages is not required although some familiarity won't |
| hurt. No prior experience with building C extensions to these |
| languages is required---after all, this is what SWIG does automatically. |
| However, you should be reasonably familiar with the use of |
| compilers, linkers, and makefiles since making |
| scripting language extensions is somewhat more complicated than |
| writing a normal C program. |
| </p> |
| |
| <p> |
| Over time SWIG releases have become significantly more capable in |
| their C++ handling--especially support for advanced features like |
| namespaces, overloaded operators, and templates. Whenever possible, |
| this manual tries to cover the technicalities of this interface. |
| However, this isn't meant to be a tutorial on C++ programming. For many |
| of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program |
| in C++, you may just want to skip those parts of the manual. |
| |
| <H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2> |
| |
| |
| <p> |
| The first few chapters of this manual describe SWIG in general and |
| provide an overview of its capabilities. The remaining chapters are |
| devoted to specific SWIG language modules and are self |
| contained. Thus, if you are using SWIG to build Python interfaces, you |
| can probably skip to that chapter and find almost everything you need |
| to know. |
| </p> |
| |
| <H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2> |
| |
| |
| <p> |
| If you hate reading manuals, glance at the "Introduction" which |
| contains a few simple examples. These |
| examples contain about 95% of everything you need to know to use |
| SWIG. After that, simply use the language-specific chapters as a reference. |
| The SWIG distribution also comes with a large directory of |
| examples that illustrate different topics. |
| </p> |
| |
| <H2><a name="Preface_nn9"></a>1.8 Backwards compatibility</H2> |
| |
| |
| <p> |
| If you are a previous user of SWIG, don't expect |
| SWIG to provide complete backwards compatibility. |
| Although the developers strive to the utmost to keep backwards compatibility, |
| this isn't always possible as the |
| primary goal over time is to make SWIG |
| better---a process that would simply be impossible if the developers |
| are constantly bogged down with backwards compatibility issues. |
| Potential incompatibilities are clearly marked in the detailed |
| <a href="#Preface_release_notes">release notes</a>. |
| </p> |
| |
| |
| <p> |
| If you need to work with different versions of SWIG and backwards |
| compatibility is an issue, you can use the SWIG_VERSION preprocessor |
| symbol which holds the version of SWIG being executed. |
| SWIG_VERSION is a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11). |
| This can be used in an interface file to define different typemaps, take |
| advantage of different features etc: |
| </p> |
| |
| <div class="code"><pre> |
| #if SWIG_VERSION >= 0x010311 |
| /* Use some fancy new feature */ |
| #endif |
| </pre></div> |
| |
| <p> |
| Note: The version symbol is not defined in the generated SWIG |
| wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11. |
| </p> |
| |
| <H2><a name="Preface_release_notes"></a>1.9 Release notes</H2> |
| |
| |
| <p> |
| The CHANGES.current, CHANGES and RELEASENOTES files shipped with SWIG in the top level directory |
| contain, respectively, detailed release notes for the current version, |
| detailed release notes for previous releases and summary release notes from SWIG-1.3.22 onwards. |
| </p> |
| |
| <H2><a name="Preface_nn10"></a>1.10 Credits</H2> |
| |
| |
| <p> |
| SWIG is an unfunded project that would not be possible without the |
| contributions of many people working in their spare time. |
| If you have benefitted from using SWIG, please consider |
| <a href="http://www.swig.org/donate.html">Donating to SWIG</a> to keep development going. |
| There have been a large varied number of people |
| who have made contributions at all levels over time. Contributors |
| are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs. |
| </p> |
| |
| <H2><a name="Preface_nn11"></a>1.11 Bug reports</H2> |
| |
| |
| <p> |
| Although every attempt has been made to make SWIG bug-free, we are also trying |
| to make feature improvements that may introduce bugs. |
| To report a bug, either send mail to the SWIG developer |
| list at the <a href="http://www.swig.org/mail.html">swig-devel mailing list</a> or report a bug |
| at the <a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as |
| possible, including (if applicable), error messages, tracebacks (if a |
| core dump occurred), corresponding portions of the SWIG interface file |
| used, and any important pieces of the SWIG generated wrapper code. We |
| can only fix bugs if we know about them. |
| </p> |
| |
| <H2><a name="Preface_installation"></a>1.12 Installation</H2> |
| |
| |
| <H3><a name="Preface_windows_installation"></a>1.12.1 Windows installation</H3> |
| |
| |
| <p> |
| Please see the dedicated <a href="Windows.html">Windows chapter</a> for instructions on installing |
| SWIG on Windows and running the examples. The Windows distribution is |
| called swigwin and includes a prebuilt SWIG executable, swig.exe, included in |
| the top level directory. Otherwise it is exactly the same as |
| the main SWIG distribution. There is no need to download anything else. |
| </p> |
| |
| <H3><a name="Preface_unix_installation"></a>1.12.2 Unix installation</H3> |
| |
| |
| <p> |
| You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG. |
| </p> |
| |
| <p> |
| <a href="http://www.pcre.org/">PCRE</a> |
| needs to be installed on your system to build SWIG, in particular |
| pcre-config must be available. If you have PCRE headers and libraries but not |
| pcre-config itself or, alternatively, wish to override the compiler or linker |
| flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables |
| to be used instead. And if you don't have PCRE at all, the configure script |
| will provide instructions for obtaining it. |
| </p> |
| |
| <p> |
| To build and install SWIG, simply type the following: |
| </p> |
| |
| <div class="shell"><pre> |
| $ ./configure |
| $ make |
| $ make install |
| </pre></div> |
| |
| <p> |
| By default SWIG installs itself in /usr/local. If you need to install SWIG in |
| a different location or in your home directory, use the <tt>--prefix</tt> option |
| to <tt>./configure</tt>. For example: |
| </p> |
| |
| <div class="shell"><pre> |
| $ ./configure --prefix=/home/yourname/projects |
| $ make |
| $ make install |
| </pre></div> |
| |
| <p> |
| Note: the directory given to <tt>--prefix</tt> must be an absolute pathname. Do <b>not</b> use |
| the ~ shell-escape to refer to your home directory. SWIG won't work properly |
| if you do this. |
| </p> |
| |
| <p> |
| The INSTALL file shipped in the top level directory details more about using configure. Also try |
| </p> |
| |
| <div class="shell"><pre> |
| $ ./configure --help. |
| </pre></div> |
| |
| <p> |
| The configure script will attempt to locate various packages on your machine |
| including Tcl, Perl5, Python and all the other target languages that SWIG |
| supports. Don't panic if you get 'not found' messages -- SWIG does not need these |
| packages to compile or run. The configure script is actually looking for |
| these packages so that you can try out the SWIG examples contained |
| in the 'Examples' directory without having to hack Makefiles. |
| Note that the <tt>--without-xxx</tt> options, where xxx is a target language, have |
| minimal effect. All they do is reduce the amount of testing done with |
| 'make check'. The SWIG executable and library files installed cannot currently |
| be configured with a subset of target languages. |
| </p> |
| |
| <p> |
| SWIG used to include a set of runtime libraries for some languages for working |
| with multiple modules. These are no longer built during the installation stage. |
| However, users can build them just like any wrapper module as described in |
| the <a href="Modules.html">Modules chapter</a>. |
| The CHANGES file shipped with SWIG in the top level directory |
| also lists some examples which build the runtime library. |
| </p> |
| |
| <p> |
| Note: |
| </p> |
| |
| <ul> |
| <li> |
| If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt> |
| before <tt>./configure</tt>. In addition, a full build of SWIG requires |
| a number of packages to be installed. Full instructions at |
| <a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>. |
| </li> |
| </ul> |
| |
| <H3><a name="Preface_osx_installation"></a>1.12.3 Macintosh OS X installation</H3> |
| |
| |
| <p> |
| SWIG is known to work on various flavors of OS X. Follow the Unix installation |
| instructions above. However, as of this writing, there is still great deal of |
| inconsistency with how shared libaries are handled by various scripting languages |
| on OS X. |
| </p> |
| |
| <p> |
| Users of OS X should be aware that Darwin handles shared libraries and linking in |
| a radically different way than most Unix systems. In order to test SWIG and run |
| the examples, SWIG configures itself to use flat namespaces and to allow undefined |
| symbols (<tt>-flat_namespace -undefined suppress</tt>). This mostly closely follows the Unix |
| model and makes it more likely that the SWIG examples will work with whatever |
| installation of software you might have. However, this is generally not the recommended |
| technique for building larger extension modules. Instead, you should utilize |
| Darwin's two-level namespaces. Some details about this can be found here |
| |
| <a href="http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html">http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html</a>. |
| |
| </p> |
| |
| <p> |
| Needless to say, you might have to experiment a bit to get things working at first. |
| </p> |
| |
| <H3><a name="Preface_testing"></a>1.12.4 Testing</H3> |
| |
| |
| <p> |
| If you want to test SWIG after building it, a check can be performed on Unix operating systems. |
| Type the following: |
| </p> |
| |
| <div class="shell"><pre> |
| $ make -k check |
| </pre></div> |
| |
| <p> |
| This step can be performed either before or after installation. |
| The check requires at least one of the target languages to be |
| installed. If it fails, it may mean that you have an uninstalled |
| language module or that the file 'Examples/Makefile' has been |
| incorrectly configured. It may also fail due to compiler issues such |
| as a broken C++ compiler. Even if the check fails, there is a |
| pretty good chance SWIG still works correctly --- you will just have to |
| mess around with one of the examples and some makefiles to get it to work. |
| Some tests may also fail due to missing dependency packages, eg PCRE |
| or Boost, but this will require careful analysis of the configure output |
| done during configuration. |
| </p> |
| |
| <p> |
| The test suite executed by the check is designed to stress-test |
| many parts of the implementation including obscure corner cases. If some |
| of these tests fail or generate warning messages, there is no reason for |
| alarm --- the test may be related to some new SWIG feature or a difficult bug |
| that we're trying to resolve. Chances are that SWIG will work just fine |
| for you. Note that if you have more than one CPU/core, then you can use |
| parallel make to speed up the check as it does take quite some time to run, |
| for example: |
| </p> |
| |
| <div class="shell"><pre> |
| $ make -j2 -k check |
| </pre></div> |
| |
| <p> |
| Also, SWIG's support for C++ is sufficiently advanced that certain |
| tests may fail on older C++ compilers (for instance if your compiler |
| does not support member templates). These errors are harmless if you |
| don't intend to use these features in your own programs. |
| </p> |
| |
| <p> |
| Note: The test-suite currently contains over 500 tests. If you |
| have many different target languages installed and a slow machine, it |
| might take more than an hour to run the test-suite. |
| </p> |
| |
| <H3><a name="Preface_examples"></a>1.12.5 Examples</H3> |
| |
| |
| <p> |
| The Examples directory contains a variety of examples of using SWIG |
| and it has some browsable documentation. Simply point your browser to |
| the file "Example/index.html". |
| </p> |
| |
| <p> |
| The Examples directory also includes Visual C++ project 6 (.dsp) files for |
| building some of the examples on Windows. Later versions of Visual Studio |
| will convert these old style project files into a current solution file. |
| </p> |
| |
| </body> |
| </html> |