Search:

[Advanced Search]



Installing HEASoft - Mac


Instructions for Source Code or Pre-Compiled Binary distributions



  • SOURCE CODE INSTALLATION:
    • Installations from the source code are generally recommended over the pre-compiled binaries to avoid any potential portability issues. Note also that source code builds are required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).

      The instructions below assume that you have already       downloaded a HEASoft source code tar file and have unpacked it (using e.g. "tar zxf [tar file]") on your machine.

      Previous HEASoft releases required use of the Rosetta binary translation utility on Apple Silicon hardware, but this restriction was lifted starting with HEASoft 6.31. The default build mode of HEASoft on Silicon Macs is now the native arm64 architecture.

    • Prerequisites:

      If they aren't installed already, you will need to install a few system-level packages required for building HEASoft from the source code distribution:

      • X11:

        We recommend XQuartz but X11 is also available via the various Mac package managers.

      • Compilers: C, C++, Perl & Fortran:

        The HEASoft 6.31 release restores support for the Apple XCode C compilers (/usr/bin/clang,clang++,perl), and we recommend using these:

        • Apple XCode: For best performance, we recommend using the native Apple C and Perl compilers provided by the XCode Command Line Tools (CLT) (/usr/bin/clang, /usr/bin/clang++, /usr/bin/perl). Please also note that having out-of-date CLT can result in malfunctions in third-party software (such as the Fortran compiler) so make sure that they are up-to-date with your OS by running: 
            % xcode-select --install


        • A Fortran compiler: A Fortran compiler is not provided by XCode but can be installed using any of the various Mac package managers. Homebrew and MacPorts are the ones used and tested most at the HEASARC and are therefore recommended above other options. Note also that when updating your Mac OS or XCode version, it is typically necessary to reinstall any third-party packages for compatibility with the new system.

          For example, install gfortran from the Homebrew gcc@12 package (after installing Homebrew itself): 
              % brew install gcc@12

    This provides /usr/local/bin/gfortran-12 (Intel) or /opt/homebrew/bin/gfortran-12 (Silicon)

          Or, install gfortran from the MacPorts gcc12 package (after installing MacPorts itself): 

              % sudo port install gcc12

    This provides /opt/local/bin/gfortran-mp-12 (Intel or Silicon)
          While you're doing this, you may also want to install the "libpng" package if you'd like to use the PNG driver in PGPLOT (the plotting package in HEASoft used by fplot and others): 
              % sudo port install libpng

    or

    % brew install libpng
          When configuring heasoft, you may then also need to use this configure option, otherwise the PNG driver in PGPLOT will not be activated: 
              % ./configure --with-png=/opt/local

    or

    % ./configure --with-png=/opt/homebrew

    etc.
      • Python:

        Python is required if you wish to use the Python tools and interfaces in HEASoft (includes IXPE tools, HEASoftPy, PyXspec, and HEASP. HEASoftPy and other packages (IXPE, NICER) require Python 3.6 (or newer), as well as pip, AstroPy (v4.0.0 or newer), NumPy (v1.7.0 or newer), SciPy (v1.5.0 or newer), NumPy (v1.7.0 or newer), SciPy (v1.5.0 or newer), and MatPlotLib, some of which are not provided for the XCode Python environment. Therefore, we recommend using e.g. Anaconda / Miniconda to install Python 3 and the requisite packages in for example your home directory: 

          % conda install astropy numpy scipy matplotlib pip

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

  % export PYTHON=$HOME/miniconda3/bin/python3   % setenv PYTHON $HOME/miniconda3/bin/python3

    • Configuring the software:

      After the prerequisite packages have been installed, the next step is to configure the software. The safest way to ensure that the correct compilers are used by HEASoft is to employ the standard environment variables CC (C compiler), CXX (C++ compiler), FC (Fortran compiler), PERL (Perl interpreter), and PYTHON (Python interpreter). For example: 

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

    % export CC=/usr/bin/clang                     % setenv CC /usr/bin/clang
    % export CXX=/usr/bin/clang++                  % setenv CXX /usr/bin/clang++
    % export PERL=/usr/bin/perl                    % setenv PERL /usr/bin/perl
    % export FC=/opt/homebrew/bin/gfortran-12      % setenv FC /opt/homebrew/bin/gfortran-12
    % export PYTHON=$HOME/miniconda3/bin/python3   % setenv PYTHON $HOME/miniconda3/bin/python3
      If these variables are not used, the HEASoft configure script will attempt to find the necessary items in one of the directories listed in your PATH environment variable, but success is not guaranteed.

      External packages (e.g. Anaconda) may set compiler or other flags in the environment which can negatively impact a HEASoft build, so Mac users are advised to unset any "FLAGS" or "alias" variables and to put the XCode /usr/bin at the front of their PATH (i.e. ahead of any third-party packages that may have inserted themselves into the PATH): 
         In Bourne shell variants (bash/sh):

    % unset CFLAGS CXXFLAGS FFLAGS LDFLAGS build_alias host_alias
    % export PATH="/usr/bin:$PATH"

   In C-shell variants (tcsh/csh):

    % unsetenv *FLAGS build_alias host_alias
    % setenv PATH="/usr/bin:$PATH"
      Alternatively, users may alter their session to cancel any Anaconda or other package initialization by editing their profile or other shell resource files (.bashrc, .cshrc, etc.).

      Other software packages (e.g. XMM-SAS) may change your DYLD_LIBRARY_PATH environment variable, and this can break a HEASoft build, so you are advised to check your DYLD_LIBRARY_PATH variable and remove any paths that aren't necessary. Typically this variable can remain empty when configuring HEASoft.

      Before configuring HEASoft, note that you should commit to the location of the installed software prior to running the configure script. Once you have built the software, library paths are hard- coded into the executables, and they will not function correctly if relocated.

      Also please also note that the compiler settings described above will NOT pass to a sudo shell, so if you want to install HEASoft in a protected location (such as /usr/local), you should configure and build the software WITHOUT using sudo in a location writeable by you (e.g. your home directory), and use 'sudo' only when performing the final 'make install' step below.

      Next, configure the software, optionally capturing the screen output to a text file for reference as shown here: 
       In Bourne shell variants (bash/sh/zsh):  In C-shell variants (tcsh/csh):

    cd heasoft-6.33.1/BUILD_DIR/            cd heasoft-6.33.1/BUILD_DIR/
    ./configure > config.txt 2>&1           ./configure >& config.txt
      The configure process may take several minutes to complete. If it is successful, the last line of screen output - or the last line in the "config.txt" file - should read "Finished". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for aid, or contact the help desk.

    • Building the software:

      If the configure was successful, proceed to build the software, again optionally capturing the screen output to a text file for reference as shown here: 
       In Bourne shell variants (bash/sh/zsh):  In C-shell variants (tcsh/csh):

    make > build.txt 2>&1                   make >& build.txt
      This process may take an hour or more to run, depending on your hardware and HEASoft download selections. If it is successful, the last line of output (in build.txt) should read "Finished make all". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for aid, or contact the help desk.

    • Installing the software:

      If 'make' was successful, proceed to install the software, again optionally capturing the screen output to a text file for reference as shown here: 
       In Bourne shell variants (bash/sh/zsh):  In C-shell variants (tcsh/csh):

    make install > install.txt 2>&1         make install >& install.txt
      This process may take 30-45 minutes to run, depending on your hardware and HEASoft download selections. If it is successful, the last line of output (in install.txt) should read "Finished make install". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for aid, or contact the help desk.

    • Initialization:

      If the "configure" step was successful, you may proceed with initializing the software. The following are example commands which you will modify to be appropriate for your system: 
         For users of Bourne Shell (sh, ash, ksh, bash, zsh):

    export HEADAS=/path/to/your/installed/heasoft-6.33.1/(PLATFORM)
    source $HEADAS/headas-init.sh

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

    setenv HEADAS /path/to/your/installed/heasoft-6.33.1/(PLATFORM)
    source $HEADAS/headas-init.csh
      In these commands, "/path/to/your/installed" is a placeholder for the actual directory path on your system identifying the location in which you unpacked heasoft, and "(PLATFORM)" is a placeholder for the platform-specific string denoting the architecture of the pre-compiled binaries you chose, for example: 
          aarch64-apple-darwin22.6.0
      The initialization is silent and only generates a message if there is an error. If it is successful, you may begin using the software. For example, type "fhelp ftools" to see a full listing of possible tools, or type "xspec" to start the Xspec spectral analysis program.

    • Calibration Database (CALDB):

      Many HEASoft tasks require access to the CALDB, which is available separately from HEASoft. The simplest way to access the CALDB is remotely, assuming a good internet connection is available. Alternatively, the CALDB may be installed locally on your system.

    • Uninstalling HEASoft:

      For guidance about removing a HEASoft installation from your system, please refer to our uninstall guide.


  • PRE-COMPILED BINARY INSTALLATION:
    • Installations of the pre-compiled binaries are not recommended due to the lack of portability of pre-compiled Perl libraries and other potential portability issues. Note that installations from the source code distribution are required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).

      The instructions below assume that you have already downloaded a HEASoft pre-compiled binary tar file and have unpacked it (using e.g. "tar zxf [tar file]") on your machine.

    • Prerequisite packages (Pre-Compiled Binaries):

      • X11:

        X11 is required in order to use any of the GUI tasks (FV, et al.). We recommend XQuartz but X11 is also available via the various Mac package managers.

      • Apple XCode:

        To make sure the necessary XCode utilities (perl and install_name_tool) are installed, you should install the Command Line Tools using this command: 

          xcode-select --install
      • Python:

        Python is required if you wish to use the Python tools and interfaces in HEASoft (includes IXPE tools, HEASoftPy, PyXspec, and HEASP. HEASoftPy and other packages (IXPE, NICER) require Python 3.6 (or newer), as well as pip, AstroPy (v4.0.0 or newer), NumPy (v1.7.0 or newer), SciPy (v1.5.0 or newer), and MatPlotLib, some of which are not provided for the XCode Python environment. Therefore, we recommend using e.g. Anaconda / Miniconda to install Python 3 and the requisite packages in for example your home directory: 

          % conda install astropy numpy scipy matplotlib pip

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

  % export PYTHON=$HOME/miniconda3/bin/python3   % setenv PYTHON $HOME/miniconda3/bin/python3
    • Configuring the software (Pre-Compiled Binaries):

      After the prerequisite packages have been installed, the next step is to configure the software: 
          cd heasoft-6.33.1/(PLATFORM)/BUILD_DIR/
    ./configure

    (optionally capturing the screen output to a text file e.g., "config.txt")
      The configure process may take several minutes to complete. If it is successful, the last line of screen output - or the last line in the "config.txt" file - should read "Finished". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for aid, or contact the help desk.

      If the configure script yields a message about a "Perl mismatch", you will either need to install HEASoft from the source code distribution, or install a version of Perl which matches that listed for your platform in our Perl reference.

    • Initialization:

      If the "configure" step was successful, you may proceed with initializing the software. The following are example commands which you will modify to be appropriate for your system: 
         For users of Bourne Shell (sh, ash, ksh, bash, zsh):

    export HEADAS=/path/to/your/installed/heasoft-6.33.1/(PLATFORM)
    source $HEADAS/headas-init.sh

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

    setenv HEADAS /path/to/your/installed/heasoft-6.33.1/(PLATFORM)
    source $HEADAS/headas-init.csh
      In these commands, "/path/to/your/installed" is a placeholder for the actual directory path on your system identifying the location in which you unpacked heasoft, and "(PLATFORM)" is a placeholder for the platform-specific string denoting the architecture of the pre-compiled binaries you chose, for example: 
          x86_64-apple-darwin21.6.0
      The initialization is silent and only generates a message if there is an error. If it is successful, you may begin using the software. For example, type "fhelp ftools" to see a full listing of possible tools, or type "xspec" to start the Xspec spectral analysis program.

    • Calibration Database (CALDB):

      Many HEASoft tasks require access to the CALDB, which is available separately from HEASoft. The simplest way to access the CALDB is remotely, assuming a good internet connection is available. Alternatively, the CALDB may be installed locally on your system.

    • Uninstalling HEASoft:

      For guidance about removing a HEASoft installation from your system, please refer to our uninstall guide.


      • HEASoft / FTOOLS Help Desk

      If FTOOLS has been useful in your research, please reference this site (https://heasarc.gsfc.nasa.gov/ftools) 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: Thursday, 21-Mar-2024 16:58:08 EDT