Installing HEAsoft (For Source or Binary Distribution)

*****************************************************************************
                         HEASOFT 6.11.1 - INTRODUCTION
*****************************************************************************

New as of HEASOFT 6.0 is the HEADAS build environment which replaces
earlier versions of configuration files and Makefiles as used in
HEASOFT 5.3.1.  The build procedure remains basically the same
however, i.e. modeled after a typical GNU software distribution.
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 traditional HEASARC software (FTOOLS, XANADU, XSTAR).

As always, we recommend removing completely any previous HEASOFT
installation before proceeding.  Users who have recently made use of
the Swift software distributions should note that starting with this
release we no longer require you to set both LHEASOFT and HEADAS
environment variables before initializing the software.  Since the
older (LHEASOFT) packages have been moved to the new HEADAS system,
there is only one environment variable (HEADAS) to set, and we have
dispensed with usage of the temporary "hinit.csh/.sh" file.  See the
instructions below for full details regarding initialization of the
software.
 
This document is a guide to installing HEASOFT 6.11.1 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 online information about FTOOLS or FV please see:

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

For correspondence regarding FTOOLS, HEATOOLS or FV please send us mail via:

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

For correspondence regarding SWIFT please visit:

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

and select Swift under "Choose a mailing list".

For online information about XANADU (XIMAGE, XRONOS and XSPEC), please see:

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

For correspondence regarding XANADU (XIMAGE, XRONOS or XSPEC), send email to:

    xanprob@athena.gsfc.nasa.gov

For online information about XSTAR please see:

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

For correspondence regarding XSTAR please send email to:

    xstarhelp@athena.gsfc.nasa.gov

For general online information on the HEASARC, please see:

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


*****************************************************************************
                SUPPORTED ARCHITECTURES AND OPERATING SYSTEMS
*****************************************************************************

For the latest information about supported architectures, operating
systems and compilers, all users should visit this web page:

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


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

The procedure for building and installing HEASOFT is modeled on GNU
software distributions.  As always, changes in the package structure
since the last release have prompted a few changes in the procedure,
so please read this entire document before continuing, and follow
the instructions step by step.

                          BEFORE YOU START

