Installing HEASoft (For Source or Binary Distribution)

*****************************************************************************
                         HEASOFT 6.13 - INTRODUCTION
*****************************************************************************

HEASOFT is the generalized term for the full set of software distributed
from the HEASARC, incorporating all of the newly-developed software in
the HEADAS environment (e.g. Swift) as well as all of the legacy HEASARC
software (FTOOLS, XANADU, XSTAR, etc.).
 
This document is a guide to installing HEASOFT from the source code or
pre-compiled binary distributions on Unix systems (and the Linux-like
Cygwin environment for Windows), available for download at:

 http://heasarc.gsfc.nasa.gov/lheasoft/download.html

This document is also available online at:

 http://heasarc.gsfc.nasa.gov/lheasoft/install.html


*****************************************************************************
                            CONTACT INFORMATION
*****************************************************************************

* For more information, please see:

    http://heasarc.gsfc.nasa.gov/ftools     (FTOOLS)
    http://heasarc.gsfc.nasa.gov/xanadu     (XSPEC, XIMAGE, XRONOS)
    http://heasarc.gsfc.nasa.gov/ftools/fv  (FV)

  For correspondence regarding all of these general utilities, please
  contact us via:

    http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp

* For correspondence regarding mission-specific software, please visit

    http://heasarc.gsfc.nasa.gov/cgi-bin/Feedback

  and select the appropriate mission under "Choose a mailing list".

* For online information about XSTAR please visit

    http://heasarc.gsfc.nasa.gov/xstar/xstar.html

  or contact the XSTAR help desk at:

    xstarhelp@athena.gsfc.nasa.gov

* For general information about the HEASARC, please visit

    http://heasarc.gsfc.nasa.gov/


*****************************************************************************
                     BUILDING AND INSTALLING HEASOFT
*****************************************************************************

The procedure for building and installing HEASOFT is modeled on GNU
software distributions.  As always, we recommend removing completely any
previous HEASOFT installation before proceeding.  A complete installation
guide follows below for both source code and binary distributions.  To
build a source code distribution, you will need to follow all of the
steps 1-8 in the installation section below; for pre-compiled binaries,
follow only steps 1-3 and 8.

For the latest information about supported architectures, operating
systems and compilers, please visit

  http://heasarc.gsfc.nasa.gov/lheasoft/support.html

and also see the known issues page at

  http://heasarc.gsfc.nasa.gov/lheasoft/issues.html

to learn of any problems identified after the latest version of HEASOFT
was released.

You will need the following to build this software:

  * Up to 2 GB free disk space (if installing all of HEASOFT):

    Actual space needed varies with system architecture and software
    packages selected.

  * Perl (5.6.0 or higher recommended):

    Many HEASOFT scripts are written in Perl, and since Perl is free
    and easy to install, we recommend you make sure a valid Perl is in
    your path before you start.  Please also note that our pre-compiled
    Perl libraries may suffer portability issues which are described in
    more detail at 

      http://heasarc.gsfc.nasa.gov/lheasoft/perl.html

  * X11 / X Windows:

    If you plan to use any graphical tools (XSPEC, XIMAGE, FV, fplot, etc.)
    you will need X11.  For more information, visit:

      http://www.x.org
      http://xquartz.macosforge.org/landing/

    Prior to installing HEAsoft, all users should make sure that they have
    included the X11 Development libraries as part of their X11 installation.
    On Linux, use the package manager (e.g. "yum" or "apt-get") to install
    e.g. "xorg-dev" or "libXt-devel".  The XQuartz installation available at
    the link above should provide the necessary development libraries and
    header files.

    Some users may find it necessary to specify the location of their X11
    libraries and header files to the configure script, e.g.

     ./configure --x-libraries=/usr/X11R6/lib --x-includes=/usr/X11R6/include

    In some newer operating systems, X11 is no longer found in the traditional
    location specified above and is in /usr/lib and /usr/include instead:

     ./configure --x-libraries=/usr/lib --x-includes=/usr/include

  * make (GNU make)

    GNU make (gmake) is *required* for building the source code distribution.
    If you do not have (g)make already, you should be able to easily install
    it using your package manager (yum, apt-get, fink, macports, etc.).
    Our configure script will determine whether an appropriate make
    utility is available.

  * C, C++, Fortran, and Perl compilers:

    Please visit 

      http://heasarc.gsfc.nasa.gov/lheasoft/support.html

    to review the latest information regarding supported compilers.

    We recommend the following:

      Linux/Cygwin: Use the default GNU compilers gcc, g++, gfortran,
      and perl located in /usr/bin/.

      Darwin: Use the default (Apple XCode / GNU) gcc, g++, and perl
      located in /usr/bin, and pair those with a supported Fortran
      compiler, for example g95 (from g95.org) or gfortran (from fink
      or MacPorts).  See the link above for more information.

    There are instructions below for choosing a specific compiler.

    A Python compiler is optional for Xspec users who wish to use the
    PyXspec module.  We recommend using only the default Python in
    /usr/bin/ for any architecture since it will be more compatible
    with code built by the default C compilers.


