Fermilab Logo
-----
Computing Division at Fermilab
Computing Division - Fermilab-Search the Computing Web-CD Departments-Index-Help Desk-FAW
System Status-Projects in the Computing Division-Security-Fermilab Policy on Computing-CD Organization-CD Internal

UPS/UPD v4 Quick Reference Card



Commonly Used Options (General)

Option
Description
-?
Prints help on screen. For csh: use "-?" with quotes.
-a
Operates on all instances that match the other options given.
-f <flavorList>
Specifies flavor. Multiple values can usually be specified. See also -H and the number options -0, -1, -2, and -3.
-g <chain> or
-c, -d, -n, -o, -t
Specifies products associated with the given chain (chain flags pre-defined for c urrent, d evelopment, n ew, o ld, t est).
-G "<declareOpts>"
Used by ups copy, upd cloneproduct, and upd install, specifies options to pass to the internally-run ups declare to customize local declaration.
-h <host>
Used in UPD commands only. Specifies distribution host. Can specify plain host name, host and Webserver port, or full URL to the ups.cgi cgi script. Default: fnkits.fnal.gov.
-H <flavorList>
Specifies flavor and builds a flavor list starting at the level specified. Multiple values accepted. Used without -0, -1, -2, or -3, finds best match. Used with -0, -1, -2, or -3, finds specified level of flavor. E.g., -2H IRIX+6.2 is like -f IRIX+6.
-j
Ignores dependencies, operates just on top level product.
-K <keywordList>
Returns values of specified keywords only.
-m <tableFileName>
Specifies table file name.
-M <tableFileDir>
Specifies table file directory.
-q <qualifierList>
Specifies required or optional qualifiers.
-r <prodRootDir>
Specifies the product root directory.
-R
Retrieves/operates on only the required dependencies.
-s
Lists what command would do; but does not execute the command.
-z <databaseList>
Specifies the local database(s).
-Z
Times the command.
-0, -1, -2, -3
Equivalent to -f or -H with zero, one, two, or three components of the local or specified system flavor. E.g., for IRIX+6.2: -0=-f NULL, -1=-f IRIX and -1 -H IRIX+6.2=IRIX.

Commonly Used "Declare" Options

When used for declaring a product instance, these options set values. In other commands, they specify search criteria.

Option
Description
-A <nodeList>
Specifies nodes authorized to access the product.
-b <compileFile>
Specifies name of the output file for the ups compile command.
-C
When initially declaring a product, -C prevents execution of CONFIGURE action. When declaring a chain, -C prevents execution of the corresponding chain action.
-D "<origin>"
Specifies the product's master source file.
-f <flavor>
Specifies flavor.
-g <chain> or
-c, -d, -n, -o, -t
Declares chain.
-O "<flags>"
Sets the value of $UPS_OPTIONS to <flags>.
-p "<description>"
Specifies product description.
-q <qualifiers>
When initially declaring a product, -q specifies qualifiers to include in the declaration. When adding a chain, -q specifies qualifiers to identify the instance.
-r <prodRootDir>
Specifies the product root directory.
-T <path or URL>
Specifies archive file path or URL. Used only when adding products to archive distribution databases.
-z <databaseList>
Specifies the local database in which to declare the product; or, if adding a chain, that in which product is declared.
-0, -1, -2, -3
See -0, -1, -2, -3 under Commonly Used Options (General).

Product Maintenance Commands

Commands for Maintaining Products on Local User Nodes

Command (gray) and Description (white)
ups declare [<declareOptions>] <product> [<version>]
Declare a product instance to a local UPS database, or add a chain to declaration.
ups undeclare [-C] [-y] [-Y] [<options>] <product> [<version>]
Remove a product declaration from local UPS database. -C disables uncurrent/unconfigure actions; -y/-Y deletes product files with/without query.
upd install [-G "<declareOptions>"] [-h <host>] [-H <flavorList>] [-i] [-I] [-j] [-R] [<options>] <product> [<version>]
Install a product and its dependencies from distribution host to local system. -i ignores errors; -I (upper case "i") uses an intermediate file for file transfers; -j downloads no dependencies; -R downloads required dependencies only.
upd fetch [-h <host>] [-i] [-J <fileName>] [<options>] <product> [<version>]
Download specified file from distribution host, or (without -J) list files available for downloading. i ignores errors. (Selected files available for individual download.)

Commands for Maintaining Products on Distribution Nodes

