NCSA HPC Systems: SoftEnv

SoftEnv is a system designed to make it easier for users to define what applications they want to use, and it allows administrators to make applications available to users. Its commands are independent of the user's shell, so both tcsh and bash users can use the same commands to change the environment.

SoftEnv uses a file called .soft created in your home directory. In this file, the desired user environment is described using a set of keywords. These keywords are read by SoftEnv when you log in and are expanded into a set of environment variables. SoftEnv uses a database managed by the system administrators to decide how to build your environment. Details are available on the An introduction to the SoftEnv system and how to use it page.

Note: You may be accustomed to the use of shell startup files (.cshrc, .bashrc, etc.) to set your environment on other Unix systems. SoftEnv is an alternative to this, and with a few exceptions (outlined below), we recommend using the .soft file to set up your environment.

Useful SoftEnv Commands

To list the available SoftEnv keywords, type softenv.

This command lists the SoftEnv keywords available along with a short description.

To see what environment changes are made by a particular keyword, use the soft-dbq command.

For example, for keyword +totalview on the Intel 64 cluster, abe:

[honest1 ~]$ soft-dbq +totalview

This is all the information associated with
the key or macro +totalview.

-------------------------------------------

Name: +totalview
Description: Totalview Debugger from Etnus
Flags: none
Groups: none
Exists on: linux-rhel4-x86_64 

-------------------------------------------

On the linux-rhel4-x86_64 architecture,
the following will be done to the environment:

  The following environment changes will be made:
    MANPATH = ${MANPATH}:/usr/apps/tools/toolworks/totalview/man
    PATH = ${PATH}:/usr/apps/tools/toolworks/totalview/bin
    TOTALVIEW = /usr/apps/tools/toolworks/totalview/bin/totalview
    TOTALVIEW_HOME = /usr/apps/tools/toolworks/totalview
    TVDSVRLAUNCHCMD = ssh

-------------------------------------------

To see the environment created by a particular macro, also use the soft-dbq command. Example on the IA-64 Linux Cluster, mercury:

[tg-login3 ~]$ soft-dbq @teragrid-basic

This is all the information associated with
the key or macro @teragrid-basic.

-------------------------------------------

Name: @teragrid-basic
Description: Basic minimal Software Stack for CTSSv3 
Flags: none
Groups: none
Exists on: linux-sles8-ia64 

-------------------------------------------

  @teragrid-basic contains the following
  keywords and macros:

  +user-paths +os-paths +moab +torque +tg-environment +tg-filesystems 
  +tgusage +softenv +gx-map +kx509 +uberftp-client +cvs-environment 
  +xcat-user +ncsa-ca +krb5

-------------------------------------------

To set/reset the environment in the current shell to what is specified in the .soft file, type resoft.

The resoft command immediately applies changes in the .soft file to the current environment. It also removes changes you've previously made to the environment via the "soft add" or "soft delete" commands.
If you need to reset your .soft file to the system default, remove your .soft file and log out. When you log back in, a new .soft file will be created for you.
To temporarily change your environment to prepend particular software in the current shell only, use the soft add command. (i.e., any added software will take precedence over everything else in your environment.)
For example, the command:
```
   soft add +totalview
```
will change your environment in the current shell to access the TotalView debugger.

This command can be added to your batch script in order to change your environment for a single job.
To temporarily change your environment to append particular software in the current shell only, use the soft append command. i.e., any added software will be at the end of your $PATH, etc.
To undo the changes made by a soft add or soft append command, use the soft delete or resoft commands.
Example: To go back to the default, run
```
  soft delete +totalview
```
Note: Only use resoft if you want to completely return to the environment as defined in your .soft file. Use the soft delete command to undo a single soft add or soft append command.
To include particular software in the environment for all new shells, you must edit your $HOME/.soft file.
For example, to change your environment to use the MPICH-VMI on the Intel 64 cluster, add the line +mpichvmi-intel to the beginning of your .soft file. The following illustrates the changes:
```
# Common TeraGrid Software Stack Version 3 (CTSSv3)
#
# Please consult TeraGrid user documentation at
#    http://www.teragrid.org/userinfo/software/softenv.php
# for information on customizing this file.
#
# TeraGrid wide basic software suite
+mpichvmi-intel
@teragrid-basic

# TeraGrid wide Globus 4 and Grid software suite
@globus-4.0

# Platform recommended development software suite
@teragrid-dev
```
Note: Order is important. If you put the MPICH VMI keyword at the end of your .soft file, the changes will be appended instead of prepended meaning that the default MPI (MVAPICH2) will be first in your path instead of MPICH VMI.

