[an error occurred while processing this directive]

HEASoft v6.32.1 - Known Issues

If you are using HEASoft v6.31.1 and don't want to upgrade to v6.32* just yet, see the HEASoft 6.31.1 Issues List.

Several packages track issues separately from this page:

The following is a list of known issues in HEASoft not covered by the above pages.

Last modified Thursday, 08-Feb-2024 17:05:08 EST

Xspec on older Macs:

Compilation of Xspec may fail on Macs running older macOS (10.15 Catalina or older), with the error:

'timespec_get' was not declared in this scope

Users should be able to get past this by editing lines 47-51 of

     heasoft-6.32.1/Xspec/src/XSutil/Utils/TimeUtility.cxx

to change this code block:

     # if defined(__APPLE__)
         timespec_get(&tnow, TIME_UTC);
     #else
         clock_gettime(CLOCK_REALTIME, &tnow);
     #endif

To just this:

     clock_gettime(CLOCK_REALTIME, &tnow);

FV in Virtual Machines:
When used on Virtual Desktops (e.g. VirtualBox), FV windows may appear blank. This issue may be mitigated by disabling "3D acceleration" in the display options.

addascaspec:
When specifying both of the optional 'outbgd' and 'errmeth' parameters for addascaspec, it fails with "Fortran runtime error: Cannot open file 'mathpha_expr': No such file or directory". A fix is provided here. To fix the problem, download that file and then:
```
Copy the new "addascaspec" into this folder (source code distribution only):

heasoft-6.32[.1]/ftools/asca/tasks/addascaspec/

Next, initialize heasoft and then:

% cd heasoft-6.32[.1]/asca/tasks/addascaspec/
% hmake install
```

xselect, nuproducts, et al.:

Some Ubuntu (and other?) Linux users may find that xselect causes a crash in e.g., nuproducts or other scripts, reporting messages such as the following:

The source file: /[path]/xsel134999_histI.xsldoesn't exist.

or

/bin/cp: cannot stat '/[path]/xsel134999_histI.xsl':
No such file or directory

or

-------------------- nuproducts  error -----------------------
nuproducts_0.3.3: Unable to copy file: '134999_bk.pha' in
'./nu50801001002A01_bk.pha'. No such file or directory

This appears to result from an uninitialized variable, and is addressed in a patch here. To rebuild xselect and fix the problem, download that file and then:

Copy the new "xsel_bin.f" into this folder (source code distribution only):

heasoft-6.32[.1]/ftools/xselect/xselflib/

Next, initialize heasoft and then:

% cd heasoft-6.32[.1]/ftools/xselect/xselflib/
% hmake clean
% hmake all
% hmake install

ximage "ra_dec_to_pixel":

Use of the ximage command ra_dec_to_pixel may result in the following error message:

