/tags/rel-1-3-15/SWIG/Doc/Manual/Preface.html
HTML | 195 lines | 148 code | 45 blank | 2 comment | 0 complexity | b507156e10a2dc999fc1fc1c44921811 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<html>
2<head>
3<title>Preface</title>
4</head>
5
6<body bgcolor="#ffffff">
7<a name="n1"></a><H1>0 Preface</H1>
8<!-- INDEX -->
9<ul>
10<li><a href="#n2">Introduction</a>
11<li><a href="#n3">Special Introduction for Version 1.3</a>
12<li><a href="#n4">SWIG Versions</a>
13<li><a href="#n5">SWIG resources</a>
14<li><a href="#n6">Prerequisites</a>
15<li><a href="#n7">Organization of this manual</a>
16<li><a href="#n8">How to avoid reading the manual</a>
17<li><a href="#n9">Backwards Compatibility</a>
18<li><a href="#n10">Credits</a>
19<li><a href="#n11">Bug reports</a>
20</ul>
21<!-- INDEX -->
22
23
24
25<a name="n2"></a><H2>0.1 Introduction</H2>
26
27
28SWIG is a software development tool for building scripting language
29interfaces to C and C++ programs. Originally developed in 1995, SWIG was
30first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for
31building user interfaces to simulation codes running on the Connection
32Machine 5 supercomputer. In this environment, scientists needed to
33work with huge amounts of simulation data, complex hardware, and a
34constantly changing code base. The use of a scripting language
35interface provided a simple yet highly flexible foundation for solving these
36types of problems. SWIG simplifies development by largely automating
37the task of scripting language integration--allowing developers and users
38to focus on more important problems.
39
40<p>
41Although SWIG was originally developed for scientific applications, it
42has since evolved into a general purpose tool that is used in a wide
43variety of applications--in fact almost anything where C/C++ programming
44is involved.
45
46<p>
47<a name="n3"></a><H2>0.2 Special Introduction for Version 1.3</H2>
48
49
50Since SWIG was released in 1996, its user base and applicability has
51continued to grow. Although its rate of development has varied, an
52active development effort has continued to make improvements to the
53system. Today, nearly a dozen developers are working to create
54SWIG-2.0---a system that aims to provide wrapping support for nearly
55all of the ANSI C++ standard and approximately ten target languages
56including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
57and Tcl.
58
59<p>
60<a name="n4"></a><H2>0.3 SWIG Versions</H2>
61
62
63For several years, the most stable version of SWIG has been release
641.1p5. Starting with version 1.3, a new version numbering scheme has
65been adopted. Odd version numbers (1.3, 1.5, etc.) represent
66development versions of SWIG. Even version numbers (1.4, 1.6, etc.)
67represent stable releases. Currently, developers are working to
68create a stable SWIG-2.0 release (late 2002).
69
70<a name="n5"></a><H2>0.4 SWIG resources</H2>
71
72
73The official location of SWIG related material is<p>
74
75<blockquote><pre>
76<a href="http://www.swig.org">http://www.swig.org</a>
77</pre></blockquote>
78
79<p>
80This site contains the latest version of the software, users guide,
81and information regarding bugs, installation problems, and
82implementation tricks.
83
84<p>
85You can also subscribe to the SWIG mailing list by visiting the page
86
87<p>
88<blockquote><pre><a href="http://mailman.cs.uchicago.edu/listinfo/swig">http://mailman.cs.uchicago.edu/listinfo/swig</a>
89</pre></blockquote>
90
91<p>
92The mailing list often discusses some of the more technical aspects of
93SWIG along with information about beta releases and future work.<p>
94
95<p>
96CVS access to the latest version of SWIG is also available. More information
97about this can be obtained at:
98
99<p>
100<blockquote><pre><a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a>
101</pre></blockquote>
102
103
104<a name="n6"></a><H2>0.5 Prerequisites</H2>
105
106
107This manual assumes that you know how to write C/C++ programs and that you
108have at least heard of scripting languages such as
109Tcl, Python, and Perl. A detailed knowledge of these scripting
110languages is not required although some familiarity won't
111hurt. No prior experience with building C extensions to these
112languages is required---after all, this is what SWIG does automatically.
113However, you should be reasonably familiar with the use of
114compilers, linkers, and makefiles since making
115scripting language extensions is somewhat more complicated than
116writing a normal C program.
117
118<a name="n7"></a><H2>0.6 Organization of this manual</H2>
119
120
121The first few chapters of this manual describe SWIG in general and
122provide an overview of its capabilities. The remaining chapters are
123devoted to specific SWIG language modules and are self
124contained. Thus, if you are using SWIG to build Python interfaces, you
125can probably skip to that chapter and find almost everything you need
126to know. Caveat: we are currently working on a documentation rewrite and many
127of the older language module chapters are still somewhat out of date.
128
129<a name="n8"></a><H2>0.7 How to avoid reading the manual</H2>
130
131
132If you hate reading manuals, glance at the "Introduction" which
133contains a few simple examples. These
134examples contain about 95% of everything you need to know to use
135SWIG. After that, simply use the language-specific chapters as a reference.
136The SWIG distribution also comes with a large directory of
137examples that illustrate different topics.
138
139<a name="n9"></a><H2>0.8 Backwards Compatibility</H2>
140
141
142If you are a previous user of SWIG, don't expect recent versions of
143SWIG to provide backwards compatibility. In fact, backwards
144compatibility issues may arise even between successive 1.3.x releases.
145Although these incompatibilities are regretable, SWIG-1.3 is an active
146development project. The primary goal of this effort is to make SWIG
147better---a process that would simply be impossible if the developers
148are constantly bogged down with backwards compatibility issues.
149
150<p>
151On a positive note, a few incompatibilities are a small price to pay
152for the large number of new features that have been
153added---namespaces, templates, smart pointers, overloaded methods,
154operators, and more.
155
156<a name="n10"></a><H2>0.9 Credits</H2>
157
158
159SWIG is an unfunded project that would not be possible without the
160contributions of many people. Most recent SWIG development has been
161supported by Matthias Köppe, William Fulton, Lyle Johnson,
162Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
163Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus, and Harco de Hilster.
164
165<p>
166Historically, the following people contributed to early versions of SWIG.
167Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
168at Los Alamos National Laboratory were the first users. Patrick
169Tullmann at the University of Utah suggested the idea of automatic
170documentation generation. John Schmidt and Kurtis Bleeker at the
171University of Utah tested out the early versions. Chris Johnson
172supported SWIG's developed at the University of Utah. John Buckman,
173Larry Virden, and Tom Schwaller provided valuable input on the first
174releases and improving the portability of SWIG. David Fletcher and
175Gary Holt have provided a great deal of input on improving SWIG's
176Perl5 implementation. Kevin Butler contributed the first Windows NT
177port.
178
179<a name="n11"></a><H2>0.10 Bug reports</H2>
180
181
182Although every attempt has been made to make SWIG bug-free, we are also trying
183to make feature improvements that may introduce bugs.
184To report a bug, either send mail to the SWIG developer
185list at <tt>swig-dev@cs.uchicago.edu</tt> or report a bug
186at <tt>http://www.swig.org</tt>. In your report, be as specific as
187possible, including (if applicable), error messages, tracebacks (if a
188core dump occurred), corresponding portions of the SWIG interface file
189used, and any important pieces of the SWIG generated wrapper code. We
190can only fix bugs if we know about them.
191
192<p><hr>
193<address>SWIG 1.3 - Last Modified : August 10, 2002</address>
194</body>
195</html>