source: trunk/docs/app-install.tex @ 383

% -----------------------------------------------------------------------
% app-install.tex: Section about how to download, install and run
%                  Duchamp. 
% -----------------------------------------------------------------------
% Copyright (C) 2006, Matthew Whiting, ATNF
%
% This program is free software; you can redistribute it and/or modify it
% under the terms of the GNU General Public License as published by the
% Free Software Foundation; either version 2 of the License, or (at your
% option) any later version.
%
% Duchamp is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
% for more details.
%
% You should have received a copy of the GNU General Public License
% along with Duchamp; if not, write to the Free Software Foundation,
% Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
%
% Correspondence concerning Duchamp may be directed to:
%    Internet email: Matthew.Whiting [at] atnf.csiro.au
%    Postal address: Dr. Matthew Whiting
%                    Australia Telescope National Facility, CSIRO
%                    PO Box 76
%                    Epping NSW 1710
%                    AUSTRALIA
% -----------------------------------------------------------------------
\secA{Obtaining and installing \duchamp}
\label{app-install}

\secB{Installing}
The \duchamp web page can be found at the following location:\\
\href{http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}%
{http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}\\
Here you can find a gzipped tar archive of the source code that can be
downloaded and extracted, as well as this User's Guide in postscript
and hyperlinked PDF formats.

To build \duchamp, you will need three main external libraries:
\textsc{pgplot}, \textsc{cfitsio} (this needs to be version 2.5 or
greater -- version 3+ is better) and \textsc{wcslib}. If these are not
present on your system, you can download them from the following
locations:
\begin{itemize}
\item \textsc{pgplot}:
\href{http://www.astro.caltech.edu/~tjp/pgplot/}%
{\footnotesize http://www.astro.caltech.edu/~tjp/pgplot/}
\item \textsc{cfitsio}:
\href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}%
{\footnotesize http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}
\item \textsc{wcslib}:
\href{http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}%
{\footnotesize http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}
\end{itemize}

\secC{Basic installation}

\duchamp can be built on Unix/Linux systems by typing (assuming that
the prompt your terminal provides is a \texttt{> } -- don't type this
character!):
\begin{quote}
{\footnotesize
\texttt{%
> ./configure\\
> make\\
> make clean (optional -- to remove the object files)\\
> make install }
}
\end{quote}

This default setup will search in standard locations for the necessary
libraries, and install the executable (\texttt{``Duchamp''}) in
\texttt{/usr/local/bin} (a copy will also be in the current
directory). If you want this to go somewhere else, \eg if you don't
have write-access to that directory, or you need to tweak the
libraries, see the next section. Otherwise, jump to the testing
section.

\secC{Tweaking the installation process}

The \texttt{configure} script allows the user to tailor the
installation according to the particular requirements of their
system. 

To install Duchamp in a directory other than \texttt{/usr/local/bin},
use the \texttt{--prefix} option with configure, specifying the
directory above the \texttt{bin/} directory \eg
\begin{quote}
{\footnotesize
\texttt{%
> ./configure --prefix=/home/mduchamp}
}
\end{quote}
and then run \texttt{make} and \texttt{make install} as stated
above. This will put the binary in the directory
\texttt{/home/mduchamp/bin}. 

If the above-mentioned libraries have been installed in non-standard
locations, or you have more than one version installed on your system,
you can specify specific locations by using the
\texttt{--with-cfitsio=<dir>}, \texttt{--with-wcslib=<dir>} or
\texttt{--with-pgplot=<dir>} flags. For example:
\begin{quote}
{\footnotesize
\texttt{%
> ./configure --with-wcslib=/home/mduchamp/wcslib-4.2}
}
\end{quote}

Duchamp can be compiled without \textsc{pgplot} if it is not installed
on your system -- the searching and text-based output remains the
same, but you will not have any graphical output.  To manually specify
this option, use the \texttt{--without-pgplot} flag:
\begin{quote}
{\footnotesize
\texttt{%
> ./configure --without-pgplot}
}
\end{quote}

(Note that CFITSIO and WCSLIB are essential, however, so flags such as
\texttt{--without-wcslib} or \texttt{--without-cfitsio} will not
work.).  Even if you do not give the \texttt{--without-pgplot} option,
and the \textsc{pgplot} library is not found, Duchamp will still
compile (albeit without graphical capabilities).

An additional option that is useful is the ability to specify which
compiler to use. This is very important for the Fortran compiler (used
for linking due to the use of \textsc{pgplot}), particularly on Mac OS
X, where \texttt{gfortran} is often used instead of \texttt{gcc}. To
specify a particular Fortran compiler, use the \texttt{F77} flag:
\begin{quote}
{\footnotesize
\texttt{%
> ./configure F77=gfortran}
}
\end{quote}

Of course, all desired flags should be combined in one
\texttt{configure} call. For a full list of the options with
\texttt{configure}, run:
\begin{quote}
{\footnotesize
\texttt{%
> ./configure --help}
}
\end{quote}
Once \texttt{configure} has run correctly, simply run \texttt{make}
and \texttt{make install} to build \duchamp and put it in the correct
place (either \texttt{/usr/local/bin} or the location given by the
\texttt{--prefix} option discussed above).

\secC{Making sure it all works}

Running make will create the executable \texttt{Duchamp-{\version}}. You can
verify that it is running correctly by running the verification shell
script:
\begin{quote}
{\footnotesize
\texttt{> ./VerifyDuchamp.sh}
}
\end{quote}
This will use a dummy FITS image in the \texttt{verification/}
directory -- this image has some Gaussian random noise, with five
Gaussian sources present, plus a dummy WCS. The script runs
Duchamp on this image with four different sets of inputs, and
compares to known results, looking for differences and reporting
any. There should be none reported if everything is working
correctly. You can then install \duchamp on your system via:
\begin{quote}
{\footnotesize
\texttt{> make install}
}
\end{quote}

\secB{Running \duchamp}
You can then run \duchamp on your own data. This can be done in one
of two ways. The first is:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -f [FITS file]}
}
\end{quote}
where \texttt{[FITS file]} is the file you wish to search. This method
simply uses the default values of all parameters.

