[303] | 1 | % ----------------------------------------------------------------------- |
---|
| 2 | % app-install.tex: Section about how to download, install and run |
---|
| 3 | % Duchamp. |
---|
| 4 | % ----------------------------------------------------------------------- |
---|
| 5 | % Copyright (C) 2006, Matthew Whiting, ATNF |
---|
| 6 | % |
---|
| 7 | % This program is free software; you can redistribute it and/or modify it |
---|
| 8 | % under the terms of the GNU General Public License as published by the |
---|
| 9 | % Free Software Foundation; either version 2 of the License, or (at your |
---|
| 10 | % option) any later version. |
---|
| 11 | % |
---|
| 12 | % Duchamp is distributed in the hope that it will be useful, but WITHOUT |
---|
| 13 | % ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
---|
| 14 | % FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
---|
| 15 | % for more details. |
---|
| 16 | % |
---|
| 17 | % You should have received a copy of the GNU General Public License |
---|
| 18 | % along with Duchamp; if not, write to the Free Software Foundation, |
---|
| 19 | % Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
---|
| 20 | % |
---|
| 21 | % Correspondence concerning Duchamp may be directed to: |
---|
| 22 | % Internet email: Matthew.Whiting [at] atnf.csiro.au |
---|
| 23 | % Postal address: Dr. Matthew Whiting |
---|
| 24 | % Australia Telescope National Facility, CSIRO |
---|
| 25 | % PO Box 76 |
---|
| 26 | % Epping NSW 1710 |
---|
| 27 | % AUSTRALIA |
---|
| 28 | % ----------------------------------------------------------------------- |
---|
[158] | 29 | \secA{Obtaining and installing \duchamp} |
---|
| 30 | \label{app-install} |
---|
| 31 | |
---|
[208] | 32 | \secB{Installing} |
---|
[258] | 33 | The \duchamp web page can be found at the following location:\\ |
---|
[158] | 34 | \href{http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}% |
---|
| 35 | {http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp}\\ |
---|
| 36 | Here you can find a gzipped tar archive of the source code that can be |
---|
| 37 | downloaded and extracted, as well as this User's Guide in postscript |
---|
| 38 | and hyperlinked PDF formats. |
---|
| 39 | |
---|
| 40 | To build \duchamp, you will need three main external libraries: |
---|
[168] | 41 | \textsc{pgplot}, \textsc{cfitsio} (this needs to be version 2.5 or |
---|
| 42 | greater -- version 3+ is better) and \textsc{wcslib}. If these are not |
---|
| 43 | present on your system, you can download them from the following |
---|
| 44 | locations: |
---|
[158] | 45 | \begin{itemize} |
---|
| 46 | \item \textsc{pgplot}: |
---|
| 47 | \href{http://www.astro.caltech.edu/~tjp/pgplot/}% |
---|
[231] | 48 | {\footnotesize http://www.astro.caltech.edu/~tjp/pgplot/} |
---|
[158] | 49 | \item \textsc{cfitsio}: |
---|
| 50 | \href{http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html}% |
---|
[231] | 51 | {\footnotesize http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html} |
---|
[158] | 52 | \item \textsc{wcslib}: |
---|
| 53 | \href{http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html}% |
---|
[231] | 54 | {\footnotesize http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html} |
---|
[158] | 55 | \end{itemize} |
---|
| 56 | |
---|
[338] | 57 | \secC{Basic installation} |
---|
| 58 | |
---|
[258] | 59 | \duchamp can be built on Unix/Linux systems by typing (assuming that |
---|
[1358] | 60 | the prompt your terminal provides is a \verb|>| -- don't type this |
---|
[158] | 61 | character!): |
---|
| 62 | \begin{quote} |
---|
[231] | 63 | {\footnotesize |
---|
[1358] | 64 | \begin{verbatim} |
---|
| 65 | > ./configure |
---|
| 66 | > make |
---|
| 67 | > make lib (optional -- to create libraries for development purposes) |
---|
| 68 | > make clean (optional -- to remove the object files) |
---|
| 69 | > make install |
---|
| 70 | \end{verbatim} |
---|
[231] | 71 | } |
---|
[158] | 72 | \end{quote} |
---|
| 73 | |
---|
[338] | 74 | This default setup will search in standard locations for the necessary |
---|
[1229] | 75 | libraries, and install the executable (\texttt{Duchamp-\version}) in |
---|
| 76 | \texttt{/usr/local/bin}, along with a \texttt{Duchamp} symbolic link |
---|
| 77 | (a copy will also be in the current directory). The full set of header |
---|
| 78 | files will be installed in \texttt{/usr/local/include/duchamp} and |
---|
| 79 | subdirectories thereof. |
---|
[158] | 80 | |
---|
[1229] | 81 | If you have made the libraries, both static |
---|
| 82 | (\texttt{libduchamp.\version.a}) and shared |
---|
| 83 | (\texttt{libduchamp.\version.so} or \texttt{libduchamp.\version.dylib} |
---|
| 84 | depending on your system) libraries will be created and installed in |
---|
[1231] | 85 | \texttt{/usr/local/lib}. Symbolic links will also be created that |
---|
| 86 | don't have the version number. |
---|
[1229] | 87 | |
---|
| 88 | If you want these to go somewhere else, \eg if you don't have |
---|
| 89 | write-access to that directory, or you need to tweak the location of |
---|
| 90 | the libraries, see the next section. Otherwise, jump to the testing |
---|
| 91 | section. |
---|
| 92 | |
---|
[338] | 93 | \secC{Tweaking the installation process} |
---|
| 94 | |
---|
[364] | 95 | The \texttt{configure} script allows the user to tailor the |
---|
| 96 | installation according to the particular requirements of their |
---|
| 97 | system. |
---|
| 98 | |
---|
[968] | 99 | To install \duchamp in a directory other than \texttt{/usr/local/bin}, |
---|
[344] | 100 | use the \texttt{--prefix} option with configure, specifying the |
---|
| 101 | directory above the \texttt{bin/} directory \eg |
---|
[158] | 102 | \begin{quote} |
---|
[231] | 103 | {\footnotesize |
---|
[1358] | 104 | \verb| > ./configure --prefix=/home/mduchamp| |
---|
[231] | 105 | } |
---|
[158] | 106 | \end{quote} |
---|
[389] | 107 | and then run \texttt{make}, (\texttt{make lib} if you like), and |
---|
| 108 | \texttt{make install} as stated above. This will put the binary in the |
---|
| 109 | directory \texttt{/home/mduchamp/bin}. The library, if made, will be |
---|
[1021] | 110 | put in \texttt{/home/mduchamp/lib} and the header files will be put in |
---|
[389] | 111 | \texttt{/home/mduchamp/include/duchamp} and subdirectories. |
---|
[338] | 112 | |
---|
| 113 | If the above-mentioned libraries have been installed in non-standard |
---|
| 114 | locations, or you have more than one version installed on your system, |
---|
[1021] | 115 | you can specify specific locations by using the \texttt{configure} flags |
---|
[1358] | 116 | \verb|--with-cfitsio=<dir>|, \verb|--with-wcslib=<dir>| or |
---|
| 117 | \verb|--with-pgplot=<dir>|. For example: |
---|
[158] | 118 | \begin{quote} |
---|
[231] | 119 | {\footnotesize |
---|
[1358] | 120 | \verb| > ./configure --with-wcslib=/home/mduchamp/wcslib-4.2| |
---|
[231] | 121 | } |
---|
[158] | 122 | \end{quote} |
---|
| 123 | |
---|
[1358] | 124 | \duchamp can be compiled without \textsc{pgplot} if it is not installed |
---|
[338] | 125 | on your system -- the searching and text-based output remains the |
---|
| 126 | same, but you will not have any graphical output. To manually specify |
---|
[1021] | 127 | this option, you can either give \texttt{--without-pgplot} or |
---|
| 128 | \texttt{--with-pgplot=no} as arguments to \texttt{configure}: |
---|
[338] | 129 | \begin{quote} |
---|
| 130 | {\footnotesize |
---|
[1358] | 131 | \verb| > ./configure --without-pgplot| |
---|
[338] | 132 | } |
---|
| 133 | \end{quote} |
---|
[320] | 134 | |
---|
[338] | 135 | (Note that CFITSIO and WCSLIB are essential, however, so flags such as |
---|
| 136 | \texttt{--without-wcslib} or \texttt{--without-cfitsio} will not |
---|
| 137 | work.). Even if you do not give the \texttt{--without-pgplot} option, |
---|
[1358] | 138 | and the \textsc{pgplot} library is not found, \duchamp will still |
---|
[338] | 139 | compile (albeit without graphical capabilities). |
---|
| 140 | |
---|
[364] | 141 | An additional option that is useful is the ability to specify which |
---|
| 142 | compiler to use. This is very important for the Fortran compiler (used |
---|
| 143 | for linking due to the use of \textsc{pgplot}), particularly on Mac OS |
---|
| 144 | X, where \texttt{gfortran} is often used instead of \texttt{gcc}. To |
---|
| 145 | specify a particular Fortran compiler, use the \texttt{F77} flag: |
---|
| 146 | \begin{quote} |
---|
| 147 | {\footnotesize |
---|
[1358] | 148 | \verb| > ./configure F77=gfortran| |
---|
[364] | 149 | } |
---|
| 150 | \end{quote} |
---|
| 151 | |
---|
| 152 | Of course, all desired flags should be combined in one |
---|
| 153 | \texttt{configure} call. For a full list of the options with |
---|
| 154 | \texttt{configure}, run: |
---|
| 155 | \begin{quote} |
---|
| 156 | {\footnotesize |
---|
[1358] | 157 | \verb| > ./configure --help| |
---|
[364] | 158 | } |
---|
| 159 | \end{quote} |
---|
| 160 | Once \texttt{configure} has run correctly, simply run \texttt{make} |
---|
| 161 | and \texttt{make install} to build \duchamp and put it in the correct |
---|
[373] | 162 | place (either \texttt{/usr/local/bin} or the location given by the |
---|
| 163 | \texttt{--prefix} option discussed above). |
---|
[364] | 164 | |
---|
[1087] | 165 | |
---|
| 166 | |
---|
[338] | 167 | \secC{Making sure it all works} |
---|
| 168 | |
---|
[364] | 169 | Running make will create the executable \texttt{Duchamp-{\version}}. You can |
---|
[321] | 170 | verify that it is running correctly by running the verification shell |
---|
| 171 | script: |
---|
[158] | 172 | \begin{quote} |
---|
[231] | 173 | {\footnotesize |
---|
[382] | 174 | \texttt{> ./VerifyDuchamp.sh} |
---|
[231] | 175 | } |
---|
[158] | 176 | \end{quote} |
---|
| 177 | This will use a dummy FITS image in the \texttt{verification/} |
---|
| 178 | directory -- this image has some Gaussian random noise, with five |
---|
| 179 | Gaussian sources present, plus a dummy WCS. The script runs |
---|
[1358] | 180 | \duchamp on this image with nine different sets of inputs, and |
---|
[158] | 181 | compares to known results, looking for differences and reporting |
---|
[382] | 182 | any. There should be none reported if everything is working |
---|
[1087] | 183 | correctly. |
---|
| 184 | |
---|
| 185 | The script performs basic checks on the output files (results, log, |
---|
| 186 | VOTable, and annotation files), but ignores most of the actual values |
---|
| 187 | of source parameters (to avoid picking up just differences due to |
---|
| 188 | precision errors). For complete checks of the files, run |
---|
[382] | 189 | \begin{quote} |
---|
[1087] | 190 | {\footnotesize |
---|
| 191 | \texttt{> ./VerifyDuchamp.sh -f} |
---|
| 192 | } |
---|
| 193 | \end{quote} |
---|
| 194 | Be warned that on some systems this could provide a large number of |
---|
| 195 | apparent errors which may only be due to precision differences. |
---|
| 196 | |
---|
| 197 | If everything worked, you can then install \duchamp on your system via: |
---|
| 198 | \begin{quote} |
---|
[382] | 199 | {\footnotesize |
---|
| 200 | \texttt{> make install} |
---|
| 201 | } |
---|
| 202 | \end{quote} |
---|
[1087] | 203 | (this may need to be run as sudo depending on your system setup and |
---|
| 204 | your prefix directory). |
---|
[158] | 205 | |
---|
[1358] | 206 | \secB{Troubleshooting the installation process} |
---|
| 207 | |
---|
| 208 | This section deals with a few common problems encountered in building |
---|
| 209 | \duchamp, along with suggested fixes. As always, if you come across |
---|
| 210 | particularly intractable problems, you are welcome to submit a bug |
---|
| 211 | report -- see below for details. |
---|
| 212 | |
---|
| 213 | \secC{Unrecognised libraries} |
---|
| 214 | |
---|
| 215 | It may be that even after explicitly giving the location of particular |
---|
| 216 | libraries, they are still not being found properly by |
---|
| 217 | \texttt{configure}. This can be a particular problem when those |
---|
| 218 | libraries are installed in a non-standard location (for instance, if |
---|
| 219 | you do not have root permissions on the machine you are using and have |
---|
| 220 | installed them yourself in a local directory). |
---|
| 221 | |
---|
| 222 | One thing to be aware of is that the paths used for linking libraries |
---|
| 223 | include your new library. You can set this using the environment |
---|
| 224 | variables \verb|LD_LIBRARY_PATH| or, on a Mac, |
---|
| 225 | \verb|DYLD_LIBRARY_PATH|. For instance, if you've installed |
---|
| 226 | \texttt{wcslib} in \texttt{/home/mduchamp/mylibs/wcslib} then you can |
---|
| 227 | update the path via |
---|
| 228 | |
---|
| 229 | \begin{quote} |
---|
| 230 | {\footnotesize |
---|
| 231 | \verb|> export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/home/mduchamp/mylibs/wcslib"| |
---|
| 232 | \,\,\, for a \texttt{bash}-like shell, or\\ |
---|
| 233 | \verb|> setenv LD_LIBRARY_PATH "${LD_LIBRARY_PATH}:/home/mduchamp/mylibs/wcslib"| |
---|
| 234 | \,\,\, for a \texttt{csh}-like shell |
---|
| 235 | } |
---|
| 236 | \end{quote} |
---|
| 237 | and similarly for \verb|DYLD_LIBRARY_PATH|. |
---|
| 238 | |
---|
| 239 | \secC{Non-standard system library locations} |
---|
| 240 | |
---|
| 241 | It may be that one of the system libraries is not being found |
---|
| 242 | correctly. This can be a problem with the \texttt{gfortran} libary. If |
---|
| 243 | \texttt{configure} cannot find it, then it will likely leave out one |
---|
| 244 | or more libraries from the linking command (such as \verb|-lcpgplot| |
---|
| 245 | or \verb|-lpgsbox|), resulting in \duchamp not building correctly. You |
---|
| 246 | may also get error messages at the linking stage (the final stage of |
---|
| 247 | running \texttt{make}) that complain of missing symbols. |
---|
| 248 | |
---|
| 249 | To force \texttt{configure} to use a non-standard location, you can |
---|
| 250 | use the \verb|LIBS| option. For instance, say your system has |
---|
| 251 | \verb|libgfortran| in some non-standard location like |
---|
| 252 | \verb|/some/other/path/libgfortran.so|, then you can run |
---|
| 253 | \texttt{configure} like so: |
---|
| 254 | |
---|
| 255 | \begin{quote} |
---|
| 256 | {\footnotesize |
---|
| 257 | \verb| > ./configure LIBS="-L/some/other/path -lgfortran"| |
---|
| 258 | } |
---|
| 259 | \end{quote} |
---|
| 260 | |
---|
| 261 | This will allow \texttt{configure} to test for other libraries using |
---|
| 262 | that location for \texttt{libgfortran}, and put that library location |
---|
| 263 | into the Makefile. |
---|
| 264 | |
---|
| 265 | Another potential problem are the X11 libraries. These are used for |
---|
| 266 | the \texttt{pgplot} display during run-time. The \texttt{configure} |
---|
| 267 | script has a specific function that searches for them, but sometimes |
---|
| 268 | it fails to locate them if they are in a non-standard place on your |
---|
| 269 | system. This can be a problem as \texttt{configure} will then fail to |
---|
| 270 | test properly for the presence of \texttt{pgplot}. If this is the |
---|
| 271 | case, use the \verb|--x-includes| and \verb|--x-libraries| flags to |
---|
| 272 | give the relevant directories. |
---|
| 273 | |
---|
| 274 | \secC{Bad command-line options} |
---|
| 275 | |
---|
| 276 | While the configure script tries to get everything right, it can |
---|
| 277 | exhibit some quirks. For instance, in getting the X11 library |
---|
| 278 | configuration right, it will sometimes provide a |
---|
| 279 | \texttt{-R/path/to/X11} argument for the linking string. This is |
---|
| 280 | accepted by \texttt{ld}, but not by all versions of \texttt{gfortran}. |
---|
| 281 | This can cause the final linking step to fail (and for the |
---|
| 282 | \texttt{-lpgplot} argument to be left off). |
---|
| 283 | |
---|
| 284 | To fix this, a shell script is provided to quickly patch the Makefile |
---|
| 285 | if necessary. If you run make and it fails, due to this error: |
---|
| 286 | \begin{quote} |
---|
| 287 | {\footnotesize |
---|
| 288 | \texttt{% |
---|
| 289 | gfortran: error: unrecognized command line option â-Râ} |
---|
| 290 | } |
---|
| 291 | \end{quote} |
---|
| 292 | or similar, run |
---|
| 293 | \begin{quote} |
---|
| 294 | {\footnotesize |
---|
| 295 | \texttt{% |
---|
| 296 | > ./fixMakefile.sh} |
---|
| 297 | } |
---|
| 298 | \end{quote} |
---|
| 299 | and try again. If it still fails, you may have to manually edit the |
---|
| 300 | Makefile. Please log a bug report to let me know! |
---|
| 301 | |
---|
| 302 | |
---|
| 303 | |
---|
[208] | 304 | \secB{Running \duchamp} |
---|
[1358] | 305 | You can now run \duchamp on your own data. This can be done in one |
---|
[158] | 306 | of two ways. The first is: |
---|
| 307 | \begin{quote} |
---|
[231] | 308 | {\footnotesize |
---|
[1358] | 309 | \verb| > Duchamp -f [FITS file]| |
---|
[231] | 310 | } |
---|
[158] | 311 | \end{quote} |
---|
| 312 | where \texttt{[FITS file]} is the file you wish to search. This method |
---|
[1159] | 313 | simply uses the default values of all parameters. The flux threshold |
---|
| 314 | can be specified using the \texttt{-t [THRESHOLD]} option: |
---|
| 315 | \begin{quote} |
---|
| 316 | {\footnotesize |
---|
[1358] | 317 | \verb| > Duchamp -f [FITS file] -t [THRESHOLD]| |
---|
[1159] | 318 | } |
---|
| 319 | \end{quote} |
---|
[158] | 320 | |
---|
| 321 | The second method allows some determination of the parameter values by |
---|
| 322 | the user. Type: |
---|
| 323 | \begin{quote} |
---|
[231] | 324 | {\footnotesize |
---|
[1358] | 325 | \verb| > Duchamp -p [parameter file]| |
---|
[231] | 326 | } |
---|
[158] | 327 | \end{quote} |
---|
| 328 | where \texttt{[parameterFile]} is a file with the input parameters, |
---|
[1159] | 329 | including the name of the cube you want to search. The \texttt{-t} |
---|
| 330 | flag can also be specified - its threshold value will override |
---|
| 331 | anything given in the parameter file. |
---|
| 332 | |
---|
| 333 | There are two example input files included with the distribution. The |
---|
| 334 | smaller one, \texttt{InputExample}, shows the typical parameters one |
---|
| 335 | might want to set. The large one, \texttt{InputComplete}, lists all |
---|
| 336 | possible parameters that can be entered, along with their default |
---|
| 337 | values, and a brief description of them. To get going quickly, just |
---|
| 338 | replace the \texttt{"your-file-here"} in the \texttt{InputExample} |
---|
| 339 | file with your image name, and type |
---|
[158] | 340 | \begin{quote} |
---|
[231] | 341 | {\footnotesize |
---|
[1358] | 342 | \verb| > Duchamp -p InputExample| |
---|
[231] | 343 | } |
---|
[158] | 344 | \end{quote} |
---|
| 345 | |
---|
[294] | 346 | To disable the use of X-window plotting (in displaying the map of |
---|
[298] | 347 | detections), one can either set the parameter \texttt{flagXOutput = |
---|
| 348 | false} or use the \texttt{-x} command-line option: |
---|
[294] | 349 | \begin{quote} |
---|
| 350 | {\footnotesize |
---|
[1358] | 351 | \verb| > Duchamp -x -p [parameter file]| |
---|
[294] | 352 | }, or\\ |
---|
| 353 | {\footnotesize |
---|
[1358] | 354 | \verb| > Duchamp -x -f [FITS file]| |
---|
[294] | 355 | } |
---|
| 356 | \end{quote} |
---|
[1159] | 357 | Note that the postscript outputs will still be produced (if required) |
---|
| 358 | -- this just affects the runtime display. |
---|
[294] | 359 | |
---|
[158] | 360 | The following appendices provide details on the individual parameters, |
---|
[258] | 361 | and show examples of the output files that \duchamp produces. |
---|
[208] | 362 | |
---|
| 363 | \secB{Feedback} |
---|
| 364 | It may happen that you discover bugs or problems with \duchamp, or you |
---|
| 365 | have suggestions for improvements or additional features to be |
---|
| 366 | included in future releases. You can submit a ``ticket'' (a trackable |
---|
[258] | 367 | bug report) at the \duchamp Trac wiki at the following location:\\ |
---|
[447] | 368 | \href{http://svn.atnf.csiro.au/trac/duchamp/newticket}% |
---|
| 369 | {http://svn.atnf.csiro.au/trac/duchamp/newticket} |
---|
[1358] | 370 | \\(there is a link to this page from the \duchamp website). |
---|
[208] | 371 | |
---|
| 372 | There is also an email exploder, duchamp-user\textbf{[at]}atnf.csiro.au, |
---|
| 373 | that users can subscribe to keep up to date with changes, updates, and |
---|
| 374 | other news about \duchamp. To subscribe, send an email (from the |
---|
| 375 | account you wish to subscribe to the list) to |
---|
| 376 | duchamp-user-request\textbf{[at]}atnf.csiro.au with the single word |
---|
| 377 | ``subscribe'' in the body of the message. To be removed from this |
---|
| 378 | list, send a message with ``unsubscribe'' in its body to the same |
---|
| 379 | address. |
---|
| 380 | |
---|
[264] | 381 | \secB{Beta Versions} |
---|
| 382 | |
---|
| 383 | On the \duchamp website there may be a beta version listed in the |
---|
| 384 | downloads section. As \duchamp is still under development, there will |
---|
| 385 | be times when there has been new functionality added to the code, but |
---|
| 386 | the time has not yet come to release a new minor (or indeed major) |
---|
| 387 | version. |
---|
| 388 | |
---|
| 389 | Sometimes I will post the updated version of the code on the website |
---|
| 390 | as a ``beta'' version, particularly if I'm interested in people |
---|
| 391 | testing it. It will not have been tested as rigorously as the proper |
---|
| 392 | releases, but it will certainly work in the basic cases that I use to |
---|
| 393 | test it during development. So feel free to give it a try -- the |
---|
| 394 | \texttt{CHANGES} file will usually detail what is different to the last |
---|
| 395 | numbered release. |
---|
[968] | 396 | |
---|
| 397 | %%% Local Variables: |
---|
| 398 | %%% mode: latex |
---|
| 399 | %%% TeX-master: "Guide" |
---|
| 400 | %%% End: |
---|