jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

web-page updates

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@2888 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley 2002-06-02 21:00:22 +00:00
commit 1cf8920951
12 changed files with 2148 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

1559
SWIG/CHANGES
View file

File diff suppressed because it is too large Load diff

25
SWIG/NEW
View file

@ -2,7 +2,7 @@ New Features and Important Changes, v1.3
Author(s) : David Beazley
January 31, 2002
June 2, 2002
1. Introduction
---------------
@ -92,6 +92,11 @@ altered SWIG's old behavior.
where you would like to make the two arguments operate as a single
object in the target language.
2.9 Types such as 'const int &', 'const double &', are passed as
values instead of pointers.
2.10 C++ namespaces are now supported.
3. Type checking
----------------
@ -117,26 +122,28 @@ typemaps to handle pointers, here are the essential details:
3.3 Instead of SWIG_GetPtr, a function of the following form is used:
int SWIG_ConvertPtr(ScriptObj *o, void **ptr, swig_type_info *ty);
int SWIG_ConvertPtr(ScriptObj *o, void **ptr, swig_type_info *ty, int flags);
Note: the function name may differ in certain implementations (read
the source). For example:
int SWIG_ConvertPtr(ScriptObj *o, void **ptr, SWIGTYPE_p_p_int);
int SWIG_ConvertPtr(ScriptObj *o, void **ptr, SWIGTYPE_p_p_int,0);
Passing a value of '0' for the type will accept any pointer. This
works kind of like 'void *'.
works kind of like 'void *'. The flags argument is reserved for
future expansion.
3.4. To create a pointer object, one uses a function similar to
ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty);
ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty, int flags);
It works in a similar manner:
p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int);
p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int, 0);
You will have to read the source to get the exact function name
used.
used. The flags argument is implementation specific and reserved
for future expansion.
3.5. If, for whatever reason, you need to obtain the 'swig_type_info *'
outside the context of a wrapper file, you can use the
@ -191,6 +198,10 @@ and it is simpler to implement than the old string based approach.
4.6 %except and %new are deprecated.
4.7 %readonly and %readwrite are deprecated. Use %immutable instead.
4.8 The %addmethods directive has been renamed to %extend.
5. Language specific changes
----------------------------

47
SWIG/README
View file

@ -1,6 +1,6 @@
SWIG (Simplified Wrapper and Interface Generator)
Version: 1.3.11 (February 1, 2002)
Version: 1.3.12 (June 2, 2002)
$Header$
@ -17,7 +17,7 @@ This distribution represents the latest development release of SWIG,
aiming to replace versions 1.1p5 and 1.1-883. The guilty parties
working on this are:
Dave Beazley (beazley@cs.uchicago.edu) (SWIG core)
Dave Beazley (beazley@cs.uchicago.edu) (SWIG core, Python, Tcl, Perl)
William Fulton (wsf@fultondesigns.co.uk) (Java)
Matthias Köppe (mkoeppe@mail.math.uni-magdeburg.de) (Guile/MzScheme)
Loic Dachary (loic@ceic.com) (Perl5)
@ -27,6 +27,7 @@ working on this are:
Masaki Fukushima (fukusima@goto.info.waseda.ac.jp) (Ruby)
Richard Palmer (richard@magicality.org) (PHP)
Luigi Ballabio (ballabio@mac.com) (Macintosh port)
Sam Liddicott (saml@liddicott.com) (PHP)
Past contributors include:
@ -56,9 +57,12 @@ What's New?
===========
The most notable changes since SWIG1.1 include the following:
- Support for C++ namespaces
- Support for C++ overloaded operators.
- Support for C++ templates.
- Support for C++ templates including member templates,
specialization, and partial specialization.
- Improved support for overloaded functions/methods.
@ -69,7 +73,8 @@ The most notable changes since SWIG1.1 include the following:
- Improved support for pointers to functions and callbacks.
- SWIG now has a full C preprocessor.
- SWIG now has a full C preprocessor with macro expansion.
Includes C99 variadic macro support.
- Code generation for the Tcl and Python modules has been
substantially improved both in terms of size and runtime
@ -123,8 +128,8 @@ if you are making extensive use of advanced SWIG features, interfaces
written for SWIG1.1 may not work. We apologize for the inconvenience,
but these changes are needed in order to fix a number of annoying
"features" in SWIG1.1. Hopefully the list of new features will
provide enough incentive for you to upgrade (and that the modifications
to your interfaces will only be minor).
provide enough incentive for you to upgrade (and that the
modifications to your interfaces will only be minor).
In addition, SWIG1.3 makes no attempt to be compatible with SWIG1.1 at
the C++ API level so language modules written for SWIG1.1 will most
@ -148,7 +153,8 @@ To build and install SWIG, simply type the following:
% ./configure
% make
% make -k check # this step is optional (see note below)
% make runtime # Optional (See note 4 below)
% make -k check # This step is optional (see note 3 below)
% make install
By default SWIG installs itself in /usr/local. If you need to install SWIG in
@ -157,6 +163,7 @@ to ./configure. For example:
% ./configure --prefix=/home/yourname/projects
% make
% make runtime
% make -k check
% make install
@ -197,6 +204,18 @@ Notes:
that we're trying to resolve. Chances are that SWIG will work just fine
for you.
Note: 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.
(4) The 'make runtime' target builds the SWIG runtime libraries. These
are needed if you plan to build applications that might involve more
than one SWIG generated module. This step requires that shared libraries
be properly configured on your machine and it may not work on all
platforms. If this step fails, SWIG will still work, but multi-module
support will be broken. Please let us know if this fails on your platform.
Examples
========
The Examples directory contains a variety of examples of using SWIG
@ -241,10 +260,10 @@ http://swig.cs.uchicago.edu/cgi-bin/wiki.pl.
Documentation
=============
The Doc/Manual directory contains the most recent set of updated
documentation for this release. As this is an unstable development
release, the documentation is not entirely up to date and is being worked
on. We are working on it, but there is a lot of documentation and it
is going to take time to complete. Please be patient.
documentation for this release. As this is a development release, the
documentation is not entirely up to date and is being worked on. We
are working on it, but there is a lot of old documentation and it is going
to take time to complete. Please be patient or volunteer to help.
!! The most up-to-date information concerning new features in SWIG1.3 is the
!! file Doc/Manual/SWIG.html.
@ -257,11 +276,11 @@ Participate!
============
Please report any errors and submit patches (if possible)! We only
have access to a limited variety of hardware (Linux, Solaris, and
Windows). All contributions help.
have access to a limited variety of hardware (Linux, Solaris, OS-X,
and Windows). All contributions help.
If you would like to join the SWIG development team or contribute a
language module to the distribution, please contact beazley@cs.uchicago.edu.
language module to the distribution, please contact swig-dev@cs.uchicago.edu.
-- The SWIG Maintainers

