%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  installing.tex       LiDIA documentation
%%  
%%  This file contains the installing instructions for LiDIA
%%  
%%  Author: Thomas Papanikolaou
%%  

\newcommand{\FTPSERVER}{ftp.informatik.th-darmstadt.de}
\newcommand{\LIDIAMAIL}{lidia@cdc.informatik.th-darmstadt.de}
\newcommand{\LIDIABUGSMAIL}{lidia-bugs@cdc.informatik.th-darmstadt.de}


\chapter{\label{Install}Installing {\LiDIA}}

In this chapter we describe the steps of {\LiDIA}'s installation
procedure.


\section{Addresses of the \LiDIA-group}

After having picked up the source of \LiDIAVersion, 
for example by anonymous ftp via 
\begin{center}
\TT{\FTPSERVER},
\end{center}
please send us an email saying that  you have done so. This enables us to
inform you about bugs, bug fixes, new version, etc.

We would also appreciate all sorts of feedback,  bug reports  and
bug  fixes,  enhancements  etc. If you have successfully installed \LiDIA,
please tell us so.  If you had no success  at  all  and  this  is
likely  to be a  bug  in \LiDIA ~(including incomplete/incorrect 
documentation) please report. Note that we will  probably  not  be
able  to  reconstruct  a  bug without a detailed description. 

We assume that \TT{LiDIA.tgz} already resides in a directory which
we call \TT{UnpackDir} from now on, i.e., if the compressed
library \TT{LiDIA.tgz} resides in \TT{/usr/local} then
\TT{UnpackDir = /usr/local}, if it resides in
\TT{d:\MATH{\backslash}} then \TT{UnpackDir = d:\MATH{\backslash}}.
\index{email}

The format suggested in the file \TT{UnpackDir/LiDIA/bug\_reports.form} 
should  be  the  guide  for  all bug reports. Approved  bugs will be  included  
in  the  file  \TT{bugs} which  resides  also in the directory \TT{UnpackDir/LiDIA}.  
Please send your suggestions, enhancements, etc.~to the email address

\centerline{\TT{\LIDIAMAIL}}


Please, send bug reports (and fixes) to the email address

\centerline{\TT{\LIDIABUGSMAIL}}


\section{Unpacking}

Since {\LiDIA} is a rather large library we have to deliver it in
compressed form. {\LiDIA} is packed using the Unix  \footnote{Unix is
a trademark of AT\&T.}
\IndexSUBTT{Unix}{tar} command and GNU's 
\IndexSUBTT{GNU}{gzip}/\IndexSUBTT{GNU}{gunzip} utilities. 
The first command is included in every Unix/Linux distribution. 
The second one can be obtained via anonymous ftp from
\begin{center}
\TT{prep.ai.mit.edu}\label{FtpDirs}
\end{center}
OS/2 -- Versions of both programs can be obtained via anonymous ftp
from
\begin{center}
\TT{ftp-os2.nmsu.edu}
or
\TT{ftp.leo.org}
\end{center}
Moreover you'll need a \TT{make} utility for OS/2 systems such
as \TT{dmake 4.0} or GNU's \IndexSUBTT{GNU}{make}. These can be
obtained at the same sites as \TT{tar} and \TT{gzip}.

\subsection{Unpacking procedure}

If you have downloaded {\LiDIA} from our ftp-server \TT{\FTPSERVER}, 
then you have a binary compressed file with the name \TT{LiDIA.tgz}.
The suffix \TT{.tgz} means \TT{t}ar-ed and \TT{gz}ip-ed. 

\ATTENTION

\IT{Be sure that you have at least 35 MB of free space on your disk
before starting with the unpacking procedure. When using OS/2 this
space must be on an HPFS -- Partition, due to the long filenames that
are frequently used.}

\bigskip

As explained above, we assume that \TT{LiDIA.tgz} already resides 
in a directory which we call \TT{UnpackDir}.
Notice that you need write permission for this directory.

On UNIX: if \TT{LiDIA.tgz} resides in \TT{/usr/local} then
\begin{center}
\TT{UnpackDir = /usr/local}.
\end{center}

On OS/2: if \TT{LiDIA.tgz} resides in \TT{d:\MATH{\backslash}} then
\begin{center}
\TT{UnpackDir = d:\MATH{\backslash}}.
\end{center}

To unpack {\LiDIA}, please execute the following steps:

\begin{enumerate}
\item[U.0] [Change directory] Change to the directory
\TT{UnpackDir}, i.e., type in:
\begin{center}
\TT{cd /usr/local}
\end{center}
or type in:
\begin{center}
\TT{d:\MATH{\backslash}}
\end{center}

