HEASoft Wrapper Utility
Users may run into problems when using HEASOFT in the same session as
other related software systems such as CIAO or XMM-SAS. These issues
usually stem from library conflicts, for example:
xspec is typically linked to /usr/lib/libstdc++.so.6, but when the
XMM-SAS software is initialized, a users' LD_LIBRARY_PATH will be
changed to put XMM-SAS directories ahead of everything else (including
/usr/lib), such that xspec - when looking for libstdc++.so.6 at runtime -
will find the xmmsasYYYYMMDD_HHMM/libextra/libstdc++.so.6 instead of the
one in /usr/lib.
When these libraries differ significantly, xspec may fail with errors
complaining that the libstdc++.so.6 it located is the wrong GLIBCXX
version. Other compiler libraries (libgfortran, libgcc_s) included in
the XMM-SAS may create similar conflicts.
Traditionally the recommendation is made to either run HEASOFT and
XMM-SAS in separate sessions (which is not ideal) or to perform the
XMM-SAS setup first and then put /usr/lib back at the head of
LD_LIBRARY_PATH (though this will likely then break the SAS tasks).
Other common problems are the use in both HEASoft and XMM-SAS of the
PGPLOT_FONT variable which will point to different locations in each
system, and the use in both HEASoft and CIAO of the PFILES variable.
In an effort to protect HEASoft tasks from these kinds of issues, we have
created a script ("hwrap") which provides an alternate runtime
environment in which an invoked task is just a wrapper to the real task, and
in which the environment is set and exported correctly for HEASoft tasks only.
Once hwrap is run, a user only needs to add the directory it creates to
their PATH to gain command-line access to all of their installed HEASoft tasks,
necessarily skipping the traditional HEASoft setup in which the HEADAS variable
is set and the "headas-init" script is sourced.
How it works:
Install HEASoft, skipping the final setup / initialization step (step 8
in the installation guide ). Note that below we will
refer to the standard $HEADAS location but neither this nor any other
HEASoft-related variables need to be set in the environment.
Download and run the
hwrap <location of installed HEASoft> <destination directory (optional)>
hwrap /path/to/heasoft-6.27/x86_64-pc-linux-gnu-libc2.27 /path/to/heasoft-6.27/
The required first argument is the location of a HEASoft installation (i.e.
what would typically be defined as HEADAS). An optional second argument may
be provided to specify the destination, a directory under which a new output
directory heasoft_wrap will be created to contain the new wrappers to
the HEASoft tasks. By default this will be made a subdirectory of the path
specified in the first argument.
When run, hwrap will create heasoft_wrap in the destination
directory, and will populate it with symbolic links for each of the tasks it
finds in what would be the standard $HEADAS/bin directory. Each symbolic link
will have the name of an existing task in $HEADAS/bin, but all will point to a
wrapper script which sets up the standard HEADAS environment and then executes
the task that was invoked.
For example, when heasoft_wrap/ftlist is invoked, the script wraps to the
'real' ftlist: first performing the usual HEASoft initialization and
then invoking the ftlist binary in $HEADAS/bin with any command-line
arguments passed along.
If not placed under the default destination or an existing version-numbered
directory (e.g. heasoft-6.27 in the second example above), users may wish to
rename the heasoft_wrap directory, for instance to denote its connection to a
specific HEASoft version, e.g. "heasoft_wrap_6.27".
Add the new heasoft_wrap directory to PATH, for example:
C shell (csh/tcsh):
setenv PATH "/path/to/my/heasoft_wrap:$PATH"
Bourne shell (sh/bash):
Users who have the traditional headas setup hard-coded in their .login / .cshrc /
.bashrc / etc. should either remove that old setup (recommended, as leaving it
in would essentially defeat the purpose of doing all this) or make sure to
prepend this new directory to their PATH as above.
Users of XMM-SAS will note that the SAS setup script (setsas.csh) requires
that you have the LHEASOFT variable set before allowing you to initialize
the SAS, but this is only to ensure that the SAS has access to HEASOFT tasks
('fkeyprint', etc.), so when using the wrapper method suggested here, users
may safely set the LHEASOFT variable to any placeholder string they like,
C shell (csh/tcsh):
setenv LHEASOFT none
Bourne shell (sh/bash):
Note once again that no changes are made to the current working environment
in this process, and no environment variables other than PATH need to be changed
in order to use HEASoft.