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 here at MCS.

Some of you might have experienced the problem of correctly defining your PATH, MANPATH, and other environment variables. Even if you didn't have problems, you certainly had to work with it to create the environment you wanted. SoftEnv attempts to make this easier for you by abstracting applications into keywords. If you want to use an application, you just have to include a keyword for it. SoftEnv and the administrators will take care of the details. SoftEnv is also better for the administrators, for we spend less time on user problems and more time on more important things.


Editing your .soft file

The .soft file is a configuration file to define the environment you want. Each line of the file defines something for your environment. The different sorts of tokens available are listed in the next section.

The first token you will probably have in your .soft file is the @default macro. This defines all of the default PATHs and MANPATHs needed for the applications you are probably used to using.

Over time, you might want to use a seperate application. Possibly the administrators suggested a key for you to use. Possibly you saw an application you wanted to use after you ran 'softenv'. Either way, just add the correct key to your .soft file and you're set. One thing to remember is that order is important. For example, if it comes first in your .soft file, it will come first in your environment.

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 common feature of SoftEnv. They are identified by +<string>. Each keyword can define one application, such as +matlab, or it can define a certain set of definitions for certain individuals, such as +adm.

Macros
Macros are probably the second most common feature of SoftEnv. They are identified by @<macro>. Macros simply define many keywords and other macros together in one statement. The most common macro you might be familiar with is @default, which gives you the default PATHs and MANPATHs and other important environment variables.

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

If statements
If statements are a new, but useful, feature of SoftEnv. They are in the following format:

 if <variable>=<value> then <operation>

So, some useful examples are:

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

These should be very useful to many people.

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. If you want to set the variable to a certain value, do the following:

 WWW_HOME = http://www.freshmeat.net

Also, you can append something to the existing value, which is invaluable when dealing with PATH variables:

 PATH += /home/abc/bin/

@remove
This is another command in the .soft file, but you probably shouldn't need to use it unless an administrator tells you to. It is used to solve the complicated problem of defining two different versions of the same application.


The order of entries in .soft

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.


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.


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.


Dynamic Environment Changes

This feature of SoftEnv edits your environment on the fly with commands from you. 'soft add <keyword>' will add the keyword to your environment. This feature is good to try out applications that you may not want forever, but you want to see if you like it. 'soft delete <keyword>' will remove any instances of the keyword 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.

'soft add|delete' does not operate on macros. You can only add keywords individually.


Commands to know

soft add|delete
This is dynamic keyword insertion or deletion. It is described just above. However, it is a command to know.

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
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.

Somewhere on the MCS website will be an FAQ for Softenv and .soft, and also a conversion help page to help users convert over to .soft from their .software or .software-beta. Those should be found fairly easily.

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


Authors

SoftEnv version 1.2.0 was created, designed, and developed mostly by Remy Evard. A smaller portion of the work was done by Alan Bailey. To contact the authors, please visit http://www.mcs.anl.gov/systems/software/