The OpenGrADS Bundle

From OpenGrads Wiki
Jump to: navigation, search

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.

Design Considerations

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

Single version

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:

Windows
These wrapper scripts will be implemented in C using native C calls as in the current Win32 Superpack
Linux/Unix
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:

Windows
cygwin/
    i386/
Mac OS X
Darwin/
    i386/
    powerpc/
Linux
Linux/
    i686/
    x86_64/
    IA64/
FreeBSD
 FreeBSD/
    i386/
    amd64/
IRIX
    IRIX64/
       MIPS/

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.

Multi-version

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.

Wrapper Scripts

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"