softenv-intro - An introduction to the SoftEnv system and how to use it
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:
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.
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.
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.
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/
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.
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
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.
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.
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.
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.
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.
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.
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.
SoftEnv 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/