

                            The Modules Package
                                
                               04 July 2001

                        INSTALLATION on RedHat 7.x guide

                              R.K. Owen, Ph.D.
                               KooZ Software
                              rk@owen.sj.ca.us
1. Introduction
_______________

Be sure to read the INSTALL guide for details on building the modules
package and for a basic overview of Unix shells.  This guide will
describe how to set up modules for all users on the system by changing
only the global system /etc/ shell files.  The procedure is specific
to Linux, but may be of general application to other Operating Systems.


2. Preparation and Shell Behavior
_________________________________

I find it beneficial to put any shell customizations into a subdirectory
to isolate what comes standard and what I've added.  Also it's generally
easier when migrating to a new platform or OS version.

First thing, make /etc/custom for placing the customization files
to be described below.

The following subsections describe the three major shells and files
sourced on login and per-process.  Login is a once-per-session
operation which is done when you initially log into your account.
A per-process operation is performed whenever a subprocess or child
process is invoked by either invoking a shell directly or via some
program that spawns a shell (for example: editors or email programs
where you can `escape' to a shell with `!').

2.1 C-shell
___________

For the C-shell (csh), and derivatives (tcsh) edit the indicated
files by adding the included lines.  Note that Linux generally uses
tcsh, and that csh is generally a link to tcsh.  The shell files
given here are specific to tcsh.  RedHat/Linux does not typically
provide default user dot files, $HOME/.login and $HOME/.cshrc,
which would get sourced if they were provided.

/etc/csh.login	- called by every csh user once per session on login,
		  a good place for setting environment variables, which
		  are inherited by child processes.
		  These lines can be added near the end, if you desire
		  to overwrite any system ``defaults''.

_________________________________________________________________________

if ( -x /etc/custom/csh.login) then
	source /etc/custom/csh.login
endif
_________________________________________________________________________

/etc/csh.cshrc	- called by every csh process.  This can be a child process
		  invoked within an editor or email program, for example.
		  It's generally a good place for defining aliases, which
		  only live within the process, and are not inherited

_________________________________________________________________________

if ( -x /etc/custom/csh.cshrc) then
	source /etc/custom/csh.cshrc
endif
_________________________________________________________________________

Notice that in both cases the custom files will not be ``sourced'' unless
the execute permission bits are set.  This allows the file inclusions to be
turned on or off by setting or unsetting the permission bits with
	chmod +x /etc/custom/csh.*
or
	chmod -x /etc/custom/csh.*

In addition to the above system files, the users' dot files files are
sourced.

$HOME/.login	- called once per session on login.  It's intended
		  for the user's environment variable customizations.

$HOME/.cshrc	- called per-process.  It's intended for the user's
		  alias customizations.

2.2 Bourne Shell
________________

The Bourne shell (sh) traditionally only sources /etc/profile on
login in addition to the user's $HOME/.profile.  However, Linux
generally uses GNU bash which does have other files ($HOME/.bashrc)
that are sourced when a child process is started up.

Linux/RedHat generally sets the default user shell to be bash.  It's
a good idea to keep it that way, if you are inclined to the Bourne shell.
If bash is invoked as sh (via a link), then bash will restrict itself
to the limited sh behavior with regards to start-up scripts.
Therefore, you will notice in some of the scripts that `sh' is aliased
to `bash' so you will be invoking bash fully.

/etc/profile	- called by every sh user once per session on login,
		  a good place for setting environment variables, which
		  are inherited by child processes.
		  These lines can be added near the end, if you desire
		  to overwrite any system ``defaults''.
_________________________________________________________________________

if [ -x /etc/custom/profile ]; then
	. /etc/custom/profile
fi
_________________________________________________________________________

/etc/bashrc	- called by every bash process, only because it's been
		  finessed by the default user .bashrc file.  This will
		  be explained below.
_________________________________________________________________________

if [ -x /etc/custom/bashrc ]; then
	. /etc/custom/bashrc
fi
_________________________________________________________________________

Notice that in both cases the custom files will not be ``sourced'' unless
the execute permission bits are set.  This allows the file inclusions to be
turned on or off by setting or unsetting the permission bits with
	chmod +x /etc/custom/profile /etc/custom/bashrc
or
	chmod -x /etc/custom/profile /etc/custom/bashrc

In addition to the above system files, the users' dot files files are
sourced.

$HOME/.profile	- called once per session on login.  It's intended
		  for the user's environment variable customizations.

$HOME/.bashrc	- called per-process (bash only).  It's intended for
		  the user's alias customizations.  This is the default
		  unless the $ENV or $BASH_ENV environment variables
		  are defined.

2.3 Korn Shell
________________

The Korn shell (ksh) sources /etc/profile on login and the
user's $HOME/.profile and whatever is pointed to by the $ENV
environment variable in the user's home directory.

Linux/RedHat generally does not install ksh automatically,
but is available as a rpm on the installation CDs.  The version
offered is the ``Public domain Korn shell'' pdksh.

/etc/profile	- called by every ksh user once per session on login,
		  a good place for setting environment variables, which
		  are inherited by child processes.
		  See the Bourne shell for customization details.

In addition to the above system files, the users' dot files files are
sourced.

$HOME/.profile	- called once per session on login.  It's intended
		  for the user's environment variable customizations.

$ENV		- called per-process (bash only), typically defined
		  as $HOME/.kshenv, but could be set to $HOME/.bashrc.
		  It's intended for the user's alias customizations.
		  If $ENV is not defined, then nothing is sourced!

3. Skeleton Files
__________________

RedHat is fairly light on the skeleton dot files. Of those
mentioned above, only .bashrc is provided.  However, if modules
is installed and implemented in the system files, then this
should be sufficient.  The purpose of the default .bashrc provided
is to source the system /etc/bashrc to overcome this deficiency
inherent to sh/bash/ksh.

4. Custom System Files
_______________________

If you have followed the above recommendations, then you are now
prepared to add your own customizations to the system, and to have
modules installed on your system for all your users.
This document will refer to the modules source directory as $MODULES_SRC, which
would be set to /usr/local/Modules/src/modules-3.x.y if that is where
you have unpacked the module sources.

The system files provided in the modules sources references a `default'
directory.  If you follow the template provided by the RKOConfigure script
and are doing a configure with
	./configure --prefix=/usr/local/Modules/@VERSION@ ...
then the different module versions are placed in /usr/local/Modules.
In this directory, the stable module version directory should be
set as a symbolic link named `default'.  New versions of the modules
package can be added, tried and tested before making it the operable
version for the general users.

(This is described in further detail in sect 2.1 of the INSTALL document.)

4.1 System Environment Variables
________________________________

There are many environment variables that are used by the various tools
found on a Unix system.  For example: `man' looks at $MANPATH to search
for man directories.  The system shell files should define these environment
variables so that the modulefiles can append onto them.  It's not a
requirement, but it does make things explicitly clear.

MANPATH			UNIX man documentation search path
PATH			executable search path
XAPPLRESDIR		X11 resource location search path

The following environment variables are typically found on Unix systems
with dynamically loaded libraries and GNU compilers and tools

CPLUS_INCLUDE_PATH	g++ include directory search path
C_INCLUDE_PATH		gcc include directory search path
INFOPATH		GNU info documentation search path
LD_LIBRARY_PATH		run-time dynamically loaded libraries search path
LD_RUN_PATH		ELF object settable run-time dynamically loaded
			library directory search path
LIBRARY_PATH		generic ld library directory search path

These environment variables are specific to GNOME and application
development.

GNOME_LIBCONFIG_PATH	GNOME library definition script search path
GNOME_PATH		GNOME application and library package search path


4.2 C-shell System Files
________________________

The C-shell /etc/custom files that were referenced in section 2.1
are located in $MODULES_SRC/etc/global.  The files of
interest are:

	csh.cshrc	Per-process run-command script.
			Defines `module' alias, and alias `sh' to `bash'.

	csh.login	Per-session run-command script.
			Sets the environment variables mentioned in sect 4.2.
			Sources the csh.modules script and sets $ENV
			to $HOME/.bashrc (see sects 2.2 & 2.3).

	csh.modules	Sources the appropriate C-shell (or derivative)
			modules init script in the `default' modules
			directory (see sect 4.0).


4.3 Bourne Shell Derivative System Files
________________________________________

The bash & ksh /etc/custom files that were alluded to in sections 2.2 & 2.3
are located in $MODULES_SRC/etc/global.  As mentioned in sect 2.2 we do
not use a strict Bourne shell, because of its limitations; therefore,
only the derivative shells will and should be used.
The files of interest are:

	bashrc		Per-process run-command script.
			Defines a module shell function, and defines a
			shell function for `sh' to reference `bash' instead.

	profile		Per-session run-command script.
			Sets the environment variables mentioned in sect 4.2.
			Sources the profile.modules script and sets $ENV
			to $HOME/.bashrc (see sects 2.2 & 2.3).

	profile.modules	Sources the appropriate Bourne shell (or derivative)
			modules init script in the `default' modules
			directory (see sect 4.0).


5. Disclaimer
_____________

The files provided by the modules package are only templates.
You will probably need to modify these files for your own system
and requirements.

