Difference between revisions of "Installing the OpenGrADS Bundle"

Revision as of 06:46, 19 November 2009

The OpenGrADS Bundle distribution of GrADS contains all the executables, fonts, map datasets, scripts and sample datasets that you need to run GrADS on your computer. Additionally, it contains the OpenGrADS User Defined Extensions that complements GrADS with a number of useful commands and functions.

Downloading the OpenGrADS Bundle

These are available from our Sourceforge download area. The following packages are available:

GrADS Version 2.0

This is the recommended latest version:

• grads2 - OpenGrADS Bundles for Mac OS X, Linux and Unix (including FreeBSD)
• grads2-windows - OpenGrADS Bundle for Microsoft Windows (tm)

GrADS Version 1.10

This is an older, legacy version, still maintained for those users who cannot yet migrate to v2.0:

• grads1 - OpenGrADS Bundles for Mac OS X, Linux and Unix (including FreeBSD)
• grads1-windows - OpenGrADS Bundle for Microsoft Windows (tm)

Important

The extensions package found at out sourceforge site is for an older (read: pre OpenGrADS Bundle distribution) GrADS v1.9.0-rc1. The extensions are included in the OpenGrADS Bundles, there is no need to install them separately.

Installing the OpenGrADS Bundle on Linux/Mac OS X/Unix

Move the Contents/ subdirectory to a directory of your choice. Put this directory in your path and you are done. You can even put it on a USB memory stick and take it on the road. You can run it directly from the memory stick without having to set an environment variable. Read on if you need more information. See the next section if you prefer the classic installation method used by COLA.

If you have admin privileges it suggested that you install the OpenGrADS Bundle under /opt:

 % mv Contents /opt/opengrads

but you could equally install it under your home directory

 % mv Contents $HOME/opengrads

Next put this installation directory in your path. Assuming you installed it under /opt/opengrads.

Bash/Bourne shell variants

 % export PATH=/opt/opengrads:$PATH

C-shell

 % set path = ( /opt/opengrads $path )

That is it! Unless you take this directory tree apart there is no need to set any other environment variable.

Alternatively, you can make a symlink of each executable under /opt/opengrads into somewhere in your path, e.g.,

  cd /usr/local/bin
  ln -s /opt/opengrads/opengrads .

Version 2.0

The following executables are provided:

    grads            GrADS package, including the OpenGrADS Extensions
    opengrads        same as "grads -CH 1"
    gribmap          Creates an index file that "maps" a GRIB data set 
                     for a GrADS descriptor file
    gribscan         Extracts grid info from a GRIB data set
    grib2scan        Extracts grid info from a GRIB2 data set
    bufrscan         Reads BUFR messages and prints out ascii values 
    gxps             Converts GrADS metafiles to Postscript
    gxeps            Converts GrADS metafiles to Encapsulated Postscript
    gxtran           Displays metafiles
    gxyat            yet another metafile translator; produces PNG with
                     anti-aliased fonts as well as SVG, PDF and PS.
    merra            starts grads with a graphical user interface
                     customized to access the MERRA datasets, see
                          http://gmao.gsfc.nasa.gov/merra
    stnmap           Maps station data
    wgrib            GRIB-1 utility, see 
                       http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html

Notice that gradsdap is now obsolete since the OpenGrADS build of grads includes OPeNDAP support.

Version 1.10

The following executables are provided:

    grads            GrADS package, including the OpenGrADS Extensions.
                      This build can read all supported formats (HDF-4 
                      requires a ctl file) and writes NetCDF through LATS
    gradshdf         GrADS package, including the OpenGrADS Extensions
                      This build can read NetCDF-3/HDF-4 files with
                      sdf/xdfopen and writes HDF-4 through LATS
    opengrads        same as "grads -CH 1"
    gribmap          Creates an index file that "maps" a GRIB data set 
                     for a GrADS descriptor file
    gribscan         Extracts grid info from a GRIB data set
    bufrscan         Reads BUFR messages and prints out ascii values 
    gxps             Converts GrADS metafiles to Postscript
    gxeps            Converts GrADS metafiles to Encapsulated Postscript
    gxtran           Displays metafiles
    gxyat            yet another metafile translator; produces PNG with
                     anti-aliased fonts as well as SVG, PDF and PS.
    merra            starts grads with a graphical user interface
                     customized to access the MERRA datasets, see
                          http://gmao.gsfc.nasa.gov/merra
    stnmap           Maps station data
    wgrib            GRIB-1 utility, see 
                       http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html

