
                             The Modules Package
                                Version 3.0
                                
                               John L. Furlani
                                SunSoft, Inc.
                             j.furlani@ieee.org

			        Peter W. Osel
                            Siemens AG, SBS DS 33
                                 pwo@Osel.DE

                                Jens  Hamisch
                          Strawberry EDV Systeme GmbH
                             jens@Strawberry.COM


                               2  October 1996

1. Introduction
_______________

This directory contains a copy of The Modules Package that uses Tcl (Tool
Command Language) developed by John Ousterhout at Sun Microsystems.  You
must obtain a copy of Tcl (at least version 7.3).  Tcl should be available
either at the same site you obtained The Modules Package or from
sprite.berkeley.edu.

For an introduction to The Modules Package, see the paper, "Modules: Providing
a Flexible User Environment", in the Proceeding of the 1991 Large Installation
Systems Administrators USENIX Conference (USENIX LISA V).  A copy of the paper
is included in Postscript form in doc/Modules-Paper.ps.  The paper describes
the concepts behind Modules and a prototype/proof-of-concept implementation
based on shell scripts being sourced into the user environment.  The
implementation details have changed, but the package concepts haven't.


2. Documentation
________________

The ./doc directory contains both the paper and man pages describing the
user's and the module writer's usage.

Big changes for 3.0:
    o  Testsuite added

    o  Support for Tcl/TclX 7.6 and Tk 4.2

    o  Introduction of user levels for generation of error messages

    o  Enhanced module logging facilities using stdout, stderr, files
       and the syslog

    o  Enhanced module trace feature

    o  Modulefile configuration management. Symbolic module file names
       and aliases

    o  Hierarchical modulecmd rc-file structure

    o  Command line switches

    o  Traceable output for module list and module command (configurable
       and on request)

    o  Active dependecy resolution. This is experimental at the moment!!!

Big changes for 2.3:
    o  Support for Tcl/TclX 7.5 and Tk 4.1

    o  Code cleanup. Added inline documentation. Unification of source
        module layouts.

    o  Added alloc tracer for locating memory leaks

    o  Added 'uname domain'.

    o  Added M_HELP as a modetype, so that 'module-info mode [help]' will
	be possible

    o  Optional support for extended Tcl (tclX) 7.x

    o  Modules now uses the standard Tcl initialization (init.tcl),
	enabling autoloading of Tcl functions.

Big changes for 2.2:
    o  Installation changed to use GNU's configure script (version 2.x).

    o  Updated to support Tcl 7.x

    o  Paths and modulefile names with '+'s in them should work now.

    o  Multi-level paths should work.  Well, at least better than 2.0.

    o  "module load ." doesn't dump core.

    o  Support for "perl" output.

    o  Ability to exit without having modulefile listed as "loaded".
        Use an argument to exit other than 0 or 1.

    o  More stringent checking of user-level command names.

    o  A sysconf.h file to help with multi-platform support.
        This area and the installation process still needs work.

    o  A new and improved cmdXResource.c

    
Big changes for 2.0:

    o  Added a new environment variable, _LOADED_MODULEFILES_, which keeps
        track of which file and directory each modulefile was loaded from.
        This is necessary for locating modulefiles if the MODULEPATH variable
        has changed or if a full pathname was specified as the modulefile to
        load.

    o  Added an update sub-command which attempts to reload all of the
        currently loaded modulefiles.  When Modules is first initialized a
        snapshot of the environment is saved into a file in the user's home
        directory.  When the update sub-command is run, the environment
        variables are restored to their earlier state and the modulefiles are
        reloaded.  Only the variables that modulefiles touch are changed.
        
    o  Added an purge sub-command which unloads all currently loaded
        modulefiles.
    
    o  set-alias should be fixed and should work for all shell types.  In the
        case of the Bourne shell-variants, it creates functions.

    o  If multiple modulefiles are listed to be added or removed and one of
        them has an error, only that modulefile will fail.  All of the other
        modulefiles will load or unload successfully (assuming they don't in
        turn have errors).

    o  INCOMPATABILITY ISSUE:  stdout is not tied to stderr any more.  So, if
        you to a 'puts stdout' in any of your modulefiles, that will go
        directly to the shell.  You should change all puts statements that
        goto stdout to goto stderr.
        
    o  avail prints out all of the modulefiles by recursively looking through
        all directories under every entry in MODULEPATH.  It will also cache
        the information since it can take much longer than the previous
        version.  Finally, only files containing the "#%Module" magic cookie
        header and that don't end in '~' will be listed.  Other files will be
        ignored.

    o  A .version file in a modulefile directory will be parsed to find out
        which modulefile is the default version for the directory name.

    o  Locating modulefiles is recursive and ignores files ending in '~' and
        which don't have the "#%Module" magic header.

    o  The switch command really works now.

    o  Added uname command for fast access to system information.  Not sure if
        uname is portable.

    o  Unload using a directoryname will look for a version that is already
        loaded instead of the default version specified by the .version file
        or by the highest lexicographical name in the directory.

    o  Added ability for modulefile-specific help and modulefile-specific
        display.



