mirror of https://github.com/swig/swig
463 lines
17 KiB
HTML
463 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Preface</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
</head>
|
|
|
|
<body bgcolor="#ffffff">
|
|
<H1><a name="Preface">1 Preface</a></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">1.1 Introduction</a></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">1.2 SWIG Versions</a></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.
|
|
Version 3.0.0 was released in 2014 focusing on adding C++11 support and C++ nested classes.
|
|
Version 4.0.0 was released in 2019 to add in Doxygen support.
|
|
Some target languages were disabled as part of a clean up and others were given a new status of either 'Supported' or 'Experimental'.
|
|
</p>
|
|
|
|
<H2><a name="Preface_license">1.3 SWIG License</a></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="https://www.swig.org/legal.html">https://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">1.4 SWIG resources</a></H2>
|
|
|
|
|
|
<p>
|
|
The official location of SWIG related material is
|
|
</p>
|
|
|
|
<div class="shell"><pre>
|
|
<a href="https://www.swig.org">https://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="https://www.swig.org/mail.html">https://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="https://www.swig.org/svn.html">SWIG Bleeding Edge</a>
|
|
</pre></div>
|
|
|
|
|
|
|
|
<H2><a name="Preface_nn6">1.5 Prerequisites</a></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">1.6 Organization of this manual</a></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">1.7 How to avoid reading the manual</a></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">1.8 Backwards compatibility</a></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">1.9 Release notes</a></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">1.10 Credits</a></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="https://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">1.11 Bug reports</a></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="https://www.swig.org/mail.html">swig-devel mailing list</a> or report a bug
|
|
at the <a href="https://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">1.12 Installation</a></H2>
|
|
|
|
|
|
<H3><a name="Preface_windows_installation">1.12.1 Windows installation</a></H3>
|
|
|
|
|
|
<p>
|
|
Please see the dedicated <a href="Windows.html#Windows">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">1.12.2 Unix installation</a></H3>
|
|
|
|
|
|
<p>
|
|
These installation instructions are for using the distributed tarball,
|
|
for example, <tt>swig-3.0.8.tar.gz</tt>.
|
|
If you wish to build and install from source on Github, extra steps are required.
|
|
Please see the <a href="https://swig.org/svn.html">Bleeding Edge</a> page on the SWIG website.
|
|
</p>
|
|
|
|
<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/">PCRE2</a>
|
|
needs to be installed on your system to build SWIG, in particular
|
|
pcre2-config must be available. If you have PCRE2 headers and libraries but not
|
|
pcre2-config itself or, alternatively, wish to override the compiler or linker
|
|
flags returned by pcre2-config, you may set PCRE2_LIBS and PCRE2_CFLAGS variables
|
|
to be used instead. And if you don't have PCRE2 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">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="https://www.swig.org/svn.html">SWIG bleeding edge</a>.
|
|
</li>
|
|
</ul>
|
|
|
|
<H3><a name="Preface_osx_installation">1.12.3 Macintosh OS X installation</a></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 libraries 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="https://developer.apple.com/library/mac/documentation/Porting/Conceptual/PortingUnix/compiling/compiling.html#//apple_ref/doc/uid/TP40002850-BCIHJBBF">Understanding Two-Level Namespaces</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">1.12.4 Testing</a></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 600 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">1.12.5 Examples</a></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>
|