Installation: SWIG 1.1 June 24, 1997 Installation (Unix) ------------------- To compile and use SWIG, you will need the following on your machine: A C++ compiler (ie. g++) An ANSI C compiler (ie. gcc) yacc or bison (only needed to rebuild the SWIG parser). To compile and install SWIG, type the following : ./configure make make install The configuration script will attempt to locate various packages on your machine, including Tcl, Perl5, and Python. 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. See the Examples section below for more details. The 'make runtime' option is an optional step that can be used to build the SWIG runtime libraries. These libraries are only used with larger packages and are not necessary for learning SWIG or trying the examples (please refer to the "Advanced topics" section of the SWIG Users manual for more details). Typing 'make test' will run a rather extensive series of tests and can be run before running 'make install' (if you are paranoid). There are a number of configuration options that you can give to 'configure' : --prefix=/usr/local Set the installation prefix. SWIG installs into /usr/local by default. --exec_prefix=/usr/local Set the prefix used to install platform specific files (binaries and libraries). Use this if the location is different than that given with --prefix. --with-lang={TCL,TCL8,PYTHON,PERL5,PERL4,GUILE} This lets you choose the default SWIG target language. By default, SWIG chooses TCL, but you can select another as shown : ./configure --with-lang=PYTHON --with-doc={ASCII,LATEX,HTML,NODOC} This lets you choose the default SWIG documentation method. By default, SWIG chooses ASCII. To test the SWIG parser after compilation, type 'make test'. Site specific installation -------------------------- While not required for compiling SWIG, the configuration script looks for various packages in order to create a makefile for compiling the examples. This makefile is also installed with the SWIG package. The following configuration options can be used to set the location of various packages. --with-tcl=pathname - Set root directory of Tcl installation. SWIG will use $pathname/include and $pathname/lib. --with-tclincl=pathname - Set exact location of Tcl include files --with-tcllib=pathname - Set exact location of Tcl library files --with-itcl=pathname - Same as above but for [incr Tcl] --with-itclincl=pathname - Location of [incr Tcl] include files --with-itcllib=pathname - Location of [incr Tcl] libraries --with-py=pathname - Set package location of Python. This is usually something like /usr/local. configure will attempt to locate the appropriate include and library files. --with-pyincl=pathname - Set location of Python include files (for example, /usr/local/include) --with-pylib=pathname - Set location of Python library files (for example, /usr/local/lib) --with-perl5=executable - Specify your perl5 executable. SWIG will figure out where files are by running this version of Perl and grabbing its configuration data. Other options : --without-yacc - Try to compile SWIG using a pregenerated YACC file generated by Berkeley YACC (byacc). Only recommended if you get compiler errors when trying to compile parser.y or parser.cxx. How to use a different C++ compiler (IMPORTANT) ------------------------------------------------ Normally, the configure script will probably use g++ as the C++ compiler. If you want to use a different compiler, do the following before running configure. setenv CXX CC # Set CXX to your C++ compiler ./configure make Changing the Makefiles to use a different C++ compiler after configuration is not recommended! If you need to do this, do this : rm config.cache setenv CXX CC ./configure make To change the C compiler (for compiling examples), follow the same procedure above, change the symbol 'CC' instead of 'CXX'. Testing : --------- There are several tests that can be done after compilation : make test - Tests the SWIG parser and performs regression tests make testbuild - Tests SWIG ability to build various modules (see below) make testall - Test both of the above The testing process requires the use of the 'bash' shell and Perl. If you don't have these, don't expect the tests to work. *** Warning : Full testing requires about 20 Mbytes of disk space and creates a collection of regression testing files. After performing the tests, you can do a 'make testclean' to clean up the test directories to their initial distribution state. The SWIG Makefiles ------------------ SWIG creates a Makefile with rules on how to build all kinds of modules for different languages. This makefile is called 'Makefile.template' in the top level directory and is installed with the SWIG library as 'swig_lib/Makefile'. Prior to installation, it is highly recommended that you run a 'make testbuild' to test this Makefile. This test will report which kinds of extensions can be built. It is normal that some tests will fail (depending on your system and installation), but if the tests fail for a language you want to use, you will want to edit the file 'Makefile.template' by hand. In this process, you can repeatedly try 'make testbuild' until you are satisfied. In addition to the 'Makefile.template' SWIG 1.1 attempts to configure more advanced makefiles for each scripting language. These are located in 'swig_lib/tcl/Makefile', 'swig_lib/perl5/Makefile', and 'swig_lib/python/Makefile'. Prior to installation, you may want to examine these Makefiles to make sure they accurately reflect your local setup. If you're happy with the setup, proceed to installation. Installation ------------ Type 'make install' to install SWIG. This will install the following : - The SWIG Library (containing interface files) - swig.h (Headers for building SWIG extensions) - libswig.a (SWIG library for building SWIG extensions) - swig.1 (man page) - swig_lib/Makefile Makefile for building extensions - Runtime libraries (if built earlier). Troubleshooting -------------- See the file TROUBLESHOOTING for solutions to several problems. While I have access to a large number of machines, it's impossible for me to test everything. If you can't get SWIG to build successfully, please send me email at beazley@cs.utah.edu. Installation for Windows 95 and NT ---------------------------------- The Win directory contains makefiles for Microsoft Visual C++ 4.x. See the README file in the Win directory for specific build instructions. Installation for Macintosh -------------------------- The Mac directory contains information about building SWIG on the Macintosh. At this time, the Macintosh version is distributed separately as a binary release. Source is also available, but is non-trivial to build due to dependencies on other packages.