To remove a softenv keyword that is part of a macro, use the @remove option. This is useful when using a different version of a software that is in the default environment, while keeping the rest of the information the same.

For example, if the Intel 10.1 compilers are default, and you want to use the Intel 9.1 compilers, do the following:

# Common TeraGrid Software Stack Version 3 (CTSSv3)
#
# Please consult TeraGrid user documentation at
#    http://www.teragrid.org/userinfo/software/softenv.php
# for information on customizing this file.
#
@remove +intel-compilers10.1 
+intel-compilers91
# TeraGrid wide basic software suite
@teragrid-basic

# TeraGrid wide Globus 4 and Grid software suite
@globus-4.0

# Platform recommended development software suite
@teragrid-dev

To permanently set an environment variable that is not set in a SoftEnv keyword, add a SoftEnv assignment statement to your .soft file.

For example, to set an environment variable called NEWVAR:

# Common TeraGrid Software Stack Version 3 (CTSSv3)
#
# Please consult TeraGrid user documentation at
#    http://www.teragrid.org/userinfo/software/softenv.php
# for information on customizing this file.
#
# TeraGrid wide basic software suite
@teragrid-basic

# TeraGrid wide Globus 4 and Grid software suite
@globus-4.0

# Platform recommended development software suite
@teragrid-dev
NEWVAR = "value"

Note that this is equivalent to the following shell commands:

setenv NEWVAR "value"

export NEWVAR="value"

To permanently add a directory to the end of a path variable (i.e. PATH, MANPATH, etc) that can not be added by using a SoftEnv keyword, use a "+=" SoftEnv statement at the end of your .soft file.

For example, to add ${HOME}/last to the end of your path:
# Common TeraGrid Software Stack Version 3 (CTSSv3)
#
# Please consult TeraGrid user documentation at
#    http://www.teragrid.org/userinfo/software/softenv.php
# for information on customizing this file.
#
# TeraGrid wide basic software suite
@teragrid-basic

# TeraGrid wide Globus 4 and Grid software suite
@globus-4.0

# Platform recommended development software suite
@teragrid-dev
PATH += ${HOME}/last
Note that this is equivalent to the shell commands:

csh: setenv PATH ${PATH}:${HOME}/last
bash: export PATH=${PATH}:${HOME}/last

To permanently add a directory to the front of a path variable (i.e. PATH, MANPATH, etc) that can not be added by using a SoftEnv keyword, use a "+=" SoftEnv statement at the beginning of your .soft file.

For example, to add ${HOME}/first to the beginning of your path:
# Common TeraGrid Software Stack Version 3 (CTSSv3)
#
# Please consult TeraGrid user documentation at
#    http://www.teragrid.org/userinfo/software/softenv.php
# for information on customizing this file.
#
# TeraGrid wide basic software suite
PATH += ${HOME}/first
@teragrid-basic

# TeraGrid wide Globus 4 and Grid software suite
@globus-4.0

# Platform recommended development software suite
@teragrid-dev
Note that this is equivalent to the shell commands:

csh: setenv PATH ${HOME}/first:${PATH}
bash: export PATH=${HOME}/first:${PATH}

Exceptions to setting your environment in SoftEnv

The following are examples that will have to go in your shell-dependent startup file (${HOME}/.cshrc or ${HOME}/.bashrc).

setting aliases
any environments set via the use of shell programming

Managing Your Environment (SoftEnv)

Useful SoftEnv Commands

Exceptions to setting your environment in SoftEnv