source: tags/release-1.6.1/docs/app-install.tex

% -----------------------------------------------------------------------
% 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 \verb|>| -- don't type this
character!):
\begin{quote}
{\footnotesize
\begin{verbatim}
 > ./configure
 > make
 > make lib (optional -- to create libraries for development purposes)
 > make clean (optional -- to remove the object files)
 > make install 
\end{verbatim}
}
\end{quote}

This default setup will search in standard locations for the necessary
libraries, and install the executable (\texttt{Duchamp-\version}) in
\texttt{/usr/local/bin}, along with a \texttt{Duchamp} symbolic link
(a copy will also be in the current directory). The full set of header
files will be installed in \texttt{/usr/local/include/duchamp} and
subdirectories thereof. 

If you have made the libraries, both static
(\texttt{libduchamp.\version.a}) and shared
(\texttt{libduchamp.\version.so} or \texttt{libduchamp.\version.dylib}
depending on your system) libraries will be created and installed in
\texttt{/usr/local/lib}. Symbolic links will also be created that
don't have the version number.

If you want these to go somewhere else, \eg if you don't have
write-access to that directory, or you need to tweak the location of
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
\verb| > ./configure --prefix=/home/mduchamp|
}
\end{quote}
and then run \texttt{make}, (\texttt{make lib} if you like), and
\texttt{make install} as stated above. This will put the binary in the
directory \texttt{/home/mduchamp/bin}. The library, if made, will be
put in \texttt{/home/mduchamp/lib} and the header files will be put in
\texttt{/home/mduchamp/include/duchamp} and subdirectories.

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{configure} flags
\verb|--with-cfitsio=<dir>|, \verb|--with-wcslib=<dir>| or
\verb|--with-pgplot=<dir>|. For example:
\begin{quote}
{\footnotesize
\verb| > ./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, you can either give \texttt{--without-pgplot} or
\texttt{--with-pgplot=no} as arguments to \texttt{configure}:
\begin{quote}
{\footnotesize
\verb| > ./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
\verb| > ./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
\verb| > ./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 nine 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. 

The script performs basic checks on the output files (results, log,
VOTable, and annotation files), but ignores most of the actual values
of source parameters (to avoid picking up just differences due to
precision errors). For complete checks of the files, run
\begin{quote}
  {\footnotesize
    \texttt{> ./VerifyDuchamp.sh -f}
  }
\end{quote}
Be warned that on some systems this could provide a large number of
apparent errors which may only be due to precision differences.

If everything worked, you can then install \duchamp on your system via:
\begin{quote}
{\footnotesize
\texttt{> make install}
}
\end{quote}
(this may need to be run as sudo depending on your system setup and
your prefix directory).

\secB{Troubleshooting the installation process}

This section deals with a few common problems encountered in building
\duchamp, along with suggested fixes. As always, if you come across
particularly intractable problems, you are welcome to submit a bug
report -- see below for details.

\secC{Unrecognised libraries}

It may be that even after explicitly giving the location of particular
libraries, they are still not being found properly by
\texttt{configure}. This can be a particular problem when those
libraries are installed in a non-standard location (for instance, if
you do not have root permissions on the machine you are using and have
installed them yourself in a local directory).

One thing to be aware of is that the paths used for linking libraries
include your new library. You can set this using the environment
variables \verb|LD_LIBRARY_PATH| or, on a Mac,
\verb|DYLD_LIBRARY_PATH|. For instance, if you've installed
\texttt{wcslib} in \texttt{/home/mduchamp/mylibs/wcslib} then you can
update the path via

\begin{quote}
{\footnotesize
\verb|> export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/home/mduchamp/mylibs/wcslib"|
\,\,\, for a \texttt{bash}-like shell, or\\
\verb|> setenv LD_LIBRARY_PATH "${LD_LIBRARY_PATH}:/home/mduchamp/mylibs/wcslib"|
\,\,\, for a \texttt{csh}-like shell
}
\end{quote}
and similarly for \verb|DYLD_LIBRARY_PATH|.

\secC{Non-standard system library locations}

It may be that one of the system libraries is not being found
correctly. This can be a problem with the \texttt{gfortran} libary. If
\texttt{configure} cannot find it, then it will likely leave out one
or more libraries from the linking command (such as \verb|-lcpgplot|
or \verb|-lpgsbox|), resulting in \duchamp not building correctly. You
may also get error messages at the linking stage (the final stage of
running \texttt{make}) that complain of missing symbols.

To force \texttt{configure} to use a non-standard location, you can
use the \verb|LIBS| option. For instance, say your system has
\verb|libgfortran| in some non-standard location like
\verb|/some/other/path/libgfortran.so|, then you can run
\texttt{configure} like so:

\begin{quote}
{\footnotesize
\verb| > ./configure LIBS="-L/some/other/path -lgfortran"|
}
\end{quote}

This will allow \texttt{configure} to test for other libraries using
that location for \texttt{libgfortran}, and put that library location
into the Makefile.

Another potential problem are the X11 libraries. These are used for
the \texttt{pgplot} display during run-time. The \texttt{configure}
script has a specific function that searches for them, but sometimes
it fails to locate them if they are in a non-standard place on your
system. This can be a problem as \texttt{configure} will then fail to
test properly for the presence of \texttt{pgplot}.  If this is the
case, use the \verb|--x-includes| and \verb|--x-libraries| flags to
give the relevant directories.

\secC{Bad command-line options}

While the configure script tries to get everything right, it can
exhibit some quirks. For instance, in getting the X11 library
configuration right, it will sometimes provide a
\texttt{-R/path/to/X11} argument for the linking string. This is
accepted by \texttt{ld}, but not by all versions of \texttt{gfortran}.
This can cause the final linking step to fail (and for the
\texttt{-lpgplot} argument to be left off).

To fix this, a shell script is provided to quickly patch the Makefile
if necessary. If you run make and it fails, due to this error:
\begin{quote}
{\footnotesize
\texttt{%
   gfortran: error: unrecognized command line option ‘-R’}
}
\end{quote}
 or similar, run 
\begin{quote}
{\footnotesize
\texttt{%
 > ./fixMakefile.sh}
}
\end{quote}
and try again. If it still fails, you may have to manually edit the
Makefile. Please log a bug report to let me know!



\secB{Running \duchamp}
You can now run \duchamp on your own data. This can be done in one
of two ways. The first is:
\begin{quote}
{\footnotesize
\verb| > 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 flux threshold
can be specified using the \texttt{-t [THRESHOLD]} option:
\begin{quote}
{\footnotesize
\verb| > Duchamp -f [FITS file] -t [THRESHOLD]|
}
\end{quote}

The second method allows some determination of the parameter values by
the user. Type:
\begin{quote}
{\footnotesize
\verb| > 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. The \texttt{-t}
flag can also be specified - its threshold value will override
anything given in the parameter file.

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, along with their default
values, 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
\verb| > 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
\verb| > Duchamp -x -p [parameter file]|
}, or\\
{\footnotesize
\verb| > Duchamp -x -f [FITS file]|
}
\end{quote}
Note that the postscript outputs will still be produced (if required)
-- this just affects the runtime display.

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://svn.atnf.csiro.au/trac/duchamp/newticket}%
{http://svn.atnf.csiro.au/trac/duchamp/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.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "Guide"
%%% End: