Project

General

Profile

TOC PREV NEXT
Fermilab CD logo Complete Guide and Reference Manual for UPS and UPD

Chapter Contents

Chapter 35: Functions used in Actions
   35.1 Overview of Functions
   35.2 Reversible Functions
   35.3 Function Descriptions
     35.3.1 addAlias
     35.3.2 doDefaults
     35.3.3 Else
     35.3.4 EndIf
     35.3.5 EndUnless
     35.3.6 envAppend
     35.3.7 envPrepend
     35.3.8 envRemove
     35.3.9 envSet
     35.3.10 envSetIfNotSet
     35.3.11 envUnset
     35.3.12 exeAccess
     35.3.13 exeActionOptional
     35.3.14 exeActionRequired
     35.3.15 execute
     35.3.16 fileTest
     35.3.17 If
     35.3.18 pathAppend
     35.3.19 pathPrepend
     35.3.20 pathRemove
     35.3.21 pathSet
     35.3.22 prodDir
     35.3.23 setupEnv
     35.3.24 setupOptional
     35.3.25 setupRequired
     35.3.26 sourceCompileOpt
     35.3.27 sourceCompileReq
     35.3.28 sourceOptCheck
     35.3.29 sourceOptional
     35.3.30 sourceReqCheck
     35.3.31 sourceRequired
     35.3.32 unAlias
     35.3.33 Unless
     35.3.34 unProdDir
     35.3.35 unsetupEnv
     35.3.36 unsetupOptional
     35.3.37 unsetupRequired
     35.3.38 writeCompileScript
   35.4 Functions under Consideration for Future Implementation
   35.5 Examples of Functions within Actions
     35.5.1 A setup Action
     35.5.2 A "declare as current" Action
   35.6 Local Read-Only Variables Available to Functions
     35.6.1 List of Current Read-Only Variables
     35.6.2 Read-Only Variables under Consideration for the Future

  Chapter 35: Functions used in Actions

  There is a set of supported functions that can be used in action stanzas. Actions are described in Chapter 34: Actions and ACTION Keyword Values . In the present chapter we give a general overview of functions, list and describe all the supported functions, provide a couple of examples of functions within actions, and list all the read-only variables available to the supported functions.

  35.1 Overview of Functions

  Table files and UPD configuration files often include actions. An action corresponds to a command, usually a UPS command, and lists functions to perform in addition to the command's internal processes, when the command is executed. The supported functions are listed and described in this chapter. A function has the format:

<function_name>([<argument_1>] [, <argument_2>] ... [<delimiter>])

  The default delimiter is the colon ( : ).

  For example, the function:

  envPrepend(<VARIABLE>, <value>)

  prepends the specified value to an existing environment variable, using the default delimiter.

  Functions are not case-sensitive; e.g., envPrepend , envprepend , and ENVPREPEND are all acceptable and equivalent. A function is specified in a shell-independent manner, but contains enough information to allow it to be transformed into a sh or csh family command (e.g., sourceRequired() , or execute() ), or to be interpreted directly by UPS (e.g., writeCompileScript() ).

  35.2 Reversible Functions

  In section 34.2.2 "Uncommands" as Actions we discussed commands that have corresponding "uncommands". Usually, when the "uncommand" is run, the desired behavior is to reverse all the functions that were performed when the original command was run. Many of the supported functions are reversible, some are not.

  Wherever you plan to default the "uncommand" action (i.e., to specifically not include an ACTION=UNCOMMAND stanza) and you want UPS to exactly reverse the ACTION=COMMAND functions, make sure that you only include reversible functions under ACTION=COMMAND. Reversible functions are identified as such in the descriptions in section 35.3 Function Descriptions .

  35.3 Function Descriptions

  35.3.1 addAlias

  Description

  Add an alias (C shell family) or function (Bourne shell family). A %s in the <VALUE> marks where the argument list should go. Reversible (runs unAlias ).

  Syntax

addAlias(<NAME>, <VALUE>)

  Example 1

