%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright 2001 by Object Craft P/L, Melbourne, Australia.
% LICENCE - see LICENCE file distributed with this software for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Installation\label{inst-guide}}

\section{Prerequisites\label{inst-pre}}

\begin{itemize}
\item Python 2.1 or later.

\item \LaTeX

Required if you want to build the PDF or PostScript documentation.

\item latex2html

Required if you want to build the HTML documentation.

\item Python 2.3 source

Required if you want to build the documentation.  The \texttt{mkhowto}
program and \LaTeX{} styles included in the distribution are used to
build the documentation.

\item \texttt{dia}

The diagrams in the documentation are edited and converted to EPS
using \texttt{dia} version 0.88 (later versions do not render fonts
correctly).
\end{itemize}

\section{Installing\label{inst-install}}

Unpack the package archive to extract the package source.  This will
create an \texttt{albatross-1.11} subdirectory.

\begin{verbatim}
tar xzf albatross-1.11.tar.gz
\end{verbatim}

Inside the \texttt{albatross-1.11} directory are a number of directories.

\begin{description}
\item{\texttt{albatross}}

Contains the Python code for the package.

\item{\texttt{doc}}

Contains the documentation source.

\item{\texttt{samples}}

Contains all of the sample programs discussed in this document.

\item{\texttt{session-server}}

Contains a simple session server which works with the Albatross
server-side session mixin classes.

\item{\texttt{test}}

Contains the unit tests.

\end{description}

The \module{Albatross} package uses the \module{distutils} package so
all you need to do is type the following command as root from the top
level directory:

\begin{verbatim}
python setup.py install
\end{verbatim}

If you have problems with this step, make sure that you contact the
package author so that the installation process can be made more
robust for other people.

If you already have a copy of Albatross installed and wish to test the
new release before installing it globally then you can install an
application private copy.  If your application is installed in
\texttt{/path/to/proj} then the following command will install a copy
of Albatross that is only visible to that application:

\begin{verbatim}
python setup.py install --install-lib /path/to/proj --install-scripts /path/to/proj
\end{verbatim}

If you wish to build the documentation you will almost certainly need
to change first line of the \texttt{Makefile} in the documentation
directory.  This points to where you have unpacked the Python
distribution so the \texttt{Makefile} can find the \texttt{mkhowto}
program.

\begin{verbatim}
cd doc
make pdf
make html
\end{verbatim}

\section{Testing\label{inst-test}}

There are a number of unit tests included in the distribution.  These
have been developed using the \module{unittest} package which is
standard in Python 2.1 and later.

Run the following commands to perform the unit tests:

\begin{verbatim}
cd test
make
\end{verbatim}

If you want to do more than run the unit tests, you can start to work
your way through the samples which are presented in this document.
