GNU Astronomy Utilities manual

3.3.1.2 Installation directory

One of the most commonly used options to configure is the directory that will host all the files which require installing, for example the actual executable files for the program, the documentation and configuration files. This is done through the --prefix option. To demonstrate its applicability, let’s assume you don’t have root access to the computer you are using which is one of the most common usage cases.

In case you don’t have super user or root access to the system, you can’t take the installation steps of the command sequence in Quick start. To be able to access the Gnuastro executable files from anywhere, you have to specify a special directory in the directories you have write access in, through the shell’s environment variables. Note that this explanation can apply to all the requirements in Requirements in case the system lacks them or the system wide install was not built with the proper configuration options. We will start with a short introduction to the shell variables.

Shell variable values are basically treated as strings of characters. You can define a variable and a value for it by running $ myvariable=a test value on the command line. Then you can see the value in the with the command $ echo $myvariable. If a variable has no value, this command will only print an empty line. This variable will be known as long as this shell or terminal is running. Other terminals will have no idea it existed. The main advantage of shell variables is that if they are exported³⁰ subsequent programs in that shell can access their value. So by setting them to any desired value, you can change the ‘environment’ of the program. The shell variables which are accessed by programs are therefore known as ‘environment variables’³¹. You can see the full list of the environment variables that your shell currently recognizes by running:

$ printenv

One of the most commonly used environment variables is PATH, it is a list of directories to search for executable names. The most basic way to run an executable is to explicitly type the full file name (including all the directory information) and run it. This is useful for simple shell scripts or programs that you don’t use too often. However, when the program (an executable) is to be used a lot, specifying all those directories will become a significant burden. The PATH environment variable keeps the address of all the directories to be searched if directory information is not explicitly given³². When you don’t have root access, you need to specify a directory for your self and add that to the PATH environment variable.

Adding your specified directory to the PATH environment variable each time you want to run your program is again very troubling and will not be much of an improvement compared to explicitely calling the executbale with directory information. So there are standard ‘startup files’ defined by your shell. The commands in these files are run each time you start your system (/etc/profile and all scripts in /etc/profile.d/), when you log in (~/.bash_profile) or on each invocation of the shell (the terminal, ~/.bashrc)³³.

HOME is another commonly used environment variable, it is any user’s (the one that is logged in) top directory. It is used so often that Bash has a special expansion for it: ~, whenever you see file names starting with the tilde sign, it actually represents the value to the HOME environment variable. The standard directory where you can keep installed files for your own user is the ~/.local/. You can use this directory as the top directory for installing all the programs (executables), libraries, manuals and shared data that you need.

Let’s call the directory you have chosen with USRDIR since the standard is just a suggestion. Please replace it with any directory name you choose. To notify the build system of the program to install the files in this directory, you can add the following option to the configure script. When you subsequently run $ make install all the installable files will be put there.

$ ./configure --prefix=USRDIR

The USRDIR/bin directory is the place where the executables (or binary files) are installed. So you have to add that to your PATH environment variable by placing the following command in the $HOME/.bashrc file or any of the startup files discussed above. The directories listed in $PATH specify the locations that the system will check to find the executable name you have asked for. Each directory is separated by a colon (:). So through the command below you will concatenate your directory to the already existing list.

export PATH=$PATH:USRDIR/bin

In case you install libraries (like the requirements of Gnuastro) with this method locally, you also have to notify the system to search for shared libraries in your installed directory. To do that add USRDIR/lib to your LD_LIBRARY_PATH environment variable similar to the example above for PATH. If you also want to access the Info and man pages documentations add the USRDIR/share/info and USRDIR/share/man to your INFODIR and MANPATH environment variables.

A final note is that order matters in the directories that are searched. In the example above, the new directory was added after the system specified directories. So if the program, library or manuals are found in the system wide directories, the user directory is no longer searched. If you want to search your local installation first, put the new directory before the already existing list like the example below.

export PATH=USRDIR/bin:$PATH

This is good when a library for example CFITSIO is already present on the system but wasn’t installed with the correct configuration flags discussed above. Since you can’t re-install, with this order, the system will first find the one you installed with the correct configuration flags. However there are security problems, because all system wide programs and libraries can be replaced by non-secure versions if they also exist in USRDIR. So if you choose this order, be sure to keep it clean from executables with the same names as important system programs.

Read in other formats.
GNU Astronomy Utilities manual, November 2015.