[env-switcher-cvs] CVS: env-switcher LICENSE,1.4,1.5 INSTALL,1.3,1.4 README,1.4,1.5

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/env-switcher/env-switcher
In directory sc8-pr-cvs1:/tmp/cvs-serv19772

Modified Files:
	LICENSE INSTALL README 
Log Message:
Update docs

Index: LICENSE
===================================================================
RCS file: /cvsroot/env-switcher/env-switcher/LICENSE,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** LICENSE	19 Jul 2003 18:11:33 -0000	1.4
--- LICENSE	15 Jan 2004 16:38:32 -0000	1.5
***************
*** 1,5 ****
  Software License for Env-switcher

! Copyright (c) 2002-2003 The Trustees of Indiana University.  
                          All rights reserved.

--- 1,5 ----
  Software License for Env-switcher

! Copyright (c) 2002-2004 The Trustees of Indiana University.  
                          All rights reserved.

Index: INSTALL
===================================================================
RCS file: /cvsroot/env-switcher/env-switcher/INSTALL,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -r1.3 -r1.4
*** INSTALL	19 Jul 2003 18:11:33 -0000	1.3
--- INSTALL	15 Jan 2004 16:38:32 -0000	1.4
***************
*** 1,5 ****
  -*- text -*-

! Copyright (c) 2002-2003 The Trustees of Indiana University.  
                          All rights reserved.

--- 1,5 ----
  -*- text -*-

! Copyright (c) 2002-2004 The Trustees of Indiana University.  
                          All rights reserved.

***************
*** 19,31 ****

  However, if someone has a burning desire to compile from source,
! configure takes two important options:

  1. --prefix=DIR: the directory where switcher will be installed
  2. --with-modulefiles=DIR: the directory base where the switcher
     module itself should be installed

  A standard "make all install" will do the deed.

  Usage
  =====
--- 19,81 ----

  However, if someone has a burning desire to compile from source,
! configure takes three important options:

  1. --prefix=DIR: the directory where switcher will be installed
  2. --with-modulefiles=DIR: the directory base where the switcher
     module itself should be installed
+ 3. --enable-suppress-errors: since env-switcher is involved in the
+    startup of *EVERY SHELL SESSION* on your machine, it is *CRITICAL*
+    to understand what this option does before proceedings.  See
+    "Shell Startup Errors", below.

  A standard "make all install" will do the deed.

+ Shell Startup Errors
+ ====================
+ 
+ There is a strong religious debate in the system administrator
+ community about how to handle errors at shell startup.  
+ 
+ - One camp says that outputting messages to stderr is acceptable, even
+   though this makes some utilities fail (e.g., scp, sftp, cpush,
+   etc.).  The rationale multi-fold:
+ 
+   1. You always want to know when there is a problem with shell
+      startup.  Otherwise, some executables (for example) may
+      mysteriously disappear from user's paths, and there is no
+      explanation as to why they are gone.
+   2. Even though *some* utilities fail, others do not.  It is always
+      possible to fix the shell startup error without much effort.
+   3. Other utilities write errors to stderr upon failure, even during
+      shell startup (e.g., xauth, ssh itself, etc.).
+ 
+ - The other camp says that you should *never* output anything to
+   stderr.  Errors should be handled or discarded silently.  Users have
+   to fend for themselves and try to figure out why certain
+   executables, libraries, or man pages have seemingly disappeared,
+   even though they have specific defaults to make them appear.
+ 
+   The main rationale is that outputting to stderr causes some
+   utilities to fail (in some cases, unavoidably -- for example,
+   there's really no good way for scp to *not* fail if something is
+   written to stderr).
+ 
+ I firmly fall in the former camp (if something is wrong, you should be
+ notified, even if it causes other things to fail).  Indeed, I added
+ capabilities to env-switcher a long, long time ago to make switcher
+ not display errors -- it simply required running a single switcher
+ command.  But some lazy system administrators need the default set for
+ them during configuration.  
+ 
+ The end result is that it really doesn't matter that much.
+ Env-switcher now has a configure switch "--enable-suppress-errors"
+ that will set switcher's default behavior in the presence of errors.
+ 
+ The name is meant to emphasize the magnitude of what you are doing:
+ you are supressing env-switcher from showing legitimate errors.  You
+ have been warned.  :-)
+    
+ 
  Usage
  =====

Index: README
===================================================================
RCS file: /cvsroot/env-switcher/env-switcher/README,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** README	19 Jul 2003 18:11:33 -0000	1.4
--- README	15 Jan 2004 16:38:32 -0000	1.5
***************
*** 1,5 ****
  -*- text -*-

! Copyright (c) 2002-2003 The Trustees of Indiana University.  
                          All rights reserved.

--- 1,5 ----
  -*- text -*-

! Copyright (c) 2002-2004 The Trustees of Indiana University.  
                          All rights reserved.

***************
*** 135,139 ****
  Let's go through those 7 steps again, and show the exact switcher
  commands that are used.  Remember that all the string names used below
! (e.g., "mpi", "lam-6.5.6", "mpich-1.2.1" are arbitrary and have no
  special meaning to switcher):

