LiDIA --- A library for computational number theory

LiDIA was developed from 1994 to 2004 at TU Darmstadt. It is not under active development. 
The authoritative repository for LiDIA used to reside at

	http://www.informatik.tu-darmstadt.de/TI/LiDIA/ftp/LiDIA/

The present version, named 2.3.0+latte-patches-YYYY-MM-DD, 
is based on the last official release, 2.3.0, of the LiDIA library.
It has minimal patches for using LiDIA within the LattE integrale project
with newer compilers and other infrastructure.
It is maintained at https://github.com/mkoeppe/LiDIA


LiDIA's build system has a mechanism to create two types of distribution archives:
the whole archive (LiDIA-2.3.0) or just packages (LiDIA-base-2.3.0,
LiDIA-FF-2.3.0, LiDIA-LA-2.3.0, LiDIA-LT-2.3.0, LiDIA-NF-2.3.0,
LiDIA-EC-2.3.0, LiDIA-ECO-2.3.0, and LiDIA-GEC-2.3.0).  All packages
are provided in tar.gz format.  Everything unpacks into the directory
./LiDIA-2.3.0. 

Package dependencies:                                                   base
 * The FF (Finite Fields) package depends only on the base package.      |
 * The LA (Linear Algebra) package depends on the FF package.	         FF
 * The LT (Lattice) package depends on the LA package.		         |
 * The NF (Number Field) package depends on the LT package.	         LA
 * The EC (Elliptic Curve) package depends on the LA package.	        / \
 * The ECO (Elliptic Curve Order) package depends on the EC package.   LT  EC
 * The GEC (Generate Elliptic Curves) package depends on both the NF   |   |
   and the ECO package.						       NF  ECO
     								        \ /
     								         GEC
     
CHANGES

See the file NEWS for a list of major changes in the current release.




C++ COMPILER REQUIREMENTS

In order to compile LiDIA, your C++ compiler MUST support some ISO C++
features.  These are:

    - type bool
    - inlining
    - mutable class members
    - explicit constructors
    - C++ style casts (i.e. static_cast<...> and const_cast<...>)
    - explicit template instantiation by ISO C++
    - template specialization by ISO C++ (template <>)
    - ISO C++ headers, such as <iostream>, <fstream>, <string>, but also
      <cstdlib>, <cstdio>, etc. 

Moreover, LiDIA makes use of some basic classes from the C++ standard
library, such as fstream, string.

If your compiler fails to support one of the above items, you should
upgrade.  Sorry for the inconvenience, but that's what a standard is for.

However, LiDIA still doesn't make use of exceptions and run-time type
information if you don't want it to.

As of release 2.1pre6, only g++ has been tested.  The g++ versions 3.x and 4.x
compile LiDIA successfully, whereas g++ 2.95.3 and 2.96 are
known to fail when compiling LiDIA.  Note that this is not LiDIA's fault...




DISK SPACE AND MAIN MEMORY REQUIREMENTS

LiDIA is a quite large system which requires a remarkable amount of
resources.  The full LiDIA distribution occupies about 70MByte when
unpacked. Configuring and building all packages typically takes about 135MByte
disk space on an i386-linux-gnu platform with ELF object file format, plus
about 25MByte for temporaries.  Installing all packages can take additional
90MByte. These amounts depend very much on the platform and on the configuration
options. You can easily consume more than 1.8GByte if you configure LiDIA with
  configure --disable-shared CXXFLAGS='-O0 -g2'
and run
  make check
On the other hand, you can reduce the disk space requirements significantly by
using appropriate configuration options if you do not need all the features
of the full LiDIA distribution and if you build only those test programs you
are interested in.

With older versions of g++, 64MByte of RAM used to be sufficient for building
LiDIA. Since recent g++ version have a much more heavy memory footprint, we
recommend you have at least 512MByte free RAM. This recommendation also
applies to building LiDIA applications, particularly when
instantiating some of LiDIA's template classes.



