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)

Prints help on screen. For csh: use "-?" with quotes.
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.
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.
Retrieves/operates on only the required dependencies.
Lists what command would do; but does not execute the command.
-z <databaseList>
Specifies the local database(s).
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.

-A <nodeList>
Specifies nodes authorized to access the product.
-b <compileFile>
Specifies name of the output file for the ups compile command.
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

archive (e.g., tar) file name/location
nodes authorized to use product; "*" used for all nodes
location of catman files included with instance
directory into which catman files are to be copied
chain name
directory containing compile file
name of the file containing compiled functions (with @, entire path to compile file)
date/time that the instance was declared to UPS or declared with a chain
userid of user that performed the declaration
product description
product instance flavor
location of Info files included with instance
directory into which Info files are to be copied
location of unformatted man page files included with instance
directory into which formatted man pages are to be copied
date/time of most recent time change
userid of user that modified the instance
master source file
product name
product root directory (with @, entire path to root directory)
product root directory prefix (dir containing PROD_DIR)
additional instance specification information often used to indicate compilation options used by developer
location of setups.[c]sh files and other UPS init files
flag to record statistics for specified products
location of table file
name of table file (with @, entire path for table file)
Directory where UPD configuration files are maintained
location of ups directory (with @, entire path to ups directory)
product version

Functions to use in Table Files

Description (R=Reversible)
addAlias(<NAME>, <VALUE>)
Add an alias (csh) or function (sh). R
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.
Unset existing variable.
Check for access to executable through the $PATH. If not found, exit with error.
Process the functions associated with action. Do not fail if action not found. R
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
Set the $<PRODUCT>_DIR variable. R
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
If <fileName> exists, source it and skip remaining functions; else continue.
Source <fileName> and skip all remaining functions; fail if file not found.
Check if specified script exists and if so, source it and check return status for error. If error, abort script and return. R
Check if <SCRIPT> exists and if so, source it. If script not found, continue. R
Source <SCRIPT> and check return status for error; fail if script not found. R
Source <SCRIPT>; fail if script not found. Return status not checked. R
Remove specified alias/function.
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

List of UPS databases; like $PRODUCTS
Location and name of file with compiled functions
Set to 1 if the -e (extended) option given in setup
Option string passed with -O (upper case o) flag
Location of the master source files
OS flavor as obtained from ups flavor
Product root directory; like $<PRODUCT>_DIR
Product flavor chosen during instance matching
Product name as declared in the UPS database
Product qualifiers declared with instance
Product version as declared in the UPS database
The shell family, sh or csh
Either "." or "source", as per ${UPS_SHELL}
Database in which product instance is declared
Path to the product instance's ups directory
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