diff options
-rw-r--r-- | Doc/Manual/Contents.html | 8 | ||||
-rw-r--r-- | Doc/Manual/Preface.html | 208 | ||||
-rw-r--r-- | README | 129 |
3 files changed, 225 insertions, 120 deletions
diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 3e9c844ed..ac21bcd1e 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -25,6 +25,14 @@ <li><a href="Preface.html#Preface_release_notes">Release notes</a> <li><a href="Preface.html#Preface_nn10">Credits</a> <li><a href="Preface.html#Preface_nn11">Bug reports</a> +<li><a href="Preface.html#Preface_installation">Installation</a> +<ul> +<li><a href="Preface.html#Preface_windows_installation">Windows installation</a> +<li><a href="Preface.html#Preface_unix_installation">Unix installation</a> +<li><a href="Preface.html#Preface_osx_installation">Macintosh OS X installation</a> +<li><a href="Preface.html#Preface_testing">Testing</a> +<li><a href="Preface.html#Preface_examples">Examples</a> +</ul> </ul> </div> <!-- INDEX --> diff --git a/Doc/Manual/Preface.html b/Doc/Manual/Preface.html index d489912bd..d17dc229c 100644 --- a/Doc/Manual/Preface.html +++ b/Doc/Manual/Preface.html @@ -21,6 +21,14 @@ <li><a href="#Preface_release_notes">Release notes</a> <li><a href="#Preface_nn10">Credits</a> <li><a href="#Preface_nn11">Bug reports</a> +<li><a href="#Preface_installation">Installation</a> +<ul> +<li><a href="#Preface_windows_installation">Windows installation</a> +<li><a href="#Preface_unix_installation">Unix installation</a> +<li><a href="#Preface_osx_installation">Macintosh OS X installation</a> +<li><a href="#Preface_testing">Testing</a> +<li><a href="#Preface_examples">Examples</a> +</ul> </ul> </div> <!-- INDEX --> @@ -117,6 +125,7 @@ about this can be obtained at: </pre></div> + <H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2> @@ -239,5 +248,204 @@ used, and any important pieces of the SWIG generated wrapper code. We can only fix bugs if we know about them. </p> +<H2><a name="Preface_installation"></a>1.12 Installation</H2> + + +<H3><a name="Preface_windows_installation"></a>1.12.1 Windows installation</H3> + + +<p> +Please see the dedicated <a href="Windows.html">Windows chapter</a> for instructions on installing +SWIG on Windows and running the examples. The Windows distribution is +called swigwin and includes a prebuilt SWIG executable, swig.exe, included in +the top level directory. Otherwise it is exactly the same as +the main SWIG distribution. There is no need to download anything else. +</p> + +<H3><a name="Preface_unix_installation"></a>1.12.2 Unix installation</H3> + + +<p> +You must use <a href="http://www.gnu.org/software/make/">GNU make</a> to build and install SWIG. +</p> + +<p> +<a href="http://www.pcre.org/">PCRE</a> +needs to be installed on your system to build SWIG, in particular +pcre-config must be available. If you have PCRE headers and libraries but not +pcre-config itself or, alternatively, wish to override the compiler or linker +flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables +to be used instead. And if you don't have PCRE at all, the configure script +will provide instructions for obtaining it. +</p> + +<p> +To build and install SWIG, simply type the following: +</p> + +<div class="shell"><pre> +$ ./configure +$ make +$ make install +</pre></div> + +<p> +By default SWIG installs itself in /usr/local. If you need to install SWIG in +a different location or in your home directory, use the <tt>--prefix</tt> option +to <tt>./configure</tt>. For example: +</p> + +<div class="shell"><pre> +$ ./configure --prefix=/home/yourname/projects +$ make +$ make install +</pre></div> + +<p> +Note: the directory given to <tt>--prefix</tt> must be an absolute pathname. Do <b>not</b> use +the ~ shell-escape to refer to your home directory. SWIG won't work properly +if you do this. +</p> + +<p> +The INSTALL file shipped in the top level directory details more about using configure. Also try +</p> + +<div class="shell"><pre> +$ ./configure --help. +</pre></div> + +<p> +The configure script will attempt to locate various packages on your machine +including Tcl, Perl5, Python and all the other target languages that SWIG +supports. Don't panic if you get 'not found' messages -- SWIG does not need these +packages to compile or run. The configure script is actually looking for +these packages so that you can try out the SWIG examples contained +in the 'Examples' directory without having to hack Makefiles. +Note that the <tt>--without-xxx</tt> options, where xxx is a target language, have +minimal effect. All they do is reduce the amount of testing done with +'make check'. The SWIG executable and library files installed cannot currently +be configured with a subset of target languages. +</p> + +<p> +SWIG used to include a set of runtime libraries for some languages for working +with multiple modules. These are no longer built during the installation stage. +However, users can build them just like any wrapper module as described in +the <a href="Modules.html">Modules chapter</a>. +The CHANGES file shipped with SWIG in the top level directory +also lists some examples which build the runtime library. +</p> + +<p> +Note: +</p> + +<ul> +<li> +If you checked the code out via Git, you will have to run <tt>./autogen.sh</tt> +before <tt>./configure</tt>. In addition, a full build of SWIG requires +a number of packages to be installed. Full instructions at +<a href="http://www.swig.org/svn.html">SWIG bleeding edge</a>. +</li> +</ul> + +<H3><a name="Preface_osx_installation"></a>1.12.3 Macintosh OS X installation</H3> + + +<p> +SWIG is known to work on various flavors of OS X. Follow the Unix installation +instructions above. However, as of this writing, there is still great deal of +inconsistency with how shared libaries are handled by various scripting languages +on OS X. +</p> + +<p> +Users of OS X should be aware that Darwin handles shared libraries and linking in +a radically different way than most Unix systems. In order to test SWIG and run +the examples, SWIG configures itself to use flat namespaces and to allow undefined +symbols (<tt>-flat_namespace -undefined suppress</tt>). This mostly closely follows the Unix +model and makes it more likely that the SWIG examples will work with whatever +installation of software you might have. However, this is generally not the recommended +technique for building larger extension modules. Instead, you should utilize +Darwin's two-level namespaces. Some details about this can be found here + +<a href="http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html">http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html</a>. + +</p> + +<p> +Needless to say, you might have to experiment a bit to get things working at first. +</p> + +<H3><a name="Preface_testing"></a>1.12.4 Testing</H3> + + +<p> +If you want to test SWIG after building it, a check can be performed on Unix operating systems. +Type the following: +</p> + +<div class="shell"><pre> + $ make -k check +</pre></div> + +<p> +This step can be performed either before or after installation. +The check requires at least one of the target languages to be +installed. If it fails, it may mean that you have an uninstalled +language module or that the file 'Examples/Makefile' has been +incorrectly configured. It may also fail due to compiler issues such +as a broken C++ compiler. Even if the check fails, there is a +pretty good chance SWIG still works correctly --- you will just have to +mess around with one of the examples and some makefiles to get it to work. +Some tests may also fail due to missing dependency packages, eg PCRE +or Boost, but this will require careful analysis of the configure output +done during configuration. +</p> + +<p> +The test suite executed by the check is designed to stress-test +many parts of the implementation including obscure corner cases. If some +of these tests fail or generate warning messages, there is no reason for +alarm --- the test may be related to some new SWIG feature or a difficult bug +that we're trying to resolve. Chances are that SWIG will work just fine +for you. Note that if you have more than one CPU/core, then you can use +parallel make to speed up the check as it does take quite some time to run, +for example: +</p> + +<div class="shell"><pre> + $ make -j2 -k check +</pre></div> + +<p> +Also, 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. +</p> + +<p> +Note: The test-suite currently contains over 500 tests. If you +have many different target languages installed and a slow machine, it +might take more than an hour to run the test-suite. +</p> + +<H3><a name="Preface_examples"></a>1.12.5 Examples</H3> + + +<p> +The Examples directory contains a variety of examples of using SWIG +and it has some browsable documentation. Simply point your browser to +the file "Example/index.html". +</p> + +<p> +The Examples directory also includes Visual C++ project 6 (.dsp) files for +building some of the examples on Windows. Later versions of Visual Studio +will convert these old style project files into a current solution file. +</p> + </body> </html> @@ -65,128 +65,17 @@ See the documentation for details of the SWIG_VERSION preprocessor symbol if you have backward compatibility issues and need to use more than one version of SWIG. -Windows Installation -==================== -Please see the Doc/Manual/Windows.html file for instructions on installing -SWIG on Windows and running the examples. The Windows distribution is -called swigwin and includes a prebuilt SWIG executable, swig.exe, included in -the same directory as this README file. Otherwise it is exactly the same as -the main SWIG distribution. There is no need to download anything else. - -Unix Installation -================= -You must use GNU `make' to build SWIG. - -http://www.gnu.org/software/make/ - -PCRE needs to be installed on your system to build SWIG, in particular -pcre-config must be available. If you have PCRE headers and libraries but not -pcre-config itself or, alternatively, wish to override the compiler or linker -flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables -to be used instead. And if you don't have PCRE at all, the configure script -will provide instructions for obtaining it. - -To build and install SWIG, simply type the following: - - % ./configure - % make - % make install - -By default SWIG installs itself in /usr/local. If you need to install SWIG in -a different location or in your home directory, use the --prefix option -to ./configure. For example: - - % ./configure --prefix=/home/yourname/projects - % make - % make install - -Note: the directory given to --prefix must be an absolute pathname. Do *NOT* use -the ~ shell-escape to refer to your home directory. SWIG won't work properly -if you do this. - -The file INSTALL details more about using configure. Also try - - % ./configure --help. - -The configure script will attempt to locate various packages on your machine -including Tcl, Perl5, Python and all the other target languages that SWIG -uses. Don't panic if you get 'not found' messages--SWIG does not need these -packages to compile or run. The configure script is actually looking for -these packages so that you can try out the SWIG examples contained -in the 'Examples' directory without having to hack Makefiles. -Note that the --without-xxx options, where xxx is a target language, have -minimal effect. All they do is reduce the amount of testing done with -'make check'. The SWIG executable and library files installed cannot currently -be configured with a subset of target languages. - -SWIG used to include a set of runtime libraries for some languages for working -with multiple modules. These are no longer built during the installation stage. -However, users can build them just like any wrapper module as described in -the documentation, Doc/Manual/Modules.html. The CHANGES file also lists some -examples which build the runtime library. - -Notes: - -(1) If you checked the code out via Git, you will have to run ./autogen.sh - before typing 'configure'. In addition, a full build of SWIG requires - the a number of packages to be installed. Full instructions at - http://www.swig.org/svn.html - -Macintosh OS X Installation -============================ -SWIG is known to work on various flavors of OS X. Follow the Unix installation -instructions above. However, as of this writing, there is still great deal of -inconsistency with how shared libaries are handled by various scripting languages -on OS X. We've tried to resolve these differences to the extent of our knowledge. - -Users of OS X should be aware that Darwin handles shared libraries and linking in -a radically different way than most Unix systems. In order to test SWIG and run -the examples, SWIG configures itself to use flat namespaces and to allow undefined -symbols (-flat_namespace -undefined suppress). This mostly closely follows the Unix -model and makes it more likely that the SWIG examples will work with whatever -installation of software you might have. However, this is generally not the recommended -technique for building larger extension modules. Instead, you should utilize -Darwin's two-level namespaces. Some details about this can be found here - -http://developer.apple.com/documentation/ReleaseNotes/DeveloperTools/TwoLevelNamespaces.html - -Needless to say, you might have to experiment a bit to get things working at first. +Installation +============ +Please read the Doc/Manual/Preface.html#Preface_installation for +full installation instructions for Windows, Unix and Mac OS X. +The INSTALL file has generic build and installation instructions for +Unix users. Testing ======= -If you want to test SWIG before installation, type the following: - - % make -k check - -'make -k check' requires at least one of the target languages to be -installed. If it fails, it may mean that you have an uninstalled -language module or that the file 'Examples/Makefile' has been -incorrectly configured. It may also fail due to compiler issues such -as broken C++ compiler. Even if 'make -k check' fails, there is a -pretty good chance SWIG still works correctly---you will just have to -mess around with one of the examples and some makefiles to get it to work. -Some tests may also fail due to missing dependency packages, eg PCRE -or Boost, but this will require careful analysis of the configure output. - -The testing suite executed by 'make -k check' is designed to stress-test -many parts of the implementation including obscure corner cases. If some -of these tests fail or generate warning messages, there is no reason for -alarm---the test may be related to some new SWIG feature or a difficult bug -that we're trying to resolve. Chances are that SWIG will work just fine -for you. Note that if you have more than one CPU/core, then you can use -parallel make to speed up the check as it does take quite some time to run, -for example: - - % make -j2 -k check - -Also, 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. - -Note: The test-suite currently contains over 500 tests. If you -have many different target languages installed and a slow machine, it -might take more than an hour to run the test-suite. +The typical 'make -k check' can be performed on Unix operating systems. +Please read Doc/Manual/Preface.html#Preface_testing for details. Examples ======== @@ -208,7 +97,7 @@ Troubleshooting In order to operate correctly, SWIG relies upon a set of library files. If after building SWIG, you get error messages like this, - % swig foo.i + $ swig foo.i :1. Unable to find 'swig.swg' :3. Unable to find 'tcl8.swg' |