*****************************************************************************
                   STEP-BY-STEP INSTALLATION INSTRUCTIONS
*****************************************************************************

1) Visit the new HEASOFT download web page:

      http://heasarc.gsfc.nasa.gov/lheasoft/download.html

   Select either the source distribution or a pre-compiled binary
   distribution for PCs (Linux or Cygwin) or Macs (Darwin).  Then
   select the HEASOFT packages you wish to download.  Note that
   selecting any of the mission-specific packages will automatically
   select any required or recommended additional packages.

2) In the directory in which you want to install the software,
   unpack the file you downloaded in step 1 using e.g.:

      gunzip -c heasoft6.13(src|arch).tar.gz | tar xf -

   This will create a heasoft-6.13/ directory containing the software
   distribution.

3) Configure the software for your platform (necessary for both binary and
   source downloads):

   * If you downloaded the source distribution, go to the
     heasoft-6.13/BUILD_DIR directory:

      cd heasoft-6.13/BUILD_DIR/

   * If you downloaded the binary distribution, go to the
     heasoft-6.13/(PLATFORM)/BUILD_DIR directory:

      cd heasoft-6.13/(PLATFORM)/BUILD_DIR/
      where (PLATFORM) = e.g. "i686-pc-linux-gnu-libc2.5" or "i686-pc-cygwin"
 
   and run the main configure script, which will probe your system
   for libraries, header files, compilers, etc., and then generate
   the main Makefile.  IMPORTANT: if building from source, please
   read the information below about configuration options.

   To produce a default configuration, the configure script may simply
   be invoked in the following way (capturing the screen output from
   configure as shown here is recommended):

      ./configure >& config.out &     (C Shell variants)
      ./configure > config.out 2>&1 & (Bourne Shell variants)

   *** If you downloaded a pre-compiled binary distribution of HEASOFT,
       proceed now to step 8. ***


   CONFIGURE OPTIONS FOR HEASOFT SOURCE CODE DISTRIBUTION:

   On Linux, Cygwin and Darwin, configure will by default choose the first
   GNU and Perl compilers (gcc, g++, gfortran/g95, perl) it finds in your
   path (i.e.  the PATH environment variable; see also the "which" command).

   To force configure to choose a compiler in an alternate location, make
   sure the compilers you want to use exist and are functional, and then set
   the relevant environment variable(s) - CC (C compiler), CXX (C++ compiler),
   FC (Fortran compiler), or PERL (Perl) - to point to the compiler(s).  To
   accomplish this, you may either include directory paths in the variables
   themselves, for example:

     C-shell variants (csh, tcsh):       Bourne shell variants (bash, sh):

      setenv CC /usr/bin/gcc              export CC=/usr/bin/gcc
      setenv CXX /usr/bin/g++             export CXX=/usr/bin/g++
      setenv FC /usr/bin/gfortran         export FC=/usr/bin/gfortran
      setenv PERL /usr/bin/perl           export PERL=/usr/bin/perl

   Or, put the compiler's directory path ahead of everything else in your
   current path and just set the compiler variables to their name.  For
   example:

     C-shell variants (csh, tcsh):       Bourne shell variants (bash, sh):

      setenv PATH "/usr/bin:$PATH"        export PATH="/usr/bin:$PATH"
      setenv CC gcc                       export CC=gcc
      setenv CXX g++                      export CXX=g++
      setenv FC gfortran                  export FC=gfortran
      setenv PERL perl                    export PERL=perl

   These steps are only necessary if you wish to override configure's
   default choices.

   The configure script does accept a number of options which can be
   examined via "./configure --help", though most users are likely to
   only need or want the following:

   --prefix=dir   (SOURCE CODE DISTRIBUTION ONLY)

     Denotes where the libraries, executables, help files, etc.,
     are to be installed.  NOTE that this is slightly different
     than the sense in which "prefix" is used in GNU software,
     in that an additional system-dependent subdirectory will
     first be appended to the prefix argument, below which the
     bin/, lib/, and other directories will be created.
     If no prefix argument is supplied to configure, the default
     is the main heasoft-6.13/ directory itself.

     * In the HEADAS build environment, there are multiple layers of
     installed directories, so if you prefer to delete the source code
     after installing HEASOFT, it is recommended that you provide a
     prefix to configure which installs the software outside of the
     source code tree.

     * Darwin and Cygwin:  If you perform the software installation
     on a disk which has a space or spaces in its name, i.e.
     "/Volumes/Apps And Docs/" or "/cygdrive/My Documents/", the
     initialization step (referred to in step 8 below) will fail because
     it reads that as two separate paths.  Paths with underscores are okay.

