NOTE: The Softenv system is no longer actively maintained. We plan to replace its functionality with the "Environment Modules" project, as this will keep a more constant computing environment across the resources of the CELS sister orginizations, like LCRC and ALCF.


See: http://modules.sourceforge.net

Max Trefonides -- 04-25-2016


NAME

softenv-intro - An introduction to the SoftEnv system and how to use it


DESCRIPTION

Basic description

SoftEnv is a system designed to make it easier for users to define what applications they want to use, and easier for administrators to make applications available to users. SoftEnv has evolved from the original implementation called Soft designed at Northeastern University in 1994. It is an (almost) complete rewrite with the inclusion of many new features that were necessary for proper operation in the environment at Argonne National Laboratory's MCS division.

In order to use SoftEnv, you create a file called ``.soft''. In this file, you describe the environment you would like using a set of keywords. These keywords are read by the SoftEnv when you login and expanded into a set of environment variables. SoftEnv uses a database managed by the systems adminitrators in order to decide exactly how to build your environment.

There are several advantages to using SoftEnv over setting up your environment yourself in your shell's startup file:

Editing your .soft file

The .soft file is a configuration file used to define the environment you want. You should create and modify this file yourself, although a basic .soft file may be provided with your account. Use any text editor to make changes.

The file essentially consists of list of commands to the SoftEnv system, with one command per line. Empty lines are ignored, and lines beginning with a '#' are considered to be comments and are also ignored.

The exact commands that you can put into your .soft file are listed in the next section.

The order of the commands is important. The things that are listed first in the .soft file are put into your environment first.

It is generally recommended that you simply use this one line in your .soft file: @default

This will give you the default environment, which includes most applications and all system paths, all in a reasonable order. As you find that you need to modify your environment over time, then you can add further keywords to your file.

Once you have edited your .soft file, you will need to update your current environment so that it reflects the changes you just made. You can do this by running the ``resoft'' command.

This man page should provide all the help you need to edit your .soft, and you can always send email to your administrators for help.

The contents of the .soft file

Keywords
Keywords are the most commonly used .soft entries. They are identified by +<string>. For example: ``+matlab'' says to add the Matlab application to your environment. A keyword expands into a set of environment variables such as PATH and MANPATH, and is typically associated with a single application. You can get a list of keywords by running the 'softenv' command.

Most keywords are already part of the default environment, so you will only want to add a keyword to your .soft in two cases: if that application is not part of the environment you already have, or if you want to reorder your environment so that the application overrides some other application.

Macros
Macros are collections of applications. Macros have the form of @<macro>, such as @default and @system. A list of macros is available by running the 'softenv' command.

