% Copyright (C) 2001, International Business Machines
% Corporation, Ted Ralphs and others. All Rights Reserved.

Having familiarized yourself with the overall design of \BB\ in
Chapter \ref{man-intro}, you are now ready to get started with using
\BB\ to develop applications of your own. The remainder of this manual
is contains the technical details you need to successfully undertake
this task. This chapter provides a description of how to get started
with \BB. This is basically the same information contained in the
README file that comes with the distribution.

Although \BB\ is inherently intended to be compiled and run on
multiple architectures and across distributed networks, for now we do not
use GNU's autoconf. The make files are designed to conveniently
allow builds for multiple architectures within a single directory
tree. This means that there may be a little hand configuring to do and you
might need to know a little about your computing environment in order
to make \BB\ compile. This should be limited to editing the make files
and providing some path names. You may also have to live with some
complaints from the compiler because of missing function prototypes,
etc.

\section{System Requirements}

Currently, to obtain and compile \BB, you need to be running some
version of Unix, preferably with the gcc/g++ compiler installed.
Before you try to compile \BB, you should first ensure that the
version of gcc/g++ you are using is at least 2.95.1 by typing {\tt gcc -v}
on the command line. If you have an earlier version, \BB\ may not
compile correctly -- ask your sysadmin for an upgrade. If you're lucky
enough to be your own sysadmin, then you're probably running Linux.
The default version that comes with some Linux distributions, such as
Redhat 6.2, is earlier than 2.95.1 so you should download and install a later
version. This may also involve upgrading some other packages on which
gcc depends.

There are a few auxiliary applications that you might also want to
have installed. If you want to use CVS to download the code and update
it automatically (highly recommended), then you should also install or
ask for CVS to be installed. If you are unsure of what CVS is, please
visit {\tt www.cvs.org}. If you choose not to use CVS, then
you can download the code as a tar file. The applications {\tt tkcvs} and 
{\tt tkdiff} provide a nice graphical interface to {\tt cvs}. Finally, if
you download {\tt doxygen} ({\tt www.doxygen.org}) and {\tt qt} 
({\tt www.trolltech.com}), you will be able to automatically generate very
nice documentation from the Bcp source code in an HTML format.

\section{Obtaining the Source Code}

\subsection{Using CVS}

To obtain the source code using CVS: 
\begin{itemize}
\item Set the {\tt CVSROOT} environment variable to be \\
{\tt :pserver:anonymous@oss.software.ibm.com:/usr/cvs/coin}
\item Issue {\tt cvs login} command with password {\tt anonymous} 
\item Issue {\tt cvs checkout MODULE} where {\tt MODULE} is one of
\begin{itemize}
\item {\tt Bcp}: branch, cut, and price framework,
\item {\tt Bcp-all}: BCP framework plus Osi and Vol
\item {\tt Mkc}: multiple knapsack with color constraints (application),
\item {\tt MaxCut}: Maximum weighted cut (application),
\item {\tt mkc7}: large sample mps file for Mkc, 
\item {\tt Vol}: volume algorithm, 
\item {\tt Cgl}: cut generator library,
\item {\tt Osi}: open solver interface, 
\item {\tt Dfo}: derivative free optimization,
\item {\tt COIN}: to get all modules,
\end{itemize}
\end{itemize}

If you are just starting with Bcp, get the module {\tt Bcp-all}. It will
automatically get the two sample applications ({\tt Mkc} and {\tt MaxCut}),
as well as the other necessary modules ({\tt Osi} and {\tt Vol}). Note that
the directory {\tt COIN/} will be installed as a subdirectory of
whatever directory you issue the CVS commands from. The simplest thing
to do is to issue the commands from your home directory and then enter
the subdirectory {\tt COIN/} to work with the source files.

\subsection{Downloading a {\tt tar} File}

The tar files can be obtained from {\tt www.coin-or.org}. Simply
download the latest files and unpack them in your home directory.
This will create a {\tt COIN/} subdirectory, if one does not already
exist, and place the source files in subdirectories of this directory.
These files follow the same naming scheme as the CVS modules.

Note that the files in the repository have {\tt .tar.gz} extension 
indicating that the archive file has been compressed using {\tt gzip}. On 
U*ix systems use gunzip to uncompress them first, on Windows Winzip can
uncompress and unpack the archive.

\section{Initial compilation and testing}

Since the whole project lives in the {\tt COIN} directory in the rest of this
section every path specified is relative to this directory.