INSTALLATION (Unix-like systems, using configure)

If you used `git clone` to obtain the source code of LiDIA,
you will first have to generate the build scripts using:

    ./bootstrap

Then proceed using `./configure' to configure LiDIA, see the file INSTALL for
compilation and generic installation instructions.

LiDIA-specific configure options:

    --enable-inline
	If set to `yes', the multi-precision arithmetic routines from the
	underlying kernel are inlined, otherwise separate function calls are
	generated.  The default is `yes'.

    --enable-exceptions
        If set to `yes', then LiDIA is built with support for
        exceptions and errors are reported by exceptions. 
        If set to `no', then LiDIA is built without support for
        exceptions. (g++ compiler switch `-fno-exceptions'.) 
        Consult the description of class LiDIA::BasicError in the
        LiDIA manual for details.
        The default is `yes'.

    --enable-namespaces
	If set to `yes', then all of LiDIA's symbols will be defined in the
	name space LiDIA (your C++ compiler must support name spaces).  The
	default is `yes'.

    --enable-assert
	If set to `yes', the assert macros will be activated by not defining
	`NDEBUG'.  The default is `no'.

    --enable-ff
	If set to `yes', the finite-fields package will be built.  The
	default is `yes'.

    --enable-la
	If set to `yes', the linear-algebra package will be built.  Since
	this package depends on the finite-fields package, the
	linear-algebra package will be built only if the finite-fields
	package is built.  The default is `yes'.

    --enable-lt
	If set to `yes', the lattice package will be built.  Since this
	package depends on the linear-algebra package, the lattice package
	will be built only if the linear-algebra package is built.  The
	default is `yes'.

    --enable-nf
	If set to `yes', the number-fields package will be built.  Since
	this package depends on the lattice package, the number-fields
	package will be built only if the lattice package is built.  The
	default is `yes'.

    --enable-ec
	If set to `yes', the elliptic-curves package will be built.  Since
	this package depends on the lattice package, the elliptic-curves
	package will be built only if the lattice package is built.  The
	default is `yes'.

    --enable-eco
	If set to `yes', the elliptic-curve-order package will be built.
	Since this package depends on the elliptic-curves package, the
	elliptic-curve-order package will be built only if the
	elliptic-curves package is built.  The default is `yes'.

    --enable-gec
	If set to `yes', the elliptic curve generation package will be
	built.  Since this package depends on the elliptic curve order
	package, the elliptic curve generation package will be built only
	if the elliptic curve order package is built.  The default is
	`yes'.

    --with-arithmetic
	Determines the multi-precision kernel for LiDIA.  Valid values are
	`gmp', `cln', `piologie', and `libI'.

	YOUR SYSTEM MUST PROVIDE THE LIBRARY OF YOUR CHOICE BEFORE
	CONFIGURING LiDIA!

	Note for Piologie users on Unix-like systems: For some reason the
	Piologie library is created as `piologie.a' instead of
	`libpiologie.a'.  Rename `piologie.a' to `libpiologie.a', or create
	a link, otherwise the configure script will not find the Piologie
	library.

    --with-extra-includes
	If the headers of the multi-precision library reside in a directory
	that is not searched by your C++ compiler, then add the path with
	this option.

    --with-extra-libs
	If the multi-precision library resides in a directory that is not
	searched by your linker, then add the path with this option.