--- 135,139 ----
  Let's go through those 7 steps again, and show the exact switcher
  commands that are used.  Remember that all the string names used below
! (e.g., "mpi", "lam-7.0.2", "mpich-1.2.1" are arbitrary and have no
  special meaning to switcher):

***************
*** 141,149 ****
     section:

!    switcher mpi --add-name lam-6.5.6 /opt/lam-6.5.6/etc

!    This copies a modulefile named "lam-6.5.6" from /opt/lam-6.5.6/etc
     into the switcher central repository, and makes the name
!    "lam-6.5.6" available under the "mpi" tag group.

  2. The MPICH OSCAR RPM is installed:
--- 141,149 ----
     section:

!    switcher mpi --add-name lam-7.0.2 /opt/lam-7.0.2/etc

!    This copies a modulefile named "lam-7.0.2" from /opt/lam-7.0.2/etc
     into the switcher central repository, and makes the name
!    "lam-7.0.2" available under the "mpi" tag group.

  2. The MPICH OSCAR RPM is installed:
***************
*** 153,161 ****
  3. The OSCAR sysadmin picks LAM/MPI to be the default:

!    switcher mpi --add-attr default lam-6.5.6 --system

!    Now all users will magically invoke the lam-6.5.6 modulefile upon
     shell initialization, and have their $PATH and $MANPATH set for
!    LAM/MPI 6.5.6.

  4. Joe User wants to see what other MPI implementations are available:
--- 153,161 ----
  3. The OSCAR sysadmin picks LAM/MPI to be the default:

!    switcher mpi --add-attr default lam-7.0.2 --system

!    Now all users will magically invoke the lam-7.0.2 modulefile upon
     shell initialization, and have their $PATH and $MANPATH set for
!    LAM/MPI 7.0.2.

  4. Joe User wants to see what other MPI implementations are available:
***************
*** 209,221 ****
  Several query options can be used to show

! % switcher --list

    List all defined tags.

! % switcher <tag> --list

    List all defined names for a given <tag>.

! % switcher <tag> --show [--system|--user]

    Shows the current attributes and corresponding values for a given
--- 209,234 ----
  Several query options can be used to show

! shell$ switcher <tag> = <name>
! 
!   This is probably the most common usage of switcher; users will set
!   their default <name> for a given <tag>.  A common example:
! 
!   switcher mpi = lam-7.0.2
! 
!   This sets the value of the "mpi" <tag> to be the <name> "lam-7.0.2".
!   Of course, the possible values for <tag> and <name> are finite --
!   you can only use the <tag>s and associated <names>s that are
!   installed on your system.  The options listed below provide the
!   valid list of <tag>s and <name>s on your system.
! 
! shell$ switcher --list

    List all defined tags.

! shell$ switcher <tag> --list

    List all defined names for a given <tag>.

! shell$ switcher <tag> --show [--system|--user]

    Shows the current attributes and corresponding values for a given
***************
*** 236,240 ****
  Administrators maintain "tags", "names", and "attributes".

! % switcher <tag> --add-tag [--force]

    Create a new tag named <tag>.  If <tag> already exists, prompt to
--- 249,253 ----
  Administrators maintain "tags", "names", and "attributes".

! shell# switcher <tag> --add-tag [--force]

    Create a new tag named <tag>.  If <tag> already exists, prompt to
***************
*** 242,251 ****
    silently.

! % switcher <tag> --rm-tag [--force]

    Remove the tag <tag> (and all of its corresponding names) if it
    exists.  Prompt for confirmation unless --force is given.

! % switcher <tag> --add-name <name> <dir> [--force]

    Creates a name for the specified <tag>, and copies a modulefile from
--- 255,264 ----
    silently.

! shell# switcher <tag> --rm-tag [--force]

    Remove the tag <tag> (and all of its corresponding names) if it
    exists.  Prompt for confirmation unless --force is given.

! shell# switcher <tag> --add-name <name> <dir> [--force]

    Creates a name for the specified <tag>, and copies a modulefile from
***************
*** 262,266 ****
    before processing creating the <name>.

! % switcher <tag> --rm-name <name> [--force]

    Removes a <tag>/<name> combination from the switcher central
--- 275,279 ----
    before processing creating the <name>.

! shell# switcher <tag> --rm-name <name> [--force]

    Removes a <tag>/<name> combination from the switcher central
***************
*** 275,279 ****
  system-default attributes.

! % switcher <tag> --add-attr <attribute> <value> [--system|--user] [--force]

    Sets the <value> for a given <attribute> under the specified <tag>.
--- 288,292 ----
  system-default attributes.

! shell$ switcher <tag> --add-attr <attribute> <value> [--system|--user] [--force]

    Sets the <value> for a given <attribute> under the specified <tag>.
***************
*** 286,290 ****
    the same if --system is not supplied).

! % switcher <tag> --rm-attr <attribute> [--system|--user] [--force]

    Delete the <attribute> from the specified <tag>.  Prompt for
--- 299,303 ----
    the same if --system is not supplied).

! shell$ switcher <tag> --rm-attr <attribute> [--system|--user] [--force]

    Delete the <attribute> from the specified <tag>.  Prompt for