\item[U.1] [Uncompress] Uncompress \TT{LiDIA.tgz} using
GNU's \IndexSUBTT{GNU}{gunzip} command, i.e., type in
\begin{center}
\TT{gunzip LiDIA.tgz} or
\TT{gzip -d LiDIA.tgz}
\end{center}
This will produce the file \TT{LiDIA.tar} on 
\TT{/usr/local} or \TT{d:\MATH{\backslash}}.
\item[U.2] [Extract archive] Use the \IndexSUBTT{Unix}{tar} command
to extract the contents of the archive
\TT{LiDIA.tar}, i.e.,
type in:
\begin{center}
\TT{tar -xvf LiDIA.tar}
\end{center}
This command e\TT{x}tracts in \TT{v}erbose
mode the contents of the \TT{f}ile 
\TT{LiDIA.tar}, i.e., it creates a directory:
\begin{center}
\TT{/usr/local/LiDIA} or \TT{d:\MATH{\backslash}\MATH{\backslash}LiDIA}.
\end{center}
\item[U.3] [Compress] You will probably want to compress
the archive \TT{LiDIA.tar}. This is done by
\begin{center}
\TT{gzip LiDIA.tar}
\end{center}
This will produce the file \TT{LiDIA.tar.gz}.
\item[U.4] [End] The unpacking procedure is completed. 
\end{enumerate}

*NOTE*

If you do not have enough free space, you can replace the steps U.1 - U.3
by the (more complicated) command
\begin{center}
\TT{gunzip -c LiDIA.tgz | tar xvf -} or\\
\TT{gzip -d -c LiDIA.tgz | tar xvf -}
\end{center}


\section{Configuring {\LiDIA}}

\subsection{Creating a new configuration file}
\label{CreFile}

\index{configuration}
Before building {\LiDIA} on a Unix system you must create a
configuration file for your system:

\begin{itemize}
\item[C.0] [Change directory] Change to the directory
\TT{LiDIA}, i.e. type in:
\begin{center}
\TT{cd /usr/local/LiDIA}
\end{center}
\item[C.1] [Configure] Start the configuration, i.e.
type in:
\begin{center}
\TT{make configure}
\end{center}
This will create a \TT{CONFIG} and a \TT{config.h} file in the
directory \TT{LiDIA/config}. The file \TT{config.h} will be copied
to the directory \TT{LiDIA/include/LiDIA}. \TT{CONFIG} contains information
such as compiler name, paths and system characteristics. It is included 
by all {\LiDIA}'s makefiles. \TT{config.h} contains useful macros that can
be used by every {\LiDIA} program to achieve more machine independence. It is 
included by the root include file \TT{lidia.h}.
\item[C.2] [End] 
\end{itemize}

If you're running an OS/2 system, things are slightly simpler:
\begin{itemize}
\item[OS.0][Change directory] Change to the directory
\TT{LiDIA}, i.e. type in:
\begin{center}
\TT{d:\MATH{\backslash} \\ cd \MATH{\backslash}\MATH{\backslash}LiDIA}
\end{center}
\item[OS.1] [Configure] 
Type in:
\begin{center}
\TT{make os2}
\end{center}
This will replace the makefile for UNIX by a makefile for
OS/2. (By typing in \TT{make unix} you can go back to the
UNIX--makefile).
\item[OS.2] [End] 
\end{itemize}

*NOTE*

By editing \TT{CONFIG.os2}, you might be able to change the C/C++ Compiler
from EMX to something else like ``WATCOM C'' or ``IBM CSet''. Note
however that the assembler files for the c-kernel are written in the
special format which is used by GNU's assembler. So you also will have
to change the makefile 
in \TT{src\MATH{\backslash}c\_kernel\MATH{\backslash}ARITH\MATH{\backslash}Intel486}
in a way such that the (much faster !!) assembler version is not (!) used.
Moreover you probably will get some problems with include--files that
don't exist on a native OS/2 compiler.


\subsection{Specifying the compiler used by the configure script}
\index{Configuration ! specify compiler}

The 'configure' script chooses the \TT{GNU g++} compiler, if it
can find it. If you have installed the \TT{GNU g++} and ,i.e., 
the \TT{AT\&T CC} compiler, you can force `configure` to use the
\TT{CC} compiler.