Notice that gradsdods/gradsnc4 execuables are now obsolete since the OpenGrADS build of grads includes OPeNDAP support and can read NetCDF-4/HDF-5 files. The gradsc executable is no longer provided, although it can be easily built from sources.

Troubleshooting

If you receive an error such as:

% grads
grads: error while loading shared libraries: libXaw.so.7: 
       cannot open shared object file: No such file or directory

for libXaw (or any other library) is because your system lacks this standard shared library. We have include many of these shared libraries used by GrADS under

  Contents/Linux/Versions/2.0.a5.oga.3/x86_64/libs

If it complains about some missing shared, copy each missing shared library from this directory to

  Contents/Linux/Versions/2.0.a5.oga.3/x86_64/gex

and try again from Contents/.

IMPORTANT

1. The wrappers under Contents/ will take care of setting the necessary environment variables. When using the Classic installation below be sure to set LD_LBRARY_PATH (or DYLD_LBRARY_PATH on Mac OS X) such that your system can find these shared libraries.
2. Do *not* copy all the libraries under libs/ to gex/, but only those that your system does not already have.
3. Do *not* replace libraries under /usr/lib or /usr/lib64 unless you know exactly what you are doing.

Installation on Windows

Using the Automatic Installer

Installing the Windows version of GrADS is very easy. If you downloaded a file called

        grads-2.0.x-win32_superpack.exe

simply run it, answer a few simple questions, and you are good to go (the installer will also automatically set your PATH so that you can run GrADS from the command line window).

Using the ZIP File

If your distribution came in the form of a zip file, simply unzip the distribution file

        grads-2.0.x.win32_superpack.zip

to a place of your choice (e.g., under C:\ or C:\OpenGrADS\) and you are ready to go. Then open Windows Explorer and click on any of the wrapper scripts under OpenGrADS (say, opengrads) and start using it. Setting your PATH This step is only necessary if your distribution came in the form of a ZIP file. You may find convenient adding the GrADS binary directory,e.g.,

        C:\OpenGraDS\Cygwin\Versions\$version\i686

to your PATH. In this example, $version stands for the particular version of the software being installed, say, 2.0.a5.oga.2. The top directory C:\OpenGrADS has also simple VBScript wrapper scripts that can be used to start the main applications. However, there are a large number of utilities that would not be accessible if you do not add the full path above.

For changing your PATH click on

  [Start]/[Control Panel]/[System]

Then select the [Advanced] tab and click on the [Environment Variables] button on the lower left. Select Path under -System Variables- and click on the [Edit] button. Do not delete the current contents of your path; simply append a ";" followed by the name of the directory where your GrADS binaries reside.

See the "GettingStarted.html" Document for additional information.

Windows Remarks

1. The wrappers under Contents/ are not functional in Windows unless you have perl installed.
2. There are a few VBScript wrappers at the very top directory, above Contents/. Just click on them.
3. However, to keep it fom being too busy wrapper for the many tilities have been omittied; setting your PATH (either automtitically with the ".exe" package or by hand with the ".zip" package) is the recommended way to get to these utilities from the command line.

Installation on Linux/Mac OS X/Unix: Classic Method

For downloading regular GrADS releases without the OpenGrAS extensions consult http://grads.iges.org/grads/downloads.html

The subdirectory Classic/ has the bin/ and data/ directories that are usually available as two separate downloads from COLA.

The executables contained in Classic/bin are typically placed in the directory /usr/local/bin. If you do not have write permission for your /usr/local/bin directory, you can put them in the ~/bin subdirectory of your home directory.

    mv Classic/bin/* /usr/local/bin

The subdirectory Classic/data contains the GrADS fonts and maps data sets needed to run GrADS. It can be downloaded from

         http://grads.iges.org/grads/downloads.html.

The contents of Classic/Data are typically placed in the directory /usr/local/lib/grads, the default location for these files. If you do not have write permission for /usr/local/lib/grads, you can place the files elsewhere, but you must also change the environment variable GADDIR so the GrADS executables will know where to find these files.

    mv Classic/data/* dirname
    setenv GADDIR dirname (If dirname is not /usr/local/lib/grads)

See the Troubleshooting section above if you get an error message such as

% grads
grads: error while loading shared libraries: libXaw.so.7: 
       cannot open shared object file: No such file or directory

Documentation and Additional Information

Detailed HTML documentation is now included in this distribution:

          Contents/Documentation.html

You can also consult the on-line documentation available from:

          OpenGrADS Website: http://opengrads.org
              GrADS Website: http://grads.iges.org/grads