Installation instructions for zhtools 3.x ----------------------------------------- The zhtools software package has been ported to the Solaris, Linux, and Mac OSX (Tiger on PPC and Intel) operating systems. To install zhtools, follow the instructions below (which, for illustrative purposes, use $HOME as the target install directory). ***************************************************************************** 1. Retrieve zhtools source and pre-build external library tar files from Web page http://hea-www.harvard.edu/saord/zhtools cd /pool # where the build files reside wget http://hea-www.harvard.edu/saord/download/zhtools/zhtools-3.0.tar.gz wget http://hea-www.harvard.edu/saord/download/zhtools/zhext.tar.gz The zhtools package is available as a source file tar file named zhtools-3.0.tar.gz (minor version number might be different) at: http://hea-www.harvard.edu/saord/zhtools ftp://sao-ftp.harvard.edu/rd/zhtools In addition to the source code in zhtools-3.0.tar.gz, you will need these external libraries: name: available at: ----- ------------- fitsio http://heasarc.gsfc.nasa.gov/ WCStools http://tdc-www.harvard.edu/software/wcstools Source code for these libraries can be retrieved from their home sites, but we make available zhext.tar.gz and zhext64.tar.gz (64-bit versions) containing binary distributions for the machines to which we have ported zhtools. Where possible, you probably should retrieve and use this tar file. The instructions below assume its use. ***************************************************************************** 2. Unpack the source tar file to create the build directory cd /pool # where the build files reside gunzip -c zhtools-3.0.tar.gz | tar xf - # unpack zhtools sources Unpack the zhtools source tar file in any convenient location. A temporary directory (i.e. pool space) is a good choice if you intend to remove the source directory after installation. ***************************************************************************** 3. Create the install directory and unpack external libraries cd $HOME # where install dir resides mkdir zhtools # create install directory cd zhtools # go there gunzip -c /pool/zhext.tar.gz | tar xf - # unpack external libraries or gunzip -c /pool/zhext64.tar.gz | tar xf - # for building 64-bit programs We have built external libraries for the following operating systems and compilers combinations and have packaged the libraries in a single tar file named zhext.tar.gz: OS FC/CC combination ----------- ----------------- Linux (FC6) g77/gcc32 Linux (FC6) gfortran/gcc Linux64 (FC6) gfortran/g77 OSX PPC g95/gcc OSX Intel g95/gcc Solaris g77/gcc Solaris f95/cc Solaris64 f95/cc Choose an installation directory to house the zhtools executables, libraries, and documentation. In keeping with standard GNU configure practice, the default install directory is /usr/local but installing there requires root access. For personal use, we recommend installing in a zhtools subdirectory of $HOME, the user home directory. Create the installation directory, if necessary, and unpack the zhext tar file in that directory. This will create an external library directory called zhext and sub-directories containing external libraries for these hosts: lib.darwin-i386 Mac OS X for Intel lib.darwin-powerpc ` Mac OS X for PowerPC lib.linux (hopefully generic) Linux lib.sol Solaris 2.8 These directories contain the external libraries for OSX, linux, and solaris. (You can remove directories you do not need for this build.) ***************************************************************************** 4. Configure the build cd /pool/zhtools-3.0 # in build directory ... ./configure --with-libs=$HOME/zhtools/zhext --prefix=$HOME/zhtools [options] Run the configure script to generate Makefiles for this host. You must tell configure where the external libraries are located. To do this, use the --with-libs command line option: ./configure --with-libs= e.g., ./configure --with-libs=$HOME/zhtools/zhext If you install in a directory other than the default of /usr/local, you will need to add the --prefix command line option: ./configure --prefix= e.g., ./configure --prefix=$HOME In this example, program files will be installed in $HOME/zhtools/bin, libraries will be installed in $HOME/zhtools/lib, and help files will be installed in $HOME/zhtools/zhhelp. When the configure script runs, it will pick the newest C and Fortran compilers it can find on your system, e.g., choosing Fortran95 above Fortran77. You can specify a specific compiler to use on the configure command line: ./configure --with-libs=${HOME}/zhtools/zhext \ --prefix=${HOME}/zhtools \ FC=g77 CC=/usr/bin/gcc-3.3 NB: Mac OSX (Tiger 10.4) does not appear to supply a Fortran compiler at all. For OSX 10.4, you should can install the g77 3.4.4 compiler (PPC only) or the gfortran 4.2 compiler (PPC and Intel), which can be retrieved from: http://hpc.sourceforge.net Note, however, you must use a matched rev. 3 gcc C compiler: you cannot mix the default gcc 4.0 compiler with the rev. 3 Fortran compiler. The above configure command line, which sets both FC and CC, will give you the proper mix of rev. 3 compilers for Mac OSX. NB: The FC3 gfortran compiler is an early revision (4.0) and is missing features required by zhtools. Therefore you MUST specify an alternate Fortran compiler and a matching C compiler for hosts where gfortran is installed as the default Fortran compiler. This is true, for example, of many Linux distributions which supply both gfortran and g77. To avoid choosing gfortran, the following configure command can be used (assuming gcc is a rev 3 compiler -- see note above for OSX): ./configure --with-libs=${HOME}/zhtools/zhext \ --prefix=${HOME}/zhtools \ FC=g77 NB: If your host is running a 64-bit OS and you need to build 64-bit applications, then you must set the compiler switches proerly and use the 64-bit external libraries. Unfortuantely, its a bit complicated. For example, gcc generally requires the -m64 switch to build 64-bit applications in environments where a choice of 32 or 64 is available but, apparently, this switch is not required when 64-bit is the only option. On a Sun workstation, gcc also seems to require the -mcpu=v9. The zhconfig script gives example configure command lines for Solaris, Linux, and OSX. Feel free to use an entry in that script, if it suits your needs. Several other secondary command line options are available for configure: --with-readline= where lib and include directories reside for readline and history libraries e.g. /usr/local. Use of readline gives nice command prompting. --with-funtools= lib directory for funtools e.g. /usr/local. If defined, programs utilizing regions will also accept funtools regions as input, which can be very useful when working with ds9. --with-blas= link specification for BLAS library. e.g. -L/usr/local/intel/mkl/LIB/ -lmkl32_def. only use highly optimized versions for your CPU, since generic version can be slow. --with-cfitsio= lib directory for cfitsio e.g. /usr/local. only if you are not using cfitsio from zhext. --with-wcs= lib directory for wcs e.g. /usr/local. only if you are not using wcs from zhext. --with-pgplot= lib directory for pgplot e.g. /usr/local. If defined, a pgplot-based program called contmap will be built. --with-data= where zhtools data directory containing caldata is located e.g. /usr/share. You almost certainly do not need this: it is used only by a few obscure zhtools programs ***************************************************************************** 5. Build zhtools cd /pool/zhtools-3.0 # in build directory ... make # build the software The build ("make") takes a few minutes on modern machines. To monitor progress and/or check for errors, redirect output to a file and use the 'tail' command: make >& foo.log &; tail -f foo.log # csh or make 1>foo.log 2>&1 &; tail -f foo.log # sh, bash ***************************************************************************** 6. Install zhtools cd /pool/zhtools-3.0 # in build directory ... make install # install binaries, help, etc. The install command will move executables into the bin sub-directory of the specified install directory. The zhtools library will be put into the lib sub-directory and the help files will be moved to a zhhelp sub-directory. ***************************************************************************** 7. Clean zhtools cd /pool/zhtools-3.0 # in build directory ... make clean # clean up unneeded temp files Once installation in complete, all files necessary to run zhtools will have been moved. Executing the clean command will clean the source tree of temp files created during the build, leaving the source files intact for later study. ***************************************************************************** 8. Optionally remove all traces of the build cd /pool # where the build files reside rm -rf zhtools-3.0 # don't even need sources rm zhtools-3.0.tar.gz # don't need source tar file rm zhext.tar.gz # don't need library tar file Once installation in complete, all files necessary to run zhtools have been moved and the source directory is no longer needed. If you don't need to refer to the source code, you can remove the entire build tree (as well as the original tar files). ***************************************************************************** 9. Add ${HOME}/zhtools/bin to your search path and go ... Add the bin sub-directory of the specified install directory to your shell search path and you will have access to zhtools programs and documentation. Note to users of zhtools 2.1: the ZHTOOLS environment variable is NOT needed. It should be removed from your environment. ***************************************************************************** 10. Questions? If you have questions about building zhtools, please send email to: eric@head-cfa.harvard.edu If you have questions about zhtools functionality, please send email to: alexey@head-cfa.harvard.edu