(If you are not new to Unix-like OS, probably you already understand the installation instructions provided along with both pieces of software.)
Once you have a functioning operating system, e.g., Mac OS X that comes along with the computer you bought, or a Linux distribution you installed on your own (Why not Windows? The answer would deserve a separate article), you may want to install your favorite analysis software right away so you can start working. But how? Usually, these packages cannot be found in the repositories and cannot be installed by just clicking Next, Next, and Next -- rather, they come in the form of a tarball (.tar.gz, .tgz).
We'll use the official distribution of HEAsoft (6.13) as the main example*. The software comes in two kind of distribution: a source distribution and a binary distribution. The source distribution contains the software in its source code -- its primitive form. To install the software, we need to
- identify the compilers in the computer which translate the code into something your computer can understand (a binary), as well as the libraries in your computer that the software needs during execution (configuring);
- translate the code (building/compiling); and
- move the compiled files to appropriate places so your computer knows where to look when you try to use the software ("installing").These can be done by executing a few commands, which will be discussed in a second.
*The installation of the Fermi Science Tools (FST) (v9r31p1) from only the binary distribution will come alongside in the relevant sessions. This seems to be in conflict with the title of the post, but the reasons are that:
- building the FST from source involves extra branches which are too much to be fitted into this post;
- installing the FST from binary is strongly recommended by the developers; and
- the similarities in the procedures can still be accessed.
In general, if a software is organized in a way consistent with the GNU standards, the same procedure applies, so let's get down to brass tacks.
Unpack
(Instruction step 2)Prior to step (1), we have to unpack the tarball we have downloaded in order to look inside. You may want to move the tarball to a location where you want the software to be installed at. A tarball refers a format of compressed, archived file. It resembles a zip file, but it consists of two steps during generation: the archive (tar) part and the actual compression (gz/gzip) part. To unpack the tarball, tar provides a one step solution (gunzip and tar in a single command):
tar -zxvf heasoft-<version>.tar.gz # for HEAsoft
tar -zxvf ScienceTools-<version>.tar.gz # for FSTThe bit with the hyphen, -zxvf, is the option part of the command:
- -z indicates that gzip is needed to decompress the file
- -x tells tar to extract (actually!) the content of the tarball
- -v stands for verbose and tells tar to print the names of the files being extracted; it is a very common option
- -f tells tar that the name coming after it is a file
Configure
(Instruction step 3)
We have come to the first step. There is a configure script for this. If you're installing from source, the script is directly under the directory BUILD_DIR, where you should now move your working directory to:
We have come to the first step. There is a configure script for this. If you're installing from source, the script is directly under the directory BUILD_DIR, where you should now move your working directory to:
cd heasoft-<version>/BUILD_DIR/ # for HEAsoft
cd ScienceTools-<version>/BUILD_DIR/ # for FSTIf you're installing from binary, there is one extra directory to go through:
cd heasoft-<version>/<platform>/BUILD_DIR/ # for HEAsoft
cd ScienceTools-<version>/<platform>/BUILD_DIR/ # for FSTYou can now execute the configure script and let it check for compilers, dependencies, etc. The command is simple:
./configure(Sometimes it is useful to write the output to a file for future reference, as suggested in the installation instructions.)
If any error message pops up at this stage, it is most likely caused by missing compilers or libraries; a quick look at the message will tell.
(If you're installing HEAsoft, you might get a Perl mismatch warning.)
Make
(Instruction step 4 & 5)If you are installing from binary and pass the configure step, then the software is ready for use -- except that you will need a better organization of the compiled files, which is accomplished by the final step.
On the other hand, if you are installing from source, this is the crucial step and is the core of the procedure. If you haven't already noticed, the configure script has created (or modified) a file called Makefile in the working directory. This is the recipe for the compilation of the source code, which may take tens of minutes or even an hour (sit back and
makeTranslation isn't easy -- this is probably the step when most nasty errors come out, such as linker errors and library conflicts. The solution really depends on your machine, and we cannot cover that here. Nevertheless, you should not ignore any errors and skip to the next step before things get sorted; in general, the next step is irreversible -- there is no simple way to revert it if improperly compiled files get scattered across your file system.
Make install
(Instruction step 6)If the previous step succeeded without any error, congratulations! The software is ready for use -- but the compiled files have to be moved to the right place so that they can be easily accessed when needed in the future. This is done by the command
make installIn general, software obtainable via the repositories and popular, community maintained packages (very loosely speaking) would have the default installation location set to a system directory (e.g. /usr/local), for which you will need root privileges. Once the files are in place, they are accessible from virtually anywhere.
Initialization (Setting up the environment)
(Instruction step 8)In the case of HEAsoft and FST, the default installation is within the directory created when the tarball was unpacked (although you can specify a custom directory during the configure step), which is not as accessible as system directories from the point of view of your computer (the shell), so an extra step is required to set up the environment. In simpler words, it tells your computer there is actually some other places to look when you call the HEAsoft or FST tools (if you can't find the key in your pocket, don't panic -- it's probably somewhere on the floor).
The corresponding commands are (assuming bash):
export HEADAS=/path/to/installed/heasoft-<version>/<platform> # for HEAsoft . $HEADAS/headas-init.shor for the FST:
export FERMI_DIR=/path/to/installed/ScienceTools-<version>/<platform> # for FST . $FERMI_DIR/fermi-init.shHowever, these are for one-time use only: after you exit the current shell (closing the Terminal window), the information on the environment set-up is lost and when you start a new one, you have to enter the same commands again. There is a way to let the shell execute the commands automatically upon start, open the file ~/.bashrc with your favorite text editor (again, assuming bash) (or ~/.profile on Mac OS), and add the two line of commands -- it is advisable to give the second line a tweak:
export HEADAS=/path/to/installed/heasoft-<version>/<platform> # for HEAsoft alias heainit=". $HEADAS/headas-init.sh" # don't forget the quotes
export FERMI_DIR=/path/to/installed/ScienceTools-<version>/<platform> # for FST alias fermi=". $FERMI_DIR/fermi-init.sh"The name alias may have already given you some hint -- every time you start a new shell, the environment set-up will not be complete until you explicitly demand it via the "shortcut" commands:
heainit # for HEAsoft
fermi # for FSTor whatever commands you are comfortable with that are unambiguous.
The reason for this is to avoid setting up all kinds of environment variables at each startup without your consent when many of them are useless to you doing some specific tasks. When you have more software installed, letting the environment initialization to carry out automatically will pour an excessive amount of information to the shell without checking for consistency. For example, two packages compiled with different versions of a compiler would conflict when the libraries are suitable for one but not the other.
