Develop Environments

Each environment can be described with Tcl, C-shell, or Bourne-shell scripts, which allows the re-use of existing scripts. The Tcl syntax is recommended; the resulting environment can be used on both UNIX and Windows systems, and Tcl supports aliases.

When necessary, the environment definition, written in any of the above languages, is automatically converted to use with Bourne-shell and the derivatives of Korn-shell and bash, C-shell and derivatives, Tcl scripts, and DOS prompt.

Each environment is described by the files shown in the following table. A minimal description of an environment consists of the start* script and the DOC file.

The .end* script is usually needed only for environments that are used with ves from the command line. The vovtasker binary caches eight recently used environments. When all eight cache slots are full and a new one is needed, the least-recently used environment is discarded without calling any of the .end* scripts.

Some C-shell implementations have small limits on some important variables, such as the length of the path. If environments are needed that exceed those limits and tcsh is on the hosts, the .tcsh script suffix can be used.

Note: A vovtasker does not execute jobs using any shell. Instead, a vovtasker uses the execve() system call. The shell implied by the environment script suffix is only used to compute the environment.

Suffix	Language	Description
start.csh	C-shell	Initialization scripts, executed before entering the environment. If multiple scripts exist for the same environment, VOV will prefer in the following order, Tcl, C-Shell, Bourne-Shell, tcsh.
start.sh	Bourne-shell
start.ksh	Korn-shell
start.tcl	Tcl
start.tcsh	tcsh
end.csh	C-shell	Termination scripts, read when exiting the environment. See comment above about choice of language
end.sh	Bourne-shell
end.tcl	Tcl
end.tcsh	tcsh
pre.tcl	Tcl	Executed before the execution of the job.
post.tcl	Tcl	Executed after the execution of the job.

General Rules

A good environment definition is minimal, incremental and reversible.

Note: These general rules are recommendations; they are not requirements. VOV works well with environments that are not minimal, incremental, or reversible.

Minimal: The definition adds only the minimum number of variables necessary to correctly execute a certain class of tools.
Incremental: It builds upon the original environment.
Reversible: It is possible to restore the original environment.

Rules to Write Environments in c-shell

In this example, an environment is created. The environment is named MYENV, which contains the directory /usr/local/bin in the path. The start script for this environment is $VOVDIR/local/environments/MYENV.start.csh.

In C-shell, either the shell variable path or the environment variable PATH can be set. An example follows:

# -- This is MYENV.start.csh
set path = ( /usr/local/bin $path )

Note: This solution has a disadvantage. Switching to the MYENV environment, the resulting PATH may contain duplicates of /usr/local/bin. In the long run, it is possible for the PATH variable to exceed its maximum allowed length (about 1kB), which can be imposed by some implementations of csh.

A better solution avoids duplicates. For this purpose, use vovenv, which is a script to manipulate environment variables. The usage for vovenv is:

vovenv OPERATION [-colon] wordlist

Operation: Description
DELETE: Deletes word from list.
APPEND: Adds the word at the end of the list.
PREPEND: Adds the word at the beginning of the list.

If -colon is used, the list is assumed to be colon-separated, as for the environment variable PATH. Otherwise, it is a space-separated list such as the C-shell variable path; Instead of -colon, -: can be written.

For example:

# -- This is a better MYENV.start.csh
set path = `vovenv PREPEND /usr/local/bin $path`

In the MYENV.end.csh file, revert the changes made by the start script with the operation DELETE of vovenv as shown below.

Note: This practice should be applied to all the environment variables that describe lists of files or directories, such as PATH, MANPATH, LD_LIBRARY_PATH and LM_LICENSE_FILE.

For example:

# -- This is MYENV.end.csh
set path = `vovenv DELETE /usr/local/bin $path`

Rules to Write Environments in Tcl

If you are familiar with Tcl, consider writing the environment definitions in this language. The advantage is the portability between UNIX and Windows.

Note: Tcl must be used to describe environments for Windows.

To write an environment in Tcl, it is important to remember that all environment variables are available through the associative array env(). For example, the value of the variable VOVDIR is accessible as $env(VOVDIR). You also need to become familiar with the following Tcl procedures supplied by VOV:

setenv name value
unsetenv name ...
vovenv name separator op arg ...
alias name words ...

These procedures look similar to their C-shell equivalent. In fact, they are Tcl procedures that are defined in $VOVDIR/tcl/vtcl/vovenvutils.tcl.

The procedures setenv and unsetenv behave as their C-shell counterparts. The procedure vovenv has the same functionality as the shell utility vovenv, but with a different syntax. Refer to the VOV/Tcl book for more information about these procedures.

Error handling: if errors are detected while processing of the environment definition, do not call exit. Instead, use the call error.

The environment MYENV that was described in the previous section can be described with the Tcl syntax as shown below.

Note: Because the colon ":" is used as a path separator, this example only works for UNIX. (The example shown after this works with Windows.)

# This is MYENV.start.tcl
vovenv PATH : PREPEND /usr/local/bin

# This is MYENV.end.tcl
vovenv PATH : DELETE /usr/local/bin

To have an environment that also works on Windows the following form can be used:

# This is MYENV.start.tcl
if { $::tcl_platform(platform) eq "windows" } {
    # Quote ; because it is the command separator in Tcl.
    vovenv PATH ";" PREPEND c:/local/bin
} else {
    vovenv PATH : PREPEND /usr/local/bin
}

For Windows environments, care must be taken in dealing with case insensitivity and with the confusion between backward and forward slashes. The variables Temp and TEMP are indistinguishable in Windows, because they differ only in case. In Tcl, however, env(Temp) and env(TEMP) are distinct and only one of the two can be used. If the value of an environment variable is needed, first call the procedure nt_preprocess_env to create an upper-case only version of the variable:

set tmpdir $env(TEMP)  ;# May not work

nt_preprocess_env
set tmpdir $env(TEMP)  ;# Guaranteed to work.

Another useful procedure is nt_slashes, which is used to convert the direction of slashes in file names. Example:

nt_preprocess_env
set tmpdir [nt_slashes $env(TEMP)]

Support for Aliases

Some customers desire the ability to define aliases in environments. Aliases are useful shorthands and reduce typing. They are useful only in command shells. Aliases are not used when taskers execute jobs.

To define an alias, you have to describe an environment using Tcl syntax. Aliases defined in the environment become available to the following shells: C-shell, Tcsh, Korn-shell. They are not available in Bourne-shell or in DOS.

The synopsis to define an alias is:

alias NAME WORD ....

For example: define an alias called 'l' for 'ls -sF':

# At the end of $VOVDIR/local/environments/BASE.start.tcl
alias lll ls -sF

% ves BASE% alias lll
ls -sF

Pre and post Conditions

As part of environment definition, you can prepare two scripts, called NameOfEnv.pre.tcl and NameOfEnv.post.tcl, which can be used to take care of pre- and post-conditions on a job by job basis.