Command (gray) and Description (white)
upd addproduct [-h <host>] [<declareOptions>] <product> [<version>]
Add a product to distribution host, and declare it to the host's UPS database.
upd modproduct [-h <host>] [<declareOptions>] <product> [<version>]
Modify a product declaration on distribution host. (-T not valid; -f can specify a list.)
upd delproduct [-h <host>] [<options>] <product> [<version>]
Delete a product instance from distribution host.

Product Usage Commands

Command (gray) and Description (white)
setup [<options>] [-j] [-R] <product> [<version>]
Make a product and its dependant products available for use (-j for no dependencies, -R for required ones only).
unsetup [<options>] <product> [<version>]
Undo a previously performed setup.
ups list [-a] [-l] [-K <keywordList>] [<options>] <product> [<version>]
List available products on local system. The -l option requests a long listing.
upd list [-h <host>] [-a] [-l] [-K <keywordList>] [<options>] <product> [<version>]
List available products on distribution host.
ups depend [-K <keywordList>] [<options>] <product> [<version>]
List product dependencies on local system.
upd depend [-h <host>] [-K <keywordList>] [<options>] <product> [<version>]
List product dependencies on distribution host.

A Few Sample Commands

Command (gray) and Description (white)
ups list -aK+:DB fred
List in condensed format the standard fields plus database for all instances of fred in $PRODUCTS.
ups list -act fred
List all instances of fred in $PRODUCTS that have a current or test chain.
setup -ej fred
Setup default instance of fred and no dependencies, enable extended functionality.
upd install fred v1_0 -h xyz -H CYGWIN32_NT:Linux+2:SunOS+6:IRIX+6 -G "-c" -C
Download fred v1_0 from host xyz for best match of given flavors; install all instances and dependencies; declare all in $PRODUCTS as current; suppress execution of CONFIGURE action in initial local product declaration.
ups declare -c fred v1_0 -f SunOS+6
Declare the current chain to the specifed (already declared) instance of fred in $PRODUCTS.
upd addproduct fred v1_0 -f CYGWIN32_NT:Linux+2:SunOS+6:IRIX+6
For the flavors listed, add instances of fred v1_0 to fnkits (default distribution host). Instances must be unwound and declared locally in $PRODUCTS. ups directory and table file are assumed to be in default locations.

Keyword List

Keyword
Description
ARCHIVE_FILE
archive (e.g., tar) file name/location
AUTHORIZED_NODES
nodes authorized to use product; "*" used for all nodes
CATMAN_SOURCE_DIR
location of catman files included with instance
CATMAN_TARGET_DIR
directory into which catman files are to be copied
CHAIN
chain name
COMPILE_DIR
directory containing compile file
COMPILE_FILE, @COMPILE_FILE
name of the file containing compiled functions (with @, entire path to compile file)
DECLARED
date/time that the instance was declared to UPS or declared with a chain
DECLARER
userid of user that performed the declaration
DESCRIPTION
product description
FLAVOR
product instance flavor
INFO_SOURCE_DIR
location of Info files included with instance
INFO_TARGET_DIR
directory into which Info files are to be copied
MAN_SOURCE_DIR
location of unformatted man page files included with instance
MAN_TARGET_DIR
directory into which formatted man pages are to be copied
MODIFIED
date/time of most recent time change
MODIFIER
userid of user that modified the instance
ORIGIN
master source file
PRODUCT
product name
PROD_DIR, @PROD_DIR
product root directory (with @, entire path to root directory)
PROD_DIR_PREFIX
product root directory prefix (dir containing PROD_DIR)
QUALIFIERS
additional instance specification information often used to indicate compilation options used by developer
SETUPS_DIR
location of setups.[c]sh files and other UPS init files
STATISTICS
flag to record statistics for specified products
TABLE_DIR
location of table file
TABLE_FILE, @TABLE_FILE
name of table file (with @, entire path for table file)
UPD_USERCODE_DIR
Directory where UPD configuration files are maintained
UPS_DIR, @UPS_DIR
location of ups directory (with @, entire path to ups directory)
VERSION
product version
+
equivalent to "PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN"

Functions to use in Table Files

