978080846c
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@12078 626c5289-ae23-0410-ae9c-e8d60b6d4f22
219 lines
7.9 KiB
HTML
219 lines
7.9 KiB
HTML
<!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_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_nn10">Credits</a>
|
|
<li><a href="#Preface_nn11">Bug reports</a>
|
|
</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. The license was clarified
|
|
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.3 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>
|
|
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">http://www.swig.org/svn.html</a>
|
|
</pre></div>
|
|
|
|
|
|
<H2><a name="Preface_nn6"></a>1.4 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.5 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.6 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.7 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 release notes
|
|
(CHANGES files).
|
|
</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_nn10"></a>1.8 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.9 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>
|
|
|
|
</body>
|
|
</html>
|