trunk/Doc/Manual/Preface.html - third_party/swig - Git at Google

 <!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 &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.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>
	<!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>