      ExternalLibs-GMP
      Copyright (c)  2016 John Abbott
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{ExternalLibs-GMP}{John Abbott}


== User documentation ==
%======================================================================

**GMP** is an **essential** external library for CoCoALib: a sufficiently
recent version of GMP must be present to permit compilation of CoCoALib.
The CoCoALib classes ``BigInt`` and ``BigRat`` are simply wrappers for
the underlying GMP types.

At the moment CoCoALib does not require the C++ interface to GMP,
however if you wish to combine CoCoALib with the external library
**Normaliz** then the C++ interface to GMP must also be present.

=== Examples ===
- [ex-BigInt1.C ../../examples/index.html#ex-BigInt1.C]
- [ex-BigInt2.C ../../examples/index.html#ex-BigInt2.C]
- [ex-BigInt3.C ../../examples/index.html#ex-BigInt3.C]
- [ex-BigRat1.C ../../examples/index.html#ex-BigRat1.C]
-

=== Download and compile GMP ===

It is common for Linux computers to have the GMP library already
installed; the CoCoALib configuration script will check for this,
and will give an error message if it cannot be found.

If you do need (or want) to build the GMP library yourself,
you can get it from
 | [**GMP** website http://www.gmplib.org/]

Note that **CoCoALib** expects **GMP** release 5.0.0 or later.

During configuration of GMP we recommend giving the option ``--enable-cxx``
even though this is not strictly necessary for CoCoALib.  We also
recommend building the static libraries (in GMP-6.1.0 both static and
shared libraries are built by default, but check the documentation of
the version of GMP which you obtained).
``` ./configure --enable-cxx
``` make

If you have the relevant permissions (and you want to), you can
"install" the GMP library by running ``make install``.  If you do
install the GMP library, it is important that you run the privileged
command ``ldconfig`` to properly register the new shared libraries.
If you do not install the library then make a note of the full path
to where the file ``libgmp.a`` is (on my computer it is in an
invisible subdirectory called ``.libs``), as you must specify this
when configuring CoCoALib.

Then configure and compile **CoCoALib** by typing (but without the
option ``--with-libgmp`` if GMP is properly installed).

``` 
cd CoCoALib-0.99
./configure --with-libgmp=<your_path_to>/libgmp.a
make
```


== Maintainer documentation ==
%======================================================================

A future version of CoCoALib may use the C++ interface to GMP, but
that it not imminent.


== Bugs, shortcomings and other ideas ==
%======================================================================

Strictly the parts of CoCoALib which compute with small finite fields
do not need the GMP library; nevertheless we chose not to permit
compilation without GMP.

I found the following website useful:
```
http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html
```

== Main changes ==
%======================================================================

**2016**
- 10 June: first version; added new note about ldconfig

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
