\section{System Requirements}
\label{requirements}

BALL has been tested on all major platforms including recent Linux distributions, MacOS X, and Windows.


\subsection{External Software and Libraries}

BALL needs {\tt flex} and {\tt bison} for automatically generating parsers
for various purposes. These utilities are standard software and should be
installed on every contemporary UN*X machine. The newest versions are
downloadable from \URL{http://www.gnu.org/software/}.

The usage of GNU {\tt make} is recommended, although BALL will also build with
other versions of {\tt make}. It is available from \URL{ftp://ftp.gnu.org/gnu/}
and easy to install.

The following packages can be found in our contrib package. You only need to install
them manually when not using the autobuild script.

BALL uses the boost library~\cite{boost} for various classes and internal tasks. A version greater 
or equal 1.35.0 is required.


The compilation of the visualization component VIEW also requires the Qt 
library (at least version 4.3), which is available from
\URL{http://qt.nokia.com/products/}.

If Qt was not installed in one of the standard library paths or the
Qt header files were not installed in one of the compiler's default
include directories, use \mbox{"\option{--with-qt-libs}{\tt{}=DIR}"} and
\mbox{"\option{--with-qt-incl}{\tt{}=DIR}"} as options to configure (see
Section \ref{section:building-ball}) to specify the paths Qt was installed
to.\index{Qt} {\tt configure} will also honor the {\tt QTDIR} environment variable.

Qt also requires OpenGL~\cite{OpenGL}. On platforms that do not provide OpenGL,
Mesa~\cite{Mesa} can be used. Mesa is a 3-D graphics library with an API which
is very similar to that of OpenGL. It can be obtained from 
\URL{http://www.mesa3d.org}.
\index{Mesa}

BALL uses GLEW, the OpenGL Extension Wrangler Library for access to the OpenGL
extensions. If the GLEW library is not installed, BALLView will still work, but
the advanced OpenGL features like volume rendering, vertex buffers and so on
will not work. GLEW is freely available from \URL{http://glew.sourceforge.net}.
\index{GLEW}

If your machine has a graphics accelerator from Intel, ATI-AMD or NVidia, you
can use the vendor-provided OpenGL drivers. The respective download locations
are \URL{http://www.intel.com/support/graphics} (Intel),
\URL{http://ati.amd.com/support/driver.html} (ATI-AMD), and
\URL{http://www.nvidia.com/content/drivers} (NVidia).

To use the Python extensions of BALL (Python is an object oriented scripting
language), \index{Python} you will also need Python (version 2.5 or above) 
installed (\URL{http://www.python.org}) and a recent version of SIP (version 
4.6.0 or above, available at \URL{http://www.riverbankcomputing.co.uk/sip/}).
SIP~\cite{SIP} \index{SIP} is a tool for generating Python bindings for \CPP 
class libraries.

Additionally you might need the \Index{FFTW} \cite{FFTW} package for fast 
Fourier transformations (version 3.1.2), available from 
\URL{http://www.fftw.org/}.

Please make sure that the required external \CPP libraries (\ie Qt and SIP)
have been compiled with the same compiler (and compiler version!) as the BALL
libraries. Otherwise you will most likely see a plethora of strange error
messages, either while linking applications or at runtime.


\section{Installation}
\label{section:building-ball}

We provide two different ways to build the libraries and applications:

The first one is the \file{autobuild} script. The build process is started by 
simply typing

\begin{lstlisting}{}
  ./autobuild
\end{lstlisting}

\noindent in the directory \directory{BALL/source}.  
This procedure is especially suited for inexperienced users, since it 
automatically downloads a contrib source package from our website. This 
package contains almost all dependencies and prevents any clashes with already 
installed libraries, by compiling and installing them in a sub folder in the 
BALL directory. Afterwards, the BALL library is configured, build and linked 
against the downloaded libraries. We recommend to use the {\tt autobuild} 
script for installations which should run out of the box on most platforms. 
This kind of installation will include all of
BALL and \mbox{BALLView's} features. If this is not desired or you want to 
configure the library with different settings, please proceed like stated below:

As an alternative BALL can be configured with a classical configure/make
run. If all requirements stated in Section \ref{requirements} are met, BALL is
built by issuing the following commands in the directory 
\directory{BALL/source}:

\begin{lstlisting}{}
  ./configure
  make
  make install
\end{lstlisting}

The following sections give further details on the configuration of the 
library, on the library files created, how to test the library, and how to 
build BALL applications.

\subsection{Configuring BALL}
\index{configure!usage}

"{\tt configure}" tries to gather as much information on your system as 
possible and then creates the necessary configuration files (\file{config.h},
\file{config.mak}, \file{common.mak}, and \file{Makefile}).
The configuration of BALL may be adapted to your needs and to your system
configuration from the command line by adding one or more of the options from
Table \ref{table:options}.
An overview of these options can also be obtained by executing "{\tt configure
--help}"

% \begin{center}
\begin{longtable}{lp{7cm}}\hline
  \\\vspace{3mm}
  \option{--x-includes}{\tt{}=DIR}&        X include files are in DIR
                                           \\\vspace{3mm}

  \option{--x-libraries}{\tt{}=DIR}&       X library files are in
                                           DIR\\\vspace{3mm}

  \option{--disable-optimization}&         do not optimize the library for
                                           speed\\\vspace{3mm}

  \option{--enable-debuginfo}&             create debug
                                           information\\\vspace{3mm}

  \option{--enable-gsl}&                   enable the build of BALL with
                                           support for GSL (GNU Scientific
                                           Library)\\\vspace{3mm}

  \option{--disable-VIEW}&                 disable the compilation of the
                                           visualization classes\\\vspace{3mm}

  \option{--enable-64}&                    build 64 bit objects (if allowed
                                           by the compiler)\\\vspace{3mm}

  \option{--with-compiler}{\tt{}=CXX}&     use CXX to compile BALL\\\vspace{3mm}

  \option{--with-cxxflags}{\tt{}=FLAGS}&   add FLAGS to the \CPP compiler flags
                                           (commas are converted to blanks)
                                           \\\vspace{3mm}

  \option{--with-ldflags}{\tt{}=FLAGS}&    add FLAGS to the linker flags
                                           (commas are converted to blanks)
                                           \\\vspace{3mm}

  \option{--with-arflags}{\tt{}=FLAGS}&    add FLAGS to the flags for the
                                           creation of the static libraries
                                           \\\vspace{3mm}

  \option{--with-dynarflags}{\tt{}=FLAGS}& add FLAGS to the flags for the
                                           creation of the shared libraries
                                           \\\vspace{3mm}

  \option{--with-qt}{\tt{}=QTDIR}&         Qt installation is in QTDIR. This
                                           option is equivalent to setting the
                                           {\tt QTDIR} environment variable.
                                           Using this option should be
                                           preferred over the next two options,
                                           which are only necessary if the Qt
                                           installation has non-standard paths
                                           for libraries and headers.\\
                                           \vspace{3mm}

  \option{--with-qt-incl}{\tt{}=DIR}&      Qt header files are in DIR\\
                                           \vspace{3mm}

  \option{--with-qt-libs}{\tt{}=DIR}&      Qt libraries are in DIR\\\vspace{3mm}

  \option{--with-moc}{\tt{}=MOC}&          The absolute path to the Qt meta
                                           object compiler (moc, typically
                                           found in {\tt\$QTDIR/bin/moc})
                                           \\\vspace{3mm}

  \option{--with-uic}{\tt{}=UIC}&          The absolute path to the Qt user
                                           interface compiler (uic, typically
                                           found in {\tt\$QTDIR/bin/uic})\\
                                           \vspace{3mm}

  \option{--with-opengl-incl}{\tt{}=DIR}&  OpenGL/Mesa header files are in
                                           DIR/GL\\\vspace{3mm}

  \option{--with-opengl-libs}{\tt{}=DIR}&  OpenGL/Mesa libraries are in
                                           DIR/GL\\\vspace{3mm}

  \option{--with-mesa}&                    use MESA instead of OpenGL\\

  \option{--with-glew-incl}{\tt{}=DIR}&    GLEW header files are in DIR/GL\\
                                           \vspace{3mm}

  \option{--with-glew-libs}{\tt{}=DIR}&    GLEW libraries are in DIR\\
                                           \vspace{3mm}

  \option{--without-libxnet}&              use \Index{libsocket}/\Index{libnsl}
                                           for linking rather than 
                                           \Index{libxnet} (under Solaris)
                                           \\\vspace{3mm}

  \option{--with-python=EXE}&              Enable Python support using the
                                           Python executable in EXE. If no
                                           executable is specified
                                           ({\tt --with-python} only),
                                           {\tt configure} looks for an
                                           installed python in the current
                                           PATH. Typically, from the executable
                                           {\tt configure} can figure out where
                                           the headers and the library are
                                           hidden, so that the following two
                                           options are usually not required.\\
                                           \vspace{3mm}
  
  \option{--with-python-incl=DIR}&         Python includes (Python.h) is in
                                           DIR\\\vspace{3mm}

  \option{--with-python-libs=DIR}&         Python library (libpython*.a) is
                                           in DIR\\\vspace{3mm}

  \option{--with-python-ldopts=X}&         Use additional options X when
                                           linking with the Python library
                                           \\\vspace{3mm}

  \option{--with-sip-lib}{\tt{}=DIR}&      the SIP library resides in DIR
                                           \\\vspace{3mm}

  \option{--with-sip-incl}{\tt{}=DIR}&     the SIP header file resides in DIR
                                           \\\vspace{3mm}

  \option{--with-sip}{\tt{}=DIR}&          the SIP executable resides in DIR
                                           \\\vspace{3mm}

  \option{--without-xdr}&                  no RPC/XDR headers available - do
                                           not build portable binary
                                           persistence support\\\vspace{3mm}

  \option{--with-fftw-lib}{\tt{}=DIR}&     Enable support for the FFTW library
                                           and search for the library in
                                           {\tt DIR}.\\\vspace{3mm}

  \option{--with-fftw-incl}{\tt{}=DIR}&    Header files for FFTW are in
                                           {\tt DIR}. Required for non-standard
                                           include paths only.\\\vspace{3mm}

  \option{--help}&                         display help information\\
\hline
\caption{Options for {\tt configure}}
\label{table:options}
\end{longtable}

For example, to compile BALL without the visualization component, specify 

\begin{lstlisting}{}
  configure --disable-VIEW
\end{lstlisting}

To compile the visualization classes using the Qt installation in
/opt/misc/qt, specify the path to the Qt directory as follows:

\begin{lstlisting}{}
  configure --with-qt=/opt/misc/qt
\end{lstlisting}

If the headers or libraries are installed in non-standard directories, you can
also specify them separately:

\begin{lstlisting}{}
  configure --with-qt-libs=/opt/lib 
		--with-qt-incl=/opt/qt/include
\end{lstlisting}

If \Index{Mesa} should be used (when compiling under Linux), the correct 
options might look like this:

\begin{lstlisting}{}	
  configure --with-qt-libs=/opt/qt/lib 
		--with-qt-incl=/opt/qt/include
    --with-opengl-libs=/opt/mesa/lib 
		--with-opengl-incl=/opt/mesa/include
\end{lstlisting}

\subsection{Building the Libraries}

After the successful termination of configure, issuing "make" will build the
shared libraries. Two different libraries will be built:

\begin{center}
	\begin{tabular}{ll}
  	\file{libBALL.so}&     the main BALL library\\
  	\file{libVIEW.so}&     the visualization classes\\
	\end{tabular}
\end{center}

The latter library is not built if "\option{--disable-VIEW}" is specified or 
configure cannot find X libraries, OpenGL libraries, or Qt libraries (and the 
respective headers).

It is also possible (although not recommended) to build the corresponding 
static libraries \file{libBALL.a} and \file{libVIEW.a} using "{\tt make
staticlibs}". Please note that statically linked binaries are huge.

\subsection{Installing the Libraries}

After compiling the libraries, they are installed in {\tt BALL/lib/\${BINFMT}/}
when calling "{\tt make install}" where {\tt \${BINFMT}} is the binary format
as determined by {\tt configure}.  Currently, the only way to install the
libraries somewhere else is by moving them by hand to the desired destination.
Wherever you install the shared libraries, please make sure to include their
location in the \ttindex{LD\_LIBRARY\_PATH} environment variable.

If you are using \Index{csh}, \Index{tcsh}, or similar shells, use the command

\begin{lstlisting}{}
   setenv LD_LIBRARY_PATH DIR
\end{lstlisting}

\noindent to set the library path. If you are using \Index{sh}, \Index{bash},
or related shells, try

\begin{lstlisting}{}   
   LD_LIBRARY_PATH=DIR
   export LD_LIBRARY_PATH
\end{lstlisting}

If you installed the shared libraries in a directory that the dynamic linker
\ttindex{ld} searches by default, it is not necessary to set {\tt
LD\_LIBRARY\_PATH}.
