---------------------------
SWIGINAC INSTALLATION NOTES
---------------------------

Dependencies
------------

Before compiling and installing swiginac, make sure that you have installed
GiNaC (ftp://ftpthep.physik.uni-mainz.de/pub/GiNaC/),
SWIG (http://sourceforge.net/project/showfiles.php?group_id=1645), and
pkg-config (http://pkg-config.freedesktop.org/wiki/). 

The version of Swiginac follows the version of GiNaC, and the current interface
is built for GiNaC version 1.5.1. Some quite substantial changes in the type
information system was made in GiNaC 1.5, so version 1.4.x and earlier will not
work. With recent SWIG and pkg-config versions you should be ready to go.

Most recent Linux distributions have packages for the above software. E.g., in
Debian Unstable (sid), the packages are:
libginac1.5
libginac-dev
swig1.3
pkg-config

Supported platforms
-------------------
We have successfully installed swiginac using the distutils file on the
following platforms:

swiginac 1.5.1:
 - Ubuntu intrepid amd64 

swiginac 1.0.0:
 - Debian Linux i386 (see also `Debian Hints`)
 - Ubuntu edgy amd64 (needs GiNaC version >=1.4)
 - MacOSX "Tiger" 10.4

Installing using distutils
--------------------------

Make sure that the dependencies (see above) are met. Additionally, the Python
module distutils must be installed.

To install swiginac and Symbolic, simply run:
python setup.py build
python setup.py install

At this point, swiginac and Symbolic should be installed in the site-packages
directory of your default Python interpreter (on Debian with Python2.5:
/usr/lib/python2.5/site-packages).

Troubleshooting
---------------

The setup.py file in swiginac depends on pkg-config
(http://pkg-config.freedesktop.org/wiki/). The package is usually present in in
most Linux distros. Pkg-config uses .pc files to resolve dependecy build and
link flags, and these files are usually put in /usr/local/lib/pkgconfig or
/usr/lib/pkgconfig. If you have installed (a recent) GiNaC previously,
choosing /usr/local as install prefix, a pkgconfig file named ginac.pc will be
installed under /usr/local/lib/pkgconfig, and this might conflict with the
current version of GiNaC. Using the wrong ginac.pc may cause the setup.py
installation to fail, since pkg-config will report wrong compilation options.
If you experience lots of compiler errors, despite the fact that you have
installed a ginac version compliant with the requirements in swiginac, type:

pkg-config --variable=prefix ginac

to see the prefix of the ginac installation used in setup.py. If the script
reports an unexpected prefix (e.g. /usr/local instead of /usr), delete the
ginac.pc file:

rm `pkg-config --variable=prefix ginac`/lib/pkgconfig/ginac.pc

Debian Hints
~~~~~~~~~~~~
Since version 1.0.0 swiginac requires GiNaC version >= 1.4.0 which is
not in Debian(etch). 

Tested packages are currently (2008-08-28) 

 libginac-dev    1.4.3-1 (testing)

with the dependencies

  libginac1.4    1.4.3-1 (testing)
  libcln5-dev    1.2.2-2 (testing)
  libcln5        1.2.2-2 (testing) 
  
* Version 1.2.0-1 of libcln5 does *not* work,  
  see bug #473494.

* Make sure that library package versions match the development packages.

* Remove an eventually existing libcln4 package.

Be aware that Debian gcc 4.0.2-2 and 4.0.2-4 are not able to compile the
wrapper code correctly in optimized mode. Therefore, expect that Python 
distutils will not work with gcc-4.0.x compilers with aggressive
optimization (-O3). To be safe, either use a 3.x [or 4.n (n > 0)] gcc
compiler or build the module with less optimization:

  CFLAGS=-O0 python setup.py build

(Thanks to Matti Peltomäki for pointing this out)

Building with gcc-4.3 and the default settings works well.


Installing using make
---------------------
For impatient:

cd src/swiginac
make
make install
cd ../Symbolic
make

More info:
Make sure that the dependencies (see above) are met.  The Makefile works on
Debian unstable, if you use other system, you may need to edit it. I.e., edit
PYTHONVERSION (e.g. 2.3), INCLUDES (must contain the directories of the Python
and ginac header files), eventually PREFIX (installation directory). The
default PREFIX is in site-packages in the Python installation, so it should
work out of the box, but if you prefer other directory, you may need to put
PREFIX in PYTHONPATH. In bash, run: export PYTHONPATH=$PYTHONPATH:$PREFIX with
PREFIX identical to the definition in Makefile.

Run:
cd src/swiginac
make 

This will construct the swiginac extension module. The module consists of the
files swiginac.py and _swiginac.so. If you prefer not to install anything, you
can use swiginac just now - import swiginac.py and you are fine.

If you want to install the module in PREFIX, run:
make install

Installing Symbolic is easily done by entering src/Symbolic and typing
make install
If you do not have root privileges, edit the PREFIX variable in Makefile to a
path where you have permissions to install files, and edit PYTHONPATH
accordingly.

Verify the installation
-----------------------
Go to your home directory and start Python. Then issue the commands:
>>> from swiginac import *
>>> x = symbol('x')
>>> y = symbol('y')
>>> print sin(x*y).diff(x,1)
cos(y*x)*y

Then, re-visit the directory containing this file, and run the unit tests:
cd tests/swiginac
python checkall.py
cd ../Symbolic
python SymbolicTests.py

Hopefully, you will get a message telling you that more than 130 tests have been
run, and that all but one went well.

Final note
----------
swiginac only has a tutorial and a talk as written documentation. Therefore,
browsing the scripts in the tests directory is a good way of learning more
about its usage. 

The SVN repository has some more documentation in its doc/ subdirectory.

Also, read the documentation that comes with  GiNaC
(http://www.ginac.de/tutorial/ and http://www.ginac.de/reference/).
