Hi folks welcome to the HEASARC the High Energy Astrophysics Science Archive Research Center
This video tutorial will go through the steps necessary to install HEASoft on your machine
We'll explain some of the different aspects to pay attention to and share resources that will help you install the software
If for some reason you can't install HEASoft on your machine
For example if you don't have permissions to install software and your organization doesn't offer it
you can download the pre-built binaries although they're not normally recommended or use a Docker image.
Even better you can use SciServer.
More information about those tools can be found linked from the software page.
For this video we're going to be installing HEASoft from source on a Mac so let's get started with the installation process
We're going to head here on the HEASoft web page you can see that the latest version is 6.34
as of August 2024.
If you've already downloaded the source code you can go ahead and click on the installation instructions for either PC Linux or Mac OS
We're going to show how to grab a fresh download of the source code so I'm going to click on download here
Note again we do recommend the source code distribution not the pre-compiled binaries
So I'm going to click on source code
And I'm on an Intel Mac
On a OS X 14 so I'm going to select that check box and then you scroll down and step two where
you download the desired packages you select which packages you want
you can click all if you want every single package that's part of HEASoft
then it'll come with all of the mission software all the general use the spectral analysis all of these tools.
If you're curious what's in a tool you can click on a link. For example click on heatools and it will bring you this link of all the tools that are included.
If I'm curious what is ftcreate you can click on it and find the help
for that specific tool I'm going to go back.
For example let's say I want Xspec
Xspec comes packaged with the HEAGen tools and the HEASPtools those are often used together.
And then I decide "oh I also want HEATools" I can just add that check mark "oh I actually want all of them" so I'm going to click all of the General-Use FTOOLS and it will get everything.
And then you can hit submit and it will download that tarball for you so we will wait while that happens.
Okay so the tool is downloaded and I've copied it into my ~/software directory. You can see here in my terminal.
And here is the tarball that is about two and a half gigabytes.
Now we're going to untar that file.
And while that is untarring we're going to
head back to the instructions. I'll hide my terminal for now.
Head back to the the download page and scroll down step 3 Install the Software
And then you can click on the link for which operating system you're on this machine is a Mac OS so I'm going to click on Mac OS and that will bring us to the more detailed instruction page
For installing HEASoft
So one thing to note about HEASoft one important thing is
it's pretty straightforward at its core.
It's the three basic gnu util steps of configure make and make install.
But before we get to those steps first we're going to go over the prerequisites.
We need the different compilers
Stepping back we'll note that HEASoft on silicon Macs the default build is the native arm64 architecture
And if you're on an Intel Mac it's an x86 architecture.
So now we can scroll down and see what compilers are required. We do require C C++ Perl Fortran.
We recommend the Apple Xcode C compilers
And you can install them with the command listed on this page xcode-select --install
We also require a Fortran compiler that is not provided by Xcode. Xcode doesn't include a Fortran compiler
so you can download that from any of your preferred Mac package managers you can download it from Macports if you prefer that or Homebrew or any of your preferred package managers
And just make sure that you know where it's installed after you install a Fortran compiler
With installing a Fortran compiler through a third party package
you do want to make sure that that third party package stays up to date with your Xcode command line tools the CLT.
Since these third-party compilers use the CLT they need to be rebuilt and reinstalled whenever you update your CLT
And then python if you are going to use any of these parts of HEASoft HEASoftPy PyXspec HEASP IXPE or NICER you also need python those tools used python
So you can install that any of your preferred ways again one of the package managers using conda various ways that you can install python along with the required minimum versions of the extra packages pip astropy numpy scipy matplotlib
And note also HEASoftPy uses pip during the installation during the building therefore it requires access to the internet while you're in the build step
And then we're going to move on to environment variables. Before compiling it helps to set some environment variables to tell HEASoft where your compilers are
So where your
C compiler C++ Perl Fortran Python interpreter all of those are located. I'm on a bash I use bash in my terminal so I can copy these lines right here and I know that this is where
my files are so I'm going to bring up my terminal again
You can see that the tarball did untar. It took just a couple of minutes
So I'm going to just paste those in.
My Fortran compiler
I downloaded Fortran using Macports
and my Fortran compiler is in a different spot so I'm going to grab that from my notes
I'm going to copy that in here.
I'm on an Intel machine for Macports so you can see that this is where fortran
was installed on my machine
For my python I am using I have installed miniforge
for my python so I'm going to copy that from my notes as well.
There are all of my environment variables
that I need to set before building HEASoft.
The next step
after setting your environment variables
And there are some extra if you have trouble you can unset some of these flags. You can put your usr/bin in front of your path. Sometimes these help if there are difficulties with building or configuring.
So then we're going to move on to configure.
And configure just like any gnu util there is there a lot of options for configure. you can type configure --help
well first I'm going to move into the directory.
So we want to go into the BUILD_DIR directory.
And we can see the configure file is listed right here.
You can see all of the different standard options that come with configure.
Some of these are very useful for example if you want to install your HEASoft in a different location than a default
the default is under the heasoft-6.34 directory under a platform specific directory in there. If you want to install it for example let's say I want it just straight in my software or in my usr/bin I would do
--prefix=/my/preferred/location
and then it would install it into that location I want it in my default location so I'm going to stick there
I'm going to then go ahead and just copy this
This command it's redirecting the output of the configure command with this arrow into config.txt
we do recommend redirecting all of your output into another file so that if there's a problem with any step of installing the software you can send us these text files and that will help us troubleshoot what went wrong on the system.
So I'm just going to go ahead and copy that
And paste that in here and then I'm going to wait. That'll take about 10 or 15 minutes and then we'll come back and move on to the next step.
Okay and now the configure step has finished.
you can see it took about 14 minutes.
We're going to look at that log file.
Before we can proceed to the next step the current step has to succeed.
We're going to check and make sure that it succeeded so I'm just going to
look at that file go all the way down to the end and it
says Finished. That's great the last line is Finished that means it was successful
n configuring. so now I'm going to
Go on to the build step so I'm
going to scroll down a little bit
And I'm just going to again just copy that make
sure we're redirecting the output into a log file
so that I can check that later and if there's
any problem we can look at that for troubleshooting.
I want to copy that in
And hit enter. The build step will take a lot longer. It could take
a few hours even depending on how large your downloaded source tarball is and
how powerful your machine is. So we will wait for this to finish now.
Okay and now we can see that the make step has finished.
Just as before we are going to make sure that it
succeeded before we can move on to the next step.
So I'm going to do just a tail on that file. Great
and it says Finished make all so that step was successful.
So now I can move on to the installation step. And
you can see that it took about an hour from 1615 until
17:19 on my machine and with the packages that I had
downloaded in the source code tarball it took about an hour.
The next step is installation so
I will scroll up on
the website behind step A4 Install.
I can just copy
this line again 'make install' I'm going to redirect it
to a file called install.txt so that we can look
for troubleshooting steps again and I will enter that
Now while that's installing again as we talked about with the configure step
it's going to install in the default location which is under the
current HEASoft directory under a platform specific directory there if I
had wanted to install the software elsewhere I would have added that
prefix option to the configure step. Because I didn't it's going to
install in the default and we'll find that once this install step finishes.
Okay so now the install step has finished.
I cleared my screen but you can see that
the install text file is here.
And we're going to check that as we did with other steps to make sure that it succeeded.
Great and the last line is "Finished make install"
so we know that that step succeeded.
So now we are going to go up
a directory into the main HEASoft-6.34
directory and we're going to see
Here is the install directory the x86 the platform
specific directory is now under our HEASoft directory
If I had specified with the configure command
the prefix option if I had specified a different location
then this platform specific directory
it would not be here the install directories would be elsewhere.
So for now the next step we are going to go to initializing.
Initializing is required for every new terminal session that you want
to use the HEASoft tools. You need to export HEADAS to
export this path into a HEADAS environment variable the path
to where it's installed and then you need to source this headas-init.sh file
csh if you're using a C-shell.
So I'm going to go into this x86 directory
We can see
those init files. We can see which directory we're
in and I'm going to just do a shortcut export HEADAS=$PWD
I can do that because that's where I am right
now if you were going to put this as a shortcut or an alias
Iin your RC file then you would need to spell out the entire directory.
But right now I can echo
that environment variable and show that it's pointing
exactly where I want it to be.
And now I'm going to source that file so
I'm going to copy this command
"source headas-init.sh"
And now I can see that "which ftlist"
it's here in my path.
I can run the tools. I can run ftversion
and see that I am using version 6.34.
And that is how you get started in
installing and then beginning to run the tools
for HEASoft after it's initialized.
Now to start actually using the tools and understanding how to do
analysis there are a lot of user guides. For example, Xspec,
a lot of the mission guides there have very detailed analysis
help pages so you can explore the different missions and figure
out what is best needed in order to analyze your data.
And you can explore the HEASARC website for more guidance about actually
using the software. If you have any questions about installing the software or
if you've run into any troubles feel free to message our help desk.
That is here at the very bottom
of this installation guide there's a link to the help desk. So you can click that
and message us if you have any difficulties. Good luck with your data analysis