Configure an Environment

VOV includes a sophisticated subsystem to manage environments. In Accelerator, an environment is a named collection of environment variables and their values. Many tools expect certain environment variables to be set for correct operation, and the variable PATH is used by most UNIX shells to locate executable programs.

A VOV environment definition consists of three scripts defined in either Tcl, C-shell, or Bourne-shell syntax. Environments that will be used on both UNIX and Windows must be written in Tcl. The names of these scripts must follow a naming convention. For example, an environment named ENV would use these three scripts:

ENV.start.tcl
ENV.end.tcl
ENV.doc

The 'start' script is used when entering the environment, the 'end' script is used when leaving the environment, and the 'doc' script contains a one-line summary of the environment's purpose.

VOV provides commands for using environments from the command line:

vel: List available environments
vesENV: Switch to environment ENV
vep: Change prompt to show environment name
veprestore: Return to original prompt

Find and View Example Environment Scripts

It is interesting and instructive to examine some of the environment definitions which are shipped with VOV. One of the most important is the BASE environment.

The most common place for environment scripts is $VOVDIR/local/environments, but you can also specify additional directories where VOV will search. We will discuss this in more detail later in the lab.

The BASE definition is in the 'local' directory of the VOV software installation, at $VOVDIR/local/environments/BASE.start.tcl

% pushd $VOVDIR/local/environments
% view BASE.start.tcl

# --
# -- Completely reset the environment to bare bones.
# -- We assume that VOVDIR and VOVARCH are set.
# --

set VOVDIR $env(VOVDIR)

if { $::tcl_platform(platform) eq "windows" } {
   #
   # --
   #
   nt_preprocess_env
   #   set vovenv(debug) 1 set WINDIR $env(WINDIR)
   setenv PATH "$WINDIR\\system32;$WINDIR"

   set MKSDIR "c:/mksdemo"
   if [file exists $MKSDIR] { 
       setenv ROOTDIR $MKSDIR
       vovenv PATH ";" APPEND $MKSDIR/mksnt
}
#
# Depending on the installation, the binaries can be in
# different directories.
#
foreach b { bin bin-O bin-g bat local/bat } { 
   set p "$VOVDIR/$b"
   #
   # Eliminate double // as in w://bat
   #
   regsub -nocase {^([a-z])://} $p {\1:/} p

   if [file exists $p] {
       vovenv PATH ";" APPEND $p
   }
}

set version [exec vovversion]
vovenv PATH ";" PREPEND c:/temp/vov/execache$version

# vovenv PATH ";" PREPEND c:/temp/vov/execache

} else {
   #
   # -- Unix BASE environment.
   #

   setenv PATH	""
   foreach b { bin bin-O bin-g } {
       if [file exists $VOVDIR/$b] {
           vovenv PATH : APPEND $VOVDIR/$b 
           break
       }
}
vovenv PATH : APPEND $VOVDIR/scripts 
vovenv PATH : APPEND $VOVDIR/local/scripts

setenv MANPATH ""
foreach mp [list /usr/man /usr/share/man /usr/local/man /usr/openwin/man $VOVDIR/man] { 
   if [file isdirectory $mp] {
       vovenv MANPATH : APPEND $mp
   }
}

setenv LD_LIBRARY_PATH ""
foreach lp [list /lib /usr/lib /usr/local/lib /usr/openwin/lib $VOVDIR/lib] { 
   if [file isdirectory $lp] {
       vovenv LD_LIBRARY_PATH : APPEND $lp
   }
}

foreach xapp { /usr/openwin/lib/app-defaults /usr/lib/X11/app-defaults } { 
   if [file isdirectory $xapp ] {
       vovenv XFILESEARCHPATH : APPEND "$xapp/%N"
   }
}

foreach p {
   /bin /usr/ucb /usr/bin /usr/local/bin
   /usr/X11/bin
   /usr/dt/bin
   /usr/openwin/bin /usr/bin/X11 
} {
    if [file isdirectory $p] { 
        vovenv PATH : APPEND $p
        }
   }
}

The BASE environment includes just the regular system commands and VOV. This is an example of a complex environment setup script; most of the ones you will need to define will be much simpler.

A simple test to verify that:

% vep

Notice that the prompt has changed to show that you are in the DEFAULT environment. This is the environment which is defined by your regular system setup files, for example, .cshrc.

% ves BASE
% printenv PATH

Notice that the PATH environment variable is now (probably) much shorter, and contains the VOV software directories.

% veprestore

Notice that the prompt has been changed back to the original.

Note: This only changes the prompt. Your shell still has whatever environment was set most recently using vep.

Add Additional Environment Directories

When you are testing and developing environments, or when you want to have project-specific ones which are not put in the system wide directory at $VOVDIR/local/environments, you can use the environment variable VOV_ENV_DIR to specify additional directories.

You will use this capability in the tutorial, so that you don't need to put our environment scripts in the system's shared environment area. You should have a ~/ncadmin directory from the previous exercises, which contains the server working directory of your private Accelerator queue.

% setenv VOV_ENV_DIR ~/ncadmin/vnc-user-name.swd/environments
% pushd $VOV_ENV_DIR

CAUTION:

The enviroments directory is generated by setup, but any user-made env-scripts placed in the directory will not be used unless VOV_ENV_DIR includes it.

Configuration Examples

In this example, you will create an enviroment which adds your personal bin directory to the path. You will put the definitions in your queue's environment directory.

Use Tcl for the environment scripts because it is more powerful than C-shell, and platform-independent.

Example 'start' script for JOHN environment

# add john bin directory to path
vovenv PATH : PREPEND /home/john/bin

This script adds the element /home/john/bin to the beginning of the PATH. There is also an APPEND operator which adds to the end of the PATH. If the exact element is already present in the path, it is left undisturbed. This avoids PATH overflow in C-shell.

Example 'end' script for JOHN environment

# remove john bin directory from path
vovenv PATH : DELETE /home/john/bin

This script removes the element /home/john/bin from the PATH.

Example 'doc' script for JOHN environment

prepend /home/john/bin to PATH

This file contains a one-line summary which is presented by the vel command.

Use the above examples to create similar files in your queue.

Compose Good Environment Scripts

There are several characteristics of a 'good' environment setup.

minimal: A minimal environment only sets the variables needed to accomplish a specific purpose.
composable: A composable environment respects pre-existing values of variables, and adds to them, rather than overwriting them. For example, when modifying LM_LICENSE_FILE, use PREPEND and APPPEND rather than simply setting it. This allows you to use commands like ves BASE+CADENCE+NASSDA and have both Cadence and Nassda tools work.
reversible: A good environment definition uses the 'end' script to revert what it set in the 'start' script, so that the environment does not gradually become polluted with obsolete values.

Environments are Cached on the vovtasker

To provide very low job dispatch latency, Accelerator caches the eight most-recently used environments in the vovtasker process. This means that jobs which run in any of those environments may start immediately without sourcing the environment definition script. It also means that if you change an env-script, you must tell the vovtaskers by using the vovtaskermgr refresh subcommand.

Summary

Most environments are defined by scripts stored in $VOVDIR/local/environments
Environment scripts are in Tcl or C-shell syntax
You can use the VOV_ENV_DIR environment variable to specify additional directories to search for environment scripts.
Environments are cached on the vovtasker, and refreshed using ncmgr reset -taskers, or nc cmd vovtaskermgr refresh