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.

• NAME
• DESCRIPTION
• Basic description
• Editing your .soft file
• The contents of the .soft file
• An example .soft file
• The order of entries in a .soft file
• Working with your .soft file
• The Case against Application Keywords
• Power Users
• Looking up keywords in the Database
• Dynamic Environment Changes
• Useful SoftEnv commands
• More Information
• Authors
• FAQ

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:

• If the environment variables are different on different kinds of systems (such as Solaris vs. Linux), SoftEnv automatically takes care of this.

• If the application you are using gets upgraded, SoftEnv will use the new values for the environment variables.

• In most cases, you can avoid all of the details of the system in order to get a useful environment. The defaults are useful. If you want to override the default, though, you can.

• SoftEnv lets you quickly change your current environment temporarily if you want to test a specific version of an application.

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:

• softenv

• resoft

• soft

• softenv-intro (this manual page)

• softenv-admin (for the curious)

• softenv-code (for the very curious)

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/

FAQ

General Questions

What is the purpose of SoftEnv, and how does it relate to .software?

SoftEnv is a software abstraction system. It allows users to specify applications they want to use in a configuration file, and then their environment is setup correctly on every UNIX system in our computing environment. . Users don't have to track application changes (like new environment variables or changed paths) or worry about new applications unless they want to.

The .soft file is used on every UNIX computer in MCS to set 3 basic things in your shell's environment:

• Your PATH.
• Your MANPATH.
• Any other environment variables you may want to set.

(Before March 2000, this functionality was handled by a file called .software.)  On a conventional UNIX system, you are responsible for setting these up yourself.   However, at MCS, the recommended values for these variables changes rather frequently.  So, rather than your having to try to keep up with all of the recommendations and special changes and then update your files yourself, we put the values in a database, and the .software system automatically looks them up for you. 

For example, if your PATH needs to be updated for you to be able to access some newly-installed piece of software, then the .soft system will change your PATH automatically the next time you login.   The way to customize your environment is explained in this FAQ.

^ Back to Questions ^

What do I put in my .soft file?

In general, we recommend just putting this line in to start with:

@default

This will add all of the system paths, tons of applications, and local customizations to your environment. 

As your needs grow over time, you can add specific applications that might not be part of the default environment (the vast majority are in the default though), or your own environment variables, or special conditional statements.  All of these are described later in this page in the Syntax section.

^ Back to Questions ^

What keys can be used in the ~/.soft file?

The command 'softenv' displays every key that exists on the new system.  Probably more than you want to see, in fact.  Read the man page for softenv for more information.

Two other useful features to know are:

• softenv -a <arch> :
  This will display keywords that only are defined on that architecture. Useful for finding out which architectures a certain keyword effects.
• softenv -k <string> :
  This will display keys with that string in their name or description. Useful for finding a key that you know exists, but you aren't sure how to spell it.

^ Back to Questions ^

Are SoftEnv keys case sensitive?

YES! Contrary to the previous .software system,  'softenv' does care about the case of words.  Therefore, +idl is not the same as +IDL, also notice these

• softenv -k Commu
• softenv -k commu

return different keys.

^ Back to Questions ^

What if I want to use a keyword only once?
How do you change your enviroment with SoftEnv on the fly?

With 'soft add <keyword>', you can at that moment, add that keyword to your environment. Similarly, with 'soft delete <keyword>', you can delete any instances of that keyword from your environment. It is also suggested that you run 'resoft' whenever you want to be sure your environment is back to normal.

For example, if you want to try out idl, do the following:

> soft add +idl
> idl &
(do whatever you want)
> soft delete +idl

Or, you can create two .soft files. If you create a .soft.idl file containing:

+idl
@default

then you  execute the command 'resoft .soft.idl'.  You will then get the environment based on that file. A plain old 'resoft' will set you back to your real environment.

^ Back to Questions ^

Can a key be added to all users in a group? (globus, adm, fl, etc)

We recognize this is helpful for many groups; however, you can't change it yourself. Send an email to systems and we will usually agree with your plan and set up the key.

^ Back to Questions ^

Where do I find more information?

At any UNIX prompt, type

• man softenv-intro
• man softenv
• man soft
• man resoft

There are other administrative man pages which systems can point you to.

^ Back to Questions ^

Are you releasing this software to the public?

