# $Id: README,v 3.1 2003/08/14 14:08:34 ronisaac Exp $

# Copyright (c) 2001-2003, Morgan Stanley Dean Witter and Co.
# Distributed under the terms of the GNU General Public License.
# Please see the copyright notice at the end of this file for more information.

=========================
README FOR Env::Modulecmd
=========================

* WHAT IS IT?

  By definition, from www.modules.org:

    The Modules package provides for the dynamic modification of a
    user's environment via modulefiles.

    Each modulefile contains the information needed to configure the
    shell for an application. Once the Modules package is initialized,
    the environment can be modified on a per-module basis using the
    module command which interprets modulefiles. Typically modulefiles
    instruct the module command to alter or set shell environment
    variables such as PATH, MANPATH, etc. modulefiles may be shared by
    many users on a system and users may have their own collection to
    supplement or replace the shared modulefiles

  Here's an example: let's say you have several releases of xemacs
  installed, and you want an easy way to choose your favorite release.
  Here's a modulefile that might be called "xemacs/21.1.14":

    #%Module

    prepend-path PATH /usr/xemacs/21.1.14/bin
    prepend-path MANPATH /usr/xemacs/21.1.14/man

  Then there's a binary, called modulecmd, which outputs eval'able
  code in a variety of languages. If your shell is ksh, you might
  type: "eval `modulecmd ksh load xemacs/21.1.14`" to properly
  configure your environment.

  Now, modulecmd supports perl as well. If you issue the command
  "modulecmd perl load xemacs/21.1.14", given the above modulefile, it
  will spit out something like this (well not exactly, but here's a
  simplified version):

    $ENV{'PATH'} = "/usr/xemacs/21.1.14/bin:" . $ENV{'PATH'};
    $ENV{'MANPATH'} = "/usr/xemacs/21.1.14/man:" . $ENV{'MANPATH'};

  That's where Env::Modulecmd comes in. You say Env::Modulecmd::load
  ('xemacs/21.1.14') and it will run modulecmd and eval the output.
  (It can also unload modules and do some other fancy stuff, like
  check for errors.)

  Note that this is useful only to people who use modulecmd and have
  some modulefiles installed.

* INSTALLATION

  To install this module type the following:

    perl Makefile.PL
    make
    make test
    make install

* DEFAULT PATHS

  There are two environment variables that are critical to the operation
  of both Env::Modulecmd and modulecmd itself:

    PERL_MODULECMD
      The full path to modulecmd. If present, Env::Modulecmd will always
      use its value to invoke modulecmd. Otherwise, it will attempt to
      invoke "modulecmd", relying on it being in the PATH.

    MODULEPATH
      A colon-separated list of directories where modulecmd itself
      should look for modulefiles. Env::Modulecmd doesn't use this value
      directly, but modulecmd will not work if it's not set properly, so
      Env::Modulecmd can set it for you as a convenience.

  At build time, you can specify default values for these two variables,
  to be used in the event they're missing from the environment when
  Env::Modulecmd is invoked. If you're building with perl5.005 or later,
  give one or both of them as arguments to "make":

    make DEFAULT_PERL_MODULECMD=/path/to/modulecmd DEFAULT_MODULEPATH=/a:/b:/c

  If you're using perl5.004 or earlier, you'll need to edit Modulecmd.pm
  by hand before installing. The two values go in the obvious spots near
  the top of the file.

  Note that these default values will work with any version of perl at
  runtime; however, the facility used to replace the tokens in
  Modulecmd.pm with the values supplied to "make" at build time requires
  perl5.005 or better.

* DOCUMENTATION

  See the pod documentation in Modulecmd.pm.

* COPYRIGHT AND LICENSE

  Written by Ron Isaacson <ron.isaacson@morganstanley.com>
  Copyright (c) 2001-2003, Morgan Stanley Dean Witter and Co.

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or (at
  your option) any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
  USA.