[XIMAGE> ra_dec_to_pixel
Conversion based on MAP1
missing operator at _@_
in expression " $coord_@_{system} eq "EQUATORIA..."

A fix is provided here. To fix the problem, download that file and then:

Copy the new "ra_dec_to_pixel.tcl" into this folder (source code distribution only):

heasoft-6.32[.1]/ftools/image/ximage/tcl/

Next, initialize heasoft and then:

% cd heasoft-6.32[.1]/ftools/image/
% hmake install

fkeypar:
In HEASoft 6.32 the task fkeypar was replaced with a wrapper to the task ftkeypar (which was designed to supplant fkeypar many years ago). A bug in the new wrapper may cause corruption of the fkeypar parameter file (~/pfiles/fkeypar.par) if fkeypar is used to read a keyword that doesn't exist. To fix this issue, please run "punlearn fkeypar" and switch to using ftkeypar directly instead.

IXPE & MatPlotLib:
The IXPE task ixpeplot_polarization may fail with a cryptic and unhelpful error message when using MatPlotLib older than version 3.7.0. To fix this issue, update to version 3.7.0 (or newer).

IXPE & AstroPy:
Due to a bug in certain 5.x versions of AstroPy, some files (such as the IXPE Level 1 event files) containing variable-length arrays may trigger in several IXPE tools a "ValueError" with the message "the heapsize limit for 'P' format has been reached. Please consider using the 'Q' format for your file.", even if the file is already formatted with the "Q" format. Affected versions of AstroPy appear to be 5.0.5, 5.0.6, 5.1.1, 5.2, 5.2.1, and 5.2.2, so users encountering this issue are advised to update to v5.3.0 or newer.

Mac "Configure failed":
The HEASoft configure script may fail with "C compiler cannot create executables", "Configure failed in the AST package!", or "configure failed for heacore component fftw!", and one of the config.logs may show

ld: library not found for -lSystem

This error typically implies that third-party compiler suites (e.g. Homebrew or MacPorts, needed in order to provide a Fortran compiler) are out-of-synch with the Apple (XCode) Command Line Tools (CLT), for example if you updated the CLT but did not reinstall MacPorts or Homebrew after doing so. Since these third-party compilers use the CLT, they must typically be rebuilt/reinstalled whenever XCode/CLT are updated.

For example, some users have worked their way past this by uninstalling the CLT and then reinstalling the CLT, then uninstalling and reinstalling the Homebrew compilers.

Other compiler-related failures during the configure stage can typically be resolved by putting /usr/bin at the front of your PATH environment variable (as recommended in our Mac installation guide), e.g. to put the Apple assembler and other system utilities ahead of third-party versions in order of preference.

WSL and Windows PATH variables:

Some users of WSL on Windows may have PATH environment variables that contain directory paths containing double quotes ("). The HEASoft initialization will fail as a result, so users need to modify their PATH variable to remove the offending characters.

CentOS 7.x compilers: Note for users of CentOS 7.x: On CentOS 7, the default GNU compiler suite is v4.8, which is not supported for building HEASoft. CentOS 7 users may install a newer 'devtoolset' compiler suite for use in building HEASoft, in the following way (for example):

    sudo yum -y install devtoolset-9
    scl enable devtoolset-9 bash

    Locate the devtoolset-9 installed directories:

    gcc -print-search-dirs
    /opt/rh/devtoolset-9/root/usr/lib/gcc/x86_64-redhat-linux/9

    In the next step, set the compiler variables accordingly (for example):

    export CC=/opt/rh/devtoolset-9/root/usr/bin/gcc
    export CXX=/opt/rh/devtoolset-9/root/usr/bin/g++
    export FC= /opt/rh/devtoolset-9/root/usr/bin/gfortran

    You will likely also need to update your LD_LIBRARY_PATH to include
    the path to the libraries needed by these compilers (for example):

    export LD_LIBRARY_PATH=/opt/rh/devtoolset-9/root/usr/lib

Using "sudo" or "screen":

Since configuring HEASoft typically works best when setting environment variables to point to specific compilers, using sudo at the configure stage is not recommended since sudo spawns a new shell that does not automatically inherit current environment settings. The sudo command should not be needed for configuring in any case; it should only be necessary when running "make install", and only then if you are writing to a root-protected area (e.g. /usr/local or /Applications).

Similarly, the screen command does not inherit all environment variables, so if you spawn a screen session before running the configure script, be sure to check or set environment variables after starting the screen utility.

"Developer cannot be verified" or "unidentified developer" error on Macs:

Some Mac users have reported problems configuring and/or running pre-compiled HEASoft binaries. To free HEASoft binaries from the Apple quarantine, use the xattr utility, e.g.:
```
$ cd heasoft-6.31.1/x86_64-apple-darwin20.6.0
$ xattr -r -d com.apple.quarantine BUILD_DIR/configure lib/* bin/*
```

Fortran compiler requirements:

HEASoft now includes a new dependency on the FGSL library which requires a Fortran 2008 feature (c_loc for targeted arrays); therefore GNU Fortran compilers older than version ~5.x are unsupported.

Perl symbol lookup error, "undefined symbol: Perl_Gthr_key_ptr":
If running a HEASoft Perl script generates an error similar to the above, it may result from a Perl version incompatibility (common when using the pre-compiled binaries), but it may also occur if you have the VERSIONER_PERL_PREFER_32_BIT environment variable set to "yes". If "echo VERSIONER_PERL_PREFER_32_BIT" returns "yes", then unset it:
```
   unset VERSIONER_PERL_PREFER_32_BIT

or, in C-shell:

   unsetenv VERSIONER_PERL_PREFER_32_BIT
```
MacPorts "unexpected token" linker issue:
If you are using MacPorts compilers in your build, 'make' may fail when building the HEASoft source code distribution with an error referring to a new Xcode linker ("ld") format ("tbd"), e.g.:
```
ld: in '/System/Library/PrivateFrameworks/CoreEmoji.framework/Versions/A/CoreEmoji.tbd', unexpected token: !tapi-tbd-v2 ...
```
The underlying issue is discussed here and here; it appears that when new versions of the XCode command line tools are released, problems such as this may affect MacPorts compilers until they catch up with Apple's changes. Users should be able to get around the error in our build by installing the MacPorts 'xcode' variant of the linker ld64 as a temporary measure:
```
    sudo port install ld64 +ld64_xcode
```
and when MacPorts eventually supports the latest XCode command line tools, you can switch back to the latest ld64 with the following:
```
    sudo port install ld64 +ld64_latest
```
Mac "suffix or operands invalid for 'movq'" Fortran compiler issue:
When using the gnu.org gfortran binaries note their recommendation that when installing new versions of the compiler you should remove the previous gfortran installation first:
```
   $ sudo rm -r /usr/local/gfortran /usr/local/bin/gfortran
```
Failure to do so may result in a corrupted compiler installation, leading to the "suffix or operands invalid for 'movq'" error.

Ubuntu ds9 & HEASoft:

After initializing HEASoft on Ubuntu Linux, the ds9 GUI (if installed) may fail to start up (mentioning "can't find package xml", "can't find package uri 1.1", or "package require base64""). This results from incompatibilities between the Tcl/Tk included with HEASoft and the Ubuntu system libraries. Until a more elegant solution can be devised, we recommend that users try one of the following options, depending on the file type of your ds9 (shell script or compiled executable - check the output from "file `which ds9`" to determine which it is):


1) If ds9 is the shell script version, edit it to change the line

     exec wish8.6 -f ${DS9_HOME-/usr/share/saods9}/library/ds9.tcl $*

   to

     exec /usr/bin/env -u LD_LIBRARY_PATH /usr/bin/wish8.6 -f ${DS9_HOME-/usr/share/saods9}/library/ds9.tcl $*

or

2) If ds9 is the compiled executable version, create a new file
   "$HEADAS/bin/ds9" containing the following lines:

     #!/bin/sh
     exec /usr/bin/env -u LD_LIBRARY_PATH /usr/bin/ds9 "$@"

   (Note this assumes that `which ds9` = /usr/bin/ds9)

   To make the new script executable, run the following command:

     $ chmod +x $HEADAS/bin/ds9

   Then, as long as $HEADAS/bin is ahead of /usr/bin in your PATH, you
   should now be able to successfully run ds9 from the command line:

     $ rehash
     $ ds9

"relocation R_X86_64_32 against `.rodata' can not be used when making a shared object":

Users building HEASoft from the source code distribution may run into this error which refers to a "Bad value" in the file heacore/wcslib/C/cel.o, from which the linker "could not read symbols". It also suggests that you "recompile with -fPIC". This situation most likely occurrs when users perform a re-build after a previously unsuccessful build attempt. To get past this issue, try the following:
```
   $ cd heasoft-6.31.1/BUILD_DIR
   $ make distclean
```
When that finishes, restart the build procedure beginning with "./configure", then "make", and let us know if this does not resolve the problem.

fv - XPA_METHOD:

Some users of the fv GUI may experience long delays at startup, or error messages of the type "XPA$WARNING: xpans needs to be running on this machine", or "XPA$ERROR: invalid host name specified: $host:$port" (when using the ds9 display device). These issues tend to occur on Macs with customized firewall settings, or on machines without valid IP addresses. This can be resolved by setting the XPA_METHOD environment variable to the value "local" (to use local/UNIX sockets instead of inet sockets):
```
        export XPA_METHOD=local          # Bourne shell (bash/sh)
or
        setenv XPA_METHOD local          # C-shell (csh/tcsh)
```
Perl version mismatch:

Pre-compiled Perl libraries used extensively by mission software (Swift, Suzaku, NuSTAR) and other packages are not especially portable, so we generally recommend building HEASoft from the source code distribution.

xspec / PLT - wenv, whead, wdata:

Some GNU Fortran compilers (gfortran 4.4.x, 4.0.x, 4.1.x) appear to have internal issues which prevent the PLT commands wenv, whead and wdata from working unless an output file is specified; i.e. attempts at producing terminal output may fail with "Fortran runtime error: Invalid argument". To get around this, provide an output file name when using these commands, for example:
```
     wenv myFile1.qdp
     whead myFile2.qdp
     wdata myFile3.qdp
```

HEASoft and other software packages (CIAO, XMM-SAS):

Please note:
Users may wish to download and run our hwrap script to create an alternate runtime environment for HEASoft to help avoid conflicts with other software packages, but if not, please take note of the potential pitfalls below:
- CIAO:
  
  Please see the following notes at the CXC website regarding the potential dangers of using CIAO and HEASoft together in the same session:
  - FTOOLS & CIAO
- XMM-SAS:
  
  The XMM-SAS setup typically adjusts your LD_LIBRARY_PATH environment variable (or DYLD_LIBRARY_PATH on macOS) to include the SAS library folders, one of which includes a copy of the C++ compiler library (libstdc++). This can cause problems building HEASoft, so we recommend that HEASoft be built in a session in which the SAS has not been initialized, or at least one in which your [DY]LD_LIBRARY_PATH is either empty or otherwise does not include the installed SAS directories.
  
  Similarly, after both SAS and HEASoft are installed, if they are initialized in the same session (terminal), C++-based tasks such as XSPEC may suffer runtime problems if the XMM-SAS library directories precede the one needed by XSPEC in [DY]LD_LIBRARY_PATH (as is the case if the SAS is initialized after HEASoft. As an example, if you compiled HEASoft on a Mac using the Homebrew compilers, XSPEC will need to have the Homebrew library path ahead of the SAS library directories in your DYLD_LIBRARY_PATH:
```
     For example:

     C-shell:

         setenv DYLD_LIBRARY_PATH "/usr/local/opt/gcc/lib/gcc/10:${DYLD_LIBRARY_PATH}

     Bourne shell:

         export DYLD_LIBRARY_PATH="/usr/local/opt/gcc/lib/gcc/10:${DYLD_LIBRARY_PATH}
  
```
  Additionally, when both the SAS & HEASoft are used in the same session and the SAS was initialized after HEASoft, the SAS setup changes the value of the environment variable PGPLOT_FONT with the result that plots in e.g. XSPEC may (or may not, depending on the software distributions in use) have no axis labels or values. Users can fix this by resetting PGPLOT_FONT to point to the HEASoft location:
```
     C-shell:

         setenv PGPLOT_FONT $HEADAS/lib/grfont.dat

     Bourne shell:

         export PGPLOT_FONT=$HEADAS/lib/grfont.dat

  
```
  or by simply re-initializing HEASoft:
```
     C-shell:

         source $HEADAS/headas-init.csh

     Bourne shell:

         . $HEADAS/headas-init.sh
  
```
  This may in turn have consequences for plotting in XMM-SAS, in which case users may need to return PGPLOT_FONT to the SAS setting when using it for data analysis.

If you have any questions about the information above, please write to us at the FTOOLS help desk. [an error occurred while processing this directive]