3. Installation

GiNaC's installation follows the spirit of most GNU software. It is easily installed on your system by three steps: configuration, build, installation.

3.1 Prerequisites

In order to install GiNaC on your system, some prerequisites need to be met. First of all, you need to have a C++-compiler adhering to the ANSI-standard ISO/IEC 14882:1998(E). We used GCC for development so if you have a different compiler you are on your own. For the configuration to succeed you need a Posix compliant shell installed in `/bin/sh', GNU bash is fine. Perl is needed by the built process as well, since some of the source files are automatically generated by Perl scripts. Last but not least, Bruno Haible's library CLN is extensively used and needs to be installed on your system. Please get it either from ftp://ftp.santafe.edu/pub/gnu/, from GiNaC's FTP site or from Bruno Haible's FTP site (it is covered by GPL) and install it prior to trying to install GiNaC. The configure script checks if it can find it and if it cannot it will refuse to continue.

3.2 Configuration

To configure GiNaC means to prepare the source distribution for building. It is done via a shell script called configure that is shipped with the sources and was originally generated by GNU Autoconf. Since a configure script generated by GNU Autoconf never prompts, all customization must be done either via command line parameters or environment variables. It accepts a list of parameters, the complete set of which can be listed by calling it with the --help option. The most important ones will be shortly described in what follows:

• --disable-shared: When given, this option switches off the build of a shared library, i.e. a `.so' file. This may be convenient when developing because it considerably speeds up compilation.

• --prefix=PREFIX: The directory where the compiled library and headers are installed. It defaults to `/usr/local' which means that the library is installed in the directory `/usr/local/lib', the header files in `/usr/local/include/ginac' and the documentation (like this one) into `/usr/local/share/doc/GiNaC'.

• --libdir=LIBDIR: Use this option in case you want to have the library installed in some other directory than `PREFIX/lib/'.

• --includedir=INCLUDEDIR: Use this option in case you want to have the header files installed in some other directory than `PREFIX/include/ginac/'. For instance, if you specify --includedir=/usr/include you will end up with the header files sitting in the directory `/usr/include/ginac/'. Note that the subdirectory `ginac' is enforced by this process in order to keep the header files separated from others. This avoids some clashes and allows for an easier deinstallation of GiNaC. This ought to be considered A Good Thing (tm).

• --datadir=DATADIR: This option may be given in case you want to have the documentation installed in some other directory than `PREFIX/share/doc/GiNaC/'.

In addition, you may specify some environment variables. CXX holds the path and the name of the C++ compiler in case you want to override the default in your path. (The configure script searches your path for c++, g++, gcc, CC, cxx and cc++ in that order.) It may be very useful to define some compiler flags with the CXXFLAGS environment variable, like optimization, debugging information and warning levels. If omitted, it defaults to -g -O2.(1)

The whole process is illustrated in the following two examples. (Substitute setenv VARIABLE value for export VARIABLE=value if the Berkeley C shell is your login shell.)

Here is a simple configuration for a site-wide GiNaC library assuming everything is in default paths:

$ export CXXFLAGS="-Wall -O2"
$ ./configure

And here is a configuration for a private static GiNaC library with several components sitting in custom places (site-wide GCC and private CLN). The compiler is persuaded to be picky and full assertions and debugging information are switched on:

$ export CXX=/usr/local/gnu/bin/c++
$ export CPPFLAGS="$(CPPFLAGS) -I$(HOME)/include"
$ export CXXFLAGS="$(CXXFLAGS) -DDO_GINAC_ASSERT -ggdb -Wall -pedantic"
$ export LDFLAGS="$(LDFLAGS) -L$(HOME)/lib"
$ ./configure --disable-shared --prefix=$(HOME)

3.3 Building GiNaC

After proper configuration you should just build the whole library by typing

$ make

Just to make sure GiNaC works properly you may run a collection of regression tests by typing

$ make check

This will compile some sample programs, run them and check the output for correctness. The regression tests fall in three categories. First, the so called exams are performed, simple tests where some predefined input is evaluated (like a pupils' exam). Second, the checks test the coherence of results among each other with possible random input. Third, some timings are performed, which benchmark some predefined problems with different sizes and display the CPU time used in seconds. Each individual test should return a message `passed'. This is mostly intended to be a QA-check if something was broken during development, not a sanity check of your system. Some of the tests in sections checks and timings may require insane amounts of memory and CPU time. Feel free to kill them if your machine catches fire. Another quite important intent is to allow people to fiddle around with optimization.

By default, the only documentation that will be built is this tutorial in `.info' format. To build the GiNaC tutorial and reference manual in HTML, DVI, PostScript, or PDF formats, use one of

$ make html
$ make dvi
$ make ps
$ make pdf

Generally, the top-level Makefile runs recursively to the subdirectories. It is therefore safe to go into any subdirectory (doc/, ginsh/, ...) and simply type make target there in case something went wrong.

3.4 Installing GiNaC

To install GiNaC on your system, simply type

$ make install

As described in the section about configuration the files will be installed in the following directories (the directories will be created if they don't already exist):

• `libginac.a' will go into `PREFIX/lib/' (or `LIBDIR') which defaults to `/usr/local/lib/'. So will `libginac.so' unless the configure script was given the option --disable-shared. The proper symlinks will be established as well.

• All the header files will be installed into `PREFIX/include/ginac/' (or `INCLUDEDIR/ginac/', if specified).

• All documentation (info) will be stuffed into `PREFIX/share/doc/GiNaC/' (or `DATADIR/doc/GiNaC/', if DATADIR was specified).

For the sake of completeness we will list some other useful make targets: make clean deletes all files generated by make, i.e. all the object files. In addition make distclean removes all files generated by the configuration and make maintainer-clean goes one step further and deletes files that may require special tools to rebuild (like the libtool for instance). Finally make uninstall removes the installed library, header files and documentation(2).