Function
Description (R=Reversible)
addAlias(<NAME>, <VALUE>)
Add an alias (csh) or function (sh). R
doDefaults([<ACTION>])
Perform default functions (valid for only SETUP and UNSETUP). R
envAppend(<VARIABLE>, <value>
[, <delimiter>])
Append <value> to existing variable. R
envPrepend(<VARIABLE>, <value>
[, <delimiter>])
Prepend <value> to existing variable. R
envRemove(<VARIABLE>, <value>
[, <delimiter>])
Remove the string <value> from existing variable.
envSet(<VARIABLE>, <value>)
Set a new variable. R
envSetIfNotSet(<VARIABLE>, <value>)
Set a new variable, if not already set.
envUnset(<VARIABLE>)
Unset existing variable.
exeAccess(<executable>)
Check for access to executable through the $PATH. If not found, exit with error.
exeActionOptional("<newaction>")
Process the functions associated with action. Do not fail if action not found. R
exeActionRequired("<newaction>")
Process the functions associated with action. Fail if action doesn't exist. R
execute("<command>", <UPS_ENV_FLAG>, [, <VARIABLE>])
Execute a shell-independent command and (opt.) assign output to a variable.
fileTest(<file>, <test> [, <errormessage>])
Run a shell test on <file>, fail if not true
pathAppend(<VARIABLE>, <value> [, <delimiter>])
Append <value> to existing $PATH-like variable. R
pathPrepend(<VARIABLE>, <value> [, <delimiter>])
Prepend <value> to existing $PATH-like variable. R
pathRemove(<VARIABLE>, <value> [, <delimiter>])
Remove the string <value> from existing $PATH-like variable. R
pathSet(<VARIABLE>, <value>)
Set a $PATH-like variable. R
prodDir()
Set the $<PRODUCT>_DIR variable. R
setupEnv()
Set the $SETUP_<PRODUCT> variable so that product can later be unsetup. R
setupOptional("[<options>] <product> [<version>]")
Setup a UPS product as a dependency, do not fail if the product doesn't exist. R
setupRequired("[<options>] <product> [<version>]")
Setup a UPS product as a dependency; fail if product not found. R
sourceCompileOpt("<fileName>")
If <fileName> exists, source it and skip remaining functions; else continue.
sourceCompileReq("<fileName>")
Source <fileName> and skip all remaining functions; fail if file not found.
sourceOptCheck(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])
Check if specified script exists and if so, source it and check return status for error. If error, abort script and return. R
sourceOptional(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [,EXIT_FLAG])
Check if <SCRIPT> exists and if so, source it. If script not found, continue. R
sourceReqCheck(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])
Source <SCRIPT> and check return status for error; fail if script not found. R
sourceRequired(<SCRIPT>.${UPS_SHELL}, UPS_ENV_FLAG [, EXIT_FLAG])
Source <SCRIPT>; fail if script not found. Return status not checked. R
unAlias(<NAME>)
Remove specified alias/function.
unProdDir()
Unset $<PRODUCT>_DIR. R
unsetupEnv()
Unset $SETUP_<PRODUCT>. R
unsetupOptional("[<options>] <product> [<version>]")
Run unsetup on a product; if unable, do not fail. R
unsetupRequired("<options>] <product> [<version>]")
Run unsetup on a product; fail if product not found. R
writeCompileScript("<fileName>", "<ACTION>" [, OLD|DATE])
Write a file of compiled functions for the given ACTION keyword value.

Read-Only Variables to use in Functions

Variable
Description
${PRODUCTS}
List of UPS databases; like $PRODUCTS
${UPS_COMPILE}.
Location and name of file with compiled functions
${UPS_EXTENDED}
Set to 1 if the -e (extended) option given in setup
${UPS_OPTIONS}
Option string passed with -O (upper case o) flag
${UPS_ORIGIN}
Location of the master source files
${UPS_OS_FLAVOR}
OS flavor as obtained from ups flavor
${UPS_PROD_DIR}
Product root directory; like $<PRODUCT>_DIR
${UPS_PROD_FLAVOR}
Product flavor chosen during instance matching
${UPS_PROD_NAME}
Product name as declared in the UPS database
${UPS_PROD_QUALIFIERS}
Product qualifiers declared with instance
${UPS_PROD_VERSION}
Product version as declared in the UPS database
${UPS_SHELL}
The shell family, sh or csh
${UPS_SOURCE}
Either "." or "source", as per ${UPS_SHELL}
${UPS_THIS_DB}
Database in which product instance is declared
${UPS_UPS_DIR}
Path to the product instance's ups directory
${UPS_VERBOSE}
Set to 1 if the -v (verbose) option specified


For assistance contact helpdesk@fnal.gov.
Information compiled and maintained by AH ; content last modified on 09/09/00; format on 05/23/05.
(Address comments about page to helpdesk@fnal.gov.)
--------
Security, Privacy, LegalFermi National Accelerator Laboratory