[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / swig / Preface.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_nn3">Special Introduction for Version 1.3</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_nn3"></a>1.2 Special Introduction for Version 1.3</H2>


<p>
Since SWIG was released in 1996, its user base and applicability has
continued to grow. Although its rate of development has varied, an
active development effort has continued to make improvements to the
system.  Today, nearly a dozen developers are working to create
SWIG-2.0---a system that aims to provide wrapping support for nearly
all of the ANSI C++ standard and approximately ten target languages
including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
and Tcl.
</p>

<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2>


<p>
For several years, the most stable version of SWIG has been release
1.1p5. Starting with version 1.3, a new version numbering scheme has
been adopted.  Odd version numbers (1.3, 1.5, etc.) represent
development versions of SWIG.  Even version numbers (1.4, 1.6, etc.)
represent stable releases.  Currently, developers are working to
create a stable SWIG-2.0 release.  Don't let the development status 
of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5.
</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 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>
CVS 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/cvs.html">http://www.swig.org/cvs.html</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>
Recent 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.   Caveat: we are currently working on a documentation rewrite and many
of the older language module chapters are still somewhat out of date.
</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 recent versions of
SWIG to provide backwards compatibility.  In fact, backwards
compatibility issues may arise even between successive 1.3.x releases.
Although these incompatibilities are regrettable, SWIG-1.3 is an active
development project.  The primary goal of this effort is to make SWIG
better---a process that would simply be impossible if the developers
are constantly bogged down with backwards compatibility issues.
</p>

<p>
On a positive note, a few incompatibilities are a small price to pay
for the large number of new features that have been
added---namespaces, templates, smart pointers, overloaded methods,
operators, and more.
</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 &gt;= 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.9 Credits</H2>


<p>
SWIG is an unfunded project that would not be possible without the
contributions of many people.  Most recent SWIG development has been
supported by Matthias K&ouml;ppe, William Fulton, Lyle Johnson,
Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus, 
Harco de Hilster, John Lenz, and Surendra Singhi.
</p>

<p>
Historically, the following people contributed to early versions of SWIG.
Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
at Los Alamos National Laboratory were the first users. Patrick
Tullmann at the University of Utah suggested the idea of automatic
documentation generation. John Schmidt and Kurtis Bleeker at the
University of Utah tested out the early versions.  Chris Johnson
supported SWIG's developed at the University of Utah. John Buckman,
Larry Virden, and Tom Schwaller provided valuable input on the first
releases and improving the portability of SWIG. David Fletcher and
Gary Holt have provided a great deal of input on improving SWIG's
Perl5 implementation. Kevin Butler contributed the first Windows NT
port.

<H2><a name="Preface_nn11"></a>1.10 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-dev 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>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	2	<html>
	3	<head>
	4	<title>Preface</title>
	5	<link rel="stylesheet" type="text/css" href="style.css">
	6	</head>
	7
	8	<body bgcolor="#ffffff">
	9	<H1><a name="Preface"></a>1 Preface</H1>
	10	<!-- INDEX -->
	11	<div class="sectiontoc">
	12	<ul>
	13	<li><a href="#Preface_nn2">Introduction</a>
	14	<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a>
	15	<li><a href="#Preface_nn4">SWIG Versions</a>
	16	<li><a href="#Preface_nn5">SWIG resources</a>
	17	<li><a href="#Preface_nn6">Prerequisites</a>
	18	<li><a href="#Preface_nn7">Organization of this manual</a>
	19	<li><a href="#Preface_nn8">How to avoid reading the manual</a>
	20	<li><a href="#Preface_nn9">Backwards Compatibility</a>
	21	<li><a href="#Preface_nn10">Credits</a>
	22	<li><a href="#Preface_nn11">Bug reports</a>
	23	</ul>
	24	</div>
	25	<!-- INDEX -->
	26
	27
	28
	29	<H2><a name="Preface_nn2"></a>1.1 Introduction</H2>
	30
	31
	32	<p>
	33	SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language
	34	interfaces to C and C++ programs. Originally developed in 1995, SWIG was
	35	first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for
	36	building user interfaces to simulation codes running on the Connection
	37	Machine 5 supercomputer. In this environment, scientists needed to
	38	work with huge amounts of simulation data, complex hardware, and a
	39	constantly changing code base. The use of a scripting language
	40	interface provided a simple yet highly flexible foundation for solving these
	41	types of problems. SWIG simplifies development by largely automating
	42	the task of scripting language integration--allowing developers and users
	43	to focus on more important problems.
	44	</p>
	45
	46	<p>
	47	Although SWIG was originally developed for scientific applications, it
	48	has since evolved into a general purpose tool that is used in a wide
	49	variety of applications--in fact almost anything where C/C++ programming
	50	is involved.
	51
	52	<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2>
	53
	54
	55	<p>
	56	Since SWIG was released in 1996, its user base and applicability has
	57	continued to grow. Although its rate of development has varied, an
	58	active development effort has continued to make improvements to the
	59	system. Today, nearly a dozen developers are working to create
	60	SWIG-2.0---a system that aims to provide wrapping support for nearly
	61	all of the ANSI C++ standard and approximately ten target languages
	62	including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
	63	and Tcl.
	64	</p>
65
66	<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2>
67
68
69	<p>
70	For several years, the most stable version of SWIG has been release
71	1.1p5. Starting with version 1.3, a new version numbering scheme has
72	been adopted. Odd version numbers (1.3, 1.5, etc.) represent
73	development versions of SWIG. Even version numbers (1.4, 1.6, etc.)
74	represent stable releases. Currently, developers are working to
75	create a stable SWIG-2.0 release. Don't let the development status
76	of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5.
77	</p>
78
79	<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
80
81
82	<p>
83	The official location of SWIG related material is
84	</p>
85
86	<div class="shell"><pre>
87	<a href="http://www.swig.org">http://www.swig.org</a>
88	</pre></div>
89
90	<p>
91	This site contains the latest version of the software, users guide,
92	and information regarding bugs, installation problems, and
93	implementation tricks.
94
95	<p>
96	You can also subscribe to the SWIG mailing list by visiting the page
97	</p>
98
99	<div class="shell"><pre>
100	<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
101	</pre></div>
102
103	<p>
104	The mailing list often discusses some of the more technical aspects of
105	SWIG along with information about beta releases and future work.
106	</p>
107
108	<p>
109	CVS access to the latest version of SWIG is also available. More information
110	about this can be obtained at:
111	</p>
112
113	<div class="shell"><pre>
114	<a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a>
115	</pre></div>
116
117
118	<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
119
120
121	<p>
122	This manual assumes that you know how to write C/C++ programs and that you
123	have at least heard of scripting languages such as
124	Tcl, Python, and Perl. A detailed knowledge of these scripting
125	languages is not required although some familiarity won't
126	hurt. No prior experience with building C extensions to these
127	languages is required---after all, this is what SWIG does automatically.
128	However, you should be reasonably familiar with the use of
129	compilers, linkers, and makefiles since making
130	scripting language extensions is somewhat more complicated than
131	writing a normal C program.
132	</p>
133
134	<p>
135	Recent SWIG releases have become significantly more capable in
136	their C++ handling--especially support for advanced features like
137	namespaces, overloaded operators, and templates. Whenever possible,
138	this manual tries to cover the technicalities of this interface.
139	However, this isn't meant to be a tutorial on C++ programming. For many
140	of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
141	in C++, you may just want to skip those parts of the manual.
142
143	<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2>
144
145
146	<p>
147	The first few chapters of this manual describe SWIG in general and
148	provide an overview of its capabilities. The remaining chapters are
149	devoted to specific SWIG language modules and are self
150	contained. Thus, if you are using SWIG to build Python interfaces, you
151	can probably skip to that chapter and find almost everything you need
152	to know. Caveat: we are currently working on a documentation rewrite and many
153	of the older language module chapters are still somewhat out of date.
154	</p>
155
156	<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
157
158
159	<p>
160	If you hate reading manuals, glance at the "Introduction" which
161	contains a few simple examples. These
162	examples contain about 95% of everything you need to know to use
163	SWIG. After that, simply use the language-specific chapters as a reference.
164	The SWIG distribution also comes with a large directory of
165	examples that illustrate different topics.
166	</p>
167
168	<H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2>
169
170
171	<p>
172	If you are a previous user of SWIG, don't expect recent versions of
173	SWIG to provide backwards compatibility. In fact, backwards
174	compatibility issues may arise even between successive 1.3.x releases.
175	Although these incompatibilities are regrettable, SWIG-1.3 is an active
176	development project. The primary goal of this effort is to make SWIG
177	better---a process that would simply be impossible if the developers
178	are constantly bogged down with backwards compatibility issues.
179	</p>
180
181	<p>
182	On a positive note, a few incompatibilities are a small price to pay
183	for the large number of new features that have been
184	added---namespaces, templates, smart pointers, overloaded methods,
185	operators, and more.
186	</p>
187
188
189	<p>
190	If you need to work with different versions of SWIG and backwards
191	compatibility is an issue, you can use the SWIG_VERSION preprocessor
192	symbol which holds the version of SWIG being executed.
193	SWIG_VERSION is a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11).
194	This can be used in an interface file to define different typemaps, take
195	advantage of different features etc:
196	</p>
197
198	<div class="code"><pre>
199	#if SWIG_VERSION >= 0x010311
200	/* Use some fancy new feature */
201	#endif
202	</pre></div>
203
204	<p>
205	Note: The version symbol is not defined in the generated SWIG
206	wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
207	</p>
208
209	<H2><a name="Preface_nn10"></a>1.9 Credits</H2>
210
211
212	<p>
213	SWIG is an unfunded project that would not be possible without the
214	contributions of many people. Most recent SWIG development has been
215	supported by Matthias Köppe, William Fulton, Lyle Johnson,
216	Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
217	Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus,
218	Harco de Hilster, John Lenz, and Surendra Singhi.
219	</p>
220
221	<p>
222	Historically, the following people contributed to early versions of SWIG.
223	Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
224	at Los Alamos National Laboratory were the first users. Patrick
225	Tullmann at the University of Utah suggested the idea of automatic
226	documentation generation. John Schmidt and Kurtis Bleeker at the
227	University of Utah tested out the early versions. Chris Johnson
228	supported SWIG's developed at the University of Utah. John Buckman,
229	Larry Virden, and Tom Schwaller provided valuable input on the first
230	releases and improving the portability of SWIG. David Fletcher and
231	Gary Holt have provided a great deal of input on improving SWIG's
232	Perl5 implementation. Kevin Butler contributed the first Windows NT
233	port.
234
235	<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2>
236
237
238	<p>
239	Although every attempt has been made to make SWIG bug-free, we are also trying
240	to make feature improvements that may introduce bugs.
241	To report a bug, either send mail to the SWIG developer
242	list at the <a href="http://www.swig.org/mail.html">swig-dev mailing list</a> or report a bug
243	at the <a href="http://www.swig.org/bugs.html">SWIG bug tracker</a>. In your report, be as specific as
244	possible, including (if applicable), error messages, tracebacks (if a
245	core dump occurred), corresponding portions of the SWIG interface file
246	used, and any important pieces of the SWIG generated wrapper code. We
247	can only fix bugs if we know about them.
248	</p>
249
250	</body>
251	</html>