      INSTALL
      Copyright (c)  2013 John Abbott and Anna M. Bigatti
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{INSTALL}{John Abbott and Anna Bigatti}

== INSTALLATION guide for CoCoALib ==

CoCoALib is supplied as **SOURCE** code in C++, and so must be **COMPILED**
before you can use it -- instructions on how to do this are below.


=== Prerequisites ===

Before compilation you must ensure that you have available:-

- the GNU ``make`` program (other versions may work too);
- a C++ compiler together with the standard C++ libraries (//e.g.// ``g++``)
- an installation of GMP (version 4.2.1 or later) -- see ``http://gmplib.org/``
- if you want to build ``CoCoA-5`` too, you need the **BOOST libraries**
   (see ``http://www.boost.org/``); more details are in [[src/CoCoA-5/INSTALL]]


=== Compilation of CoCoALib ===

Use the ``cd`` comand to go to the root directory ``CoCoALib-nnn``.
In most cases the following two commands will suffice:
```
  ./configure
  make
```

The command ``make`` compiles CoCoALib (and puts it in ``lib/libcocoa.a``);
it also compiles & runs the test suite, and will compile CoCoA-5 if possible.
The compilation generally takes a few minutes.  If there were no problems
you'll get the reassuring message:

``` Good news: all tests passed


==== Notes ====

(1) The configure script looks for the GMP library, and makes a few checks.
    It assumes your compiler is ``g++``.  If it encounters a problem, it will
    print out a helpful error message telling you.

(2) The command ``make library`` will compile the library but not run the tests.
    The command ``make check`` will run the tests -- they are in ``src/tests/``.

(3) For the adventurous: the command
```       ./configure --help
    explains the various options the script recognizes.
    Also look at [[INSTALL-advanced]]



=== Documentation & Examples ===


Main documentation for CoCoALib: [[index]]

Example programs using CoCoALib: [[../../examples/index]]



=== Microsoft Windows ===

If you have Microsoft Windows, read the file [[INSTALL-MicrosoftWindows]]


=== In Case of Trouble ===

If you encounter problems while using CoCoALib (or trying to compile it),
the best way to let us know is to report the issue via
```    http://cocoa.dima.unige.it/redmine/

Please tell us also the platform and compiler you are using.

Alternatively you can send us email at ``cocoa@dima.unige.it``

