Installing HEASoft (For Source or Binary Distribution)

*****************************************************************************
HEASOFT 6.25 - 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 the appropriate page for your
operating system:
http://heasarc.gsfc.nasa.gov/lheasoft/ubuntu.html (PC Linux: Debian-based)
http://heasarc.gsfc.nasa.gov/lheasoft/fedora.html (PC Linux: RPM-based)
http://heasarc.gsfc.nasa.gov/lheasoft/macos.html (macOS / Mac OS X)
http://heasarc.gsfc.nasa.gov/lheasoft/cygwin.html (PC Cygwin)
Please also visit 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/ubuntu.html (PC Linux: Debian-based)
http://heasarc.gsfc.nasa.gov/lheasoft/fedora.html (PC Linux: RPM-based)
http://heasarc.gsfc.nasa.gov/lheasoft/macos.html (macOS / Mac OS X)
http://heasarc.gsfc.nasa.gov/lheasoft/cygwin.html (PC Cygwin)
to review the latest information regarding supported compilers
for your particular OS.
We recommend the following:
Linux/Cygwin: 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
managers:
apt-get install perl-modules
yum install perl-ExtUtils-MakeMaker
Darwin: Use the default (Apple XCode) clang (or gcc), clang++
(or g++), perl, and python located in /usr/bin, and pair those
with a supported Fortran compiler, for example g95 or gfortran
(from e.g. 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.
* 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
*****************************************************************************
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.25(src|arch).tar.gz | tar xf -
This will create a heasoft-6.25/ 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.25/BUILD_DIR directory:
cd heasoft-6.25/BUILD_DIR/
* If you downloaded the binary distribution, go to the
heasoft-6.25/(PLATFORM)/BUILD_DIR directory:
cd heasoft-6.25/(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
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
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
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:
--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.25/ 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.
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:
wcslib:
configure: WARNING: Compilation of Fortran wrappers and PGSBOX disabled
configure: WARNING: Compilation of WCS utilities disabled
configure: WARNING: CFITSIO disabled
configure: WARNING: PGPLOT disabled
itk:
configure: WARNING: Found Makefile - using build library specs for itcl
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. \*\*\*). You may safely ignore references
in the build log to "char ***" or '...__PRETTY_FUNCTION__," ***...'.
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-darwin17.7.0/, either under heasoft-6.25/ 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.25/ 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, do
the following:
* For users of C Shell variants (csh, tcsh):
setenv HEADAS /path/to/your/installed/heasoft-6.25/(PLATFORM)
source $HEADAS/headas-init.csh
* For users of Bourne Shell (sh, ash, ksh, and bash):
export HEADAS=/path/to/your/installed/heasoft-6.25/(PLATFORM)
. $HEADAS/headas-init.sh
In the examples above, (PLATFORM) is a placeholder for the platform-
specific string denoting your machine's architecture, for example:
x86_64-pc-linux-gnu-libc2.27
x86_64-apple-darwin17.7.0
The version numbers above will vary depending on your installation.
If you are uncertain what to use here, simply look in the heasoft-6.25/
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 edit the relevant file for their
shell (e.g. .cshrc, .bashrc, .login, .profile) to create an alias
for initializing HEASoft, for example:
For users of C Shell variants (csh, tcsh):
setenv HEADAS /path/to/your/installed/heasoft-6.25/(PLATFORM)
alias heainit "source $HEADAS/headas-init.csh"
For users of Bourne Shell (sh, ash, ksh, and bash):
HEADAS=/path/to/your/installed/heasoft-6.25/(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.
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" 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.