THE BASE UDF INSTALLATION
(The udfLibrarian)

Overview

This document outlines the installation of the UDF udfLibrarian software package which is the first step in installing any UDF based software. The udfLibrarian is the basic UDF software installer. Through it any of the UDF application packages can be easily added to the UDF analysis environment. It also provided the means to update installed packages.

The udfLibrarian is a Tcl/Tk based application. It is known to install under all popular operating systems includeing: WINDOWS, Linux, Unix, and OSX. The use of the udfLibrarian requires that Tcl/Tk be installed on the host system. Besides installing the udfLibrarain the install defines the required environment varaibles used within UDF and checks for the existence of various software packages which may be required by later installs of different applications.

Installing the udfLibrarian proceeds in 3 steps. The steps are virtually identical on all platforms these are:

  1. Check that all needed software is on your system.
  2. Get the installation package and install script.
  3. Install the package.
The installation itself is straight forward, requires minimal user intervention, and generally completes in about a minute.

System Requirements

With the exception possibly of the Tcl/Tk package, most of the software required to install the various UDF applications and management programs are native to the various operating systems. Because non-WINDOWS installs are source installs gcc and make are required on all non-WINDOWS platforms. WINDOWS installs are binary were needed. The install procedure makes use of three standard UNIX utilities: tar, gzip, and ls. These three utilities are provided for WINDOWS systems in the base UDF installation.

The table below lists the software that needs to be present on a particular system before installing the udfLibrarian and subsequent UDF packages. Where relevant version numbers are given as are URL's. The two following subsections describe how to check the version numbers of the various packages and URL's to use to obtain the packages if they are either out of date or not up to revision. Note that if you are running a non-WINDOWS platform most of these packages can either be obtained or upgraded directly from you software distribution.

Software REQUIRED?
OSX UNIX Linux WINDOWS
gcc (>= 2.7.2) YES YES YES NO
tar1 YES YES YES NO
make2 YES YES YES NO
Tcl/Tk (>= 8.4.11)3 YES YES YES YES
xfree86 or xorg-X11 YES YES YES NO
1 The GNU version of tar is recommended but most others will work.
2 The GNU verson or tar is recommended, others sometimes have problems.
3 Make sure the development package is installed also. This is not required under WINDOWS.

Checking Versions

If you're not sure what version of Tcl/Tk or gcc you are running you can check them using the following steps. The Tcl/Tk version is obtained by:

  1. Enter the tcl shell with the command: tclsh
  2. Issue the command info tclversion to get the tcl version number.
  3. Issue the command: exit to end the tcl shell.
The gcc compiler version number is obtained by issuing the command: gcc -v

Download URL List

Downloads of the required software packages can be found at the sites listed below.

Tcl/Tk (Non-Windows): http://www.tcl.tk
Tcl/Tk (Windows): http://www.activestate.com 1
xorg-11: http://wiki.x.org/wiki/
GNU components: http://www.gnu.org
1 Click on Tcl in upper right-hand corner of page then select Standard Distribution in next page. Select Windows on the page after the contant information page.

Tcl/Tk and WINDOWS

When Tcl/Tk installs on WINDOWS it installs two executables tclshXX and wishXX where XX will be the version number 84 or 85. This is fine for the installation, however, some packages especially those wihich deal with data, assume that the executables installed are without the appended version numbers. On windows this can be accounted by copying wishXX to wish and tclshXX to tclsh.

Obtaining the Installation Software

The UDF basic install software packages are obtained from:

http://Image.msfc.nasa.gov/Software/UDFSoftware/Unix/
From that site download the packages EasyUDFInstall.tcl and MININSTALL.tar. EasyUDFInstall is the installer and MININSTALL.tar contains the software to be installed. Place both packages in the same directory.

Installation

To begin, from a terminal window on nun-WINDOWS systems or from a command window on WINDOWS systems, change directory to the directory where the packages were downloaded. Begin the install by executing the command:

./EasyUDFInstall.tcl.
This will bring up the install window:

STEP 1: THE INSTALL TYPE

There are two install methods. The first, EASY INSTALL, is the recommended installation method. Here you need only identify an installation directory for the software and one for the data.

In a CUSTOM INSTALL you will be asked to define all of the required environment variables which will be used in the installation of the udfLibrarian package. The install will use these definitions to create all of the required directories.

STEP 2: DIRECTORY DEFINITIONS

The selection of where various components of the UDF software are installed is preformed in the second step of the installation. This proceeds differently depending on whether you select the EASY or CUSTOM install method.

