***************************************************************************** HEASOFT 6.28 - 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: https://heasarc.gsfc.nasa.gov/lheasoft/download.html This document is also available online at: https://heasarc.gsfc.nasa.gov/lheasoft/install.html ***************************************************************************** CONTACT INFORMATION ***************************************************************************** * For more information, please see: https://heasarc.gsfc.nasa.gov/ftools (FTOOLS) https://heasarc.gsfc.nasa.gov/xanadu (XSPEC, XIMAGE, XRONOS) https://heasarc.gsfc.nasa.gov/ftools/fv (FV) For correspondence regarding all of these general utilities, please contact us via: https://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp * For correspondence regarding mission-specific software, please visit https://heasarc.gsfc.nasa.gov/cgi-bin/Feedback and select the appropriate mission under "Choose a mailing list". * For online information about XSTAR please visit https://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 https://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: https://heasarc.gsfc.nasa.gov/lheasoft/ubuntu.html (PC Linux: Debian-based) https://heasarc.gsfc.nasa.gov/lheasoft/fedora.html (PC Linux: RPM-based) https://heasarc.gsfc.nasa.gov/lheasoft/macos.html (macOS / Mac OS X) Please also visit the known issues page at https://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 3 GB free disk space (if installing all of HEASOFT): Actual space needed varies with system architecture and software packages selected. * Perl: 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 https://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: https://www.x.org https://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, Perl, Python: Please visit https://heasarc.gsfc.nasa.gov/lheasoft/ubuntu.html (PC Linux: Debian-based) https://heasarc.gsfc.nasa.gov/lheasoft/fedora.html (PC Linux: RPM-based) https://heasarc.gsfc.nasa.gov/lheasoft/macos.html (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 managers: 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. 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: https://heasarc.gsfc.nasa.gov/lheasoft/download.html 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.28(src|arch).tar.gz | tar xf - This will create a heasoft-6.28/ 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.28/BUILD_DIR directory: cd heasoft-6.28/BUILD_DIR/ * If you downloaded the binary distribution, go to the heasoft-6.28/(PLATFORM)/BUILD_DIR directory: cd heasoft-6.28/(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.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: 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): 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.28/ 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: 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 ***". 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.28/ 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.28/ 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.28/(PLATFORM) source $HEADAS/headas-init.csh * For users of Bourne Shell (sh, ash, ksh, and bash): export HEADAS=/path/to/your/installed/heasoft-6.28/(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.31 x86_64-apple-darwin19.6.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.28/ 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.28/(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.28/(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.