Please visit the known bugs page at

         http://heasarc.gsfc.nasa.gov/lheasoft/bugs.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 building all of HEASOFT)
     Actual space needed varies with system architecture and software
     packages selected.

 - ANSI C compiler
     We support the proprietary compilers on SunOS 5.6 (Solaris 2.6)
     and higher, and gcc v3.1 or higher on all platforms.  The default
     compiler chosen by configure on SunOS is the proprietary "cc".
     On Linux, Darwin, and Cygwin systems, only the GNU compilers are
     supported, and gcc (cc/gcc on Darwin) is chosen first by configure.
     There are instructions below for choosing a specific compiler.

 - ANSI C++ compiler (several caveats, so please read carefully)
     On SunOS 5.6 (Solaris 2.6) and higher, we support (and recommend) the
     proprietary "CC" compiler (SunStudio12 preferred), and also g++ 3.1 or
     higher.  For all other platforms we only support g++ 3.1 and higher.

     Some packages (notably Xspec 12) may require more recent versions of g++.
     Please note that there is a problem with g++ 3.4.3 that prevents Xspec 12
     from linking, but otherwise the 3.2.x, 3.3.x, and 3.4.x or 4.x.x compilers
     should be sufficient to build Xspec 12.

     There are instructions below for choosing a specific compiler.

 - Fortran compiler
     * On PC Linux, the GNU Fortran compiler (gfortran or g77) is recommended.
     * On Mac OS X, g95 (fink-installed or from http://www.g95.org/) is
       recommended, but gfortran (fink- or macports-installed) is also
       supported.
     * On SunOS/Solaris, we recommend f95 (Workshop or SunStudio) but
       gfortran is also supported.

 - make
     GNU make (gmake) is *required* for building our software.  If you
     do not have gmake installed, you can obtain it by anonymous ftp
     via the GNU website:

        http://www.gnu.org/order/ftp.html

     Note that on most Linux and Mac OS X platforms, the default
     "make" command is GNU make (gmake) though (as on Mac OS X)
     it may not necessarily be named "gmake".  Our configure script
     will determine whether the appropriate make utility is available.

 - 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.

 - X11 / X-Windows
     If you plan to use any graphical tools (XSPEC, XIMAGE, FV, etc.) you
     will need X11.  See http://www.X11.org/ or http://www.xdarwin.org/.

     Prior to building HEAsoft, all users should make sure that they
     have included the X11 Development libraries as part of their X11
     installation.  For Mac OS X users, the "X11 SDK" is included in
     the "packages" folder of Apple's XCode developer tools, which
     should be on your Mac OS X CD distribution.  If not, it's available
     from the Apple XCode website:

          http://developer.apple.com/tools/xcode/.

     or via the fink utility as the "x11-dev" package. 

     Linux users should use the "sudo apt-get" method to install "x-dev",
     (or "xorg-dev"), "libx11-dev", and "libxt-dev" packages.

     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


*****************************************************************************
                   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 Linux (PC or MAC), Darwin (Intel or PPC), Solaris,
   or Cygwin.  Then select the HEASOFT packages you wish to download.
   Note that selecting any of the mission-specific packages will
   automatically select any 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 heasoft-6.11.1<src|arch>.tar.gz | tar xf -

   This will create a heasoft-6.11.1/ 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.11.1/BUILD_DIR directory:

      cd heasoft-6.11.1/BUILD_DIR/

   * If you downloaded the binary distribution, go to the
     heasoft-6.11.1/<PLATFORM>/BUILD_DIR directory:

      cd heasoft-6.11.1/<PLATFORM>/BUILD_DIR/
      where <PLATFORM> = e.g. "i686-pc-linux-gnu-libc2.3.4" 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 by (we recommend capturing the screen output from configure
   as below):

      ./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 DISTRIBUTION:

   By default, configure will choose a proprietary compiler (cc) for
   Solaris, and will choose gcc for Linux, Darwin, and Cygwin.
   For C++ compilers (not required for all packages), configure will
   choose "CC" on Solaris (recommended), and g++ everywhere else.
   For Fortran compilers, configure will choose g77 or gfortran on
   Linux, g95 on Darwin, and f90 or f95 on Solaris.

   To override these choices, make sure the compilers you want to use exist,
   are functional, and in your path, and set the CC (for C compiler) and 
   CXX (for C++ compiler) environment variables.  For example, to use
   supported GNU compilers, in C Shell variants, type:

      setenv CC gcc
      setenv CXX g++
      setenv FC g77

   and in Bourne shell variants, type:

      CC=gcc
      export CC

      CXX=g++
      export CXX

      FC=g77
      export FC

   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:

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

      --prefix=dir
           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.11.1/ directory itself.

           * NOTE FOR DARWIN and CYGWIN USERS:  If you perform the software
           installation on a disk which has a space or spaces in its name,
           i.e. ("/local/scratch G3/heasoft-6.11.1/") the initialization step
           (referred to in the INITIALIZATION AND SETUP section below) will
           fail because it reads that as two separate paths.  Paths with
           underscores are okay.

      --enable-static
           Supplying this option will add the appropriate flags to your
           build such that all linking with HEASOFT libraries will be
           done statically rather than dynamically (as is the default).

           This option is not available for builds which include XSPEC 12,
           as the method by which local models are used relies on dynamic
           loading of the models library(ies).

           * NOTE FOR DARWIN and CYGWIN USERS:  Libraries containing Fortran
           must be built statically, but this is handled internally by our
           configure script, so you do not need to provide this flag to
           configure under Darwin or Cygwin.


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! 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. sparc-sun-solaris2.9/, either under heasoft-6.11.1/ 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! The best
   method is the same as that described in step 5.

8) At this point, HEASOFT should be completely installed, either
   under the directory heasoft-6.11.1/ or under the prefix <dir> you
   specified to configure.  Read the next section "INITIALIZATION AND
   SETUP" carefully to begin using the software.

   ******* VERY IMPORTANT *********************************************
   In the new 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
   out of the same source tree, execute:

      make distclean

   before logging into the new machine and starting again with Step 3 above.


*****************************************************************************
                        INITIALIZATION AND SETUP
*****************************************************************************

* NOTE that if you downloaded a precompiled 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 and 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.11.1/<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.11.1/<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.

   In the examples above, <PLATFORM> reflects your machine's architecture,
   for example:

      i686-pc-linux-gnu-libc2.5
      i386-apple-darwin10.8.0
      powerpc-apple-darwin9.8.0
      sparc-sun-solaris2.9

   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 headas directory (or under the <dir> you specified
   as a prefix to configure) to view the correct name.


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!


* A final note on usage: In order to view the newer HEADAS help files
  which are all in HTML format, you must have either Netscape or the
  linemode browser "lynx" installed on your system.  See "fhelp -h" for
  more information.


*****************************************************************************
            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 (see also the
      *** VERY IMPORTANT *** note in steps 3 and 8).

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.