The EASY INSTALL

Selecting EASY INSTALL brings up the menu:

The UDF BASE DATA DIRECTORY is the directory under which all UDF data sets will be installed. It should be on a device which has a lot of free room. No UDF data sets are installed in the base install but this establishes the location where data which is promoted and used by various applications will be put. The install will create a directory udfData under the selected directory with subdirectories under that directory. The selected base directory must exist, it is not created in the install.

The UDF BASE SOFTWARE DIRECTORY is the directory under which all UDF software packages are installed. The install will create a directory uHome under the selected directory with subdirectories under that. Currently there is about 150MB of applications and associated manuals which can be installed through the udfLibrarian.

If you have IDL installed on the system, the IDL BASE DIRECTORY is the directory under which it is installed. IDL is not required for the install and is needed only if you plan on installing any of the IDL-based UDF applications. If you do not have IDL installed just leave this entry blank. If you install IDL later you can always manually set the appropriate environment variables then. If you identify the base IDL directory at this point the install will setup the IDL based environment variables needed when installing IDL-based applications. NOTE: The IDL base directory should have under it a subdirectory external which contains the file export.h. If you enter a base IDL directory this will be checked for during the install.

If you set the IDL BASE DIRECTORY then you need to identify the version number of the IDL installation. If you are running IDL 6.4 the version is specified as 6.4.

Once you have selected the based directories click NEXT.

The CUSTOM INSTALL

Selecting CUSTOM INSTALL brings up the menu:

The UDF_DATA is the directory under which all UDF data sets will be installed. This should be on a device which has a lot of free room. No UDF data sets are installed in the base install but this establishes the location where data which is promoted and used by various applications will be put. The install create this directory with subdirectories under it. If the selected directory does not exist it will be created in the install.

The UDF_HOME is the directory under which all UDF core software packages are installed. This includes the C-based access and database software subroutines as well as the UDF configuration files. The full set of UDF core packages requires about 20MB. If the selected directory does not exist it will be created in the install.

The GPH_HOME is the directory under which all UDF graphics core software packages are installed. The full set of UDF graphics core packages requires about 30MB. If the selected directory does not exist it will be created in the install.

The UDFTOOL_HOME is the directory under which all UDF C-based application packages as well as the Tcl/Tk based UDF management packages are installed. The full set of UDF application and managment packages currently reguires about 20 MB. The size will increase as new applications are developed and added. If the selected directory does not exist it will be created in the install.

The TCLTOOLS_HOME is the directory under which all Tcl/Tk core packages are installed as well as Tcl/Tk application packages. The full set of TCL core and application packages currently reguires about 10 MB. The size will increase as new applications are developed and added. If the selected directory does not exist it will be created in the install.

The IDLTOOLS_HOME is the directory under which all IDL-based UDF application packages are installed. The full set of IDL application packages currently reguires about 3 MB. The size will increase as new applications are developed and added. If the selected directory does not exist it will be created in the install.

The UDFDOC_HOME is the directory under which all UDF html documentaton packages are installed. The full set of documentation packages currently reguires about 25 MB. The size will increase as new documents added. If the selected directory does not exist it will be created in the install.

If you have IDL installed on the system, the IDL BASE DIRECTORY is the directory under which it is installed. IDL is not required for the install and is needed only if you plan on installing any of the IDL-based UDF applications. If you do not have IDL installed just leave this entry blank. If you install IDL later you can always manually set the appropriate environment variables then. If you identify the base IDL directory at this point the install will setup the IDL based environment variables needed when installing IDL-based applications. NOTE: The IDL base directory should have under it a subdirectory external which contains the file export.h. If you enter a base IDL directory this will be checked for during the install.

If you set the IDL BASE DIRECTORY then you need to identify the version number of the IDL installation. If you are running IDL 6.4 the version is specified as 6.4.

Once you have selected the based directories click NEXT.

STEP 3: CHECKS

At this point the install script determines the settings for all of the required UDF environment variables and also performs a number of checks. The environment variable settings are shown in a popup window. An example is shown below.

Should any problems be encountered in any of the internal checks these will also be addressed in the same window. The two most common problems are that the defined base directories do not exist or if they do they are not writable. To correct these click on the BACK button an reselect the base directories.