addAlias(askfor, `echo May I have some %s, please\?')

  Defines the alias askfor , which when run with an argument like cake , e.g.,:

% askfor cake

  produces the response:

May I have some cake, please?

  Example 2

addAlias(setup,'${UPS_SOURCE} `${UPS_PROD_DIR}/bin/ups setup %s`')

  ${UPS_SOURCE} is set to " . " or " source " depending on the shell, and %s is presumed to stand for a product name. This defines the alias setup . When issued with a product name, e.g.,

% setup upd

  it sources the executable ${UPS_PROD_DIR}/bin/ups with the arguments setup and upd .

  35.3.2 doDefaults

  Description

  Perform the default functions for the command corresponding to the specified action (only SETUP and UNSETUP have default functions). If no action listed (e.g., doDefaults() ), then the action under which this function occurs is used. Reversible (runs doDefaults ).

  Note: If an ACTION corresponding to the given command is included in the file, the command's default functions will be executed only if doDefaults is specified underneath it. If there is no ACTION for the command, and hence no doDefaults function listed, the default functions will be executed when the command is issued.

  Syntax

doDefaults([<ACTION>])

  Example

doDefaults([SETUP])

  Specifies that the default functions for the setup command will be run when the command is issued. More typically, this is specified in the following manner:

ACTION=SETUP
       doDefaults()

  35.3.3 Else

  Description

  A conditional, to be used with If and EndIf or with Unless and EndUnless . Else takes no command string. Else is optional, but we recommend including it for clarity it even if no code follows it. See sections 35.3.17 If and 35.3.33 Unless for descriptions of processing. Also see sections 35.3.4 EndIf and 35.3.5 EndUnless .

  Syntax

Else()

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

If( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring) 
EndIf( test -d ${UPS_PROD_DIR}/exciting )

  35.3.4 EndIf

  Description

  Closes a conditional; to be used with If and optionally Else . The EndIf statement must include a command that exactly matches the command in the corresponding If statement. This is because UPS must be able to invert this to get an unsetup action (to unsetup, the order gets inversed and the inverse of the actions are called). Also see sections 35.3.17 If and 35.3.3 Else .

  Syntax

EndIf(<same command as used in If statement>)

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

If( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring) 
EndIf( test -d ${UPS_PROD_DIR}/exciting )

  35.3.5 EndUnless

  Description

  Closes a conditional; to be used with Unless and optionally Else . The EndUnless statement must include a command that exactly matches the command in the corresponding If statement. This is because UPS must be able to invert this to get an unsetup action (to unsetup, the order gets inversed and the inverse of the actions are called). Also see sections 35.3.33 Unless and 35.3.3 Else .

  Syntax

EndUnless(<same command as used in Unless statement>)

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

Unless( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting) 
EndUnless( test -d ${UPS_PROD_DIR}/exciting )

  35.3.6 envAppend

  Description

  Append <value> to existing environment variable. Reversible (runs envRemove ).

  It is better to append than prepend if you just want to provide a value in case one is not there. If you want to override any existing value, you should prepend.

  Note: Use the function pathAppend for $PATH.

  Syntax

envAppend(<VARIABLE>, <value> [, <delimiter>])

  Example

envAppend(PYTHONPATH, ${UPS_PROD_DIR}/lib)

  Appends the value of ${UPS_PROD_DIR}/lib to the variable PYTHONPATH , using the default delimiter.

  35.3.7 envPrepend

  Description

  Prepend <value> to existing environment variable. Reversible (runs envRemove ).

  It is better to prepend than append if you want to override any existing value. If you just want to provide a value in case one is not there, you should append.

  Note: Use the function pathPrepend for $PATH.

  Syntax

envPrepend(<VARIABLE>, <value> [, <delimiter>])

  Example

envPrepend(PYTHONPATH, ${UPS_PROD_DIR}/lib)

  Prepends the value of ${UPS_PROD_DIR}/lib to the variable PYTHONPATH , using the default delimiter.

  35.3.8 envRemove

  Description

  Remove the string <value> from existing environment variable.

  Note: Use the function pathRemove for $PATH.

  Syntax

envRemove(<VARIABLE>, <value> [, <delimiter>])

  Example

envRemove(PYTHONPATH, ${UPS_PROD_DIR}/lib)

  Removes the value of ${UPS_PROD_DIR}/lib from the variable PYTHONPATH ; assumes the default delimiter.

  35.3.9 envSet

  Description

  Set a new environment variable. This is particularly useful for representing long strings. Reversible (runs envUnset ).

  Note: Use the function pathSet for $PATH.

  Syntax

envSet(<VARIABLE>, <value>)

  Example

envSet(UPD_USERCODE_DIR, ${UPS_THIS_DB})

  Sets ${UPD_USERCODE_DIR} (the local database used by UPD ) to ${UPS_THIS_DB} (the database in which the product is declared).

  35.3.10 envSetIfNotSet

  Description

  Set a new environment variable, if not already set. This is particularly useful for representing long strings.

  Syntax

envSetIfNotSet(<VARIABLE>, <value>)

  Example

envSetIfNotSet(HOST, `long_hostname`)

  If not already set, this sets the variable HOST to a long hostname.

  35.3.11 envUnset

  Description

  Unset existing environment variable.

  Syntax

envUnset(<VARIABLE>)

  Example

envUnset(MYVAR)

  Unsets the variable $MYVAR.

  35.3.12 exeAccess

  Description

  Check for access to specified existing executable through the $PATH. If executable is found continue. If not found, exit with error.

  Syntax

exeAccess(<executable>)

  Example

exeAccess(gcc)

  Ensures that a version of the product gcc is in your $PATH.

  35.3.13 exeActionOptional

  Description

  Process the functions associated with the specified action for the same product instance. Do not fail if the action doesn't exist. Reversible.

  Syntax

exeActionOptional("<newaction>")

  Example

exeActionOptional("CONFIGURE")

  Process the functions in CONFIGURE action. If no CONFIGURE action, processing continues.

  35.3.14 exeActionRequired

  Description

  Process the functions associated with the specified action for the same product instance. Fail if it doesn't exist. Reversible.

  Syntax

exeActionRequired("<newaction>")

  Example

exeActionRequired("CONFIGURE")

  Process the functions in CONFIGURE action. If no CONFIGURE action, processing fails.

  35.3.15 execute

  Description

  Execute a shell-independent command and (optionally) assign the output to an environment variable, <VARIABLE> .

  The functions execute , sourceRequired , sourceReqCheck , sourceOptional , and sourceOptCheck each take a required parameter ( UPS_ENV_FLAG ) which indicates whether to define UPS local variables. This parameter can take the following values:

  UPS_ENV

  define all local UPS environment variables before sourcing (the script or command relies on these being defined)

  NO_UPS_ENV

  do not define the local UPS environment variables (the script or command doesn't use them)

  If the optional third argument, <VARIABLE> , is not specified, then the specified command is executed but the output from that command is not saved. This command does not have to be shell-independent.

  Syntax

execute("<command>", <UPS_ENV_FLAG>, [, <VARIABLE>])

  Example

execute("echo Call final installation script for
 ${UPS_PROD_NAME} ${UPS_PROD_VERSION}", NO_UPS_ENV)

  (All on one line.) UPS echoes the given text and sources the current script for the product.

  35.3.16 fileTest

  Description

  Run a shell test on <file> , fail if <test> is not true (see man test ).

  Syntax

fileTest(<file>, <test> [, <errormessage>])

  Example

fileTest(/, -w, "You must be root to run this command.")

  This tests for write access in the root directory and returns the shown error message if the test fails.

  35.3.17 If

  Description

  A conditional, to be used with EndIf and optionally with Else , in the order If(<command>)...Else()...Endif(<command>) . We recommend that Else always be included for clarity, even if no code follows it.

  • If the command in the If statement succeeds, then UPS runs the code following the If statement and preceding any Else and/or EndIf statement.
  • If the command result is false, then UPS runs the code following the Else statement and preceding the EndIf statement. If there is no Else statement, UPS does nothing.

  Also see sections 35.3.4 EndIf and 35.3.3 Else .

  A conditional If()...Else()...Endif() structure has no effect on dependencies. It may not work as you expect if you put If()...EndIf() around SetupOptional() and/or SetupRequired() statements. Developers writing table files that use If() statements to conditionally run setup commands must test thoroughly using setup -V , and must read the generated script files.

  Syntax

If(<command>)

  Example

  Here is a standard example:

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

If( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring) 
EndIf( test -d ${UPS_PROD_DIR}/exciting )

  Here is an example showing behavior with dependencies. If foo depends on bar (i.e., bar appears in foo 's dependency list), then the code:

SetupRequired(foo)
  If( some command that's true )
     SetupRequired(bar)
  Else()
  Endif( some command )

  puts nothing inside the If statement in the generated script files, since the SetupRequired(bar) is redundant.

  Similarly, if foo depends on bar v2, then:

If( some command )
     SetupRequired(bar v1)
  Else()
     SetupRequired(bar v2)
  Endif( some command )

  sets up either bar v1 or nothing , since the second one is redundant. If you want different dependencies, you must use different stanzas in the table file.

  35.3.18 pathAppend

  Description

  Append <value> to existing $PATH-like environment variable. Reversible (runs pathRemove ).

  It is better to append than prepend if you just want to provide a value in case one is not there. If you want to override any existing value, you should prepend.

  Syntax

pathAppend(<VARIABLE>, <value> [, <delimiter>])

  Example

pathAppend(PATH, ${UPS_PROD_DIR}/bin)

  Appends the value ${UPS_PROD_DIR}/bin to the $PATH variable using the default delimiter.

  35.3.19 pathPrepend

  Description

  Prepend <value> to existing $PATH-like environment variable. Reversible (runs pathRemove ).

  It is better to prepend than append if you want to override any existing value. If you just want to provide a value in case one is not there, you should append.

  Syntax

pathPrepend(<VARIABLE>, <value> [, <delimiter>])

  Example

pathPrepend(PATH, ${UPS_PROD_DIR}/bin)

  Prepends the value ${UPS_PROD_DIR}/bin to the $PATH variable using the default delimiter.

  35.3.20 pathRemove

  Description

  Remove the string <value> from existing $PATH-like environment variable. Reversible (runs pathAppend ).

  Syntax

pathRemove(<VARIABLE>, <value> [, <delimiter>])

  Example

pathRemove(PATH, ${UPS_PROD_DIR}/bin)

  Removes the value ${UPS_PROD_DIR}/bin from the $PATH variable.

  35.3.21 pathSet

  Description

  Set a $PATH-like environment variable (in csh family, setting a $PATH is different than setting other environment variables). No choice of delimiter offered. Reversible (runs envUnset ).

  If this gets set wrong, your $PATH could get deleted. (To recover from this problem, should it occur, simply run setup setpath .)

  Syntax

pathSet(<VARIABLE>, <value>)

  Example

pathSet(PATH, /afs/fnal.gov/ups/<prod1/v1_0/SunOS+5/bin: ...)

  Sets the $PATH to the value given (sample value truncated after first delimiter for brevity).

  35.3.22 prodDir

  Description

  Set the $<PRODUCT>_DIR environment variable to the root directory of the product instance. Reversible (runs unProdDir ).

  Syntax

prodDir()

  35.3.23 setupEnv

  Description

  Set the $SETUP_<PRODUCT> environment variable so that product can later be unsetup. Reversible (runs unsetupEnv ).

  Syntax

setupEnv()

  35.3.24 setupOptional

  Description

  Setup another UPS product as a dependency, do not fail if the product doesn't exist. Reversible (runs unsetupOptional ).

  Syntax

  The syntax is similar to the command setup :

setupOptional("[<options>] <product> [<version>]")

  Example

setupOptional("perl")

  Setup the default instance of the product perl , if available. Do not fail if not found.

  35.3.25 setupRequired

  Description

  Setup another UPS product as a dependency; fail if product not found. Reversible (runs unsetupRequired ).

  Syntax

  The syntax is similar to the command setup :

setupRequired("[<options>] <product> [<version>]")

  Example

setupRequired("-j Info")

  Setup the default instance of the product Info and no dependencies; fail if not available.

  35.3.26 sourceCompileOpt

  Description

  If <fileName> exists, then source it and skip remaining functions; otherwise just complete the remaining functions. This is typically used in conjunction with writeCompileScript ; see section 35.3.38 writeCompileScript .

  Syntax

sourceCompileOpt("<fileName>")

  Example

sourceCompileOpt("/my/compile/script")

  This sources the specified script which was created with writeCompileScript . If script doesn't exist, process continues.

  35.3.27 sourceCompileReq

  Description

  Source <fileName> and skip all remaining functions; fail if file not found. This is typically used in conjunction with writeCompileScript ; see section 35.3.38 writeCompileScript .

  Syntax

sourceCompileReq("<fileName>")

  Example

sourceCompileReq("/my/compile/script")

  This sources the specified script which was created with writeCompileScript . If script doesn't exist, process fails.

  35.3.28 sourceOptCheck

  Description

  Check if specified script exists and if so, source it and check return status for error. If error, abort script and return. Reversible (runs sourceOptCheck on the "un" script, e.g., current and uncurrent ).

  The functions execute , sourceOptCheck , sourceOptional , sourceReqCheck , and sourceRequired each take a required parameter ( UPS_ENV_FLAG ) which indicates whether to define UPS local variables. This parameter can take the following values:

  UPS_ENV

  define all local UPS environment variables before sourcing (the script or command relies on these being defined)

  NO_UPS_ENV

  do not define the local UPS environment variables (the script or command doesn't use them)

  The functions sourceOptCheck , sourceOptional , sourceReqCheck , and sourceRequired each take an optional parameter ( EXIT_FLAG ). This parameter can take the following values:

  CONTINUE

  after sourcing the script, continue with the next function (the default)

  EXIT

  after sourcing the script, skip the rest of the functions

  Syntax

sourceOptCheck(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceOptCheck(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If so, first and check return status for error. If error, abort script and return.

  35.3.29 sourceOptional

  Description

  Check if <SCRIPT> exists and if so, source it. If script not found, continue. Reversible (runs sourceOptional on the "un" script, e.g., current and uncurrent ).

  See section 35.3.28 sourceOptCheck for information about the parameters UPS_ENV_FLAG and EXIT_FLAG .

  Syntax

sourceOptional(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceOptional(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If so, first . If not, continue.

  35.3.30 sourceReqCheck

  Description

  Source <SCRIPT> and check return status for error; fail if script not found. If error, abort script and return. Reversible (runs sourceOptCheck on the "un" script, e.g., current and uncurrent ).

  See section 35.3.28 sourceOptCheck for information about the parameters UPS_ENV_FLAG and EXIT_FLAG .

  Syntax

sourceReqCheck(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceReqCheck(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If not, it will fail. If script exists, first and check return status for error. If error, abort script and return.

  35.3.31 sourceRequired

  Description

  Source <SCRIPT> ; fail if script not found. Return status not checked. Reversible (runs sourceOptional on the "un" script, e.g., current and uncurrent ).

  See section 35.3.28 sourceOptCheck for information about the parameters UPS_ENV_FLAG and EXIT_FLAG .

  Syntax

sourceRequired(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceRequired(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If not, it will fail. If script exists, first .

  35.3.32 unAlias

  Description

  Remove alias/function of specified name.

  Syntax

unAlias(<NAME>)

  35.3.33 Unless

  Description

  A conditional; to be used with EndUnless and optionally with Else , in the order Unless(<command>)...Else()...EndUnless(<command>) . The Unless statement must include a command. If the command result is false, UPS executes statements that follow Unless and that precede either EndUnless or Else , whichever it encounters. If the command result is true and an Else statement exists, UPS executes statements that follow Else and precede EndUnless . If the command is true and no Else statement exists, UPS does nothing.

  See also sections 35.3.3 Else and 35.3.5 EndUnless . See section 35.3.17 If for information on dependencies; EndUnless works in an analogous manner.

  Syntax

Unless(<command>)

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

Unless( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting) 
EndUnless( test -d ${UPS_PROD_DIR}/exciting )

  35.3.34 unProdDir

  Description

  Unsets the $<PRODUCT>_DIR environment variable. Reversible (runs prodDir ).

  Syntax

unProdDir()

  35.3.35 unsetupEnv

  Description

  Unsets the $SETUP_<PRODUCT> environment variable. Reversible (runs setupEnv ).

  Syntax

unsetupEnv()

  35.3.36 unsetupOptional

  Description

  Runs unsetup on a product, does not fail if the product doesn't exist or if it's already unsetup. Reversible (runs setupOptional ).

  Syntax

  The syntax is similar to the command unsetup :

unsetupOptional("[<options>] <product> [<version>]")

  For previously setup products, the only options that are recognized include -e , -j , and -v .

  Example

unsetupOptional("perl")

  Unsets the default instance of the product perl , if already setup. Does not fail if product doesn't exist or has already been unsetup.

  35.3.37 unsetupRequired

  Description

  Runs unsetup on a product; fails if product not found. Reversible (runs setupRequired ).

  Syntax

  The syntax is similar to the command unsetup :

unsetupRequired("<options>] <product> [<version>]")

  For previously setup products, the only options that are recognized include -e , -j , and -v .

  Example

unsetupRequired("perl")

  Unsets the default instance of the product perl , if already setup. Fails if product doesn't exist or has already been unsetup.

  35.3.38 writeCompileScript

  Description

  Write a file of compiled functions for the given ACTION keyword value. It actually writes four files in total: <script>.[c]sh and un<script>.[c]sh .

  The function writeCompileScript takes an optional parameter which can be one of the following:

  OLD

  if fileName exists, move the old one to fileName.old before creating the new one.

  DATE

  if fileName exists, move the old one to fileName.<datestamp> before creating the new one.

  Syntax

writeCompileScript("<fileName>", "<ACTION>" [, OLD|DATE])

  Example

writeCompileScript("/my/compile/script", "SETUP", OLD)

  This executes the SETUP action and writes the output of the functions to the specified script, first saving the pre-existing script to /my/compile/script.old . This function knows to ignore the function sourceCompileReq or sourceCompileOpt if it encounters either at the top of the list of SETUP functions. See sections 35.3.26 sourceCompileOpt and 35.3.27 sourceCompileReq .

  35.4 Functions under Consideration for Future Implementation

  copyCatMan

  Will copy catman files from source directory specified in table file by CATMAN_SOURCE_DIR to target directory specified in the UPS database configuration file by CATMAN_TARGET_DIR. Reversible (will run uncopyCatMan )

  copyHtml

  Will copy html files from source directory specified in table file by HTML_SOURCE_DIR to target directory specified in the UPS database configuration file by HTML_TARGET_DIR.

  copyInfo

  Will copy Info files from source directory specified in table file by INFO_SOURCE_DIR to target directory specified in the UPS database configuration file by INFO_TARGET_DIR.

  copyMan

  Will copy man files from source directory specified in table file by MAN_SOURCE_DIR to target directory specified in the UPS database configuration file by MAN_TARGET_DIR. Reversible (will run uncopyMan )

  copyNews

  Will copy news files from source directory specified in table file by NEWS_SOURCE_DIR to target directory specified in the UPS database configuration file by NEWS_TARGET_DIR.

  else ()

  Will begin an alternative branch

  elseif (<condition>)

  Will proceed to another condition

  endif ()

  Will end a conditional branch

  if (<condition>)

  Will begin a conditional branch

  uncopyCatMan

  Will remove catman files from target directory specified in the UPS database configuration file by CATMAN_TARGET_DIR. Reversible (will run copyCatMan )

  uncopyMan

  Will remove man files from target directory specified in the UPS database configuration file by MAN_TARGET_DIR. Reversible (will run copyMan )

  35.5 Examples of Functions within Actions

  35.5.1 A setup Action

  This first example shows a setup action:

ACTION=SETUP
 prodDir()
 setupEnv()
 pathAppend(PATH, ${UPS_PROD_DIR}/bin)
 setupRequired("crow")
 setupOptional("gypsy")

  When the product instance gets setup, UPS does five things in addition to setup 's internal processes:

  • sets the variable $<PRODUCT>_DIR to the product root directory
  • sets the variable $SETUP_<PRODUCT> to identify the product instance for unsetup
  • appends the product's bin directory to the path
  • sets up the product crow (and aborts the setup if a suitable current instance of crow is not available)
  • sets up the product gypsy , if found ( setup proceeds whether or not a suitable current instance of gypsy is available).

  35.5.2 A "declare as current" Action

  A second example illustrates steps for UPS to complete when the product instance is declared as current to the database:

ACTION=CURRENT
 execute("echo Call final install script for ${UPS_PROD_NAME} ${UPS_PROD_VERSION}")
 sourceRequired(${UPS_UPS_DIR}/current, UPS_ENV)

  UPS echoes the given text and sources the current script for the product.

  35.6 Local Read-Only Variables Available to Functions

  The read-only variables listed below are set by UPS and available for use with the functions described in section 35.3 Function Descriptions . In several functions, the flag UPS_ENV_FLAG controls whether these variables get set (see section 35.3.28 sourceOptCheck ).

  These UPS variables do not get exported to the environment, but exist only for the duration of, and in the context of, the processing of an action (actions are described in Chapter 34: Actions and ACTION Keyword Values ). By contrast, the environment variables $<PRODUCT>_DIR and $SETUP_<PRODUCT> (described in section 23.1 setup under Environment Variables Set by Default During setup ), if defined, remain set and available for use as long as the product is setup.

  35.6.1 List of Current Read-Only Variables

  When you use these variables, always enclose them in curly brackets ({}) as shown in the list.

Local Read-Only Variable Local Read-Only Variable Description of Value Description of Value
${PRODUCTS} ${PRODUCTS} Generally has the same value as the environment variable $PRODUCTS. The difference is that (read-only) ${PRODUCTS} keeps the value set at the time UPS was invoked, whereas (environment) $PRODUCTS may be reset. Generally has the same value as the environment variable $PRODUCTS. The difference is that (read-only) ${PRODUCTS} keeps the value set at the time UPS was invoked, whereas (environment) $PRODUCTS may be reset. You can reset $PRODUCTS (i.e., using the function envSet (PRODUCTS, "<value>" in the table file) in order to use a new value in the temp file; $PRODUCTS won't get overwritten by ${PRODUCTS} as the temp file executes. See the example that follows this table. You can reset $PRODUCTS (i.e., using the function envSet (PRODUCTS, "<value>" in the table file) in order to use a new value in the temp file; $PRODUCTS won't get overwritten by ${PRODUCTS} as the temp file executes. See the example that follows this table. Note that this is not valid for the other read-only variables in this table; if you try to reset them (as environment variables), your values will get overwritten by the read-only values as the temp file executes. Note that this is not valid for the other read-only variables in this table; if you try to reset them (as environment variables), your values will get overwritten by the read-only values as the temp file executes.
${UPS_REQ_QUALIFIERS} ${UPS_REQ_QUALIFIERS} Requested product qualifiers (including optional ones), as opposed to the declared product qualifiers. Requested product qualifiers (including optional ones), as opposed to the declared product qualifiers. For example, if you run setup fred -q opt1:opt2 and fred is declared with QUALIFIERS="opt1", then ${UPS_PROD_QUALIFIERS} is "opt1", while ${UPS_REQ_QUALIFIERS} is "opt1:opt2". For example, if you run setup fred -q opt1:opt2 and fred is declared with QUALIFIERS="opt1", then ${UPS_PROD_QUALIFIERS} is "opt1", while ${UPS_REQ_QUALIFIERS} is "opt1:opt2".
${UPS_COMPILE} ${UPS_COMPILE} Location and file name of a file containing compiled functions (see Chapter 38: Use of Compile Scripts in Table Files ). It has the value of the combined keywords: COMPILE_FILE_DIR/COMPILE_FILE Location and file name of a file containing compiled functions (see Chapter 38: Use of Compile Scripts in Table Files ). It has the value of the combined keywords: COMPILE_FILE_DIR/COMPILE_FILE
${UPS_DIR} ${UPS_DIR} Entire path to the ups directory of a product. (This is not the same as the environment variable $UPS_DIR that points to the root directory of the UPS product!) Entire path to the ups directory of a product. (This is not the same as the environment variable $UPS_DIR that points to the root directory of the UPS product!)
${UPS_EXTENDED} ${UPS_EXTENDED} This set to 1 if the -e (extended) option was specified in the setup command (see section 25.2.1 -e ) This set to 1 if the -e (extended) option was specified in the setup command (see section 25.2.1 -e )
${UPS_OPTIONS} ${UPS_OPTIONS} Option string that was passed with the -O (upper case o ) flag (see Chapter 25: Generic Command Option Descriptions ) Option string that was passed with the -O (upper case o ) flag (see Chapter 25: Generic Command Option Descriptions )
${UPS_ORIGIN} ${UPS_ORIGIN} This specifies the location of the master source files. This specifies the location of the master source files.
${UPS_OS_FLAVOR} ${UPS_OS_FLAVOR} Operating system flavor as obtained from ups flavor Operating system flavor as obtained from ups flavor
${UPS_OVERRIDE} ${UPS_OVERRIDE} This contains the UPS command line option -H <flavor> that would override the default; not set by default. Can be used to "lie" to UPS about the flavor of the machine. May be expanded in the future to contain other UPS command line options. This contains the UPS command line option -H <flavor> that would override the default; not set by default. Can be used to "lie" to UPS about the flavor of the machine. May be expanded in the future to contain other UPS command line options.
${UPS_PROD_DIR} ${UPS_PROD_DIR} Product instance root directory; same value as the environment variable $<PRODUCT>_DIR Product instance root directory; same value as the environment variable $<PRODUCT>_DIR
${UPS_PROD_FLAVOR} ${UPS_PROD_FLAVOR} Product flavor chosen during instance matching Product flavor chosen during instance matching
${UPS_PROD_NAME} ${UPS_PROD_NAME} Product name as declared in the UPS database Product name as declared in the UPS database
${UPS_PROD_QUALIFIERS} ${UPS_PROD_QUALIFIERS} Product qualifiers chosen during instance matching. Product qualifiers chosen during instance matching. These are the qualifiers declared with the selected instance . They are not necessarily the same set of qualifiers specified on the command line via the -q option (the UPS matching algorithm chooses the "best fit" based on the specified qualifiers; not necessarily an exact match). These are the qualifiers declared with the selected instance . They are not necessarily the same set of qualifiers specified on the command line via the -q option (the UPS matching algorithm chooses the "best fit" based on the specified qualifiers; not necessarily an exact match).
${UPS_PROD_VERSION} ${UPS_PROD_VERSION} Product version as declared in the UPS database Product version as declared in the UPS database
${UPS_SHELL} ${UPS_SHELL} Value can be csh or sh. Value can be csh or sh.
${UPS_SOURCE} ${UPS_SOURCE} Value can be "source" for csh or "." for sh Value can be "source" for csh or "." for sh
${UPS_THIS_DB} ${UPS_THIS_DB} Database in which this product instance is declared. Database in which this product instance is declared.
${UPS_UPS_DIR} ${UPS_UPS_DIR} Path to the product instance's ups directory Path to the product instance's ups directory
${UPS_VERBOSE} ${UPS_VERBOSE} This is set to 1 if the -v (verbose) option was specified (see Chapter 25: Generic Command Option Descriptions ). This is set to 1 if the -v (verbose) option was specified (see Chapter 25: Generic Command Option Descriptions ).

  $PRODUCTS vs. ${PRODUCTS}: Resetting $PRODUCTS

  This example is intended to illustrate the interaction between the read-only variable ${PRODUCTS} and the environment variable $PRODUCTS. There are a couple of potentially confusing points.

  Let ${PRODUCTS} be set to /fnal/ups/db . Say in your table file you set $PRODUCTS to /path/to/mydb in the SETUP action, like this:

ACTION=SETUP
    envSet(PRODUCTS, "/path/to/mydb:${PRODUCTS}")

  Now ${PRODUCTS} and $PRODUCTS are different. The following execute functions show the difference in the values. The function:

execute("echo $PRODUCTS", NO_UPS_ENV)

  would produce:

/path/to/mydb:/fnal/ups/db

  whereas the same function using ${PRODUCTS}, e.g.,

execute("echo ${PRODUCTS}", NO_UPS_ENV)

  would produce only:

/fnal/ups/db

  $PRODUCTS vs. ${PRODUCTS}: Effects on setup and ups depend

  Another issue is the setup... functions. Say you have a product fred v1_0 declared in /path/to/mydb (the database not included in ${PRODUCTS}). If you include a setupRequired or setupOptional function later in the SETUP action, e.g.,:

ACTION=SETUP
    envSet(PRODUCTS, "/path/to/mydb:${PRODUCTS}")
    setupRequired(fred v1_0)

  the setup will fail because these functions only reference the read-only variable ${PRODUCTS}, which in this case doesn't include your product. You can get around this by using the execute function to set the product up:

execute ("setup fred v1_0", NO_UPS_ENV)

  This function uses the environment variable $PRODUCTS.

  Remember though, when you run a ups depend on a product, only products identified in setupRequired or setupOptional functions get listed. You would not see fred v1_0 listed in the ups depend output for the main product in our example.

  35.6.2 Read-Only Variables under Consideration for the Future

  We plan to make the keyword values, listed in section 28.4 List of Supported Keywords , available as read-only variables available to functions. The read-only variable corresponding to a keyword will typically include "UPS_" prepended to it. E.g., the read-only variable corresponding to the keyword DECLARED will be ${UPS_DECLARED}. Several of these are already implemented in this way, e.g., ${UPS_PROD_DIR} corresponds to the keyword PROD_DIR.

TOC PREV NEXT

Last revised on May 2014

TOC PREV NEXT
Fermilab CD logo Complete Guide and Reference Manual for UPS and UPD

Chapter Contents

Chapter 35: Functions used in Actions
   35.1 Overview of Functions
   35.2 Reversible Functions
   35.3 Function Descriptions
     35.3.1 addAlias
     35.3.2 doDefaults
     35.3.3 Else
     35.3.4 EndIf
     35.3.5 EndUnless
     35.3.6 envAppend
     35.3.7 envPrepend
     35.3.8 envRemove
     35.3.9 envSet
     35.3.10 envSetIfNotSet
     35.3.11 envUnset
     35.3.12 exeAccess
     35.3.13 exeActionOptional
     35.3.14 exeActionRequired
     35.3.15 execute
     35.3.16 fileTest
     35.3.17 If
     35.3.18 pathAppend
     35.3.19 pathPrepend
     35.3.20 pathRemove
     35.3.21 pathSet
     35.3.22 prodDir
     35.3.23 setupEnv
     35.3.24 setupOptional
     35.3.25 setupRequired
     35.3.26 sourceCompileOpt
     35.3.27 sourceCompileReq
     35.3.28 sourceOptCheck
     35.3.29 sourceOptional
     35.3.30 sourceReqCheck
     35.3.31 sourceRequired
     35.3.32 unAlias
     35.3.33 Unless
     35.3.34 unProdDir
     35.3.35 unsetupEnv
     35.3.36 unsetupOptional
     35.3.37 unsetupRequired
     35.3.38 writeCompileScript
   35.4 Functions under Consideration for Future Implementation
   35.5 Examples of Functions within Actions
     35.5.1 A setup Action
     35.5.2 A "declare as current" Action
   35.6 Local Read-Only Variables Available to Functions
     35.6.1 List of Current Read-Only Variables
     35.6.2 Read-Only Variables under Consideration for the Future

  Chapter 35: Functions used in Actions

  There is a set of supported functions that can be used in action stanzas. Actions are described in Chapter 34: Actions and ACTION Keyword Values . In the present chapter we give a general overview of functions, list and describe all the supported functions, provide a couple of examples of functions within actions, and list all the read-only variables available to the supported functions.

  35.1 Overview of Functions

  Table files and UPD configuration files often include actions. An action corresponds to a command, usually a UPS command, and lists functions to perform in addition to the command's internal processes, when the command is executed. The supported functions are listed and described in this chapter. A function has the format:

<function_name>([<argument_1>] [, <argument_2>] ... [<delimiter>])

  The default delimiter is the colon ( : ).

  For example, the function:

  envPrepend(<VARIABLE>, <value>)

  prepends the specified value to an existing environment variable, using the default delimiter.

  Functions are not case-sensitive; e.g., envPrepend , envprepend , and ENVPREPEND are all acceptable and equivalent. A function is specified in a shell-independent manner, but contains enough information to allow it to be transformed into a sh or csh family command (e.g., sourceRequired() , or execute() ), or to be interpreted directly by UPS (e.g., writeCompileScript() ).

  35.2 Reversible Functions

  In section 34.2.2 "Uncommands" as Actions we discussed commands that have corresponding "uncommands". Usually, when the "uncommand" is run, the desired behavior is to reverse all the functions that were performed when the original command was run. Many of the supported functions are reversible, some are not.

  Wherever you plan to default the "uncommand" action (i.e., to specifically not include an ACTION=UNCOMMAND stanza) and you want UPS to exactly reverse the ACTION=COMMAND functions, make sure that you only include reversible functions under ACTION=COMMAND. Reversible functions are identified as such in the descriptions in section 35.3 Function Descriptions .

  35.3 Function Descriptions

  35.3.1 addAlias

  Description

  Add an alias (C shell family) or function (Bourne shell family). A %s in the <VALUE> marks where the argument list should go. Reversible (runs unAlias ).

  Syntax

addAlias(<NAME>, <VALUE>)

  Example 1

addAlias(askfor, `echo May I have some %s, please\?')

  Defines the alias askfor , which when run with an argument like cake , e.g.,:

% askfor cake

  produces the response:

May I have some cake, please?

  Example 2

addAlias(setup,'${UPS_SOURCE} `${UPS_PROD_DIR}/bin/ups setup %s`')

  ${UPS_SOURCE} is set to " . " or " source " depending on the shell, and %s is presumed to stand for a product name. This defines the alias setup . When issued with a product name, e.g.,

% setup upd

  it sources the executable ${UPS_PROD_DIR}/bin/ups with the arguments setup and upd .

  35.3.2 doDefaults

  Description

  Perform the default functions for the command corresponding to the specified action (only SETUP and UNSETUP have default functions). If no action listed (e.g., doDefaults() ), then the action under which this function occurs is used. Reversible (runs doDefaults ).

  Note: If an ACTION corresponding to the given command is included in the file, the command's default functions will be executed only if doDefaults is specified underneath it. If there is no ACTION for the command, and hence no doDefaults function listed, the default functions will be executed when the command is issued.

  Syntax

doDefaults([<ACTION>])

  Example

doDefaults([SETUP])

  Specifies that the default functions for the setup command will be run when the command is issued. More typically, this is specified in the following manner:

ACTION=SETUP
       doDefaults()

  35.3.3 Else

  Description

  A conditional, to be used with If and EndIf or with Unless and EndUnless . Else takes no command string. Else is optional, but we recommend including it for clarity it even if no code follows it. See sections 35.3.17 If and 35.3.33 Unless for descriptions of processing. Also see sections 35.3.4 EndIf and 35.3.5 EndUnless .

  Syntax

Else()

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

If( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring) 
EndIf( test -d ${UPS_PROD_DIR}/exciting )

  35.3.4 EndIf

  Description

  Closes a conditional; to be used with If and optionally Else . The EndIf statement must include a command that exactly matches the command in the corresponding If statement. This is because UPS must be able to invert this to get an unsetup action (to unsetup, the order gets inversed and the inverse of the actions are called). Also see sections 35.3.17 If and 35.3.3 Else .

  Syntax

EndIf(<same command as used in If statement>)

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

If( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring) 
EndIf( test -d ${UPS_PROD_DIR}/exciting )

  35.3.5 EndUnless

  Description

  Closes a conditional; to be used with Unless and optionally Else . The EndUnless statement must include a command that exactly matches the command in the corresponding If statement. This is because UPS must be able to invert this to get an unsetup action (to unsetup, the order gets inversed and the inverse of the actions are called). Also see sections 35.3.33 Unless and 35.3.3 Else .

  Syntax

EndUnless(<same command as used in Unless statement>)

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

Unless( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting) 
EndUnless( test -d ${UPS_PROD_DIR}/exciting )

  35.3.6 envAppend

  Description

  Append <value> to existing environment variable. Reversible (runs envRemove ).

  It is better to append than prepend if you just want to provide a value in case one is not there. If you want to override any existing value, you should prepend.

  Note: Use the function pathAppend for $PATH.

  Syntax

envAppend(<VARIABLE>, <value> [, <delimiter>])

  Example

envAppend(PYTHONPATH, ${UPS_PROD_DIR}/lib)

  Appends the value of ${UPS_PROD_DIR}/lib to the variable PYTHONPATH , using the default delimiter.

  35.3.7 envPrepend

  Description

  Prepend <value> to existing environment variable. Reversible (runs envRemove ).

  It is better to prepend than append if you want to override any existing value. If you just want to provide a value in case one is not there, you should append.

  Note: Use the function pathPrepend for $PATH.

  Syntax

envPrepend(<VARIABLE>, <value> [, <delimiter>])

  Example

envPrepend(PYTHONPATH, ${UPS_PROD_DIR}/lib)

  Prepends the value of ${UPS_PROD_DIR}/lib to the variable PYTHONPATH , using the default delimiter.

  35.3.8 envRemove

  Description

  Remove the string <value> from existing environment variable.

  Note: Use the function pathRemove for $PATH.

  Syntax

envRemove(<VARIABLE>, <value> [, <delimiter>])

  Example

envRemove(PYTHONPATH, ${UPS_PROD_DIR}/lib)

  Removes the value of ${UPS_PROD_DIR}/lib from the variable PYTHONPATH ; assumes the default delimiter.

  35.3.9 envSet

  Description

  Set a new environment variable. This is particularly useful for representing long strings. Reversible (runs envUnset ).

  Note: Use the function pathSet for $PATH.

  Syntax

envSet(<VARIABLE>, <value>)

  Example

envSet(UPD_USERCODE_DIR, ${UPS_THIS_DB})

  Sets ${UPD_USERCODE_DIR} (the local database used by UPD ) to ${UPS_THIS_DB} (the database in which the product is declared).

  35.3.10 envSetIfNotSet

  Description

  Set a new environment variable, if not already set. This is particularly useful for representing long strings.

  Syntax

envSetIfNotSet(<VARIABLE>, <value>)

  Example

envSetIfNotSet(HOST, `long_hostname`)

  If not already set, this sets the variable HOST to a long hostname.

  35.3.11 envUnset

  Description

  Unset existing environment variable.

  Syntax

envUnset(<VARIABLE>)

  Example

envUnset(MYVAR)

  Unsets the variable $MYVAR.

  35.3.12 exeAccess

  Description

  Check for access to specified existing executable through the $PATH. If executable is found continue. If not found, exit with error.

  Syntax

exeAccess(<executable>)

  Example

exeAccess(gcc)

  Ensures that a version of the product gcc is in your $PATH.

  35.3.13 exeActionOptional

  Description

  Process the functions associated with the specified action for the same product instance. Do not fail if the action doesn't exist. Reversible.

  Syntax

exeActionOptional("<newaction>")

  Example

exeActionOptional("CONFIGURE")

  Process the functions in CONFIGURE action. If no CONFIGURE action, processing continues.

  35.3.14 exeActionRequired

  Description

  Process the functions associated with the specified action for the same product instance. Fail if it doesn't exist. Reversible.

  Syntax

exeActionRequired("<newaction>")

  Example

exeActionRequired("CONFIGURE")

  Process the functions in CONFIGURE action. If no CONFIGURE action, processing fails.

  35.3.15 execute

  Description

  Execute a shell-independent command and (optionally) assign the output to an environment variable, <VARIABLE> .

  The functions execute , sourceRequired , sourceReqCheck , sourceOptional , and sourceOptCheck each take a required parameter ( UPS_ENV_FLAG ) which indicates whether to define UPS local variables. This parameter can take the following values:

  UPS_ENV

  define all local UPS environment variables before sourcing (the script or command relies on these being defined)

  NO_UPS_ENV

  do not define the local UPS environment variables (the script or command doesn't use them)

  If the optional third argument, <VARIABLE> , is not specified, then the specified command is executed but the output from that command is not saved. This command does not have to be shell-independent.

  Syntax

execute("<command>", <UPS_ENV_FLAG>, [, <VARIABLE>])

  Example

execute("echo Call final installation script for
 ${UPS_PROD_NAME} ${UPS_PROD_VERSION}", NO_UPS_ENV)

  (All on one line.) UPS echoes the given text and sources the current script for the product.

  35.3.16 fileTest

  Description

  Run a shell test on <file> , fail if <test> is not true (see man test ).

  Syntax

fileTest(<file>, <test> [, <errormessage>])

  Example

fileTest(/, -w, "You must be root to run this command.")

  This tests for write access in the root directory and returns the shown error message if the test fails.

  35.3.17 If

  Description

  A conditional, to be used with EndIf and optionally with Else , in the order If(<command>)...Else()...Endif(<command>) . We recommend that Else always be included for clarity, even if no code follows it.

  • If the command in the If statement succeeds, then UPS runs the code following the If statement and preceding any Else and/or EndIf statement.
  • If the command result is false, then UPS runs the code following the Else statement and preceding the EndIf statement. If there is no Else statement, UPS does nothing.

  Also see sections 35.3.4 EndIf and 35.3.3 Else .

  A conditional If()...Else()...Endif() structure has no effect on dependencies. It may not work as you expect if you put If()...EndIf() around SetupOptional() and/or SetupRequired() statements. Developers writing table files that use If() statements to conditionally run setup commands must test thoroughly using setup -V , and must read the generated script files.

  Syntax

If(<command>)

  Example

  Here is a standard example:

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

If( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring) 
EndIf( test -d ${UPS_PROD_DIR}/exciting )

  Here is an example showing behavior with dependencies. If foo depends on bar (i.e., bar appears in foo 's dependency list), then the code:

SetupRequired(foo)
  If( some command that's true )
     SetupRequired(bar)
  Else()
  Endif( some command )

  puts nothing inside the If statement in the generated script files, since the SetupRequired(bar) is redundant.

  Similarly, if foo depends on bar v2, then:

If( some command )
     SetupRequired(bar v1)
  Else()
     SetupRequired(bar v2)
  Endif( some command )

  sets up either bar v1 or nothing , since the second one is redundant. If you want different dependencies, you must use different stanzas in the table file.

  35.3.18 pathAppend

  Description

  Append <value> to existing $PATH-like environment variable. Reversible (runs pathRemove ).

  It is better to append than prepend if you just want to provide a value in case one is not there. If you want to override any existing value, you should prepend.

  Syntax

pathAppend(<VARIABLE>, <value> [, <delimiter>])

  Example

pathAppend(PATH, ${UPS_PROD_DIR}/bin)

  Appends the value ${UPS_PROD_DIR}/bin to the $PATH variable using the default delimiter.

  35.3.19 pathPrepend

  Description

  Prepend <value> to existing $PATH-like environment variable. Reversible (runs pathRemove ).

  It is better to prepend than append if you want to override any existing value. If you just want to provide a value in case one is not there, you should append.

  Syntax

pathPrepend(<VARIABLE>, <value> [, <delimiter>])

  Example

pathPrepend(PATH, ${UPS_PROD_DIR}/bin)

  Prepends the value ${UPS_PROD_DIR}/bin to the $PATH variable using the default delimiter.

  35.3.20 pathRemove

  Description

  Remove the string <value> from existing $PATH-like environment variable. Reversible (runs pathAppend ).

  Syntax

pathRemove(<VARIABLE>, <value> [, <delimiter>])

  Example

pathRemove(PATH, ${UPS_PROD_DIR}/bin)

  Removes the value ${UPS_PROD_DIR}/bin from the $PATH variable.

  35.3.21 pathSet

  Description

  Set a $PATH-like environment variable (in csh family, setting a $PATH is different than setting other environment variables). No choice of delimiter offered. Reversible (runs envUnset ).

  If this gets set wrong, your $PATH could get deleted. (To recover from this problem, should it occur, simply run setup setpath .)

  Syntax

pathSet(<VARIABLE>, <value>)

  Example

pathSet(PATH, /afs/fnal.gov/ups/<prod1/v1_0/SunOS+5/bin: ...)

  Sets the $PATH to the value given (sample value truncated after first delimiter for brevity).

  35.3.22 prodDir

  Description

  Set the $<PRODUCT>_DIR environment variable to the root directory of the product instance. Reversible (runs unProdDir ).

  Syntax

prodDir()

  35.3.23 setupEnv

  Description

  Set the $SETUP_<PRODUCT> environment variable so that product can later be unsetup. Reversible (runs unsetupEnv ).

  Syntax

setupEnv()

  35.3.24 setupOptional

  Description

  Setup another UPS product as a dependency, do not fail if the product doesn't exist. Reversible (runs unsetupOptional ).

  Syntax

  The syntax is similar to the command setup :

setupOptional("[<options>] <product> [<version>]")

  Example

setupOptional("perl")

  Setup the default instance of the product perl , if available. Do not fail if not found.

  35.3.25 setupRequired

  Description

  Setup another UPS product as a dependency; fail if product not found. Reversible (runs unsetupRequired ).

  Syntax

  The syntax is similar to the command setup :

setupRequired("[<options>] <product> [<version>]")

  Example

setupRequired("-j Info")

  Setup the default instance of the product Info and no dependencies; fail if not available.

  35.3.26 sourceCompileOpt

  Description

  If <fileName> exists, then source it and skip remaining functions; otherwise just complete the remaining functions. This is typically used in conjunction with writeCompileScript ; see section 35.3.38 writeCompileScript .

  Syntax

sourceCompileOpt("<fileName>")

  Example

sourceCompileOpt("/my/compile/script")

  This sources the specified script which was created with writeCompileScript . If script doesn't exist, process continues.

  35.3.27 sourceCompileReq

  Description

  Source <fileName> and skip all remaining functions; fail if file not found. This is typically used in conjunction with writeCompileScript ; see section 35.3.38 writeCompileScript .

  Syntax

sourceCompileReq("<fileName>")

  Example

sourceCompileReq("/my/compile/script")

  This sources the specified script which was created with writeCompileScript . If script doesn't exist, process fails.

  35.3.28 sourceOptCheck

  Description

  Check if specified script exists and if so, source it and check return status for error. If error, abort script and return. Reversible (runs sourceOptCheck on the "un" script, e.g., current and uncurrent ).

  The functions execute , sourceOptCheck , sourceOptional , sourceReqCheck , and sourceRequired each take a required parameter ( UPS_ENV_FLAG ) which indicates whether to define UPS local variables. This parameter can take the following values:

  UPS_ENV

  define all local UPS environment variables before sourcing (the script or command relies on these being defined)

  NO_UPS_ENV

  do not define the local UPS environment variables (the script or command doesn't use them)

  The functions sourceOptCheck , sourceOptional , sourceReqCheck , and sourceRequired each take an optional parameter ( EXIT_FLAG ). This parameter can take the following values:

  CONTINUE

  after sourcing the script, continue with the next function (the default)

  EXIT

  after sourcing the script, skip the rest of the functions

  Syntax

sourceOptCheck(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceOptCheck(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If so, first and check return status for error. If error, abort script and return.

  35.3.29 sourceOptional

  Description

  Check if <SCRIPT> exists and if so, source it. If script not found, continue. Reversible (runs sourceOptional on the "un" script, e.g., current and uncurrent ).

  See section 35.3.28 sourceOptCheck for information about the parameters UPS_ENV_FLAG and EXIT_FLAG .

  Syntax

sourceOptional(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceOptional(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If so, first . If not, continue.

  35.3.30 sourceReqCheck

  Description

  Source <SCRIPT> and check return status for error; fail if script not found. If error, abort script and return. Reversible (runs sourceOptCheck on the "un" script, e.g., current and uncurrent ).

  See section 35.3.28 sourceOptCheck for information about the parameters UPS_ENV_FLAG and EXIT_FLAG .

  Syntax

sourceReqCheck(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceReqCheck(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If not, it will fail. If script exists, first and check return status for error. If error, abort script and return.

  35.3.31 sourceRequired

  Description

  Source <SCRIPT> ; fail if script not found. Return status not checked. Reversible (runs sourceOptional on the "un" script, e.g., current and uncurrent ).

  See section 35.3.28 sourceOptCheck for information about the parameters UPS_ENV_FLAG and EXIT_FLAG .

  Syntax

sourceRequired(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])

  Example

sourceRequired(${UPS_UPS_DIR}/current.${UPS_SHELL}, UPS_ENV)

  Check if ${UPS_UPS_DIR}/current exists. If not, it will fail. If script exists, first .

  35.3.32 unAlias

  Description

  Remove alias/function of specified name.

  Syntax

unAlias(<NAME>)

  35.3.33 Unless

  Description

  A conditional; to be used with EndUnless and optionally with Else , in the order Unless(<command>)...Else()...EndUnless(<command>) . The Unless statement must include a command. If the command result is false, UPS executes statements that follow Unless and that precede either EndUnless or Else , whichever it encounters. If the command result is true and an Else statement exists, UPS executes statements that follow Else and precede EndUnless . If the command is true and no Else statement exists, UPS does nothing.

  See also sections 35.3.3 Else and 35.3.5 EndUnless . See section 35.3.17 If for information on dependencies; EndUnless works in an analogous manner.

  Syntax

Unless(<command>)

  Example

Action=Setup 
ProdDir() 
SetupEnv() 
EnvSetIfNotSet(FOO,":")
EnvPrepend(FOO, ${UPS_PROD_DIR}/basic) 

Unless( test -d ${UPS_PROD_DIR}/exciting ) 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/boring)
Else() 
  EnvPrepend(FOO, ${UPS_PROD_DIR}/exciting) 
EndUnless( test -d ${UPS_PROD_DIR}/exciting )

  35.3.34 unProdDir

  Description

  Unsets the $<PRODUCT>_DIR environment variable. Reversible (runs prodDir ).

  Syntax

unProdDir()

  35.3.35 unsetupEnv

  Description

  Unsets the $SETUP_<PRODUCT> environment variable. Reversible (runs setupEnv ).

  Syntax

unsetupEnv()

  35.3.36 unsetupOptional

  Description

  Runs unsetup on a product, does not fail if the product doesn't exist or if it's already unsetup. Reversible (runs setupOptional ).

  Syntax

  The syntax is similar to the command unsetup :

unsetupOptional("[<options>] <product> [<version>]")

  For previously setup products, the only options that are recognized include -e , -j , and -v .

  Example

unsetupOptional("perl")

  Unsets the default instance of the product perl , if already setup. Does not fail if product doesn't exist or has already been unsetup.

  35.3.37 unsetupRequired

  Description

  Runs unsetup on a product; fails if product not found. Reversible (runs setupRequired ).

  Syntax

  The syntax is similar to the command unsetup :

unsetupRequired("<options>] <product> [<version>]")

  For previously setup products, the only options that are recognized include -e , -j , and -v .

  Example

unsetupRequired("perl")

  Unsets the default instance of the product perl , if already setup. Fails if product doesn't exist or has already been unsetup.

  35.3.38 writeCompileScript

  Description

  Write a file of compiled functions for the given ACTION keyword value. It actually writes four files in total: <script>.[c]sh and un<script>.[c]sh .

  The function writeCompileScript takes an optional parameter which can be one of the following:

  OLD

  if fileName exists, move the old one to fileName.old before creating the new one.

  DATE

  if fileName exists, move the old one to fileName.<datestamp> before creating the new one.

  Syntax

writeCompileScript("<fileName>", "<ACTION>" [, OLD|DATE])

  Example

writeCompileScript("/my/compile/script", "SETUP", OLD)

  This executes the SETUP action and writes the output of the functions to the specified script, first saving the pre-existing script to /my/compile/script.old . This function knows to ignore the function sourceCompileReq or sourceCompileOpt if it encounters either at the top of the list of SETUP functions. See sections 35.3.26 sourceCompileOpt and 35.3.27 sourceCompileReq .

  35.4 Functions under Consideration for Future Implementation

  copyCatMan

  Will copy catman files from source directory specified in table file by CATMAN_SOURCE_DIR to target directory specified in the UPS database configuration file by CATMAN_TARGET_DIR. Reversible (will run uncopyCatMan )

  copyHtml

  Will copy html files from source directory specified in table file by HTML_SOURCE_DIR to target directory specified in the UPS database configuration file by HTML_TARGET_DIR.

  copyInfo

  Will copy Info files from source directory specified in table file by INFO_SOURCE_DIR to target directory specified in the UPS database configuration file by INFO_TARGET_DIR.

  copyMan

  Will copy man files from source directory specified in table file by MAN_SOURCE_DIR to target directory specified in the UPS database configuration file by MAN_TARGET_DIR. Reversible (will run uncopyMan )

  copyNews

  Will copy news files from source directory specified in table file by NEWS_SOURCE_DIR to target directory specified in the UPS database configuration file by NEWS_TARGET_DIR.

  else ()

  Will begin an alternative branch

  elseif (<condition>)

  Will proceed to another condition

  endif ()

  Will end a conditional branch

  if (<condition>)

  Will begin a conditional branch

  uncopyCatMan

  Will remove catman files from target directory specified in the UPS database configuration file by CATMAN_TARGET_DIR. Reversible (will run copyCatMan )

  uncopyMan

  Will remove man files from target directory specified in the UPS database configuration file by MAN_TARGET_DIR. Reversible (will run copyMan )

  35.5 Examples of Functions within Actions

  35.5.1 A setup Action

  This first example shows a setup action:

ACTION=SETUP
 prodDir()
 setupEnv()
 pathAppend(PATH, ${UPS_PROD_DIR}/bin)
 setupRequired("crow")
 setupOptional("gypsy")

  When the product instance gets setup, UPS does five things in addition to setup 's internal processes:

  • sets the variable $<PRODUCT>_DIR to the product root directory
  • sets the variable $SETUP_<PRODUCT> to identify the product instance for unsetup
  • appends the product's bin directory to the path
  • sets up the product crow (and aborts the setup if a suitable current instance of crow is not available)
  • sets up the product gypsy , if found ( setup proceeds whether or not a suitable current instance of gypsy is available).

  35.5.2 A "declare as current" Action

  A second example illustrates steps for UPS to complete when the product instance is declared as current to the database:

ACTION=CURRENT
 execute("echo Call final install script for ${UPS_PROD_NAME} ${UPS_PROD_VERSION}")
 sourceRequired(${UPS_UPS_DIR}/current, UPS_ENV)

  UPS echoes the given text and sources the current script for the product.

  35.6 Local Read-Only Variables Available to Functions

  The read-only variables listed below are set by UPS and available for use with the functions described in section 35.3 Function Descriptions . In several functions, the flag UPS_ENV_FLAG controls whether these variables get set (see section 35.3.28 sourceOptCheck ).

  These UPS variables do not get exported to the environment, but exist only for the duration of, and in the context of, the processing of an action (actions are described in Chapter 34: Actions and ACTION Keyword Values ). By contrast, the environment variables $<PRODUCT>_DIR and $SETUP_<PRODUCT> (described in section 23.1 setup under Environment Variables Set by Default During setup ), if defined, remain set and available for use as long as the product is setup.

  35.6.1 List of Current Read-Only Variables

  When you use these variables, always enclose them in curly brackets ({}) as shown in the list.

Local Read-Only Variable Local Read-Only Variable Description of Value Description of Value
${PRODUCTS} ${PRODUCTS} Generally has the same value as the environment variable $PRODUCTS. The difference is that (read-only) ${PRODUCTS} keeps the value set at the time UPS was invoked, whereas (environment) $PRODUCTS may be reset. Generally has the same value as the environment variable $PRODUCTS. The difference is that (read-only) ${PRODUCTS} keeps the value set at the time UPS was invoked, whereas (environment) $PRODUCTS may be reset. You can reset $PRODUCTS (i.e., using the function envSet (PRODUCTS, "<value>" in the table file) in order to use a new value in the temp file; $PRODUCTS won't get overwritten by ${PRODUCTS} as the temp file executes. See the example that follows this table. You can reset $PRODUCTS (i.e., using the function envSet (PRODUCTS, "<value>" in the table file) in order to use a new value in the temp file; $PRODUCTS won't get overwritten by ${PRODUCTS} as the temp file executes. See the example that follows this table. Note that this is not valid for the other read-only variables in this table; if you try to reset them (as environment variables), your values will get overwritten by the read-only values as the temp file executes. Note that this is not valid for the other read-only variables in this table; if you try to reset them (as environment variables), your values will get overwritten by the read-only values as the temp file executes.
${UPS_REQ_QUALIFIERS} ${UPS_REQ_QUALIFIERS} Requested product qualifiers (including optional ones), as opposed to the declared product qualifiers. Requested product qualifiers (including optional ones), as opposed to the declared product qualifiers. For example, if you run setup fred -q opt1:opt2 and fred is declared with QUALIFIERS="opt1", then ${UPS_PROD_QUALIFIERS} is "opt1", while ${UPS_REQ_QUALIFIERS} is "opt1:opt2". For example, if you run setup fred -q opt1:opt2 and fred is declared with QUALIFIERS="opt1", then ${UPS_PROD_QUALIFIERS} is "opt1", while ${UPS_REQ_QUALIFIERS} is "opt1:opt2".
${UPS_COMPILE} ${UPS_COMPILE} Location and file name of a file containing compiled functions (see Chapter 38: Use of Compile Scripts in Table Files ). It has the value of the combined keywords: COMPILE_FILE_DIR/COMPILE_FILE Location and file name of a file containing compiled functions (see Chapter 38: Use of Compile Scripts in Table Files ). It has the value of the combined keywords: COMPILE_FILE_DIR/COMPILE_FILE
${UPS_DIR} ${UPS_DIR} Entire path to the ups directory of a product. (This is not the same as the environment variable $UPS_DIR that points to the root directory of the UPS product!) Entire path to the ups directory of a product. (This is not the same as the environment variable $UPS_DIR that points to the root directory of the UPS product!)
${UPS_EXTENDED} ${UPS_EXTENDED} This set to 1 if the -e (extended) option was specified in the setup command (see section 25.2.1 -e ) This set to 1 if the -e (extended) option was specified in the setup command (see section 25.2.1 -e )
${UPS_OPTIONS} ${UPS_OPTIONS} Option string that was passed with the -O (upper case o ) flag (see Chapter 25: Generic Command Option Descriptions ) Option string that was passed with the -O (upper case o ) flag (see Chapter 25: Generic Command Option Descriptions )
${UPS_ORIGIN} ${UPS_ORIGIN} This specifies the location of the master source files. This specifies the location of the master source files.
${UPS_OS_FLAVOR} ${UPS_OS_FLAVOR} Operating system flavor as obtained from ups flavor Operating system flavor as obtained from ups flavor
${UPS_OVERRIDE} ${UPS_OVERRIDE} This contains the UPS command line option -H <flavor> that would override the default; not set by default. Can be used to "lie" to UPS about the flavor of the machine. May be expanded in the future to contain other UPS command line options. This contains the UPS command line option -H <flavor> that would override the default; not set by default. Can be used to "lie" to UPS about the flavor of the machine. May be expanded in the future to contain other UPS command line options.
${UPS_PROD_DIR} ${UPS_PROD_DIR} Product instance root directory; same value as the environment variable $<PRODUCT>_DIR Product instance root directory; same value as the environment variable $<PRODUCT>_DIR
${UPS_PROD_FLAVOR} ${UPS_PROD_FLAVOR} Product flavor chosen during instance matching Product flavor chosen during instance matching
${UPS_PROD_NAME} ${UPS_PROD_NAME} Product name as declared in the UPS database Product name as declared in the UPS database
${UPS_PROD_QUALIFIERS} ${UPS_PROD_QUALIFIERS} Product qualifiers chosen during instance matching. Product qualifiers chosen during instance matching. These are the qualifiers declared with the selected instance . They are not necessarily the same set of qualifiers specified on the command line via the -q option (the UPS matching algorithm chooses the "best fit" based on the specified qualifiers; not necessarily an exact match). These are the qualifiers declared with the selected instance . They are not necessarily the same set of qualifiers specified on the command line via the -q option (the UPS matching algorithm chooses the "best fit" based on the specified qualifiers; not necessarily an exact match).
${UPS_PROD_VERSION} ${UPS_PROD_VERSION} Product version as declared in the UPS database Product version as declared in the UPS database
${UPS_SHELL} ${UPS_SHELL} Value can be csh or sh. Value can be csh or sh.
${UPS_SOURCE} ${UPS_SOURCE} Value can be "source" for csh or "." for sh Value can be "source" for csh or "." for sh
${UPS_THIS_DB} ${UPS_THIS_DB} Database in which this product instance is declared. Database in which this product instance is declared.
${UPS_UPS_DIR} ${UPS_UPS_DIR} Path to the product instance's ups directory Path to the product instance's ups directory
${UPS_VERBOSE} ${UPS_VERBOSE} This is set to 1 if the -v (verbose) option was specified (see Chapter 25: Generic Command Option Descriptions ). This is set to 1 if the -v (verbose) option was specified (see Chapter 25: Generic Command Option Descriptions ).

  $PRODUCTS vs. ${PRODUCTS}: Resetting $PRODUCTS

  This example is intended to illustrate the interaction between the read-only variable ${PRODUCTS} and the environment variable $PRODUCTS. There are a couple of potentially confusing points.

  Let ${PRODUCTS} be set to /fnal/ups/db . Say in your table file you set $PRODUCTS to /path/to/mydb in the SETUP action, like this:

ACTION=SETUP
    envSet(PRODUCTS, "/path/to/mydb:${PRODUCTS}")

  Now ${PRODUCTS} and $PRODUCTS are different. The following execute functions show the difference in the values. The function:

execute("echo $PRODUCTS", NO_UPS_ENV)

  would produce:

/path/to/mydb:/fnal/ups/db

  whereas the same function using ${PRODUCTS}, e.g.,

execute("echo ${PRODUCTS}", NO_UPS_ENV)

  would produce only:

/fnal/ups/db

  $PRODUCTS vs. ${PRODUCTS}: Effects on setup and ups depend

  Another issue is the setup... functions. Say you have a product fred v1_0 declared in /path/to/mydb (the database not included in ${PRODUCTS}). If you include a setupRequired or setupOptional function later in the SETUP action, e.g.,:

ACTION=SETUP
    envSet(PRODUCTS, "/path/to/mydb:${PRODUCTS}")
    setupRequired(fred v1_0)

  the setup will fail because these functions only reference the read-only variable ${PRODUCTS}, which in this case doesn't include your product. You can get around this by using the execute function to set the product up:

execute ("setup fred v1_0", NO_UPS_ENV)

  This function uses the environment variable $PRODUCTS.

  Remember though, when you run a ups depend on a product, only products identified in setupRequired or setupOptional functions get listed. You would not see fred v1_0 listed in the ups depend output for the main product in our example.

  35.6.2 Read-Only Variables under Consideration for the Future

  We plan to make the keyword values, listed in section 28.4 List of Supported Keywords , available as read-only variables available to functions. The read-only variable corresponding to a keyword will typically include "UPS_" prepended to it. E.g., the read-only variable corresponding to the keyword DECLARED will be ${UPS_DECLARED}. Several of these are already implemented in this way, e.g., ${UPS_PROD_DIR} corresponds to the keyword PROD_DIR.

TOC PREV NEXT

Last revised on May 2014