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.