3. Building and Installing Modules
__________________________________
(Read the INSTALL file for a more recent description of installation
procedures.)

First, you'll need to decide on a location to keep Modules on your network.

The path name to the initialization files must be the same on all of the
systems using Modules.  This is because your users' .cshrc or other shell
startup files must hard code this directory in order to source their Modules
initialization file.

You will also need to choose a location for the 'modulecmd' program and all of
your modulefiles.  The location of these can be different on different
systems, but it is not recommended.  These paths are used in the Modules
initialization files.  If you decide not to use this structure, then you
will need to edit the initialization files by hand.  Use the --prefix
configure option to control the installation of Modules.  See below for more
configure options.

Example:
	If you decide to keep Modules in /depot/Modules, run
            "configure --prefix=/depot/Modules" 

	initialization file   -->  /depot/Modules/init
	modulefiles           -->  /depot/Modules/modulefiles
	modulecmd             -->  /depot/Modules/bin
 	manual pages          -->  /depot/Modules/man
 	Tcl libraries	      -->  /depot/Modules/lib/tcl	(if any)

The Modules Package is written in conformant ANSI C and should build on any
UNIX machine with an ANSI C compiler like the GNU C compiler.  Check the
MACHINES file for a list of machines and OSs Modules has been test built on.
The module error logger requires the ANSI C 'stdarg.h' being installed. At
the moment there's no support for traditional vargargs handling using 
'varargs.h'.

To build Modules, first build Tcl and run the tests provided with Tcl to
verify it built correctly.

If yout want to use the testsuite, you should install dejagnu-1.2 or better
before configuring modules. Be sure to have your PATH pointing to 'runtest'
when calling 'configure'.

Then run the GNU autoconf script, ./configure.
A Makefile will be automatically generated.

