This document briefly describes the necessary steps to install the GIPPtools software collection.

System Requirements

There are two requirements that must be met to run the programs in the GIPPtools package:

  1. You will need a working Java virtual machine (sometimes also called a Java Runtime Environment or simply JRE) supporting Java 8 or newer!

  2. The second system requirement is the availability of some console or terminal window on your computer where you can type commands. None of the GIPPtools programs utilizes a graphical user interface. They all take their parameters and options exclusively from the command line!

Downloading

Current releases of the GIPPtools software can always be obtained via the GeoForschungsZentrum (GFZ) in Potsdam. Please see the "Software" section of the GIPP web page for the download location.

At the moment, there are two binary distributions. One for Unix style operating systems and one for the Microsoft Windows family. (Apple macOS user should use the Unix variant.)

Installing

After downloading the GIPPtools, you need to unpack the file first. The Unix version is distributed as gzipped TAR archive file. Use the gunzip program to decompress the archive and extract files with the tar command. The Windows release is contained in a ZIP file. A simply double-click on the file icon should show the content.

No matter which platform you use, after unpacking the archive file you should have a directory called gipptools-<RELEASE> where <RELEASE> is the release number of GIPPtools package you downloaded previously. It contains subdirectories such as bin, doc and java.

You can copy or move the whole gipptools-<RELEASE> directory to any location you want. It is also possible to rename the directory to whatever you deem suitable. However, you must not alter the directory structure inside GIPPtools directory! (The start scripts for all utilities relies on the given filenames and directory structure.)

Testing the Installation

As a first test if things are working properly change to the GIPPtools directory and try to start e.g. the ‘cubeinfo’ command:

Unix
cd gipptools-<RELEASE>
./bin/cubeinfo --version
Windows
cd gipptools-<RELEASE>
.\bin\cubeinfo --version

If everything works correctly, the program cubeinfo should respond with a release string followed by copyright and license information. In case of problems, the start script should complain with an error message. Try to resolve the problem and try again.

Setup Environment Variables

If the previous test succeeded you have finished the installation and can already use the GIPPtools programs. However, it is rather inconvenient to always type the long pathname or to change to the GIPPtools directory first. So you should consider adding the GIPPtools bin directory to the PATH environment variable of your operating system.

Other environment variables, which may be used to adapt the GIPPtools software, are GIPPTOOLS_HOME, GIPPTOOLS_JAVA and GIPPTOOLS_OPTS. Here, the GIPPTOOLS_HOME variable contains the location of the (main) GIPPtools directory on your computer. Similar, the GIPPTOOLS_JAVA environment variable points to an installation of the Java virtual machine. Finally, GIPPTOOLS_OPTS can be used to fine-tune the Java runtime.

Usually, you do not need to set GIPPtools specific environment variables at all, since the start scripts automatically detect the required Java virtual machine and the GIPPtools installation directory!
However, you might find these variables useful if the automatic detection should ever fail. The variables are also come in handy when experimenting with different Java virtual machines or in cases where several GIPPtools releases are installed at the same time.

The last environment variable you may want to modify is only relevant for Unix systems. On Unix the MANPATH variables contains a list of all directories where the man command will search for manual pages. Consequently, man will only display GIPPtools manual pages if you have added the GIPPtools man subdirectory to MANPATH.

Uninstalling

If, for whatever reason, you want to get rid of the GIPPtools simply delete the main gipptools-<RELEASE> directory and you are done! None of the GIPPtool programs secretly creates any configuration files (especially not any hidden ones) nor is the operating system secretly modified in any way.

Don’t forget to undo any modifications to the environment variables you may have done manually.