Comments
Comments are started with a pound sign (#) and affect the rest of the line from where it starts.

If statements
If statements allow you to conditionally modify your environment. They have this format:
 if <variable> = <value> then <operation>
 and
  if <variable> != <value> then <operation>

The <variable> portion of the clause must be an environment variable present at the time of evaluating the if statment (i.e. typically at login time).

The <value> portion should be a string value.

The <operation> is a SoftEnv command: either a keyword or a macro.

Some useful examples are:

 if ARCH=solaris-2 then +gcc-2.3
 if HOSTNAME=gaea then +emacs-20.2
 if ARCH != sun4 then @default

For convenience when using conditional clauses in your .soft, the soft system guarantees a few environment variables for you:

ARCH

This environment variable will contain a string that is unique for each architecture within the computing environment. A list of valid strings for ARCH can be found at MCS by running this command: whatami -list

HOSTNAME

This environment variable will contain a string that is the short name for the computer you are currently using. It does not include the domain name portion of the hostname.

HOST

This environment variable will contain the long version of the name of the host you are currently using.

Environment Variables
You can also simply set an environment variable from your soft file. These commands have the following syntax: <variable> = <value> <variable> += <value>

The first form is used to set a variable to a certain value, e.g.:

 WWW_HOME = http://www.freshmeat.net

The second form is used to append a string to the existing value, which is invaluable when dealing with PATH variables:

 PATH += /home/abc/bin/

@remove <keyword>
This keyword can be used to remove specific applications and macros from your environment. It turns out that this is a fairly tricky operation because most of SoftEnv's values are computed at login time, before the results of conditionals are known. As a result, the @remove keyword does not really ``remove'' the application from the created environment. Instead, it keeps that application from being added by subsequent parts of the .soft file.

Thus, the rules for using @remove include:

@remove can only be used to remove keywords, not macros.

@remove should be used towards the beginning of your .soft. It will remove any following references to that keyword, but will not remove the keyword from any preceding portions of the environment that have been defined.

@remove applies to all architectures and hosts, regardless of conditionals.

The best time to use @remove is when you want to use a very specific version of an application, but a different version is included in the default system. I.e., if gcc-2.1 were part of the default system, you might do:

  @remove +gcc-2.1
  @default
  +gcc-2.5

In general we recommend that you check with the administrators before using the @remove command.

An example .soft file

Here's a simple example .soft file:

  # A simple .soft file.
  # Remember to type "resoft" after working on this file.
  # Use the basic environment.
  @default
  # Add the current beta totalview system on Solaris boxes.
  if ARCH = solaris-2 then +totalview-beta

  # Set up my environment variables
  CVSROOT = /project/code/CVS
  PATH += /home/gropp/bin
  PATH += /home/gropp/bin/$ARCH
  if HOST = fire then MYTESTVAR = on_fire

The order of entries in a .soft file

Each line in the .soft file causes a set of environment variables to take on a particular value. The effects of these variables take place in the order specified in the file. This means that the order of the entries in the .soft file is very important.

For example, a line saying ``FOO = bar'' sets the environment variable FOO to bar. Let's say you have these two lines in your .soft:

  FOO = bar
  FOO = qux

When .soft is finished executing, FOO will be equal to ``qux''.

This is a bit trickier when it comes to setting your PATH, because your shell reads your PATH variable and looks for programs by reading each directory in your path in the order that the directories are in the PATH variable. Let's say you have these two lines in your .soft:

  @default
  PATH += ${HOME}/test/bin

These two lines will set your PATH to the value of the default system path, and then append the directory $HOME/test/bin to the PATH. This is probably what you want.

However, let's say you had these two entries in your .soft:

  +totalview-2.3
  @default

These entries mean ``put totalview-2.3 in my path, and then put all the system directories in my path''. This will work great as long as you really want totalview-2.3. However, if totalview gets upgraded, and totalview-2.5 becomes a part of the system directories, you will still be getting totalview-2.3. This may be what you want, but it may not.

Working with your .soft file

When your .soft file is read by soft, it creates csh and sh cache files that are called:

  .soft.cache.csh
  .soft.cache.sh

These are built directly from your .soft file.

If there are any detectable errors in your .soft file, a warning will be printed as the file is processed.

Whenever a change is made to the .soft file, the changes can be loaded into the current enviroment by running this command:

  resoft

If you're using a file other than '.soft', you can load your enviroment by pointing the resoft command at that file:

  resoft .soft-other

The next time you login, you will get the environment created from your .soft, not this other file. This is because your .soft is used on each different system, and changing the default cache can get fairly confusing.

The Case against Application Keywords

Thus, having the application keyword ``+xemacs-19.13'' will add the directory for xemacs-19.13 to your PATH, the manual directory to your MANPATH, and any environment variables specific to that version of xemacs to your environment. Note - using an application keyword is usually not a good idea! Most applications should be available in the default system paths. Only use these if you need a very specific version of some application, and understand that you will get this version of that application, even if the default system one has been upgraded to a newer one or something.

Power Users

All that said, you may prefer to build your own environment rather than using the default. Go for it and may the force be with you.

In the output of ``softenv'', flags are included next to keywords. These tell you whether or not a keyword is included as part of the default environment, and whether or not we recommend looking into these keys when building your own environment.

Looking up keywords in the Database

You can get all of the information related to a keyword with a single command. If you want to do this, execute the following:

  soft-dbq <keyword>
  or
  soft-dbq <macro>

The output of this command will show you what architectures this keyword has an effect, and exactly what is done to your environment. For example, it will show the changes to your PATH variable and any other changes.

Dynamic Environment Changes

This feature of SoftEnv edits your environment on the fly with commands from you. 'soft add <keyword|macro>' will add the keyword or macro to your environment. This feature is a good way to try out applications that you may not want forever, but you want to see if you like. 'soft delete <keyword|macro>' will remove any instances of the keyword or macro from your environment. So the following set of commands will allow you to use gcc-2.5:

  soft add +gcc-2.5
    # gcc-2.5 is now put into your environment
  soft delete +gcc-2.5

It is recommended that you use resoft whenever you think it is necessary. 'resoft' is guaranteed to return your environment to your initial settings.

Useful SoftEnv commands

soft add|delete <keyword>
This is dynamic keyword insertion or deletion. It is described right above.

softenv
This program will print all of the keys and macros available for use in the SoftEnv system. A list of the macros come first, and the keys follow. A paragraph at the top of the output explains how to read the output.

resoft <file>
This command will reload your environment. So, for example, whenever you make changes to your .soft, run resoft and the changes will take effect. If <file> is specified, then that file is used instead of .soft. However, that file needs to be in your home directory, because it writes to that directory.

man softenv-intro
This manual page.

More Information

More information can be found in manual pages, text files, and web pages.

A few manual pages you might want to look at are the following:

Also, if the installation directory of SoftEnv is known to you, the doc directory will contain text files and html files of the documentation.

SoftEnv also includes a web page of SoftEnv FAQs that should be part of the local web documentation.

Lastly, more information can be found by emailing your administrators or the creaters of SoftEnv.

Authors

SoftEnv version 1.4.2 was created by Remy Evard, and was designed and developed by Remy Evard and Alan Bailey. To contact the authors, please visit http://www.mcs.anl.gov/systems/software/