Some Modules-specific configure options...  (See also ./configure --help)


    --with-force-path=<path>	With force path=<path>
    --without-force-path	Without  - " -		[DEF]

  o The force-path option allows you to specify a path that should be kept
      at the end of the PATH environment variable.
     

    --with-split-size=<size>	With split size=<size>
    --without-split-size	Without  - " -		[DEF]

  o Some C Shell implementations have a size requirement on the length of
      the line which can be evaluated.  If you run into very long
      environment changes, you may run into this problem.  Select size to be
      something less than the size your C Shell will accept.  C Shell limits
      are around 1024.


    --enable-cache		With directory cache	[DEF]
    --disable-cache		Without  - " -

  o Modules will maintain a cache of the available modulefiles for each
      directory in the modulefile search path.  The cache greatly
      accelerates how long it takes to determine the list of available
      modulefiles.


    --enable-shell-funcs	With sh functions	[DEF]
    --disable-shell-funcs	Without  - " -

  o Does your Bourne Shell support functions?  If so, then the modulefile
      set-alias will work properly.  If not, aliases will not be available
      when using the Bourne Shell.

            
    --enable-shell-eval		With shell alias eval
    --disable-shell-eval	Without  - " -		[DEF]

  o This specifies whether aliases will be evaulated by the C Shell or
      sourced from a temporary file.  Some C Shells can't handle the
      specification of aliases in the eval line very well.  To get around
      this problem, when aliases are set by a modulefile, a temporary file
      is created and then sourced into the C Shell.  This guarentees the
      aliases are evaluated correctly.
 

    --enable-free		With free() calls
    --disable-free		Without  -" -		[DEF]

  o Since the modulecmd is transient, disabling calls to free() can provide
      some small performance enhancement since the memory usage is low and
      the program will exit rapidly.  If you want the calls to free() back
      in for some reason, set this option.


    --with-cache-umask=<umask> With cache files umask=<umask>
    --without-cache-umask      0				[DEF]

  o Set the umask for creating cache files.  The default of 0 creates
      modulecachefiles that are writable by anyone.  If you don't like
      world writable files, or mount the Modules file system read-only
      set it to 002.  Don't forget to occasionally refresh the cache
      files by running module avail with an account that has write
      permissions.


     --with-static		Link static (don't use dynamic libraries)
     --without-static		Use dynamic libraries	[DEF]

  o A note.  I've found that at least the X11 libraries should be linked
      statically.  If you encounter problems, e.g. getting some warnings
      about version mismatch of dynamic libraries, link the modulecmd
      statically.

  o If you're using Tcl/TclX 7.5 on an SunOS or Solaris box, the dynamic
      loader library (libdl.so.1) will be liked in. Since this is not
      available as a staic library, using  --without-static is recommended.


     --with-tclx		With extended TCL (tclX) commands
     --without-tclx		Without  - " -		[DEF]

  o Extended Tcl is a superset of standard Tcl and is built alongside
      the standard Tcl sources.  It adds many new commands to standard
      Tcl, e.g. Unix Access Commands, File I/O Commands, String and
      Character Manipulation Commands, ...  See the manual pages that
      come with tclX for a complete list of added features.


     --with-module-path=<path>	With user defined MODULEPATH
     --without-module-path	Default $prefix/modulefiles	[DEF]

  o Set the MODULEFILE environment variable in all initialization
      files to the given <path> (colon separated!).  The default
      is to use $prefix/modulefiles.


     --with-autoload-path=<path>	directories where Tcl will search
					for libraries to load
     --without-autoload-path		Default $prefix/lib/tcl	[DEF]

  o <path> will be prepended to Tcl's auto_path variable.  These
      directories are searched for library functions that can be
      autoloaded.  Note that this path has to be *space* separated and
      enclosed in double quotes!!
      The default is to use "$prefix/lib/tcl".


     --with-tcl-include=<path>		directory to lookup the TCL headers
     --with-tcl-libraries=<path>	directory to lookup the TCL libs
     --with_tclx_include=<path>		directory to lookup the TCLX headers
     --with_tclx_libraries=<path>	directory to lookup the TCLX libs

  o <path> will be passed to the C compiler using the -I or -L option in 
      order to specifiy directories to look up the TCL(X) includes and
      libraries.
      By default 'configure' will scan system directories in order to 
      locate the TCL(X) headers and libraries.


     --with-debug=<level>		Set up the debug level to the
					specified value
     --without-debug			Disable debugging [DEF]

  o The debug level will be set to the specified value. Available values
      may be looked up in 'modules_def.h'. Debugging may be configured in
      order to trace:

	- module commands
	- TCL interpreter initialization
	- callback functions
	- module file localization
	- utility functions

      Enable this feature for debugging only! The higher the debugging level,
      the greater the amount of runtime information printed! All debug mes-
      sages will be spooled to <stderr>.

      The debug-level cannot be changed at runtime at the moment! It is
      configured as a fixed value at compile time!


     --enable-parseable-msgs		Configure parseable error messages
     --disable-parseable-msgs		Use the traditional ones

  o Switch between traditional error messages in multi-line format or parse-
      able ones that lokk like the GNU messages. The parseable message format
      is:

	module(line):Message-Type:Message-Number: Text

      with Message-Type being one of:

	INFO, WARNING, PROBLEM, ERROR, FATAL, PANIC, DEBUG

      and an unique message id in decimal format.


      --enable-logging                  Enable the module logging feature
      --disable-logging                 No module logging [DEF]
      --with-log-facility-verbose[=<facility>] 
      --with-log-facility-info[=<facility>]
      --with-log-facility-debug[=<facility>]
      --with-log-facility-debug[=<facility>]
      --with-log-facility-warn[=<facility>]
      --with-log-facility-problem[=<facility>]
      --with-log-facility-problem[=<facility>]
      --with-log-facility-fatal[=<facility>]
      --with-log-facility-panic[=<facility>]

   o Turn logging on and define the logging facilities for the different
     error levels. Ech facility may be a syslog-facility as 'local7.debug',
     a standard stream as 'stderr', a filename or the word 'no' for dis-
     abling a single log facility.


      --with-trace-load=<value>  
      --with-trace-unload=<value>
      --with-trace-switch=<value>
      --with-trace-disp=<value>
      --with-trace-list=<value>
      --with-trace-avail=<value>
      --with-trace-help=<value>
      --with-trace-init=<value>
      --with-trace-use=<value>
      --with-trace-unuse=<value>
      --with-trace-update=<value>
      --with-trace-purge=<value>
      --with-trace-clear=<value>
      --with-trace-whatis=<value>
      --with-trace-apropos=<value>

   o Turns tracing for the specific module command on or off. The value
     is a list of colon separated TCL regular expressions matching the
     module files to be traced. This maybe overridden using the 
     'module-trace' command. See 'modulefile(4)' for detailed information.



I have provided a number of example modulefile in the example-modulefiles
directory.  This should help provide you with some idea on how to write
modulefiles.

If you upgrade from a previous module version and have adapted the
MODULEPATH environment variable in your installed init files, don't
forget to set the MODULEFILE in the configuration step:
 
	./configure --with-module-path=$MODULEPATH

Just type 'make' and it should build.

If you have dejagnu installed, you may want to run the testsuite now. Type
'make check' and it should run.

Finally, type 'make install' and 'modulecmd' along with the initfiles will be
installed.


4. modules-interest@eng.auburn.edu
__________________________________

As of release 2.0, I have worked with Richard Elling to create a
Modules interest alias for discussion about Modules and other
Modules-related packages such as Richard's user-setup.

If you would like to be added to the modules-interest alias, mail
majordomo@eng.auburn.edu with "subscribe modules-interest address" in the
body of the message where "address" is your Internet e-mail address.


5. Miscellaneous
________________

tcsh(1) user might want to add the following to their tcsh startup file
(~/.cshrc or ~/.tcshrc): 

# programm tcsh's completion for module command:
complete module \
	'n/use/d/' \
	'n/unuse/d/' \
	'n/*/(load unload switch display avail use \
		unuse update purge list clear help \
		initadd initrm initswitch initlist initclear)/'


You might want to add the following line to /etc/magic, so that file(1)
recognizes modulefiles:

#
# John Furlani's Modules modulefiles
#
0	string		#%Module1.0	Modules modulefile version 1.0


6. Special Thanks
_________________

Ken Manheimer and Don Libes at the National Institute of Standards and
Technology deserve special thanks for their help and ideas toward the
original paper, design considerations, and the use of Tcl.

Maureen Chew and others at Sun Microsystems have provided me with an
test site and many ideas on how to improve my Tcl implementation of
Modules.

Leif Hedstrom added GNU's autoconf support, x-resource command, helped
significantly with the port to Tcl 7.x and has provided valuable input.

I would also like to thank Richard Elling at Auburn University for his 
comments, help with the Modules' man pages and his application
'user-setup'.  A paper on 'user-setup' was presented at this year's
USENIX LISA VI conference.  The paper and the application can be
acquired via anonymous ftp from ftp.eng.auburn.edu.

Peter W. Osel <pwo@guug.de> added support for Extended Tcl (TclX),
autoloading of Tcl functions, autoconf 2.x;
 
There are many others that deserve thanks but too many to list here --
thanks to everyone who has helped.


7. Bugs and Comments
____________________

Report bugs to 'j.furlani@ieee.org'.  Please try to provide a full
environment listing and a copy of the modulefiles you're trying to
manipulate.  Be as explicit and detailed as possible.

Comments and suggestions for improvement are always welcome.

Thanks,
John L. Furlani
