%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  use.tex       LiDIA documentation
%%
%%  This file contains comments on the design of LiDIA
%%  
%%  Copyright   (c)   1994   by   Lehrstuhl Prof. Dr. J. Buchmann
%%
%%  Authors: Thomas Papanikolaou
%%           VM, changed the example program.
%%

\chapter{How to use the \LiDIA\  library}

Once \LiDIA\  is installed properly (see section \ref{Install}, page 
\pageref{Install}) its library is used as any other {\CPP} library. We 
illustrate the use of the \LiDIA\ library by an example. The following 
little {\CPP} program reads a number from the standard input and prints 
its factorization  on the standard output.

\begin{quote}

\begin{verbatim}
 #include <LiDIA/rational_factorization.h>

 int main()
 {
   rational_factorization f;
   bigint n;
   
   cout << "\n Please enter a number: "; 
   cin >> n;
   
   f.assign(n);
   f.factor();
   
   if (f.is_prime_factorization())
     cout<<"\n Prime Factorization: " << f << "\n";
   else 
     cout<<"\n Factorization: "<< f << "\n";
   return 0;
 }

\end{verbatim}
\end{quote}

It uses the \LiDIA\  factorization class (compare the description 
of \BF{rational\_factorization}).
This is done by including \TT{\LT LiDIA/rational\_factorization.h\GT}. 
In general, the \LiDIA\  include file for the data type \TT{xxx} is
\TT{\LT LiDIA/xxx.h\GT}. Since all data types and algorithms of 
\LiDIA\  reside in \Index{libLiDIA.a} this is the only library that 
has to be linked. The program \TT{fact.c} can be compiled
and linked using the following command (we assume that you have
installed \LiDIA\  in \TT{/usr/local} and that you have compiled
\LiDIA\  on a \TT{sparc8} machine using \TT{g++}):

\TT{g++ -O fact.c -I/usr/local/include -L/usr/local/lib/LiDIA/sparc8-sun-solaris2.5.1/g++ -o fact -lLiDIA -lm}

On an OS/2 system the program can be compiled and linked using the
following command (we assume that you have installed \LiDIA\  in
\TT{d:\MATH{\backslash}LiDIA} and that you have compiled \LiDIA\  using 
\TT{EMX}):

\TT{gcc -O2 fact.C -Id:/LiDIA/include -Ld:/LiDIA/lib/LiDIA/os2/g++ -lLiDIA -lbsd -lstdcpp}

(If you updated your environment variables as described in chapter
\ref{confvar} in the description of \TT{LIDIA\_INSTALL\_DIR} you may
also use the following simpler command: 

\TT{gcc -O2 fact.C -lLiDIA -lbsd -lstdcpp}

%If you installed LiDIA to some default path you still have to specify
%the path to the library, i.e.~you need the \TT{-L} -- option, but
%you may leave out the \TT{-I} -- option.)

\bigskip

Here is a sample running session:

\begin{quote}
\TT{host\% fact <RET>}\\[2ex]
\TT{Please enter an integer   18446744073709551617 <RET>}\\[2ex]
\TT{Prime Factorization:   [(274177,1)(67280421310721,1)]}
\end{quote}


\bigskip

Some programs need information which is stored in the files
\begin{center}       
                  LIDIA\_PRIMES and GF2n.database.       
\end{center}

The built-in directory, where programs are looking for
those files is
\begin{center}
                  LIDIA\_INSTALL\_DIR/lib/LiDIA,
\end{center}

which is the correct path, if you have installed the
library via "make install". If you have not installed the 
library, you must set the environment variables, i.e. 
using tcsh,
\begin{center}
 \begin{verbatim}
     setenv LIDIA_PRIMES_NAME LIDIA_HOME_DIR/lib/LIDIA_PRIMES
     setenv LIDIA_GF2N        LIDIA_HOME_DIR/lib/GF2n.database
 \end{verbatim}
\end{center}
\index{LIDIA\_PRIMES\_NAME}
\index{LIDIA\_GF2N}
 