9
swigweb/compat.ht
View file

@ -44,6 +44,9 @@ Metrowerks Code Warrior 10. Given the limited availability and
experience with the Macintosh, this version of SWIG should only
be used by exceptionally brave users. SWIG has not been fully tested with Python or
Perl on the Macintosh although some users have reported success.
<p>
<b>Note:</b>SWIG-1.3.12 does support OS-X/Darwin. Simply download the Unix
sources, configure, and build from the command terminal.
</blockquote>
</ul>
@ -76,11 +79,13 @@ There is also <a href="http://www.ultravioletconsulting.com/projects/swigjs">Swi
<h3> Compilation Requirements </h3>
SWIG is implemented in C++ and is distributed in source form.
SWIG is implemented in C and C++ and is distributed in source form.
You will need a working C++ compiler (i.e., g++) to build SWIG and at
least one of the supported scripting languages to use it (or else it
isn't going to be very useful). SWIG does not depend upon any of the
supported scripting languages for its own compilation. Finally,
although SWIG is written in C++, a C++ compiler is not required to use
although SWIG is partly written in C++, a C++ compiler is not required to use
SWIG--it works just fine with both ANSI C and C++.

4
swigweb/doc.ht
View file

@ -7,8 +7,8 @@ SWIG Documentation, Presentations, and Papers
<H3>SWIG1.3</h3>
<ul>
<li> <a href="Doc1.3/index.html">Development Documentation</a> for SWIG1.3.
<li> Also available in <a href="swigdoc.pdf">PDF</a> and <a href="swigdoc.ps">postscript</a>.
<li> <a href="Doc1.3/index.html">Development Documentation</a> for SWIG1.3.12.
<li> Also available in <a href="swigdoc.pdf">PDF</a> and <a href="swigdoc.ps">postscript</a> (SWIG-1.3.11).
</ul>
<h3>SWIG1.1</h3>

13
swigweb/download.ht
View file

@ -38,9 +38,16 @@ with ANSI C++ compilers and will probably generate a lot of compiler
warnings. Sorry.
<p>
<a href="http://prdownloads.sourceforge.net/swig/swig-1.3.11.tar.gz">SWIG 1.3.11</a>
is the latest development release (2002/02/01). View the <a href="release.html">release notes</a>. Windows users should download <a href="http://prdownloads.sourceforge.net/swig/swigwin-1.3.11.zip">swigwin-1.3.11</a> which includes a prebuilt executable. A Macintosh port (macswig-1.3.11) also may be available from the
SourceForge <a href="http://sourceforge.net/project/showfiles.php?group_id=1645">releases</a> area.
<a
href="http://prdownloads.sourceforge.net/swig/swig-1.3.12.tar.gz">SWIG
1.3.12</a> is the latest development release (2002/06/02). View the <a
href="release.html">release notes</a>. Windows users should download
<a
href="http://prdownloads.sourceforge.net/swig/swigwin-1.3.12.zip">swigwin-1.3.12</a>
which includes a prebuilt executable. A Macintosh port
(macswig-1.3.12) also may be available from the SourceForge <a
href="http://sourceforge.net/project/showfiles.php?group_id=1645">releases</a>
area.
<p>
<a href="http://prdownloads.sourceforge.net/swig/swig1.1p5.tar.gz">SWIG 1.1p5</a>

29
swigweb/exec.ht
View file

@ -4,12 +4,12 @@ Executive Summary
<img src="images/exec.png" alt="Executive Summary">
<p>
SWIG is an interface compiler that connects programs written in C,
C++, and Objective-C with scripting languages including <a href="http://www.perl.org">Perl</a>,
SWIG is an interface compiler that connects programs written in C and
C++ with scripting languages including <a href="http://www.perl.org">Perl</a>,
<a href="http://www.python.org">Python</a>, and
<a href="http://www.scriptics.com">Tcl/Tk</a>. It works by taking the declarations commonly found in C/C++ header
files and using them to generate the glue code (wrappers) that scripting
languages need to access the underlying C/C++ code.
languages need to access the underlying C/C++ code.
<p>
John Ousterhout has written a
@ -50,8 +50,8 @@ such a module.
SWIG is sometimes compared to interface definition language (IDL)
compilers such as those you would find with systems such as CORBA and
COM. Although there are a few similarities, the whole point of SWIG
is to make it so you don't have to screw around with that stuff. If
anything, it's much more of a rapid application development and
is to make it so you don't have to add an extra layer of IDL specifications
to your application. If anything, it's much more of a rapid application development and
prototyping tool. Specifically:
<p>
@ -93,12 +93,13 @@ to other more specialized scripting language extension building tools
programmers who want to add a scripting language component to their
applications. Because of this, SWIG tends to have a slightly
different focus than tools designed to build small modules for
widespread use in a scripting language distribution. In particular,
SWIG tends to provide much greater support for C/C++ while
deemphasizing most of the low-level details related to the internal
operation of the target language. In contrast, tools specialized to a
particular language allow for a greater degree of customization
(although they are often much more difficult to use).
widespread use in a scripting language distribution. By far, the most
significant difference between SWIG and similar tools is that SWIG
implements the full C++ type system--with support for all C datatypes,
C++ classes, namespaces, and templates. By focusing on types, SWIG is
able to provide a high degree of reliability and it is able to handle
the wrapping of large-scale C/C++ code that appears in real
applications.
<p>
A number of <a href="doc.html">papers and tutorials</a> describing SWIG are available.
@ -109,6 +110,8 @@ in their <a href="projects.html">projects</a>.
<p>
SWIG has been freely available in various forms since February, 1996
and a large number of developers have made contributions. Today, SWIG
remains an all-volunteer effort. Approximately 700 people subscribe
remains an all-volunteer effort. Approximately 750 people subscribe
to the SWIG mailing list (swig@cs.uchicago.edu) and a public CVS
repository is available at the University of Chicago.
repository is available at the University of Chicago. Over 12000 people
downloaded the last SWIG release (SWIG-1.3.11).

373
swigweb/future.ht Normal file
View file

@ -0,0 +1,373 @@
SWIG-1.3.12, SWIG-2.0 and Beyond
<h2>SWIG-1.3.12, SWIG 2.0, and Beyond</h2>
<p>
Author: David Beazley (beazley@cs.uchicago.edu)
<p>
June 2, 2002
<p>
With the release of SWIG-1.3.12, I thought I'd take a few moments of
everyone's time to talk about the past, the present, and the future of
SWIG development. I'm really quite excited about the current release
because I think it represents a huge turning point in SWIG's
development. Furthermore, it is only the beginning of bigger and
better things to come. However, we definitely need your help.
<p>
To put a little perspective on the discussion, I'd start with a few
development statistics. In the last 12 months, there have been over
300 entries added to the CHANGES log and over 4000 CVS commits.
Although that may not sound like a lot compared to a huge software
project, it is significant in the context of SWIG. As a point of
comparison, there has been more SWIG development this year than in any
other year of the project and more than in the previous three years
combined. This even includes the first few years of development in
which there was also a lot of activity. Furthermore, many of the
recent changes have been extremely non-trivial (e.g., templates,
namespaces, type system, operators, etc.). As a result, SWIG is more
capable than I ever imagined possible.
<p>
Regrettably, I must admit that I've been a little negligent in
discussing the roadmap for where I thought this flurry of SWIG
development was actually headed. In part, this is because I've been
buried in work. However, the real reason is that I didn't really know
where we were going---except that in a time far far far away in the
future, we might arrive at some kind of "stable" release with a
version number other than "1.3.x". Needless to say, that's not a very
compelling story.
<p>
That said, I've spent a lot of time thinking about SWIG and trying to
wrap my brain around it. Specifically, just what is (or should be)
the primary focus of this project and what are we really trying to do?
That's what the rest of this message is about.
<h3>SWIG Prehistory</h3>
<p>
The first version of SWIG was written in 1995. The original system
was developed to help with some software wrapping problems I
encountered while writing molecular dynamics software at Los
Alamos. Later that year, I became interested in extending the wrapper
generator to support other scripting languages so it was rewritten in
C++ and modified with multiple backends (Tcl, Perl, and Guile). This
led to a first public release in February, 1996. Feedback from this
release led to a series of enhancements and the release of SWIG 1.0 in
September 1996. Throughout this process, my intent was to create a
tool that I would want to use---I never viewed the project as an
CS experiment in programming languages or software engineering.
<h3>SWIG 1.1</h3>
SWIG-1.1 (June, 1997) represented a series of enhancements that were
added in response to feedback at conferences and from users. Shadow
classes, exception handling, typemaps, and a number of more useful
features were added. However, the overall structure of the system was
relatively unchanged from the initial version. Following the release
of 1.1, a series of minor patch releases were made. This resulted in
the release of SWIG-1.1p5 in February, 1998. Unfortunately, this
release would remain the last "stable" release for quite a long
time---in fact, it is still listed as the last "stable" release on the
SWIG web page!
<h3>SWIG Hell</h3>
Even during the development of SWIG-1.1, it was clear that the whole
design of the system was deeply flawed. The implementation was a mess
and the C/C++ support was full of holes and nasty corner cases.
Furthermore, there was no unifying principle that tied all of the
different SWIG directives together. Not only that, fixing these
problems appeared to be nothing short of impossible---requiring a
total ground-up rewrite at best. The only redeeming quality was that
the system basically worked "well enough," it was extensively
documented, and its flaws mostly known. People could use it and there
were work-arounds for most common problems.
<p>
To deal with the design problem, there were at least four attempts to
completely rewrite SWIG, some of which were attempted in parallel with
the work on SWIG-1.1. Unfortunately, none of these were ever
completed. The primary problem was a strong "second system" effect and
a desire to make SWIG do everything that one might conceivably want to
do with a wrapper generator (somehow). Clearly, this was a recipe for
disaster. In fact, all such attempts to rewrite SWIG were eventually
abandoned several years ago. In hindsight, I think the real problem
was that these rewrite efforts focused far too much attention on
implementation technique rather than principles. In short, the
failure of these efforts was due to a lack of clarity in understanding
how SWIG ought to work (regardless of how it was actually
implemented).
<h3>SWIG Restart (1.3a1-1.3a5)</h3>
<p>
Having languished for several years, the SWIG1.1p5 release had a
growing pile of maintenance issues. It didn't work for newer versions
of certain language modules and a lot of minor bug reports and feature
requests had been building up. With a lot of help from Loic Dachary and
Thien-Thi Nguyen, we put together the 1.3a1 release (February,
2000). This was mostly a bug fix release to 1.1p5 except that the
preprocessor module from SWIG1.2 was added and a lot of minor
enhancements were added.
<p>
For the next six months, a massive effort was made to rewrite all of
SWIG's internal data structures (strings, lists, hashes, etc.). This
work was all going on underneath the covers while we tried to keep
SWIG in an operational state. The primary focus of this work was
really one of cleanup. Having given up on a total rewrite, perhaps
we could settle with making the implementation incrementally better
than before. In addition this, Matthias Koppe jumped on board to
reimplement the Guile module and to make other improvements to the system.
<p>
An important aspect of these releases was that many parts of the
system not directly related to wrapper code generation were removed.
This included the documentation system and Objective-C support. These
were not removed because they weren't useful. Instead, the
documentation system was removed because it accounted for nearly half
of the special SWIG directives, yet had no direct bearing on what SWIG
actually did. Obective-C support was removed because it was tangled
with C++ support in a way that was very difficult to understand and
maintain. The removal of these features was seen as a way to vastly
simplify cleanup--and to buy some time where we could rethink their
role in a future release.
<h3>SWIG Redux (1.3.6-1.3.11)</h3>
This work, started in February 2001, is the beginning of the current
SWIG implementation. With the help of William Fulton, Matthias Koppe,
Lyle Johnson, Luigi Ballabio, Jason Stewart, Richard Palmer, Sam
Liddicot, and others, this work can best be described as the wholesale
destruction of everything remaining from SWIG-1.1. The language
module API, type system, the parser, numerous SWIG directives, and
SWIG library files---all destroyed or rewritten. Not only that, we
started introducing significant incompatibilities with
SWIG-1.1---mostly in an effort to correct past wrongs and get
ourselves out of the tangled mess of earlier versions. A huge number
of long-standing bugs and difficult feature requests have also been
resolved.
<p>
The general goal of this development could best be described as an
attempt to reduce SWIG to an easily described set of general "ideas"
about how it should operate. Special SWIG directives have been
eliminated or combined with others. Different parts of the system have
been better integrated. Features not directly related to wrapper code
generation have been removed and the system has become more
focused. Changes in internal data structures and APIs have allowed
SWIG to capture more information from interface files and to resolve
hard corner cases. More often than not, these are things that you
never notice unless you are an old user and you suddenly realize that
a problem you had several years back has disappeared.
<p>
Along with the destruction of old code, this work has quietly
introduced a new core--the most significant features of which are a
new C++ type system and multi-pass compilation. More importantly,
this work has really tried to provide a more principled foundation for
future SWIG development. However, just what is this "more principled
foundation?"
<h3>Convergence (1.3.12)</h3>
With the upcoming 1.3.12 release, SWIG is about to take a big leap
forward. Almost all of this is due to one realization---that almost
every hard problem in past SWIG releases has been directly related to
errors and limitations in its type system. Types are the key to
understanding the structure of C and C++ code. They are at the heart
of understanding advanced language features like namespaces, nested
classes, and templates. They are directly related to the data
marshalling that occurs in wrappers. Not only that, they interact
with nearly every SWIG directive. A proper type system *is* the
necessary foundation for moving SWIG forward.
<p>
To be honest, I don't think that the emphasis on types is entirely
obvious. In fact, a great deal of work in past SWIG rewrites has
focused on the problem of C++ parsing. For instance, modifying the
parser to handle more advanced C++ code or representing parse trees as
XML. Furthermore, if one looks at the SWIG mailing list, you can find
a *lot* of messages related to issues of C++ parsing whereas almost no
one ever talks about types (well, other than typemaps). Even other
wrapper generation tools seems to spend a lot of time dealing with the
parsing issue. Although parsing is clearly important, I don't think it
has ever been the real problem in SWIG. This is because even though a
parser can tell you what's in a header file, it doesn't tell you
anything about how the different pieces of the system behave or how
they might interact. To do that, you need to do a lot more than just
parsing--and that's really the whole point.
<p>
Although earlier 1.3 releases have made big improvements to the type
system, SWIG-1.3.12 is the first release that really tries to tackle
the type-system issue in a major way. We have patched nearly all
remaining holes in the type system and we have added full support for
C++ namespaces. Not only that, we have completely reimplemented C++
template support in a way that supports templates, member templates,
and template specialization. Luigi and I are currently using this to
work on proper SWIG library support for parts of the C++ standard
library and the Standard Template Library (STL). Although some crusty
C programmers (present company excepted), might balk at such apparent
insanity, this work has impacted all parts of SWIG at all levels.
Even a variety of subtle errors in C support have been fixed by this
work.
<p>
In addition to the type system work, SWIG-1.3.12 contains continued
reduction in the implementation. Directives have been removed,
refined, renamed, or consolidated. We're still narrowing the focus of
the system and working towards some kind of convergence. "Convergence
to what?!?", you ask.
<h3>So, what is SWIG?</h3>
In a nutshell, SWIG is a C/C++ declaration compiler that generates
wrapper code (okay, so you knew that much). However, to really
understand what SWIG is doing and where SWIG-1.3.x is headed, it is
useful to know that the whole system is essentially being built around
three extensions to the C++ type system:
<ul>
<p>
<li><b>Typemaps.</b> Typemaps are rules that define the process by which
data is converted between languages. They are fully integrated
with the C++ type system and they are applied using a type-based
pattern matching mechanism. All data conversion SWIG is
defined by typemaps and is fully reconfigurable.
<p>
<li><b>Declaration annotation.</b> There are special directives that modify
the wrapping behavior of individual declarations. Declarations
can be selectively identified and decorated with arbitrary
attributes that affect wrapper generation. Like typemaps,
declaration matching is fully integrated with the C++ type system.
Almost all SWIG customization directives are a form of declaration
annotation.
<p>
<li><b>Class extension.</b> The ability to extend classes and structures
with new methods/attributes when building wrappers. Classes
are part of the type system so class extension is naturally
integrated with the C++ type system as well (big surprise).
</ul>
<p>
And that's it--this is the end-game of SWIG-1.3.x development. When
stabilized and documented it will become SWIG-2.0.
<h3>The Bigger Picture</h3>
I really want to emphasize that all of this work is part of a much
bigger picture. SWIG is used by a surprising number of people in
industry, government, and academia. It's used to build systems used
by millions of people every day. It has even shown up in video games
and other unlikely settings. Although SWIG doesn't have the same
visibility as many large software projects, over 12000 people have
downloaded SWIG-1.3.11 in the last 4 months. Clearly someone is using
it for something! Because of this, I think it is important for us to
work on moving SWIG towards a more solid foundation. Doing so will
give the system more credibility and long term viability---and it will
be a lot more fun to use!
<p>
It's also worth nothing that there are some rather interesting CS
connections at work here. Extensions to the type system and typemaps
have some interesting relations to work in programming languages. The
SWIG declaration annotation system and class extension feature seem
oddly similar to work in the emerging area of Aspect Oriented
Programming (AOP). There are undoubtedly connections to other areas
of software engineering and architecture.
<p>
The key point is that SWIG isn't going to connect to anything if
no-one can quite describe what it is or how it works.
<h3>SWIG-2.0 and the Future</h3>
SWIG-1.3.12 still represents work in progress. There are bugs, the
documentation is still incomplete, and there are parts of the
implementation that are rather ugly. We are also still working out a
few very hard problems like nested classes, callback functions, and
overloading. A few old features are still missing (Objective-C,
documentation). However, I believe the end of the 1.3.x series is
near and achievable.
<p>
Over the summer, a few more 1.3.x releases may appear but the current
plan is to aim for a SWIG-2.0 release in September. This release is
really moving towards the design principles described above and will
be a very major enhancement over SWIG-1.1.
<p>
As for the future, a number of interesting ideas are on the table. I
want to add support for contracts/assertions in order to solve some
reliability issues that arise when retrofitting legacy codes with a
scripting interface. Support for an extension language has been
promoted by David Fletcher and was suggested by someone else on the
mailing list rather recently. I have a graduate student working on
SWIG support for the Microsoft CLR and .NET languages. Other work
might include support for alternative parsers, dynamically loadable
language modules, and so forth. However, none of this is really going
to materialize if we can't get the 2.0 release stablized. In fact, I
see SWIG-2.0 as a necessary step for moving forward with these ideas.
<h3>We need your help! Yes, you.</h3>
Nobody gets paid to work on SWIG. The developers are volunteers who
work in their spare time. Furthermore, SWIG is not supported by
investors, a large corporation, or research grants. I work on it
because it's fun, challenging, and useful. I presume that other
developers do the same. However, we only have limited resources and
we need your help.
<ul>
<li>
If you like SWIG and find it useful, we need you to try new versions.
We want you to torture test the releases and to break them. We need
bug reports. No bug is too obscure or unimportant---we *will* fix it
if we can. We also need feedback about things that are annoying or
compatibility features that might help in going from 1.1 to 2.0.
<p>
<li> We need help with documentation, examples, testing, libraries, and all
sorts of other aspects of the release. Even if you have never
written a SWIG language module or dived into its implementation,
there are many ways that you can help. Consider writing a case study
about how you wrapped a big library. Contribute tests that break the
implementation in horrible ways. Help with the web page or FAQ.
<p>
<li> Most of the SWIG-1.3.x work has focused on the SWIG core. However, as
the 2.0 release nears, we will be working on a variety of enhancements
to the language modules. If there are things you would like to see
in any of the language modules, you need to let us know.
<p>
<li> There are SWIG language modules that have not made it into the
distribution. Examples that I know about include ITCL, Swig-Eiffel,
and Swig-Lua. We would gladly make these part of the standard SWIG
distribution. However, we also need help to do it. Porting from
SWIG-1.1 is no easy task, but we're more than willing to help. It's
not as bad as one might imagine.
<p>
<li> We are always looking for developers. Subscribe to
swig-dev@cs.uchicago.edu (http://mailman.cs.uchicago.edu/listinfo/swig-dev)
or send me email to get involved.
</ul>
<h3>Acknowledgements</h3>
I'd just like to thank everyone who has submitted feedback, bugs, made
contributions, and put up with my occasional thrashing over the years.
I welcome any comments about this document and how we can make SWIG even
better.
<p>
Dave Beazley (beazley@cs.uchicago.edu) <br>
June 2, 2002

11
swigweb/history.ht
View file

@ -45,14 +45,9 @@ back to ANSI C.
handling of overloaded functions added.
<li>September 23, 2001. SWIG-1.3.8 released.
<li>September 25, 2001. SWIG-1.3.9 released.
<li>December 10, 2001. SWIG-1.3.10 released.
<li>January 31, 2002. SWIG-1.3.11 released.
<li>June 2, 2002. SWIG-1.3.12 released.
</ul>
<p>
Currently SWIG is being rewritten in ANSI C and reorganized in an
attempt to simplify the construction of language modules and to
improve the quality of the code that is generated. As this is only a
part-time project for just about everyone involved, this work will be
completed when it is completed.

31
swigweb/index.ht
View file

@ -1,10 +1,10 @@
Simplified Wrapper and Interface Generator
<p>
<img src="images/swig12.png" alt="Simplified Wrapper and Interface Generator">
<h2>Welcome to SWIG</h2>
<p>
SWIG is a software development tool that connects programs written in
C, C++, and Objective-C with a variety of high-level programming
C and C++ with a variety of high-level programming
languages. SWIG is primarily used with common scripting languages
such as Perl, Python, Tcl/Tk, Ruby, Guile and MzScheme, however the list of
<a href="compat.html#SupportedLanguages">supported languages</a> also includes
@ -22,15 +22,13 @@ noncommercial use.
<li> <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SwigWiki!</a>
</ul>
<h3>Important Notice</h3>
<h3>SWIG-1.3.12, SWIG-2.0 and Beyond!</h3>
SWIG is currently in a state of redevelopment in which substantial
parts of the system are being reimplemented. This work can be found
in the SWIG1.3 series of releases. If you are concerned about
stability or are a first-time user, you may want to download some
variant of SWIG1.1 instead. Caveat--SWIG1.1 may not be compatible
with recent releases of certain scripting languages such as Perl 5.6
and Guile.
After nearly three years of redevelopment, the SWIG-1.3.x effort is
nearly complete. Read all about it in <a href="future.html">Dave's
message</a> about SWIG's past, present, and future--and the
realization that SWIG is more easily described as an extension to the
C++ type system (as opposed to an extension of C++ parsing).
<p>
SWIG is an all volunteer effort. We are always looking for fearless people with
@ -39,6 +37,19 @@ an abundance of spare time.
<p>
<h3>News</h3>
<p>
<b>2002/06/02</b>
<a href="Doc1.3/index.html">Updated documentation</a> for SWIG-1.3.12 is online.
<p>
<b>2002/06/02</b> <a
href="http://prdownloads.sourceforge.net/swig/swig-1.3.12.tar.gz">SWIG-1.3.12</a>
has been released. This is the most capable SWIG release ever! New
features include support for C++ namespaces, enhanced support for C++
templates, new library files, updated documentation, and a huge number of minor enhancements.
See the <a href="download.html">download</a> page for release notes
and versions for Windows and Macintosh.
<p>
<b>2002/04/03</b> Robert Tolbert has contributed <a href="swigdoc.pdf">PDF</a> and <a href="swigdoc.ps">postscript</a> versions of the SWIG-1.3.11 documentation. Check it out.

9
swigweb/subversion.ht
View file

@ -13,6 +13,15 @@ SWIG Subversion
</em>
</center>
<p>
<li>Alternative mission statement:
<p>
<center>
<em>
"You know, for kids." <br>
</em>
</center>
<p>
<li>The ever-so-impressive SWIG <a href="screenshot.html">screenshot</a>.
<li><a href="visual.html">Visual SWIG 2000++</a>--the version for funding agents and managers.

156
swigweb/tutorial.ht
View file

@ -32,7 +32,7 @@ char *get_time()
</pre></tt></ul>
<h3> Interface file </h3>
<h3>Interface file </h3>
Now, in order to add these files to your favorite language, you need to write an
"interface file" which is the input to SWIG. An interface file for these
@ -81,27 +81,6 @@ the rest of the program. In this case, we have built a dynamically
loadable extension that can be loaded into the Tcl interpreter using
the 'load' command.
<p>
If your machine does not support dynamic loading, it is also easy to
build a new version of the tclsh interpreter as follows :
<blockquote>
<pre><tt>
unix % swig -tcl -ltclsh.i example.i
unix % gcc example.c example_wrap.c -I/usr/local/include \
-L/usr/local/lib -ltcl -lsocket -ldl -lm -o my_tclsh
unix % my_tclsh
% puts $My_variable
3.0
% fact 5
120
%
</tt></pre></blockquote>
In this case, the new version of
tclsh is functionally identical to the original, but has new functions
added to it.
<h3> Building a Python module </h3>
Turning C code into a Python module is also easy. Simply do the following (shown for Irix):
@ -148,7 +127,6 @@ Sun Feb 11 23:01:07 1996
unix %
</pre></tt></blockquote>
<h3> Building a Java module </h3>
SWIG will also generate JNI code for accessing C/C++ code from Java. Here is an example building a Java module (shown for Cygwin):
@ -173,32 +151,54 @@ Mon Mar 4 18:20:31 2002
$
</pre></tt></blockquote>
<h3> SWIG for the truly lazy </h3>
As it turns out, it is not always necessary to write a special interface
file. If your C code is relatively clean, you can just run SWIG directly
on the source like this :
file. If you have a header file, you can often just include it directly in the
SWIG interface. For example:
<blockquote>
<tt> <pre>
unix % swig -tcl -module example example.c
unix % gcc -c example.c example_wrap.c -I/usr/local/include
unix % ld -shared example.o example_wrap.o -o example.so
</pre></tt></blockquote>
%module example
%{
/* Includes the header in the wrapper code */
#include "header.h"
%}
/* Parse the header file to generate wrappers */
%include "header.h"
</pre></tt>
</blockquote>
Alternatively, some people might just include SWIG directives in a header
file with conditional compilation. For example:
<blockquote>
<pre>
#ifdef SWIG
%module example
%{
#include "header.h"
%}
#endif
extern int fact(int n);
...
</pre>
</blockquote>
<h3> Running SWIG under Microsoft Windows </h3>
SWIG also works perfectly well under all known 32 bit versions of Windows including 95/98/NT/2000/XP. SWIG
is typically invoked from the command prompt and can be used with
NMAKE. Modules are typically compiled in the form of a DLL that
can be dynamically loaded into Tcl, Python, or whatever language you are using. With a little
work, SWIG can also be used as a custom build option within
MS Developer Studio.
SWIG also works perfectly well under all known 32 bit versions of
Windows including 95/98/NT/2000/XP. SWIG is typically invoked from
the command prompt and can be used with NMAKE. Modules are typically
compiled in the form of a DLL that can be dynamically loaded into Tcl,
Python, or whatever language you are using. With a little work, SWIG
can also be used as a custom build option within MS Developer Studio.
<h3> That's it (well, mostly) </h3>
<h3>That's it (well, more or less)</h3>
That's about everything you need to know. Here's the short checklist :
That's about everything you need to know to get started. Here's the short checklist :
<ul>
<li> Make sure you specify a module name.
@ -207,3 +207,83 @@ That's about everything you need to know. Here's the short checklist :
pages for your compiler).
<li> Relax.
</ul>
<h3>Surely there's more to it...</h3>
The above example is intentionally simple, but the general idea
extends to more complicated C/C++ programming tasks. In fact, it is
important to know that SWIG is a fairly complete C++ compiler with
support for nearly every language feature. This includes
preprocessing, pointers, classes, inheritance, and even C++ templates.
SWIG can also be used to package structures and classes into proxy
classes in the target language---exposing the underlying functionality in a very
natural manner.
<p>
To illustrate, suppose you wanted to wrap the following C++ data structure:
<blockquote>
<pre>
// pair.h. A pair like the STL
namespace std {
template&lt;class T1, class T2&gt; struct pair {
T1 first;
T2 second;
pair() : first(T1()), second(T2()) { };
pair(const T1 &f, const T2 &s) : first(f), second(s) { }
};
}
</pre>
</blockquote>
To wrap with SWIG, you might specify the following interface:
<blockquote>
<pre>
// pair.i - SWIG interface
%module pair
%{
#include "pair.h"
%}
// Ignore the default constructor
%ignore std::pair::pair();
// Parse the original header file
%include "pair.h"
// Instantiate some templates
%template(pairii) std::pair&lt;int,int&gt;;
%template(pairdi) std::pair&lt;double,int&gt;;
</pre>
</blockquote>
Now, compiling (Python):
<blockquote>
<pre>
$ swig -proxy -python -c++ pair.i
$ c++ -c pair_wrap.c -I/usr/local/include/python2.1
$ c++ -shared pair_wrap.c -o paircmodule.so
$ python
Python 2.1 (#3, Aug 20 2001, 15:41:42)
[GCC 2.95.2 19991024 (release)] on sunos5
Type "copyright", "credits" or "license" for more information.
>>> import pair
>>> a = pair.pairii(3,4)
>>> a.first
3
>>> a.second
4
>>> a.second = 16
>>> a.second
16
>>> b = pair.pairdd(3.5,8)
>>> b.first
3.5
>>> b.second
8
</pre>
</blockquote>