The second method allows some determination of the parameter values by
the user. Type:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -p [parameter file]}
}
\end{quote}
where \texttt{[parameterFile]} is a file with the input parameters,
including the name of the cube you want to search. There are two
example input files included with the distribution. The smaller one,
\texttt{InputExample}, shows the typical parameters one might want to
set. The large one, \texttt{InputComplete}, lists all possible
parameters that can be entered, and a brief description of them. To
get going quickly, just replace the \texttt{"your-file-here"} in the
\texttt{InputExample} file with your image name, and type
\begin{quote}
{\footnotesize
\texttt{> Duchamp -p InputExample}
}
\end{quote}

To disable the use of X-window plotting (in displaying the map of
detections), one can either set the parameter \texttt{flagXOutput =
false} or use the \texttt{-x} command-line option:
\begin{quote}
{\footnotesize
\texttt{> Duchamp -x -p [parameter file]}
}, or\\
{\footnotesize
\texttt{> Duchamp -x -f [FITS file]}
}
\end{quote}

The following appendices provide details on the individual parameters,
and show examples of the output files that \duchamp produces.

\secB{Feedback}
It may happen that you discover bugs or problems with \duchamp, or you
have suggestions for improvements or additional features to be
included in future releases. You can submit a ``ticket'' (a trackable
bug report) at the \duchamp Trac wiki at the following location:\\
\href{http://sourcecode.atnf.csiro.au/cgi-bin/trac\_duchamp.cgi/newticket}%
{\footnotesize 
http://sourcecode.atnf.csiro.au/cgi-bin/trac\_duchamp.cgi/newticket}
\\(there is a link to this page from the Duchamp website).

There is also an email exploder, duchamp-user\textbf{[at]}atnf.csiro.au,
that users can subscribe to keep up to date with changes, updates, and
other news about \duchamp. To subscribe, send an email (from the
account you wish to subscribe to the list) to
duchamp-user-request\textbf{[at]}atnf.csiro.au with the single word
``subscribe'' in the body of the message. To be removed from this
list, send a message with ``unsubscribe'' in its body to the same
address.

\secB{Beta Versions}

On the \duchamp website there may be a beta version listed in the
downloads section. As \duchamp is still under development, there will
be times when there has been new functionality added to the code, but
the time has not yet come to release a new minor (or indeed major)
version. 

Sometimes I will post the updated version of the code on the website
as a ``beta'' version, particularly if I'm interested in people
testing it. It will not have been tested as rigorously as the proper
releases, but it will certainly work in the basic cases that I use to
test it during development. So feel free to give it a try -- the
\texttt{CHANGES} file will usually detail what is different to the last
numbered release.