\begin{itemize}
 \item Change to the directory config:
       \begin{center}
                cd config
        \end{center}

  \item Set the environment variables \TT{CC} and \TT{CXX}, i.e. in \TT{tcsh}:
        \begin{center}
          \begin{verbatim}
                setenv CC  cc       (the C-Compiler)
                setenv CXX CC       (the C++-Compiler)
          \end{verbatim}
        \end{center}

   \item Remove config.cache if necessary:
         \begin{center}
                rm config.cache
         \end{center}

   \item Start the 'configure' script:
         \begin{center}
                ./configure
         \end{center}

   \item If you have chosen \TT{gmp} as the integer arithemtic,
         change to the directory \TT{../src} and configure the \TT{gmp}:
         \begin{center}
           \begin{verbatim}
                cd ../src
                make configure
           \end{verbatim}
         \end{center}
\end{itemize}



\subsection{Configuration variables}\label{confvar}
\label{ConfVar}
\index{configuration ! variable}

We will now describe the variables contained in the configuration
file created in section \ref{CreFile}.

\begin{itemize}
\item LIDIA\_HOME\\
This is the location of {\LiDIA} after the unpacking
procedure. In our example this would be 
\TT{/usr/local/LiDIA} or \TT{d:\MATH{\backslash}LiDIA}
\item LIDIA\_INSTALL\_DIR\\
This is the directory where the library and include 
files of {\LiDIA} are to be installed in. We
recommend that you use a standard directory which is
searched by default by the linker, i.e., \TT{/usr/local}.
For OS/2 systems using emx we recommend to either use a
standard directory like \TT{d:\MATH{\backslash}emx} or
-- better in our opinion -- to update the paths in \TT{config.sys}:\\
Add \TT{d://LiDIA/include} to \TT{C\_INCLUDE\_PATH} and
\TT{CPLUS\_INCLUDE\_PATH} and add 
\TT{d://LiDIA/lib/LiDIA/os2/compiler\_name} to \TT{LIBRARY\_PATH}.
\item LIDIA\_ARCH\\
This is the destination architecture of {\LiDIA}. To
allow the installation of {\LiDIA} on different
machines in a single directory (i.e. \TT{/usr/local}),
the installation procedure copies {\LiDIA}'s library into the directory 
\begin{center}
\TT{LIDIA\_INSTALL\_DIR/lib/LiDIA/LIDIA\_ARCH/compiler\_name}
\end{center}
For example, for the architecture \TT{sparc7} a directory
\begin{center}
\TT{/usr/local/lib/LiDIA/sparc7/compiler\_name} 
\end{center}
would be created and {\LiDIA}'s sparc7-compiled library would 
be put into this directory.
\item TARGET\\
For known architectures (or in other words, architectures for which
we have assembly support) TARGET is equal to LIDIA\_ARCH. In all
other cases, it is set to C, that is {\LiDIA} will compile the C version
of the kernel.
\item BIGINT\\
This is used to decide which integer arithmetic is to be compiled with
{\LiDIA}. At the moment we support three possibilities: \TT{gmp}, \TT{libI},
and \TT{lip}. We suggest that you use the \TT{gmp} with the GNU g++
compiler and \TT{libI} otherwise. Use \TT{lip}, if you have chosen
\TT{libI} during the configuration process and TARGET has been set
to c by configure. In this case, no \TT{libI} assembler code is
available for your machine.
\item GMM\\
{\LiDIA}'s general memory manager can be also replaced by any other one
supporting its interface. At the moment we support three different
memory managers: \TT{malloc}, \TT{dentzer} and \TT{boehm}. While the first
two are non-collecting, Boehm's manager is garbage-collecting. Please read
the README file in \TT{LiDIA/src/kernel/memory/boehm} for more information.
ATTENTION: Boehm's GC manager is not completely incorparated into the
build procedure of \LiDIA. You may have to edit the makefile for non-Unix
architectures. Again, follow the instructions in the README file.
\item CC\\
This variable holds the C compiler. This could be one of
SunOS \IndexTT{cc}, GNUS's \IndexSUBTT{GNU}{gcc} or any 
\index{ANSI} ANSI C compiler. \index{compiler} 
(If you want to use the \TT{gcc} compiler with the AT\&T \TT{CC}
compiler please set the environment variable \TT{ccC},
for example by typing in your \TT{csh}
\TT{setenv ccC /usr/local/bin/gcc}.)
\item CXX\\
This variable holds the {\CPP} compiler. This could be one of
AT\&T's \IndexSUBTT{AT\&T}{CC}, GNUS's \IndexSUBTT{GNU}{g++},
Sun's SunPro \IndexSUBTT{SunPro}{CC}, or any ANSI \IndexSUB{ANSI}{C++ compiler}.
\item CFLAGS\\
These are the flags for the C compiler (see CC).
\item CXXFLAGS\\
These are the flags for the {\CPP} compiler (see CXX).
\item LDFLAGS\\
These are the flags for the loader.
\item AS\\
This variable holds the assembler. Note {\LiDIA}'s assembler
must understand the -P (preprocessor) option (i.e. use
\TT{/bin/as} or \TT{/usr/bin/as})
\item ASPPFLAGS\\
This variable is set to -DHAVE\_ELF if your system runs ELF-format.
This variable is only necessary, if you use \TT{libI} in the kernel
(see BIGINT). 
\item RANLIB\\
This is the Unix \TT{ranlib} command. It does not exist
on all operating systems (e.g non-BSD \index{BSD}); in this
case it should be defined to \TT{echo}.
\item KERNEL\_FLAGS\\
This variable allows additional flags for the C kernel
of {\LiDIA} that are not needed on the higher levels. 
\item HAS\_RANDOM\\
This variable is set to \TT{random.o} if no random number
function is defined on your system.
\end{itemize}

For an example of a configuration file, see 
\begin{center}
\TT{UnpackDir/LiDIA/config/CONFIG}.
\end{center}

\subsection{Editing a configuration file\label{LidConf}}

Although the configuration variables are chosen carefully, you probably
want to edit your own configuration file, for example
\begin{itemize}
\item to replace the C, {\CPP} compiler: {\LiDIA}'s
configuration script preferably uses GNU's
\TT{g++} if it exists and then AT\&T's \TT{CC}.
\item to change the compilation flags: {\LiDIA}'s
script defines only standard optimization (-O2).
\end{itemize}

\begin{itemize}
\item[E.0] [Save] Copy the existing configuration file
to a safe place. i.e. type in
\begin{center}
\TT{cp CONFIG CONFIG.FCS}
\end{center}
\item[E.1] [Edit] Edit with your favorite editor the
configuration file for your architecture
according to section \ref{ConfVar}, i.e.
type in
\begin{center}
\TT{vi CONFIG}
\end{center}
\item[E.2] [End]
\end{itemize}

\section{Compiling {\LiDIA}}
\label{LidMake}

{\LiDIA} is built using the \index{Unix} Unix command make.
For OS/2 you can use GNUmake or DMake 4.0, which can be obtained from
the same places where you have obtained gzip and tar from (see page
\pageref{FtpDirs}).

\begin{itemize}
\item[M.0] [Change directory] Change to the directory
\TT{UnpackDir/LiDIA}, i.e. type in:
\begin{center}
\TT{cd /usr/local/LiDIA}
\end{center}
On OS/2 systems use
\begin{center}
\TT{d:\MATH{\backslash} \\ cd \MATH{\backslash}LiDIA}
\end{center}
instead.
\item[M.1] [Configure] If you have not already configured
{\LiDIA} (see section \ref{LidConf}) run the \TT{make} 
command on the target \TT{configure}, i.e.
type in:
\begin{center}
\TT{make configure}
\end{center}
\index{make configure}
This will run the steps E.0 - E.2.
On OS/2 systems type in
\begin{center}
\TT{del config\MATH{\backslash}CONFIG} \\ 
\TT{move config\MATH{\backslash}CONFIG.os2 config\MATH{\backslash}CONFIG}
\end{center}
instead.
\item[M.2] [Make] Run the \TT{make} command, i.e.
type in:
\begin{center}
\TT{make}\ \  or\ \  \TT{make appl}
\end{center}
\TT{make}  leads to the compilation of the library
sources, while \TT{make appl} compiles these sources
and moreover the example programs which have the form 
\TT{\ldots\_appl.c}. If the library is already
compiled and you use \TT{make appl}, only the example
programs will be compiled. \index{make appl}
\item[M.3] [End]
\end{itemize}

The architectures for which we give \TT{libI} assembly support are at the moment

\begin{center}
\TT{sparc7, sparc8, mips, i386, i486, i586}
\end{center}

Moreover, {\LiDIA} has been succesfully compiled on 
\begin{center}
\TT{alpha, hp9000/7xx, rs6k, sparc, cray c90} and \TT{OS/2} systems
\end{center}

\section{Installing {\LiDIA}}
\label{LidInst}

After the compilation is done type

\begin{center}
\TT{make install}
\end{center} \index{make install} 

to install {\LiDIA}'s library in 
\begin{center}
LIDIA\_INSTALL\_DIR/lib/LiDIA/LIDIA\_ARCH/compiler\_name/libLiDIA.a
\end{center}
and {\LiDIA}'s include directory in 
LIDIA\_INSTALL\_DIR/include/LIDIA.

On OS/2 systems eventually change some environment variables
appropriately, see  the description of the configuration variable
\TT{LIDIA\_INSTALL\_DIR}.

\bigskip
This completes the installation procedure.