LiDIA's build procedure uses GNU Libtool, which adds the following 
options to "configure":

    --enable-shared
    --enable-static
	These options determine whether shared and/or static library
	versions will be built.  Only the latter option defaults to `yes'.

    --with-pic
    --without-pic
	Normally, shared libraries use position-independent code, and
	static libraries use direct jump instructions which need to be
	edited by the linker.  The --with-pic option enforces
	position-independent code even for static libraries, whereas
	--without-pic does not demand position-independent code even when
	building shared libraries.  Using one of these options can halven
	compilation time and reduce disk space usage because they save
	the source files from being compiled twice.  Note that only
	position-independent code can be shared in main memory among
	applications; using position-dependent code for dynamically linked
	libraries just defers the linking step to program load time and
	then requires private memory for the relocated library code.

    --enable-fast-install
	LiDIA comes with some example applications, which you may want to
	run in the build tree without having installed the shared library.
	To make this work, Libtool creates wrapper scripts for the actual
	binaries.  With --enable-fast-install=yes, the (hidden) binaries
	are prepared for installation and must be run from the (visible)
	wrapper scripts until the shared library is installed.  With
	--enable-fast-install=no, the binaries are linked with the
	uninstalled library, thus necessitating a relinking step when
	installing them.  As long as you do not run the hidden binaries
	directly and use the provided make targets for installing, you need
	not care about these details.  However, note that installing the
	example applications without having installed the shared library in
	the configured libdir will work only with the setting
	--enable-fast-install=yes, which is the default.  This can be
	important when preparing binary installation images.


COMPILER FLAGS

You can provide any desired compiler flag by setting the variable CXXFLAGS
in the environment or in the command line passed to `configure'.  For
example, type

	./configure CXXFLAGS="<your desired flags>"

The configure script presets CFLAGS and CXXFLAGS with -O2, if these are
empty or unset. 

If you have problems to build LiDIA due to memory exhaustion, it will
probably help to limit inlining (some packages contain quite large inlined
functions).  If you are using GCC, the appropriate option to limit inlining
is -finline-limit-N (GCC-2.x) resp. -finline-limit=N (GCC-3.x), where N
should be chosen to be between 300 and 1000 (GCC's default is 10000).  This
will also result in faster compilation times and smaller object files for
some source files.

Likewise, the GNU g++ compiler flags -Wreturn-type might drastically
increase memory consumption (see the GCC FAQ, e.g. http://gcc.gnu.org/faq/).
Note that -Wall implies -Wreturn-type.


EXTENDED FEATURES

LiDIA's Makefile suite provides all targets proposed in the GNU Makefile
standards, including `install-exec', `install-data', and `uninstall'.
Furthermore, VPATH builds and staged installs (using DESTDIR) are supported.


BUILDING AND INSTALLING THE EXAMPLES

To build the examples, type

	make examples

and to install the examples type

	make install-examples


BUILDING THE DOCUMENTATION

To run the documentation through LaTeX2e and produce the DVI file
doc/LiDIA.dvi, type

	make dvi

Note: As of release 2.1pre6, this also requires the "texi2dvi" script,
which comes with the GNU texinfo tools, to be available on your system.

You can additionally convert the DVI file into Postscript, yielding
doc/LiDIA.ps, by running

	make ps

and generate compressed versions doc/LiDIA.ps.{gz,bz2} using

	make psgz
	make psbz2

If you have pdflatex, you can as well build doc/LiDIA.pdf.  Just type

	make pdf
or
	make dsc

The latter produces doc/LiDIA.dsc in addition to doc/LiDIA.pdf.  The dsc
file is a Postscript wrapper providing access to LiDIA.pdf for PS tools
like psselect, Ghostview, and others.  Making the dsc file requires the
"pdf2dsc" utility which comes with Ghostscript 6.x.  Note that the
combination of pdf+dsc is as compact as a compressed PS file.  However, you
will probably not be able to print doc/LiDIA.dsc because that file uses
pointers into LiDIA.pdf which will be dangling when copied into a spool
directory.  For printing, better make doc/LiDIA.ps.


BUILDING THE MANUAL

You can build the manual with "make doc" once the package is configured. Note
that you need a (PDF-)LaTeX installation for this to work.

If you do not have the EC and EM Type 1 fonts installed, then edit
doc/LiDIA.tex and uncomment the line that instructs LaTeX to use the package
ae.  Using package "ae" will produce better-looking postscript output for
on-screen viewing.