The OpenGrADS Bundle
A bundle is a directory in the file system that groups related OpenGrADS resources in one place. Executables, scripts, map and font files are examples of resources that are needed to run GrADS and its utilities. Notice that although the concept of a bundle is modeled after Mac OS X bundles, they are not the same.
The GrADS binaries and support data are typically placed in the directory /usr/local/bin
/usr/local/ bin/ grads gribmap gxeps ... gex/ (OpenGrADS extensions) lib/ grads/ hires lowres mres udunits.dat font0.dat ... tables/
The these files can be relocated to any other directory provided that the binaries are in your PATH and that the GADDIR environment variable is set point to the location of the support data files (the files under /usr/local/lib/grads above). In addition, the environment variable GASCRP is used t define the default path for the application to look GrADS scripts.
The OpenGrADS project aims at producing tun-key GrADS distributions that have the following features:
- Native installation, using the Windows installer or the MacOS Package Manager, for example
- Zero or at least minimum configuration installations, with no need to set any environment variable by hand
- Relocatable installations, so the user can copy the root installation to a USB memory stick and take it on the road without the need for re-installing it.
- Multi-platform installations. A user could install multiple operating system versions on a single DVD or USB memory stick or on a network disk, with the correct binary being automatically selected at run time.
- Multi-version installations. A user could install multiple GrADS versions on a single DVD or USB memory stick or on a network disk, with the correct binary being automatically selected at run time.
One derived requirement is that such installations require complete packages: binaries for one or more platform, support data and in some cases support scripts.
Anatomy of the OpenGrADS Bundle
The basic structure of a single-version OpenGrADS bundle is very simple and somewhat mimics the Mac OS X Modern Bundle:
OpenGrADS/ Contents/ grads gribmap gxeps ... Linux/ i686/ grads gribmap gxeps ... gex/ (User Defined Extensions) libs/ (Additional Shared Libraries) x86_64/ grads gribmap gxeps ... gex/ (User Defined Extensions) libs/ (Additional Shared Libraries) Resources/ SupportData/ hires lowres mres udunits.dat font0.dat ... tables/ Scripts/ basemap.gs lats4d.gs default.gui ... SampleDatasets/ model.ctl model.gmp model.grb
The Resources/ Directory
The Scripts/ directory contains the GrADS script library, Athena GUI scripts and otherwise useful scripts in support of the OpenGrADS extensions. The executables under Contents are simply wrapper scripts which detect the installation directory and architecture and dispatch the appropriate binary further down:
- These wrapper scripts will be implemented in C using native C calls as in the current Win32 Superpack
- These wrapper scripts are implemented in Perl scripts.
The name of the directories containing the binaries will be determined by the platform uname -s and uname -m POSIX commands (or alternatives where uname is not available.) Typical directory names are:
- Mac OS X
Darwin/ i386/ powerpc/
Linux/ i686/ x86_64/ IA64/
FreeBSD/ i386/ amd64/
The gex/ Directory
The gex/ directory contains shared libraries (file extension .gex) and dispatch tables (file extension .udxt implementing the OpenGrADS User Defined Extensions. It may also contain other shared libraries required by these extensions (e.g., libgfortran.so).
The libs/ Directory
The libs/ directory contains additional shared libraries that may be required in some systems (but may cause conflict in others.) If you get an error message saying that a given shared library is missiong from your system and you find such library under libs/ you may want to move this lobrary to the parallel gex/directory.
In this case we use the same versioning scheme similar to Mac OS X Framework Bundles. Focusing on the binary directory
Linux/ i686/ -> Versions/Current/i686 x86_64/ -> Versions/Current/x86_64 Versions/ A/ i686/ grads gribmap gxeps ... gex/ x86_64/ grads gribmap gxeps ... gex/ B/ i686/ grads gribmap gxeps ... gex/ x86_64/ grads gribmap gxeps ... gex/ Current -> B
The Versions/ directory is the only real directory at this top level. The i686/ and x86_64/ directories are symbolic links to items in Versions/Current. From the user point of view, whether one has multiple platforms is an implementation detail; it always defaults to the current version. However, by specifying the --with-version option to the wrapper scripts under Contents/ one can select a specific version.
The very top level, under Contents/, contains wrapper scripts with names that match the actual executables down below, e.g.,
These wrappers are typically Perl scripts which automatically detects its own installation location, platform, processor type, etc., and start the corresponding executable down below. Click at the links above for a manual page describing the several options available with such wrappers. One can always get documentation for a given wrapper with the --help option:
% opengrads --help
Typical options are:
--asif name behave as if this script was called *name*
--ga2udxt print the value of the GA2UDXT variable right before calling the real "grads"
--gaddir print the value of the GA2UDXT variable right before calling the real "grads"
--gascrp print the value of the GA2UDXT variable right before calling the real "grads"
--help print this page
--with-arch arch select OpenGrADS bundle with this architecture; default is the results of `uname -n`. Usually one would take the default, unless perhaps when Java becomes available.
--with-mach mach select OpenGrADS bundle with this type of processor; default is the results of `uname -m`. Usually one would take the default. However, on architectures such as Linux sometimes i386 works more reliably than the neative x86_64.
--with-version x.y.z select OpenGrADS bundle with version x.y.z
--version print OpenGrADS Bundle version
You can also control the behavior of the wrapper with these environment variables:
GA2UDXT The name of the directory where grads looks for its User Denied eXtension Table; when GA2UDXT is already set this wrapper will not redefine it.
GADDIR The name of the directory where grads looks for its fonts and map database files; when GADDIR is already set this wrapper will not redefine it
GADSET This wrapper sets this variable with the name of the directory containg th sample datasets. From the grads command line one can enter
ga-> @ open /model.ctl
GAGUI The name of the Athena GUI script to start grads with. Currently the *merra.gui* script when the file name for this wrapper is *merra*
GASCRP Space delimited list of directories where grads looks for its scripts; this wrapper always adds the Resources/Scripts directory to the end of this list
GAVERSION By default selects this version of the software instead of "Current"