Yes, this software will be open-source and released as part of Msys, the MCS Systems Administration Toolkit. The coding was done by Remy Evard ([email protected]) and Alan Bailey ([email protected]).

^ Back to Questions ^

How can I find out what is included in the default?

Run the command 'softenv'. If there is a '*' on the left side of a keyword, that tells you that this keyword or macro is included in the definition of @default.

^ Back to Questions ^

What if I really hate all these .soft files, and want to define my environment using only my .cshrc file?

Create a file called .nosoft in your home directory. This will disable all parsing of .software, .software-beta, and .soft files.

May the force be with you. :)

^ Back to Questions ^

How do I have my cron jobs use my .soft?

The SoftEnv system creates sh and csh scripts in your home directory that are loaded by the shell to build your environment. Cron jobs don't do this automatically, but you can arrange for them to do so by loading them directly.

If your cron job is an SH script, do this near the beginning: . $HOME/.soft.cache.sh

If it's a csh script, do this: source $HOME/.soft.cache.csh

Note that if your cron job is just a simple command in your crontab then this won't work... the command needs to be invoked from a script that first does one of the above calls, and then calls the command.

^ Back to Questions ^

Syntax Questions

What is the syntax of a SoftEnv file (~/.soft)?

The .software file is a basic text file. Lines starting with a # are considered to be comments and are ignored.  Blank lines are fine too.  Note:

• += and = are valid for setting environment variables, use them wisely
• Conditionals are very versatile, and can be used for a lot of things
• The @remove function removes keywords and macros from any macros later in your .soft file.

Each line in the .soft will look like one of these:

@{macro}
+{key}
PATH+=/foo
MANPATH+=/foo/foo
CVSROOT=/home/foo/foo
if ARCH=solaris-2 then PATH+=/foo
if ARCH=sun4 then @sun4-legacy-apps
if HOSTNAME=gaea then +gcc-2.3.1
@remove {key} {macro}

An example ~/.soft file would be:

^ Back to Questions ^

How do I use IF (conditional) statements in my .soft file?

Conditionals are very versatile now, and are a totally different syntax as compared to the old syntax. Use them like:

if ARCH=linux then +idl

You can use any variable in the conditional; however, only

• ARCH --  the architecture of the machine you are on.
• HOST -- the long name of the machine you are on (ex. fire.mcs.anl.gov)
• HOSTNAME -- the short name of the machine you are on (ex. fire)

are provided. You can also include anything after the 'then' in the statement, such as PATH sets, keyword additions, or macro additions.

You can additionally create any other variables you might want. Some examples:

FOO="`whatami`"
if FOO=sun4 then +adm

MYVAR="`/homes/username/bin/usedefault`"
if MYVAR="yes" then @default

if HOSTNAME=fire then PATH+=/homes/username/bin/fire

^ Back to Questions ^

What are valid ARCH values?

You can use anything from the output of 'whatami -l'.  However,  at this moment (Feb 2000), only five of those will do anything:

• linux
• irix-6
• solaris-2
• sun4
• aix-4

(Notice also that these are different than the architecture strings used with .software or .software-beta.)

^ Back to Questions ^

Trouble Shooting Questions

My environment is broken. I can't even run 'rm', what do I do??

Type resoft, which will almost always give you a working environment. Then create a .soft file with @default in it, and log out and log back in. This
will create a clean environment from your .soft file.

^ Back to Questions ^

There is a problem using application foo. What should I do?

First, check your .soft file to make sure it is sane.

• If there are two different versions of that application defined, that is usually a problem.
• Did you define the version of that application you actually want to use?
• You can also try putting the keyword ahead of your @default definition, which might work.

If all else fails, send email to systems, and we'll see what the problem is.

^ Back to Questions ^

On login, I get a message that says my software environment is being updated. What is happening?

That either means you updated your .soft file recently, or an administrator made a change to the database.

To find out what changes an administrator made, view this webpage containing information from the rcs updates to the database.

^ Back to Questions ^

I use .soft, and on login, I get a warning about my .software or .software-beta files. I want to get rid of it.

Assuming your environment is set up how you want it, you can remove your .software or .software-beta files from your home directory,
either by deleting them or renaming them.

^ Back to Questions ^

It says there are unrecognized words in my .soft file. What do i do?

View the file ~/.soft.cache.csh. The errors that occured listed near the top of that file. Then you can edit your .soft file to fix the errors.

^ Back to Questions ^