When installing on a non-WINDOWS platform the install attempts to located the directories which contain Tcl header file tcl.h and one of either the libX11.a or the libX11.so X library. If the tcl.h file is present the C-backing for some of the slower Tcl/Tk scripts can be compiled and if the X library is present X-Window displays can be implemented by some of the graphical applications. Neither of the files is required to run any of the UDF applications, however, many will run faster if these files can be located. The file \tcl.h is looked for in the directory /usr/include and the X libraries in the directories /usr/lib and /usr/X11R6/lib. If the files cannot be located in the specified directories then the popup menu below will appear allowing the user to search for the files in other directories. The search is made in the directory indicated in the entry box as well as all directories beneath that directory. Depending on the depth of the search, this can take some time. If the file is found in one of the directories then SUCCESS will appear in the lower portion of the popup, otherwise NO SUCCESS. Multiple searches can be made. On success click OK for the install to set the required environment variables to the directory in which the file was located.

STEP 4: SOFTWARE INSTALLATION

Once all problems setting the environment varaibles have been solved click FINISH INSTALL to complete the software installation. A final window will appear in which as status of the installation is followed ending with INSTALLATION COMPLETE when the install has concluded. The full installation time is generally under a minute. Click DONE or QUIT to close the window.

Finishing Up

At this point it is a good idea to make the environment variable settings which were established in the install permanent. This is facilitated by through the use of the udfEnvVar.txt created in the installation process.

On non-WINDOWS platforms the environment variables can be set either system wide by modifying the system-wide login profile file or user-wide by modifying your own personal login configuration file. In a non-WINDOWS install the udfEnvVar.txt file has the appropriate environment varaibles settings for both the BASH/KSH family of shells and the TCSH/CHSH family of shells. Simply cut and paste the appropriate settings from the udfEnvVar.txt file into your .bash, .profile, .tcshrc, or .cshrc file. Note that the file tells you whether you are adding a new environment variable or replacing an existing one.

On a WINDOWS platform, right click on the computer desktop (My Computer) icon, then left click on properties. Select the Advanced tab, then the Environment Variables button. Except for the Path variable, perform the following: under the System variables pane select New, in the Variable Name box enter the variable as shown in the udfEnvVar.txt file, press tab, then in the Variable Value box enter the corresponding path or value and click OK. Finally, click on Path in the System variables pane, select edit, make certain you are at the end of the variable value, append to the end the paths shown in the udfEnvVar file then click OK. Click OK to exit Evironmental Variables and OK to exit System Properties.

USERS of IDL versions 5.2 or under: If you use IDL with a version of 5.2 or less and you had the install set up the appropriate IDL environment varaibles you will need to make a change in the IDL_DLM_PATH environment variable which you will find in the udfEnvVar.txt file. If the environment variable has the field in its path you need to replace this. Replace this field (including the <>) with $IDL_DIR/bin/bin.XXX where XXX will generally be your OS (linux, solaris, etc). To determine what XXX is on your system list the contents of the $IDL_DIR/bin directory. On WINDOWS systems you need to put in the full directory path rather than $IDL_DIR (remember to use \ and not / to separate directories).

First Steps

The installed packages may lag the current revisions available so once the udfLibrarian has been installed it is a good idea to make sure that it and the packages installed are up to date. In essence you will use the udfLibrarian to update itself. The first step is to invoke the udfLibrarian as: udfLibrarian. This will bring up the udfLibrarian interface:

Under PACKAGES click on UDFTOOLS and TCLTOOLS and under SHOW click on UPDATES. The interface will then look like:
Now click on REQUEST. Any packages that appear in open area to the right are packages which have revisions higher than the packages which were just installed. Highlight each package and then click INSTALL. This will obtain the packages from the software archive and install them. At this point you are up to date.

The next step is to begin to add applications. What you install will depend on what you plan to do. Applications can be installed at any time and new applications are continually being added to the software archive as they are developed and made available. Once application that is almost universally used is the DBTOOLS application under the UDFTOOLS Packages. This package provides the dBAsk application which is used to manage the installed UDF data sets.

How to use the udfLibrarian and the applications which are available through it are covered in the udfLibrarian documentation. The documentation itself is obtained through the udfLibrarian. Invoke the udfLibrarian application. Select DOCS under PACKAGES and NEW under SHOW. Click on REQUEST. From the list of packages shown select the udfLibrarian documentation and click on INSTALL. Now from your favorite web browser point to $UDFDOC_HOME/Index.html. This contains a list of all available UDF documentation (installed and uninstalled). Select the udfLibrarian documentation and begin there.

One final comment. In general you never need to install any of the packages listed under the UDF_HOME and GPH_HOME sofware packages. These packages will be automatically installed when you install an application which required them. Once installed, however, they should be checked every now and then to see if any need to be upgraded.