Installing HEASoft (For Source or Binary Distribution)

                         HEASOFT 6.29 - 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 Linux and Mac systems, available
for download at:

This document is also available online at:

                            CONTACT INFORMATION

* For more information, please see:     (FTOOLS)     (XSPEC, XIMAGE, XRONOS)  (FV)

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

* For correspondence regarding mission-specific software, please visit

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

* For online information about XSTAR please visit

  or contact the XSTAR help desk at:

* For general information about the HEASARC, please visit


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 the appropriate page for your
operating system: (PC Linux: Debian-based) (PC Linux: RPM-based)  (macOS / Mac OS X)

Please also visit the known issues page at

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 3 GB free disk space (if installing all of HEASOFT):

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

  * X11 / X Windows:

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

    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, Perl, Python:

    Please visit (PC Linux: Debian-based) (PC Linux: RPM-based)  (macOS / Mac OS X)

    to review the latest information regarding supported compilers
    for your particular OS.

    We generally recommend the following:

      Linux: Use the default GNU compilers gcc, g++, gfortran, and
      perl located in /usr/bin/.  Linux users may need to install
      extra modules for example using the "yum" or "apt-get" package

         apt-get install perl-modules
         yum install perl-ExtUtils-MakeMaker

      Darwin: We now recommend that you use only a set of third-party
      compilers such as the GCC packages offered by MacPorts or
      HomeBrew, and avoid using the XCode compilers.  See the macOS
      link above for the latest information.

    There are instructions below for choosing a specific compiler.

    Many HEASOFT scripts are written in Perl, so you will almost
    certainly want to have a Perl installation before you start.
    Please also note that our pre-compiled Perl libraries may
    suffer portability issues that are described in more detail at:

    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.

  * A terminal library (ncurses, curses, tinfo) is required for
    building HEASoft, and is typically available using a package
    manager, for example:

       apt-get install libncurses5-dev
       yum install ncurses-devel


1) Visit the new HEASOFT download web page:

   Select either the source distribution or a pre-compiled binary
   distribution for PCs (Linux) 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
   additional required or recommended 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.29(src|arch).tar.gz | tar xf -

   This will create a heasoft-6.29/ directory containing the software

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.29/BUILD_DIR directory:

      cd heasoft-6.29/BUILD_DIR/

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

      cd heasoft-6.29/(PLATFORM)/BUILD_DIR/
      where (PLATFORM) = e.g. "x86_64-pc-linux-gnu-libc2.31"

   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.txt &     (C Shell variants)
      ./configure > config.txt 2>&1 & (Bourne Shell variants)

   *** For Mac OS: You should commit to the location of the software
       prior to running the configure script.  Once you have built
       the software (or simply run configure in the case of the
       pre-compiled binaries), library paths are hard-coded into
       the executables, and they cannot easily be relocated.

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


   The configure script will by default choose the first GNU and Perl
   compilers (gcc, g++, gfortran, 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, zsh):

      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
      setenv PYTHON /usr/bin/python       export PYTHON=/usr/bin/python

   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

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

      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
      setenv PYTHON python                export PYTHON=python

   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:


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

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

   You may notice some WARNING messages in the screen output from configure,
   and may safely ignore those from the third-party packages wcslib and itk:

     configure: WARNING: Compilation of Fortran wrappers and PGSBOX disabled
     configure: WARNING: Compilation of WCS utilities disabled
     configure: WARNING: CFITSIO disabled
     configure: WARNING: PGPLOT disabled

     configure: WARNING: Found Makefile - using build library specs for itcl


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

   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. \*\*\*).  You may safely ignore references
   in the build log to "char ***".

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. x86_64-apple-darwin19.6.0/, either under heasoft-6.29/ 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.29/ 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.


   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, do
   the following:

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

      setenv HEADAS /path/to/your/installed/heasoft-6.29/(PLATFORM)
      source $HEADAS/headas-init.csh

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

      export HEADAS=/path/to/your/installed/heasoft-6.29/(PLATFORM)
      . $HEADAS/

   In the examples above, (PLATFORM) is a placeholder for the platform-
   specific string denoting your machine's architecture, for example:


   The version numbers above will vary depending on your installation.
   If you are uncertain what to use here, simply look in the heasoft-6.29/
   directory (or under the directory you specified as a prefix to configure)
   to find the correct name.

   Users who are more familiar with the UNIX environment and shell
   configuration files may wish to create an alias for these steps
   in their default shell (by editing e.g. .cshrc, .bashrc, .login,
   .profile, etc.).

   Please note that the initialization is a "silent" process, i.e. if
   successful, you should not receive any screen output.  Running a
   simple command such as "fhelp ftools" should provide an indication
   of success.  The "fhelp" utility provides help for each package and
   task in HEASoft (run "fhelp -h" for more information).  For example:
   "fhelp ftools" will provide you with a complete list of tasks
   available in HEASOFT, "fhelp heatools" will display an overview of
   the HEATOOLS package, 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!


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

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.


If FTOOLS has been useful in your research, please reference this site ( and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

Web page maintained by: Bryan K. Irby

HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Tuesday, 20-Jul-2021 12:35:50 EDT