Michelson Science Center Software Tree

A.B. 10/2001, 1/2003

Introduction

This short document describes our model for the software tree containing distributed Michelson Science Center (MSC) software, and how to create, modify, and use it. The scheme here should be taken as our recommendations on how to package end-user software, but (overstating the obvious) you should feel free to package the software to accomodate your system preferences.

The objective of this tree structure is to provide a unified packaging scheme for the software we distribute to our user base. Our goals for this packaging scheme are:

Provide a convenient, consistent structure (recommendation) for users to download, install, use, and maintain the software in their local environment.
Develop this structure that will both allow for multi-user and single-user installations.
Develop this structure such that it will equally support users and/or administrators with and without root access; equivalently users and/or administrators with and without the desire to install MSC packages into Unix-standard common areas such as /usr/local/bin and /usr/local/lib

Top-Level Tree Structure

The root of the Michelson Science Center software tree is the mscSoftware directory -- which can be placed in an arbitrary location in the user's file system.

As depicted here, inside mscSoftware are the next level of directories that provide major divisions for software components, packages, libraries, data, and documentation: bin, data, doc, include, info, lib, man, and src. This directory structure emulates Unix standards, and each subdirectory are described in turn below. Finally there are a pair of shell scripts mscEnv.csh and mscEnv.sh that facilitate the setting of common environment variables shared by MSC packages.

The bin directory is the container for MSC executables (e.g. getCal, wbCalib) -- this is the directory that the user places in his executable search path to use these executables (see mscEnv.csh below). The bin directory itself is flat with no internal substructure -- all executables are at the top level in this directory.

The doc, info, and man directories contain documentation on MSC packages and software (e.g. this documentation, man pages).

The data directory contains data resources used by MSC packages (e.g. the Hipparcos catalog, used by getCal).

The include directory contains header files for libraries that MSC or third-party packages compile against; the lib directory contains the corresponding libraries used in linking executables. Further in lib is the modules subdirectory, for Perl modules shared among MSC components.

The src directory contains the source for MSC libraries, scripts, and programs.

mscEnv.csh (mscEnv.sh for sh/bash users) is used to set a number of common environment variables that facilitate access to Michelson Science Center software and help different MSC packages work together:

MSCPATH -- local path specification to mscSoftware (e.g. /home/bode/mscSoftware)
MSCBIN -- local path specification to bin ($MSCPATH/bin). Putting MSCBIN in your executable search path gives you no-muss-no-fuss access to MSC executables.
MSCDATA -- local path specification to data ($MSCPATH/data)
MSCINFO -- local path specification to info ($MSCPATH/info)
MSCMAN -- local path specification to man ($MSCPATH/man)
MSCLIB -- local path specification to lib ($MSCPATH/lib)
MSCINCLUDE -- local path specification to include ($MSCPATH/include)
MSCSRC -- local path specification to src ($MSCPATH/src)
MSCMODULES -- local path specification to lib/modules ($MSCLIB/modules)

Setting up mscSoftware

In order to assist you with the tedium of setting up a directory structure by the recipe we describe here, we provide a simple shell script mkMSCSoftwareTree that creates an empty tree such as we describe here. [Shift-clicking the mkMSCSoftwareTree link will open a save file dialog window in most browsers.] mkMSCSoftwareTree also creates initial versions of mscEnv.csh and mscEnv.sh for the user. Sample output from a successful mkMSCSoftwareTree run is given here, and gives a specific listing of the various directories created.

Structure within the src directory

As mentioned above, the src directory contains the source for all installed MSC packages -- scripts, libraries, and programs. When a user downloads an MSC component (s)he should place it in the src directory. Strictly speaking, the structure inside src is completely arbitrary; as long as all the relevant derived pieces are copied and/or linked into the relevant global access directories (i.e. bin, include, info, and lib -- see the installation discussion below), the different substructures inside of src have no operational implications. So, the user can arrange src to suit his needs...

That having been said, clearly some substructure in src will help to keep things organized, and we at the MSC have developed a tree structure that we find serves our needs. The general flavor of this structure is illustrated below:

The template tree created by mkMSCSoftwareTree follows these conventions for src directory structure (see the mkMSCSoftwareTree output for a complete listing).

Installing Software in src

Depending on how you like to manage your source distributions, you can follow (or not) the src structure described above. Either way, MSC packages dowloaded to your local environment need to be unpacked, configured, built, and then installed -- typically into directories at the top-level (e.g. bin, lib, man). This will usually be done with a configure, make, install sequence:

> configure
> make
> make install

Please consult the build instructions for individual packages for specific build and install instructions.