%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  trouble.tex       LiDIA documentation
%%
%%         This file contains the documentation of the 
%%               template instantiation procedure
%%         and gives compiler specific hints.
%%  
%%  Copyright   (c)   1997   by  LiDIA-Group 
%%
%%  Authors: Markus Maurer, Stefan Neis, Patrick Theobald
%%


\chapter{Template instantiation and trouble shooting}


\section{Template instantiation}

\markright{\BF{template instantiation}}
\label{template_introduction}
\label{template_introduction2}
\label{template_instantiation}

\subsection{Using GNU's g++}

The \TT{GNU g++} compiler offers three methods for creating instantiations
for template classes. In \LiDIA\ we only support the method of 
explicit instantiation of all the template classes you use, so far. 
The creation of a new instantiation for \LiDIA\ template classes is
very simple. To instantiate TEMPLATE\_TYPE \MATH{<} type \MATH{>} 
you have to create an entry of the form 
\begin{verbatim}
L_type.o:       instant.c
        $(CXX) -c instant.c $(CXXFLAGS) -I$(LIDIA_INC) -o L_type.o
        -DTYPE=type -DTEMPLATE_TYPE -include=/home/LiDIA/type.h
\end{verbatim}

in the file \TT{makefile.inst} of the appropriate template directory.
The parameter -DTYPE (i.e. USER\_TYPE) determines the name of the
argument type. 
\TT{-include} has to contain the path to the header file 
corresponding to the argument type.\\
The define \TT{-DTEMPLATE\_TYPE} determines the chosen 
template type and so the requirements to the argument type. For
further informations refer to the file \TT{makefile.inst} of the
appropriated template directory.

An example is the instantiation of the \LiDIA\ template class
\TT{lidia\_vector} for type \TT{bigint}. The file 
\TT{LIDIA-HOME/src/templates/vector/makefile.inst} contains an
entry of the form
\begin{verbatim}
Lv_bigint.o:    instant.c
        $(CXX) -c instant.c $(CXXFLAGS) -I$(LIDIA_INC) -o Lv_bigint.o 
        -DTYPE=bigint -DLIDIA_VECTOR -include $(LIDIA_INC)/LiDIA/bigint.h
\end{verbatim}
and furthermore, the name \TT{Lv\_bigint.o} is added to the list
\TT{CXXOBJ} at the end of \TT{makefile.inst}. When you call
\TT{make g++} in that directory, the corresponding \TT{makefile}
includes \TT{makefile.inst} and compiles all instantiation files
listed in \TT{CXXOBJ}, especially \TT{Lv\_bigint.o}. At the end,
all object files must be put in the library.


\subsection{Using AT\&T CC, HP CC, MIPS CC}

The \TT{AT\&T CC}, \TT{cfront-3.01}, compiler doesn't need special information
for creating new template instances. If during linking the linker
finds some templates, that must be instantiated, the compiler knows the header
file of the template class and searches for the corresponding source
file, which must have the same basename as the header file. Then it
instantiates the template class automatically. Only template 
specializations must seperately be compiled and put into the library.
This is done by the \LiDIA\ \TT{makefiles}.

There is one problem with \TT{cfront-3.01}. 
Because of an error in the CC compiler, give the full name
\begin{center}
LIDIA\_INSTALL\_DIR/lib/LiDIA/LIDIA\_ARCH/compiler\_name/libLiDIA.a 
\end{center}
instead of \mbox{-lLiDIA} when linking your programs. If you use 
\mbox{-lLiDIA} the instantiation mechanism of CC fails.


%\subsection{Using SunPro}

%The mechanism for creating instantiations with the \TT{SunPro} compiler is
%very similiar to the method used by the \TT{AT\&T CC} compiler. The only
%visible difference for the user is the file
%\$(LIDIA\_HOME)/lib/Templates.DB/template.opt. This file contains the
%descriptions for "unusual" template classes e.g. spezializations. For
%further informations about the syntax and the semantics of the entries
%please refer to the SunPro User's Guide.



\subsection{Using GNU g++ with repo patch}

You might want to use \TT{gcc} with the repo--patch from \TT{ftp.cygnus.com}, since
this patch automatically instantiates templates at link time, thus allowing
to remove the template instantiations from the library. (On SUN's, the
\LiDIA --library shrinks from ca.~7 MB to ca.~4 MB). However to apply this
patched \TT{gcc} you must be sure, that you do not need the class
\BF{lidia\_vector}, since the patch does not support virtual base classes.
In case you do not need this class and if you want to use the repo-patch do
the following to compile \LiDIA:
\begin{itemize}
\item Run \TT{make configure} (as usual).
\item Edit \TT{\$(LIDIA\_HOME)/config/CONFIG}: set \TT{CXXNAME} to \TT{CC}
instead of \TT{c++} and add \TT{-frepo -DLIDIA\_INCLUDE\_C} to the
\TT{CXXFLAGS}.
\item Remove \TT{\$(LIDIA\_HOME)/include/LiDIA/lidia\_vector.h}.
        (Just to make sure, that nobody can use \BF{lidia\_vector}. It
        might compile, but it will definitly not work, so better remove it.)
\item Edit \TT{\$(LIDIA\_HOME)/include/LiDIA/math\_vector.h},\TT{sort\_vector.h}, and
  \TT{file\_vector.h}: Remove the keyword
virtual from the declaration of these classes, e.g.~
replace \TT{class math\_vector: public virtual base\_vector\TEMPL{T}} by
\TT{class math\_vector : public base\_vector\TEMPL{T}}.
\item Rename the files in \TT{\$(LIDIA\_HOME)/src/simple\_classes/lattice}
to give them the ending \TT{.cc} instead of \TT{.c} (Yes, this is really
necessary, sorry about that!).
\item Go to the directory \TT{\$(LIDIA\_HOME)/src/simple\_classes/lattice}
and link all the \TT{.o}--files together, e.g.~do \TT{gcc L*.o}; this will
produce a lot of error messages which can be safely ignored and
instantiate all the stuff needed for the lattice--classes (doing this
automatically at link time mysteriously fails). Then rerun \TT{make} to
get the new \TT{.o}--files into the library. Finally do a \TT{make ranlib}.
\end{itemize}

\BF{ATTENTION}\\
\IT{Don't even try to build the sample application files delivered with
\LiDIA. \TT{gcc} with \TT{repo-patch} requires its programs to be first
compiled (with \TT{-frepo}) and then linked in an extra step. This is not
yet supported by our makefiles.}

If you use the repo--Version of \LiDIA\ for compiling your applications be
sure to always add the switch \TT{-DLIDIA\_INCLUDE\_C} when compiling. This
switch is needed to automatically include the parts of our sources that
might be needed at link time for instantiating templates. (We would do this
automatically, but we did not find any way to detect at compile time
whether or not we are using the repo-patch.)


\section{Problems when compiling \LiDIA}

\subsection{SGI, Irix 5.2}

On \TT{Irix 5.2} we had the problem, that the object files become very
large, which results in a very big library. Because the \TT{ar}
command copies the library several times, when inserting new object
files in the library, the \TT{tmp} directory is often too small
and that process stops with an error message.
Give a further option to the \TT{ar} command, to force the \TT{ar}
to copy the library to the local directory, i.e. set \TT{AR} to
\TT{ar rul} in the \LiDIA\ \TT{config/CONFIG} file.


\subsection{HP UX, HP CC}

On \TT{HP unix}, using the \TT{HP CC} compiler, we had the problem, that the
instantiation mechanism failed. The compiler produced a necessary 
instantiation of an object, but nevertheless it terminated with the
error message, that it could not resolve these templates. We used
the option \TT{+T} to run the compiler in translator mode and this
solved the described problem.












