From 4bf045ce2c72f3cf3a20caa9dc42b26c9e6b6458 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Thu, 2 May 2013 07:29:30 +0100 Subject: Move installation and install check instructions from README to Preface section in the documentation. --- Doc/Manual/Contents.html | 8 ++ Doc/Manual/Preface.html | 208 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+) (limited to 'Doc/Manual') 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 @@
  • Release notes
  • Credits
  • Bug reports +
  • Installation + 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 @@
  • Release notes
  • Credits
  • Bug reports +
  • Installation + @@ -117,6 +125,7 @@ about this can be obtained at: +

    1.5 Prerequisites

    @@ -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.

    +

    1.12 Installation

    + + +

    1.12.1 Windows installation

    + + +

    +Please see the dedicated Windows chapter 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. +

    + +

    1.12.2 Unix installation

    + + +

    +You must use GNU make to build and install SWIG. +

    + +

    +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 INSTALL file shipped in the top level directory 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 +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 --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 Modules chapter. +The CHANGES file shipped with SWIG in the top level directory +also lists some examples which build the runtime library. +

    + +

    +Note: +

    + + + +

    1.12.3 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. +

    + +

    +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. +

    + +

    1.12.4 Testing

    + + +

    +If you want to test SWIG after building it, a check can be performed on Unix operating systems. +Type the following: +

    + +
    +    $ make -k check
+
    + +

    +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. +

    + +

    +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: +

    + +
    +    $ 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. +

    + +

    1.12.5 Examples

    + + +

    +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". +

    + +

    +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. +

    + -- cgit v1.2.3