\begin{itemize}
\item First, edit the file {\tt Makefiles/Makefile.location}. This file 
   contains definitions for which libraries you want to build and
   the location of libraries that might be needed (e.g., zlib to read
   compressed MPS files). Set the following variables as needed.
  \begin{itemize}
  \item {\tt CoinDir}: to the path to the {\tt COIN/} directory
  \item Uncomment lines that add support for different libraries 
    such as libz, and different LP solvers.
  \item Set the paths for the added libraries. 
  \end{itemize}
\item You should not need to make any modifications to 
  {\tt Bcp/Makefile}. 
\item Now, edit the application specific make file. This
  is {\tt Examples/MaxCut/Makefile.maxcut} for the MaxCut example. 
  Here are the variables that you can set:
  \begin{itemize}
  \item {\tt USER\_OPT}: options the compiler should use
    for compiling the user's code.
  \item {\tt COMM\_PROTOCOL}: which message-passing
    protocol to use. Currently the options are {\tt PVM} and {\tt NONE}
    (compile as a serial application). 
  \item {\tt USER\_SRC\_PATH}: a list of directories (besides {\tt TM}, 
    {\tt LP}, etc. -- see Section \ref{source-files} for the directory
    structure) the user has source codes in.
  \end{itemize}
\item In addition, you will see that there are some other
  variables to set once you have written your own application. These
  include paths to your source files and the names of your source files.
  We will discuss how to construct this make file in more detail later
  in the manual. 
\end{itemize}
        
\subsection{Compiling for serial execution}

As mentioned above, {\tt COMM\_PROTOCOL} must be set to {\tt NONE} in the user
application Makefile. 

\begin{itemize}
\item First you have to create the volume library (if you plan to use the
  volume algorithm as your LP engine):
  \begin{itemize}
  \item Change directory into {\tt Faa/Vol} and type {\tt make}
  \end{itemize}
\item Create the Osi library:
  \begin{itemize}
  \item Change directory into {\tt Osi} and type {\tt make}
  \end{itemize}
\item Type ``{\tt make}'' in the application directory. To
  start out, we recommend that you try to compile the {\tt MaxCut}
  application in the directory {\tt Examples/MaxCut}
  application module. Dependency files will be created in 
  {\tt Bcp/dep} and in 
  {\tt Examples/MaxCut/dep}. Object files will be placed in 
  {\tt Bcp/\$(ARCH)} and in 
  {\tt Examples/MaxCut/\$(ARCH)}, where \$(ARCH) is the platform you
  run on combined with the optimization level (e.g, Linux-g or AIX-4.3-O).
  This latter directory also contains the executable named {\tt bcps} (the
  ``s'' stands for being serial).
\item To test the sample program type {\tt \$(ARCH)/bcps sample.par} on the
  command line. The sample parameter file and sample data file are included 
  in the distribution.
\end{itemize}

\subsection{Compiling for distributed networks}

To use \BB\ on a network of computers fist a message passing library must be
installed. At the moment \BB\ has an interface to the 
{\em Parallel Virtual Machine} (PVM) software only (an MPI interface is
planned). The current version of PVM can be obtained at 
{\tt www.ccs.ornl.gov/pvm}. It should compile and install without 
any problem. The user will have to set a few environment variable (such as 
{\tt PVM\_ROOT}), but this is all explained clearly in the PVM
documentation. Note that there must be a link to the compiled executable
from the {\tt \$PVM\_ROOT/bin/\$PVM\_ARCH} directory in order for
parallel processes to be spawned correctly.

The compilation procedure for \BB\ and the location of the files are almost
identical to what's described in the previous subsection with the following
differences:

\begin{itemize}
\item Set {\tt COMM\_PROTOCOL} to {\tt PVM} in the user application Makefile.
\item The executable name will be {\tt bcpp}.
\item Make a symbolic link from the
  {\tt \$(PVM\_ROOT)/bin/\$(PVM\_ARCH)/} directory 
  to the executable.
  This is required by PVM unless you override the
  default directory in your PVM hostfile.
\item Start the PVM daemon by typing ``{\tt pvm}'' on the command line
  and then typing ``{\tt quit}''.
\item To test the sample program first start up the pvm daemon on each of the
  machines you plan to use in the computation (how to do this is also
  explained in the PVM documentation) and then start \BB\ by issuing the
  {\tt \$(ARCH)/bcpp sample.par} command. The sample parameter file and 
  sample data file are included in the distribution.
\end{itemize}

Now you should have successfully compile and execute the sample application.
Once you have accomplished this much, you are well on your way to having an
application of your own. 
