diff options
Diffstat (limited to 'Doc/Manual/Preface.html')
| -rw-r--r-- | Doc/Manual/Preface.html | 251 |
1 files changed, 251 insertions, 0 deletions
diff --git a/Doc/Manual/Preface.html b/Doc/Manual/Preface.html new file mode 100644 index 0000000..630657a --- /dev/null +++ b/Doc/Manual/Preface.html @@ -0,0 +1,251 @@ +<!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-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> +SVN 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.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 >= 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ö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-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> |