4) * SKIP TO STEP 8 IF YOU ARE USING A PRE-COMPILED BINARY DISTRIBUTION *

   This step is only necessary if you are building the source code
   distribution:

   Start the build process. We strongly recommend that you capture all
   output into a log file. Then, if you need to report a problem,
   please send us the ENTIRE log file. And since it may take some time
   to run (from minutes to hours, depending on the speed of your system)
   we recommend that you build it in the background:

      make >& build.log &     (C Shell variants)
      make > build.log 2>&1 & (Bourne Shell variants)

   To check on the build progress in real-time (if you wish) try:

      tail -f build.log

5) VERY IMPORTANT: Check your build.log for errors before proceeding!
   If a problem occurs and is discovered at this point, it may be easy
   to correct (contact the appropriate help address listed above). By
   contrast, if an error occurs, but you continue with the next step,
   it may make resolving the problem more complex or more time-consuming.

   The easiest way to check your build.log for errors is to look
   for occurrences of the string ***. (Most UNIX utilities which
   use regular expression matching require these to be "escaped"
   using backslashes, e.g. \*\*\*).

6) Perform the final installation of the executables, libraries,
   help files, calibration data, perl scripts, etc, by executing:

      make install >& install.log &     (C Shell variants)
      make install > install.log 2>&1 & (Bourne Shell variants)

   This will create an appropriately-named system-dependent directory,
   e.g. i386-apple-darwin12.2.0/, either under heasoft-6.13/ or, if you
   specified a prefix argument to configure, (see step 3 above), in
   the directory you selected at that time.

7) VERY IMPORTANT: Check your install.log for errors before proceeding!
   The best method is the same as that described in step 5.

   At this point, HEASOFT should be completely installed, either
   under the directory heasoft-6.13/ or - if you gave a "--prefix"
   option to configure - under the prefix-ed directory you specified.
   Read the next section "INITIALIZATION AND SETUP" carefully to begin
   using the software.

   In the HEADAS build environment, there are multiple layers of
   installed directories, so if you did not provide an installation
   --prefix outside the source tree to the configure script in step 3,
   do NOT attempt to remove the HEASOFT source code after installation!

   If you now want to build and install for a different architecture
   or machine using the same source code tree, execute

      make distclean

   before starting over with step 3 above.

8) INITIALIZATION AND SETUP: 

   Please note that if you downloaded a pre-compiled binary distribution,
   you still MUST have run the configure script as described in step 3
   above before performing the software initialization described here.

   Now that you have installed the software, all that remains is to
   set up your environment to use it.  To initialize the software, we
   recommend the following:

   * For users of C Shell variants (csh, tcsh):

     Edit your $HOME/.cshrc to include lines based on the following:

      setenv HEADAS /path/to/your/installed/heasoft-6.13/(PLATFORM)
      alias heainit "source $HEADAS/headas-init.csh"

   * For users of Bourne Shell (sh, ash, ksh, and bash):

     Edit your $HOME/.bashrc (or $HOME/.login, or $HOME/.profile) to
     include lines based on the following:

      HEADAS=/path/to/your/installed/heasoft-6.13/(PLATFORM)
      export HEADAS
      alias heainit=". $HEADAS/headas-init.sh"

   From then on, you can simply type "heainit" when you log on, and
   your environment will be prepared to use the software.  Please note
   that the initialization is a "silent" process, i.e. if successful,
   you should not receive any output from typing your "heainit" command.

   In the examples above, (PLATFORM) reflects your machine's architecture,
   for example:

      i386-apple-darwin12.2.0
      i686-pc-linux-gnu-libc2.12
      x86_64-unknown-linux-gnu-libc2.12

   The version numbers above will vary depending on your machine.  If
   If you are unsure what the exact name of your installed location is,
   simply look in the heasoft-6.13/ directory (or under the directory
   you specified as a prefix to configure) to view the correct name.

   To find out which tools are available to you and to learn more about
   them, use the "fhelp" facility (run "fhelp -h" for more information),
   for example: "fhelp ftools.txt" will provide you with a complete list
   of tasks available in HEASOFT, and "fhelp ftverify" will display the
   help page for the ftverify task.


If you have trouble with any part of this process, please contact
the appropriate help desk for your software (see CONTACT INFORMATION
above), providing as much detail about the problem as you can.

Thank you for using HEASOFT!


*****************************************************************************
            ADDING LOCAL MODELS TO XSPEC 12 AFTER INSTALLATION
*****************************************************************************

NOTE: Local models can only be built using the HEASOFT source
      distribution.  Users should not remove their source distribution
      after installing in order for local model building to function
      properly.

In XSPEC 12, local models are always built into shared libraries which can
be loaded at xspec run-time.  This is performed with two new xspec commands,
'initpackage' and 'lmod', which simplify the process in comparison with
previous versions.  Please refer to Appendix C of the XSPEC 12 manual for
details.  There is no longer an option or need to build and install xspec
local models during the main HEASOFT build.  Those wishing to automate the
loading of their local model libraries upon xspec start-up (whether for
themselves or for system-wide users), should also refer to the "Customizing
XSPEC" section of the manual.