Project

General

Profile

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

Chapter Contents

Chapter 23: UPS Command Reference
   23.1 setup
     23.1.1 Command
Syntax

     23.1.2 Commonly Used
Options

     23.1.3 All Valid
Options

     23.1.4 More Detailed
Description

     23.1.5 setup
Examples

   23.2 unsetup
     23.2.1 Command
Syntax

     23.2.2 All Valid
Options

     23.2.3 More Detailed
Description

     23.2.4 unsetup
Examples

   23.3 ups configure
     23.3.1 Command
Syntax

     23.3.2 Commonly Used
Options

     23.3.3 All Valid
Options

     23.3.4 More Detailed
Description

     23.3.5 ups configure
Examples

   23.4 ups copy
     23.4.1 Command
Syntax

     23.4.2 Commonly Used
Options

     23.4.3 All Valid
Options

     23.4.4 Options Valid with
-G

     23.4.5 More Detailed
Description

     23.4.6 ups copy
Examples

   23.5 ups declare
     23.5.1 Command
Syntax

     23.5.2 Commonly Used
Options

     23.5.3 All Valid
Options

     23.5.4 More Detailed
Description

     23.5.5 ups declare
Examples

   23.6 ups depend
     23.6.1 Command
Syntax

     23.6.2 Commonly Used
Options

     23.6.3 All Valid
Options

     23.6.4 ups depend
Examples

   23.7 ups exist
     23.7.1 Command
Syntax

     23.7.2 Commonly Used
Options

     23.7.3 All Valid
Options

     23.7.4 More Detailed
Description

     23.7.5 ups exist
Examples

   23.8 ups flavor
     23.8.1 Command
Syntax

     23.8.2 Commonly Used
Options

     23.8.3 All Valid
Options

     23.8.4 More Detailed
Description

     23.8.5 ups flavor
Examples

   23.9 ups get
     23.9.1 Command
Syntax

     23.9.2 All valid
options

     23.9.3 ups get
Example

   23.10 ups help
     23.10.1 ups help
Example

   23.11 ups list
     23.11.1 Command
Syntax

     23.11.2 Commonly Used
Options

     23.11.3 All Valid
Options

     23.11.4 More Detailed
Description

     23.11.5 ups list
Examples

   23.12 ups modify
     23.12.1 Command
Syntax

     23.12.2 Commonly Used
Options

     23.12.3 All Valid
Options

     23.12.4 More Detailed
Description

     23.12.5 ups modify
Example

   23.13 ups parent
     23.13.1 Command
Syntax

     23.13.2 Commonly Used
Options

     23.13.3 All Valid
Options

     23.13.4 More Detailed
Description

     23.13.5 ups parent
Example

   23.14 ups start
     23.14.1 Command
Syntax

     23.14.2 Commonly Used
Options

     23.14.3 All Valid
Options

     23.14.4 More Detailed
Description

     23.14.5 ups start
Examples

   23.15 ups stop
     23.15.1 Command
Syntax

     23.15.2 Commonly Used
Options

     23.15.3 All Valid
Options

     23.15.4 More Detailed
Description

     23.15.5 ups stop
Examples

   23.16 ups tailor
     23.16.1 Command
Syntax

     23.16.2 Commonly Used
Options

     23.16.3 All Valid
Options

     23.16.4 More Detailed
Description

     23.16.5 ups tailor
Example

   23.17 ups touch
     23.17.1 Command
Syntax

     23.17.2 Commonly Used
Options

     23.17.3 All Valid
Options

     23.17.4 ups touch
Example

   23.18 ups unconfigure
     23.18.1 Command
Syntax

     23.18.2 Commonly Used
Options

     23.18.3 All Valid
Options

     23.18.4 More Detailed
Description

     23.18.5 ups unconfigure
Example

   23.19 ups undeclare
     23.19.1 Command
Syntax

     23.19.2 Commonly Used
Options

     23.19.3 All Valid
Options

     23.19.4 More Detailed
Description

     23.19.5 ups undeclare
Examples

   23.20 ups verify
     23.20.1 Command
Syntax

     23.20.2 Commonly Used
Options

     23.20.3 All Valid
Options

     23.20.4 ups verify
Example

  Chapter 23: UPS Command
Reference

  This chapter contains full
usage information on all the UPS commands. In particular, for each command you will
find:

  • a statement of the
    purpose and/or function of the command
  • the command syntax
  • a listing of commonly
    used options, without descriptions
  • a listing of all valid
    options, with command-specific descriptions
  • (as needed) a section
    called "Options Valid with -G"
  • (as needed) a section
    called "More Detailed Description" which typically includes:
    • detailed
      command-specific usage information
    • information on
      environment variables that affect execution of the command or are
      affected by it
    • a list of internal
      functions the command performs (if more extensive than suggested by
      the command description)
  • command examples

  23.1 setup

  Issue the setup command
for a product prior to invoking the product. The setup command
performs the necessary operations in your login environment to make
an installed, declared product instance accessible to you.
Typically, the operations include modifying environment variables
or adding to your $PATH.

  23.1.1 Command
Syntax

% setup [<options>] <product> [<version>]

  23.1.2 Commonly Used
Options

  See section 23.1.3 All Valid Options for descriptions of each option.

 
Table 23.1.2-a:Table 23.1.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.1.3 All Valid
Options

 
Table 23.1.3-a:Table 23.1.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-B Specifies strict dependency mode. Don't setup differing versions of things already setup, and don't setup if the dependencies have conflicting versions, etc.
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-e -e Sets $UPS_EXTENDED (to the value 1 ). This is
useful for SETUP actions which call scripts. Sets $UPS_EXTENDED (to the value 1 ). This is
useful for SETUP actions which call scripts.
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores dependencies, sets up just specified
top-level product Ignores dependencies, sets up just specified
top-level product
-k -k Prevents execution of unsetup files prior to
(subsequent) setup Prevents execution of unsetup files prior to
(subsequent) setup
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> .
This is useful for SETUP actions which call scripts. Sets the value of $UPS_OPTIONS to <flags> .
This is useful for SETUP actions which call scripts.
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-R -R Sets up only the required (non-optional)
dependencies. Sets up only the required (non-optional)
dependencies.
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Specifies product instance chained to
"test" Specifies product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups (relative to the product root directory) Specifies location of ups directory; default value is ups (relative to the product root directory)
-v ( vv ) -v ( vv ) Prints out extra debugging information.
(-vv for more, -vvv for even more) Prints out extra debugging information.
(-vv for more, -vvv for even more)
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup ) Times the command (does not include time for
sourcing of temp file for setup )
-. -. shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace} shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace}

h4.

The flavor options
p<>.   Flavor may be specified using -f ,
using -H by itself or
in combination with any of the valid numbers or just using one of the valid
numbers.
These options are not valid with each other (except -H with a number
option).

  If a dependency is specified
in the table file with a particular flavor, the flavor specified on
the command line is ignored for that dependency.

 
Table 23.1.3-b:Table 23.1.3-b:

-f
<flavor>
-f
<flavor>
Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list. Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list.
-H
<flavor>
-H
<flavor>
Useful to set the host to a different type, such as when
installing products for another platform. Can be used in combination
with the valid flavor numbers, 0, 1, 2, ...
p<>. If it is used without an accompanying
number, UPS finds the best match instance for the specified flavor
family. (The first one that matches in the ups flavor -l command.)
Useful to set the host to a different type, such as when
installing products for another platform. Can be used in combination
with the valid flavor numbers, 0, 1, 2, ...
p<>. If it is used without an accompanying
number, UPS finds the best match instance for the specified flavor
family. (The first one that matches in the ups flavor -l command.)
-0 -0 Specifies flavor for operating system generic to NULL. {font-weight: bold;font-family: monospace} Specifies flavor for operating system generic to NULL. {font-weight: bold;font-family: monospace}
-1, -2, -3, -4, -5 -1, -2, -3, -4, -5 Specifies flavor for operating
system generic, starting with basic OS, and adding details with each
increase in number for Basic OS + version + release + patch + build. Specifies flavor for operating
system generic, starting with basic OS, and adding details with each
increase in number for Basic OS + version + release + patch + build.
(no number) (no number) Specifies flavor for operating system to the highest
detail defied, basic OS + version + release + patch + build. Specifies flavor for operating system to the highest
detail defied, basic OS + version + release + patch + build.

  23.1.4 More Detailed
Description

  In general, UPS products require that the setup command be
issued on a product instance before invoking it (unless it is a
dependent product of one that is already setup). The setup
processes are intended to make the appropriate changes to the user's
software environment to make the requested product
available for use.

  Only one instance of a product
can be setup at a time. Each time you run setup on an
additional instance of the same product, the previously active
instance is automatically unsetup first.

  Internal Processes

  • Check node
    authorization
  • If necessary, process
    UNSETUP action
  • Process SETUP
    action
  • Source the temp
    file

  Environment Variables
Set by Default During setup

  When an instance is setup,
either or both of the two environment variables
$<PRODUCT>_DIR and $SETUP_<PRODUCT> may get defined. By
default, both do.
$<PRODUCT>_DIRpoints to the root directory of the product instance selected
by the setup command$SETUP_<PRODUCT>a string containing all the information that the unsetup command
needs in order to identify the instance when it is time to remove
access to the product
p<>.   In both of them,
<PRODUCT> is the name of the product in upper case. Using
the product upd (on the fermicloud050) as an example:

% setup upd
% echo $UPD_DIR
/fnal/ups/db/../prd/upd/v4_8_0/NULL
% echo $SETUP_UPD
upd v4_8_0 -f NULL -z /fnal/ups/db

  Use of the
$SETUP_<PRODUCT> Variable by unsetup

  unsetup uses the
environment variable $SETUP_<PRODUCT>, by default, to
determine which instance to unsetup. If this variable was not set during product setup (i.e., the setup default
functions were not run, or setupEnv() was not run), then when you run unsetup , you
must specify on the command line which instance to unsetup; running
simply unsetup
<product>
causes no action to be taken. See Use of the $SETUP_<PRODUCT> Variable under section 23.2 unsetup for more information regarding the unsetup command.

  23.1.5 setup
Examples

  In the following examples, when we say that all dependencies of a
product get set up, we mean all except optional dependencies that
are unavailable.

  Setup default instance
of product

% setup git

  This sets up the current
instance of the product git for the best match flavor of your OS. If the product
has any dependencies, they get setup too, by default.

% setup -v git

  This command sets up the same
instance as above, but displays verbose information (usually used
for debugging, but useful to see what's going on). If any file that
is "opened for read" does not exist, you'll see ERROR at the end of the line. This
is often but not always a fatal error. The output looks like
this:

UPSMAT: Searching UPS database - /fnal/ups/db
UPSFIL: /fnal/ups/db/.upsfiles/dbconfig - Open file for read
UPSFIL: /fnal/ups/db/.upsfiles/dbconfig - Read 6 item(s)
UPSMAT: Looking for Product = git
UPSMAT: Matching with Chain - current
UPSFIL: /fnal/ups/db/git/current.chain - Open file for read
UPSFIL: /fnal/ups/db/git/current.chain - Read 2 item(s)
UPSMAT:  get_instance: flavor Linux64bit+2.6-2.12 quals
Found one!
First post!
UPSMAT: Found 1 instances in /fnal/ups/db/git/current.chain
UPSMAT: Matching with Version v1_8_5_3 in Product git
UPSMAT: Using Flavor = Linux64bit+2.6-2.12, and Qualifiers =
(and much more)

  Restrict the setup of
dependent products

% setup -R ruby

  Use of the -R option sets
up the specified product and its required dependencies only.

% setup -j ruby

  Use of the -j option sets
up only the specified product; none of its dependencies get
setup.

  Setup a chained instance
(other than the default "current")

% setup -t prod1
% setup -g test prod1

  Either of these commands sets
up the instance of prod1 chained to "test" (for the default flavor). To setup any
chained instance other than current, include the chain flag in the
command.

  Setup a product
specifying its version

% setup prod1 v5_23a

  This command sets up version
v5_23a of prod1 whether or not it has a chain. Run a ups list command
to get the version information.

  Setup a product declared
with qualifiers

% setup -q BUILD prod1

  This command sets up the
current instance of prod1 for the operating system on which you're working,
along with its build dependencies (assuming the qualifier BUILD has
been implemented in the product files in the standard way, see
section 17.2.3 Products Requiring Build (In-House and
Third-Party)
).

  Remember that qualifiers are case-sensitive.

  Setup a product and
activate extended functionality

  To setup the instance of
product prod1 chained to development, and all of prod1 's dependencies, and to activate extended setup
actions, enter:

% setup -d -e prod1

  The -e option sets
$UPS_EXTENDED on for prod1 and for any of its UPS product requirements that were declared with the -e option. This is used to activate any extended functionality the
product provider may have included in the setup action for this
instance (e.g., defining extra environment variables).

  23.2 unsetup

  The unsetup command
makes the specified product no longer available for use. It undoes
the changes made to the environment by setup . You may
need to explicitly unsetup a UPS product if you are short on environment variable space
and want to get rid of extra environment variables or shorten the
$PATH variable length; otherwise you typically don't need to run
this command.

  23.2.1 Command
Syntax

% unsetup [<options>] <product> [<version>]

  23.2.2 All Valid
Options

  Typically, this command is
issued with no options.

 
Table 23.2.2-a:Table 23.2.2-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-e -e Sets $UPS_EXTENDED (to the value 1 ). Sets $UPS_EXTENDED (to the value 1 ).
-f
<flavor>
-f
<flavor>
Described in "The flavor
options"
. Described in "The flavor
options"
.
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores dependencies, runs unsetup on just
on top level product Ignores dependencies, runs unsetup on just
on top level product
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<options>"
-O
"<options>"
Sets the value of $UPS_OPTIONS to <options> . Sets the value of $UPS_OPTIONS to <options> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
qualifiers : colon separated list of required or optional qualifiersin any order
that are to be part of the instance qualifiers : colon separated list of required or optional qualifiers
that are to be part of the instance
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vv ) -v ( vv ) Prints out extra debugging information, vv for more, vvv for more. Prints out extra debugging information, vv for more, vvv for more.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which the
product(s) are declared Specifies the database(s) in which the
product(s) are declared
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )
shorthand for -r `pwd` -M ups -m ${UPS_PRODUCT}.table shorthand for -r `pwd` -M ups -m ${UPS_PRODUCT}.table

  23.2.3 More Detailed
Description

  unsetup is
intended to undo the changes to your software environment made
during product setup. It makes the product no longer available for
use. You may need to explicitly unsetup a UPS product if you are short on environment variable space
and want to get rid of extra environment variables or shorten the
$PATH variable length. Unsetup gets done automatically for you when
you setup a different instance of the same product.

  When you no longer need to
access a product, in most cases you can simply type:

% unsetup <product>

  for example:

% unsetup prod1

  Sometimes this isn't
sufficient. The $SETUP_<PRODUCT> variable governs the
behavior, as described below.

  Use of the
$SETUP_<PRODUCT> Variable

  unsetup uses the
environment variable $SETUP_<PRODUCT>, by default, to
determine which instance to unsetup. If this variable was not set during product setup (i.e., the setup default
functions were not run, or setupEnv() was not run), then you must specify on the
command line which instance to unsetup; running simply unsetup
<product>
causes no action to be taken.

  If $SETUP_<PRODUCT> has
been set (the usual case), it is best to run unsetup with no
options (except possibly -j as discussed
below). If any instance-identifying information besides product
name is specified on the unsetup command
line, this information gets ignored.

  Behavior of unsetup for
Product Dependencies

  The behavior of unsetup as
regards product dependencies depends upon a couple of factors:

  • whether an UNSETUP
    action exists in the main product's table file
  • whether
    $SETUP_<PRODUCT> has been defined for the product
    dependency

  If ACTION=UNSETUP is defined
for the main product, then:

  1. if it includes
    the function unsetupRequired for the dependency with no instance-identifying information (e.g., unsetupRequired
    (<dep_product>)
    only; no options or version), and if
    $SETUP_<PRODUCT> is defined for the dependency, unsetup will be
    run on the instance identified by $SETUP_<PRODUCT>.
  2. if it includes
    the function unsetupRequired for the dependency with no instance-identifying information (e.g., unsetupRequired
    (<dep_product>)
    only; no options or version), and if
    $SETUP_<PRODUCT> is not defined for the dependency, no unsetup will be
    performed for the dependency.
  3. if it includes
    the function unsetupRequired for the dependency with some instance-identifying information
    (e.g., unsetupRequired -q
    "build" <dep_product>
    ), then unsetup is run
    on this specified instance of the product dependency; if
    $SETUP_<PRODUCT> is defined for the dependency, it is
    ignored.

  If ACTION=UNSETUP is not defined for the main product, then:

  1. if
    $SETUP_<PRODUCT> is defined for the product dependency, then unsetup will be
    run on the instance identified by $SETUP_<PRODUCT>.
  2. if
    $SETUP_<PRODUCT> is not defined for the dependency, no unsetup will be
    performed for the dependency.

  If you use the -j option in the unsetup command
of the main product, only the main product gets unsetup; its
product dependencies are left untouched.

  Internal Processes

  • Check node
    authorization
  • Process UNSETUP
    action
  • Source the temp
    file

  The UNSETUP default functions
are to undo the default SETUP functions (i.e., unset
$<PRODUCT>_DIR and $SETUP_<PRODUCT>).

  Note: If there is no UNSETUP
action, then unsetup undoes
everything done in SETUP action. However, if SETUP includes
non-reversible functions, these cannot be undone by unsetup .

  23.2.4 unsetup
Examples

% unsetup lxr

  This command unsets the product lxr . When you no longer need to access a product, in most
cases you can simply use the product name to identify it.

% unsetup -j ruby

  The -j option in
this command causes UPS to unsetup the product, while leaving all its dependencies setup.

  23.3 ups configure

  For any product instance whose
table file includes a CONFIGURE action, the ups configure command executes this action. A CONFIGURE action usually includes
functions to construct symbolic links, copy files, or perform
automatic local customization of the product. The ups configure command gets run by default by ups declare when
the product is initially declared to a database (see section 23.5 ups declare , in particular the -C option), but
can be run manually as needed (e.g., on nodes of different
flavors).

  23.3.1 Command
Syntax

% ups configure [<options>] <product> [<version>]

  23.3.2 Commonly Used
Options

 
Table 23.3.2-a:Table 23.3.2-a:

-f
<flavor>
-f
<flavor>
A valid number or -H (alone or with a valid number) A valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
colon separated list of required or optional qualifiers
that are to be part of the instance in any order in any order
-z
<databaseList>
-z
<databaseList>
database : use this database to get instance information
database : use this database to get instance information

|

  23.3.3 All Valid
Options

 
Table 23.3.3-a:Table 23.3.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) in any order Finds product instance with the specified
qualifiers (required and/or optional) in any order
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )
. . shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table

  23.3.4 More Detailed
Description

  Installation/configuration
procedures that can be completely automated are typically collected
in the table file in a CONFIGURE action ( actions are described in Chapter 34: Actions and ACTION Keyword Values ), or in a script
called configure which
is called from the table file. The configuration may involve
creating links to the product root directory from other areas. If
the area is not identical for each machine flavor accessing the UPS database in which the product instance has been declared
(i.e., the same path but separate areas), then you will need to run
the ups
configure
command manually once per flavor, on a node of
that flavor. If each node mounts a unique area, you generally have
to run special commands (e.g., ups install , ups
initialize
, etc.) that are documented in the product's INSTALL_NOTE file. If
you are not sure whether you need to configure a product instance
on each flavor/node, look through the configuration steps in the
table file to see what they do.

  Internal Processes

  • Check node
    authorization
  • Process CONFIGURE
    action
  • Execute temp file

  23.3.5 ups configure
Examples

  Assuming prod1
is a product that requires ups configure to
be run manually for each machine flavor in a cluster. The sample
command, which should be issued from a machine of flavor Linux+2
runs the CONFIGURE action in the table file associated with the
product prod1 , version v1_6_4 for flavor Linux+2.

% ups configure prod1 v1_6_4 -f Linux+2

  A
command like this, but with the appropriate flavor, must be run for
each machine flavor represented in the cluster.

  23.4 ups copy

  The ups copy command
was designed as a UPS product development tool allowing a new instance of a
product to be declared "like" another.

  23.4.1 Command
Syntax

% ups copy -G "<ups_declare_options> <product> <version>" \ [<options>] <product> <version>

  23.4.2 Commonly Used
Options

  See section 23.4.3 All Valid Options for descriptions of each option.

 
Table 23.4.2-a:Table 23.4.2-a:

-f
<flavor>
-f
<flavor>
A valid number of -H (alone or with a valid number) A valid number of -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-G
"<options>"
-G
"<options>"
-q
<qualifierList>
-q
<qualifierList>
-r
<prodRootDir>
-r
<prodRootDir>
-T <path or
URL>
-T <path or
URL>
-W -W
-X -X
-z
<databaseList>
-z
<databaseList>

|

  23.4.3 All Valid
Options

 
Table 23.4.3-a:Table 23.4.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-A nodes -A nodes Authorized nodes Authorized nodes
-b compileFile -b compileFile compile file name (.sh and .csh will be added
automatically) compile file name (.sh and .csh will be added
automatically)
-c -c Finds source product instance chained to
"current" Finds source product instance chained to
"current"
-C -C don't do configure don't do configure
-d -d Finds source product instance chained to
"development" Finds source product instance chained to
"development"
-D origin -D origin products' master source file products' master source file
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-G
"<options>"
-G
"<options>"
Specifies options to be passed to the ups
declare
command for target product instance; see below Specifies options to be passed to the ups
declare
command for target product instance; see below
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name of source product
instance Specifies table file name of source product
instance
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory of source
product instance Specifies table file directory of source
product instance
-n -n Finds source product instance chained to
"new" Finds source product instance chained to
"new"
-o -o Finds source product instance chained to
"old" Finds source product instance chained to
"old"
-O
"<options>"
-O
"<options>"
Sets the value of $UPS_OPTIONS to <options> . Sets the value of $UPS_OPTIONS to <options> .
-p
"description"
-p
"description"
product description product description
-q
<qualifierList>
-q
<qualifierList>
Finds product instance on distribution node
with the specified qualifiers (required and/or optional) in any order Finds product instance on distribution node
with the specified qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory of
source product instance Specifies the product root directory of
source product instance
-t -t Finds source product instance chained to
"test" Finds source product instance chained to
"test"
-T <path or
URL>
-T <path or
URL>
Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format.
-u
<compileDir>
-u
<compileDir>
directory of file to put compiled information into directory of file to put compiled information into
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory of source product
instance; default value is ups Specifies location of ups directory of source product
instance; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-W -W Uses environment variables (e.g.,
$SETUP_<PRODUCT>) to identify dependent product instances for
target product (that is, it uses instances that are already setup
in preference to what is listed in table file) Uses environment variables (e.g.,
$SETUP_<PRODUCT>) to identify dependent product instances for
target product (that is, it uses instances that are already setup
in preference to what is listed in table file)
-X -X Executes the ups declare command instead of just echoing it Executes the ups declare command instead of just echoing it
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.4.4 Options Valid
with -G

  In order to distinguish the
target product instance from the source, the declarations for the
two instances must differ by at least one instance-identifying
element. The -G option
provides the means to specify the target instance identifiers; it
takes a list of ups declare command line elements as an argument. Any identifier not specified
via -G retains the
value of the source instance. The elements valid for use with -G include <product> , <version> and the following subset of the ups declare options:

  -A
<nodeList>
, -c , -d , -D
<origin>
, -f
<flavor>
, -g
<chainName>
, -n , -o , -O
"<flagList>"
, -p
"<description>"
, -q
<qualifierList>
, -t , -z
<databaseList>
, -0 , -1 , -2 , -3 , -4

  See section 23.5 ups declare for details on each option. If the argument
to -G includes the
product version, the product name must be included ahead of the
version; the first unflagged element is always interpreted as the
product name and the second as the version.

  23.4.5 More Detailed
Description

  The command ups copy is
intended mainly for product developers declaring new instances on
their development systems. It simplifies declaration of new
instances of products that already exist in a UPS database. There is no restriction against using ups
copy
to copy the installation of a different product,
however it's usually not particularly helpful in that
situation.

  Notes:

  • ups copy runs ups
    declare
    if you use the -X (uppercase -x )
    option; if not used, the declare command is just echoed.
  • Use the -G option to
    specify declaration information that is to be different from the
    installation you're using as a model. At least one
    instance-identifying element must be specified using -G to
    distinguish the source from the target instance.
  • If you use the option -W ,
    you will pick up the current environment. For example, if the
    previously declared instance depends on v1_0 of some product (e.g., joe v1_0), but the new instance should have joe v2_0 as a dependency, first run setup joe v2_0 ,
    then run ups copy with -W .

  Internal Processes

  • Process COPY
    action
  • Create a table file
    entry for new instance (may use environment for UPS product requirements)
  • If simulation only,
    write table file entry to temp and echo appropriate declare
    command
  • Otherwise, write/merge
    in table file and declare new instance (see ups declare internals)
  • Execute temp file

  23.4.6 ups copy
Examples

% ups copy dog v1 -G "dog v3 -f Linux+2 -q test -m v3.table -M ups\ 
-r /path/to/dog/v3" 

  This command runs a ups
copy
command for dog version v3, without the -X option so
that the ups declare command just gets echoed, not executed. The -G argument here
gives the product name and version plus options to be used by the ups
declare
command: the flavor ( -f Linux+2 ), a
qualifier ( -q test ), the
table file name and location (given via -m and -M ),
and the product root directory (given via -r ). The command
output looks like this:

/var/tmp/baaa006ni_table_dog 
ups declare dog v3 -f "Linux+2" -q "test" -r "/path/to/dog/v3"\
 -U "ups" -m "v3.table" -M "ups" 

  The second command is
identical to the first example except that the -X option
instructs it to execute the ups declare command:

% ups copy dog v1 -G "dog v3 -f Linux+2 -q test -r /path/to/dog/v3 \ 
-M ups -m v3.table" -X

  23.5 ups declare

  The ups declare command is used for two separate purposes:

  1. to initially
    declare an instance to a database (and optionally add a chain at
    the same time)
  2. to add a chain
    to a previously declared instance

  23.5.1 Command
Syntax

  For initially declaring
an instance

% ups declare <flavor_option> %{font-weight: bold;font-family: monospace}-r <prodRootDir>% [<other_options>] \ 
<product> <version>

  For declaring a
chain

% ups declare <chain_option> [<other_options>] <product> \ 
<version>

  23.5.2 Commonly Used
Options

  See section 23.5.3 All Valid Options for descriptions of each option.

  For initially declaring
an instance

 
Table 23.5.2-a:Table 23.5.2-a:

-f
<flavor>
-f
<flavor>
A valid number or -H (alone or with a valid number) A valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-m
<tableFileName>
-m
<tableFileName>
-q
<qualifierList>
-q
<qualifierList>
-r
<prodRootDir>
-r
<prodRootDir>
-z
<databaseList>
-z
<databaseList>

|

  For declaring a
chain

 
Table 23.5.2-b:Table 23.5.2-b:

-f
<flavor>
-f
<flavor>
A valid number or -H (alone or with a valid number) A valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.5.3 All Valid
Options

 
Table 23.5.3:Table 23.5.3:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen. Prints command description and option usage
information to screen.
-A
<nodeList>
-A
<nodeList>
Specifies nodes authorized to access the
product; sets the keyword AUTHORIZED_NODES Specifies nodes authorized to access the
product; sets the keyword AUTHORIZED_NODES
-b
<compileFile>
-b
<compileFile>
Specifies name of the output file for the ups
compile
command (described in Chapter 38: Use of Compile Scripts in Table Files ); sets the keyword
COMPILE_FILE Specifies name of the output file for the ups
compile
command (described in Chapter 38: Use of Compile Scripts in Table Files ); sets the keyword
COMPILE_FILE
-c -c Chains the product instance to "current";
when this chain gets declared, the corresponding ACTION=CURRENT in
the table file gets executed, if it exists. Chains the product instance to "current";
when this chain gets declared, the corresponding ACTION=CURRENT in
the table file gets executed, if it exists.
-C -C When initially declaring a product, -C prevents execution of the CONFIGURE action. When initially declaring a product, -C prevents execution of the CONFIGURE action. When declaring a chain, -C prevents
execution of the corresponding chain action. When declaring a chain, -C prevents
execution of the corresponding chain action.
-d -d Chains the product instance to "development";
when this chain gets declared, the corresponding ACTION=DEVELOPMENT
in the table file gets executed, if it exists. Chains the product instance to "development";
when this chain gets declared, the corresponding ACTION=DEVELOPMENT
in the table file gets executed, if it exists.
-D
"<origin>"
-D
"<origin>"
Specifies the product's master source file;
sets the keyword ORIGIN (all spaces get removed from <origin> for the keyword value) Specifies the product's master source file;
sets the keyword ORIGIN (all spaces get removed from <origin> for the keyword value)
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Chains the product instance to <chainName> (this is useful for user-defined chains). When any chain gets
declared, the corresponding ACTION=<CHAIN_NAME> in the table
file gets executed. Chains the product instance to <chainName> (this is useful for user-defined chains). When any chain gets
declared, the corresponding ACTION=<CHAIN_NAME> in the table
file gets executed.
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-L -L Adds the STATISTICS keyword to the version
file, thereby instructing UPS to keep statistics on this product instance. Adds the STATISTICS keyword to the version
file, thereby instructing UPS to keep statistics on this product instance.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name; when initially
declaring a product, sets the keyword TABLE_FILE. Specifies table file name; when initially
declaring a product, sets the keyword TABLE_FILE.
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory; when
initially declaring a product, sets the keyword TABLE_DIR. Specify
only if file is not in one of the two default locations, namely
under $PRODUCTS/<product> or in the ups directory. Specifies table file directory; when
initially declaring a product, sets the keyword TABLE_DIR. Specify
only if file is not in one of the two default locations, namely
under $PRODUCTS/<product> or in the ups directory.
-n -n Chains the product instance to "new"; when
this chain gets declared, the corresponding ACTION=NEW in the table
file gets executed, if it exists. Chains the product instance to "new"; when
this chain gets declared, the corresponding ACTION=NEW in the table
file gets executed, if it exists.
-o -o Chains the product instance to "old"; when
this chain gets declared, the corresponding ACTION=OLD in the table
file gets executed, if it exists. Chains the product instance to "old"; when
this chain gets declared, the corresponding ACTION=OLD in the table
file gets executed, if it exists.
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-q
<qualifiers>
-q
<qualifiers>
When initially declaring a product, -q specifies required and/or optional qualifiers to include in the
declaration, and sets the keyword QUALIFIERS. When initially declaring a product, -q specifies required and/or optional qualifiers to include in the
declaration, and sets the keyword QUALIFIERS. When adding a chain, -q specifies
required and/or optional qualifiers to identify the instance. When adding a chain, -q specifies
required and/or optional qualifiers to identify the instance.
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory; when
initially declaring a product, sets the keyword PROD_DIR. Specifies the product root directory; when
initially declaring a product, sets the keyword PROD_DIR. A note for developers: you may find it
convenient to use the construction -r \pwd\ if
you're working in the product root directory. A note for developers: you may find it
convenient to use the construction -r \pwd\ if
you're working in the product root directory.
-t -t Chains the product instance to "test"; when
this chain gets declared, the corresponding ACTION=TEST in the
table file gets executed, if it exists. Chains the product instance to "test"; when
this chain gets declared, the corresponding ACTION=TEST in the
table file gets executed, if it exists.
-T <path or
URL>
-T <path or
URL>
Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. When
initially declaring a product, it sets the keyword
ARCHIVE_FILE. Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. When
initially declaring a product, it sets the keyword
ARCHIVE_FILE.
-u
<compileDir>
-u
<compileDir>
Specifies the directory for the output file
(which is named via the -b option) for
the ups
compile
command; sets the keyword COMPILE_DIR. Specifies the directory for the output file
(which is named via the -b option) for
the ups
compile
command; sets the keyword COMPILE_DIR.
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups ;
when initially declaring a product, sets the keyword UPS_DIR Specifies location of ups directory; default value is ups ;
when initially declaring a product, sets the keyword UPS_DIR
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database in which to declare
the product (see section 27.1 Database Selection Algorithm ); or, if adding a chain,
specifies the database(s) in which product is declared Specifies the database in which to declare
the product (see section 27.1 Database Selection Algorithm ); or, if adding a chain,
specifies the database(s) in which product is declared
-Z -Z Times the command Times the command

  23.5.4 More Detailed
Description

  Declaring an Instance
for the First Time

  In the ups declare command:

  • -C prevents
    execution of the CONFIGURE action, if any, and is normally not
    included. The default (and usually desired) behavior is to execute
    the CONFIGURE action.
  • You must include a
    flavor specification, there is no default flavor when a product is
    first declared. It sets the value of the FLAVOR keyword.
  • Most products require a table file. The table
    file must exist before running ups declare . In
    most cases you need to include the table file name ( -m ). (Since in a
    very few cases a table file isn't required, -m is not a
    strictly required option.)
  • If the product's table
    file was placed in either of the two default locations (under /path/to/database/<product> or in the product's ups directory), then -M
    <table_file_dir>
    is not needed. Only use the -M option if you have moved the table file to a separate location
    where UPS won't otherwise find it.
  • In most cases you need
    to include product root directory ( -r ). Exceptions
    include wrapper products which consist only of a table file, and
    thus have no product root directory.
  • If the product's ups directory tar file
    was unwound in the default location ( $<PRODUCT>_DIR/ups ), then -U
    <ups_dir>
    is not needed. If the ups directory is located elsewhere
    (or named differently), this specification must be included. In
    general, you should not include this qualifier.
  • If you choose not to
    specify the target database explicitly ( -z
    <database>
    ), UPS chooses it automatically via the $PRODUCTS variable. If
    $PRODUCTS points to multiple databases, you need to be a little
    careful about database selection. The database matching algorithm
    is described in section 27.1 Database Selection Algorithm .
    p<>.   If the product has
    dependencies that are declared in different databases, UPS must be able to find all of them in order to resolve the
    dependencies. You can rely on $PRODUCTS if all the necessary
    databases are included in it. Otherwise specify them on the command
    line (e.g., -z
    <database1>:<database2>:...>
    or -z
    $PRODUCTS:<database1>:<database2>:...
    ).
  • You may include chain
    information on this command. See the description below.

  Adding Chains to an
Existing Instance

  When you add one or more chains
to an existing instance, UPS doesn't allow you to change anything else about that
instance. Regarding the options to specify:

  • You of course need to
    specify the chain or chains to add using either -g
    <chain_name>
    or one of -c , -d , -n , -o , -t .
  • -C prevents the
    corresponding chain action(s) in the table file from being
    executed.
  • You do not strictly need
    to specify flavor. UPS will default to the best flavor match (described in
    section 27.2.4 Flavor and Qualifier Matching Algorithm ). You can
    override the default using -f or a valid number
    (.
  • Specify qualifiers
    ( -q )
    as necessary to select the appropriate instance (in any order) .
  • Specify the database
    ( -z )
    as necessary to select the appropriate instance.

  Internal Processes

  • Find database to
    use
  • If necessary, process
    `UNCHAIN' action
  • Process DECLARE
    action
  • If necessary, process
    CONFIGURE action
  • If necessary, warn if
    there is a TAILOR action
  • If necessary, process
    the `CHAIN' action
  • If necessary, warn if
    there are START/STOP actions
  • If current chain, try
    to copyman, copycatman and copyInfo files
  • Execute the temp
    file
  • If successful, modify
    all appropriate files on disk

  23.5.5 ups declare
Examples

  Declare a product with
no chain using defaults where possible

% ups declare myprod v1_0 -f Linux+2 -m myprod.table \ 
            -r /path/to/myprod/v1_0/Linux+2

  UPS finds the product in the directory given by the -r option, and
declares it to a database in $PRODUCTS according to the selection
algorithm discussed in 27.1 Database Selection Algorithm . The product instance gets
declared with the specified name, version and flavor, and no
qualifiers. UPS looks for the table file, called myprod.table in the two default
locations (command fails if table file doesn't exist, or is not
found in either location).

  Declare a product with
no chain using defaults where possible

% ups declare myprod2 v1_0 -2 -g test -m myprod2.table \
           -r myprod2/v1_0/FictionalOS+a -z /my/local/db:$PRODUCTS

  For this example, we assume the
local machine flavor is FictionalOS+a.b. UPS finds the product in the directory given by the -r option. The specified path is taken relative to PROD_DIR_PREFIX. UPS declares the product to one of the listed databases
according to the selection algorithm discussed in 27.1 Database Selection Algorithm . Each of the dependencies,
if any, must exist in at least one of the listed databases.

  The product instance gets
declared with the specified name, version, no qualifiers, and the
chain "test". The flavor declaration is the level -2 specification
of the machine, namely FictionalOS+a. UPS looks for the table file, called myprod2.table in the two default
locations (command fails if table file doesn't exist, or is not
found in either location).

  Add a chain to a
previously declared instance

% ups declare myprod2 v1_0 -2 -g test -m myprod2.table \  
         -r myprod2/v1_0/FictionalOS+a -z /my/local/db:$PRODUCTS
% ups declare myprod2 v1_0 -2 -c -z /my/local/db:$PRODUCTS

  This command declares the
product instance of the previous example "current" (via the -c option). Generally, a product is first declared as "test", and then
after a "debugging period" (often several weeks), an updated
release is cut and chained to "current". Notes:

  • In most UPS/UPD commands you specify either chain (often defaulted
    to "current") or version. Here you need both: the version is
    required to identify the instance, and the chain is required
    because it is being assigned.
  • You should specify the
    database /my/local/db first since that's how it was initially declared. UPS will traverse the databases in the same order to find
    the right instance.

  23.6 ups depend

  The ups depend command lists product dependencies of the specified product
instance(s) as declared in the (local) database. On user nodes it
is generally used to determine what products will get setup along
with the "parent" product. UPD uses it on product servers to determine what
dependencies to install.

  23.6.1 Command
Syntax

% ups depend [<options>] <product> [<version>]

  23.6.2 Commonly Used
Options

  See section 23.6.3 All Valid Options for descriptions of each option.

 
Table 23.6.2-a:Table 23.6.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-j -j
-K
<keywordList>
-K
<keywordList>
-l -l
-q
<qualifierList>
-q
<qualifierList>
-R -R
-z
<databaseList>
-z
<databaseList>

|

  23.6.3 All Valid
Options

 
Table 23.6.3-a:Table 23.6.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-B Show complete dependency tree, without pruning repeated product mentions
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores lower level dependencies, finds
direct dependencies of top level product only Ignores lower level dependencies, finds
direct dependencies of top level product only
-K
<keywordList>
-K
<keywordList>
Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords
-l -l Produces a long listing including all the
table file functions that would be executed in a setup command. Produces a long listing including all the
table file functions that would be executed in a setup command.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-R -R Lists only the required (non-optional)
dependencies. Lists only the required (non-optional)
dependencies.
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databases>
-z
<databases>
Specifies the database(s) to search Specifies the database(s) to search
-Z -Z Times the command Times the command

  ups depend
Examples

  Execute command with qualifiers

  The first example requests
information for art v1_08_10 with qualifiers for art

% ups depend art v1_08_10 -q debug:e4:nu
art v1_08_10 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|__cetpkgsupport v1_04_02 -f NULL -z /nusoft/app/externals -g current
|__messagefacility v1_10_26 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |__fhiclcpp v2_17_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|     |__cetlib v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|        |__cpp0x v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|           |__boost v1_53_0 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|              |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__root v5_34_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|  |__geant4 v4_9_6_p02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__clhep v2_1_3_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__xerces_c v3_1_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__g4emlow v6_32 -f NULL -z /nusoft/app/externals
|  |  |__g4neutron v4_2 -f NULL -z /nusoft/app/externals
|  |  |__g4neutronxs v1_2 -f NULL -z /nusoft/app/externals
|  |  |__g4nucleonxs v1_1 -f NULL -z /nusoft/app/externals
|  |  |__g4photon v2_3 -f NULL -z /nusoft/app/externals
|  |  |__g4pii v1_3 -f NULL -z /nusoft/app/externals
|  |  |__g4radiative v3_6 -f NULL -z /nusoft/app/externals
|  |  |__g4surface v1_0 -f NULL -z /nusoft/app/externals
|  |__fftw v3_3_3 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__gsl v1_16 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__pythia v6_4_28 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:gcc48
|  |__postgresql v9_1_5b -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__python v2_7_5c -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |     |__sqlite v3_08_00_02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__mysql_client v5_5_27 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q e4
|  |__xrootd v3_3_4 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |__libxml2 v2_9_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|__cppunit v1_12_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|__gccxml v0_9_20130621 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__cmake v2_8_8 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -g current
|__tbb v4_1_3 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4

  The next example requests
information for redmine

% ups depend redmine
redmine v1_4_1 -f NULL -z /fnal/ups/db -g current
|__ruby v1_9_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__cvs v1_12_13 -f Linux+2 -z /fnal/ups/db
|__git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current
|__subversion local -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current

  The -R option
requests only the dependencies listed as "required." In both examples, all
dependencies are required so the output is the same.

% ups depend -R redmine
redmine v1_4_1 -f NULL -z /fnal/ups/db -g current
|__ruby v1_9_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__cvs v1_12_13 -f Linux+2 -z /fnal/ups/db
|__git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current
|__subversion local -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current

  23.7 ups exist

  The ups exist command is used to test whether a setup command
issued with the same command line elements is likely to succeed. It
was designed primarily for use in scripts.

  23.7.1 Command
Syntax

% ups exist [<options>] <product> [<version>]

  23.7.2 Commonly Used
Options

  See section 23.7.3 All Valid Options for descriptions of each option.

 
Table 23.7.2-a:Table 23.7.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid
number) Or a valid number or -H (alone or with a valid
number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-j -j
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.7.3 All Valid
Options

 
Table 23.7.3-a:Table 23.7.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-B <depProdName>=
"<options>"
-B <depProdName>=
"<options>"
Specifies options to prepend to the setupRequired line (in
table file) for the dependent product <depProdName> Specifies options to prepend to the setupRequired line (in
table file) for the dependent product <depProdName>
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-e -e Sets $UPS_EXTENDED (to the value 1 ). Sets $UPS_EXTENDED (to the value 1 ).
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores dependencies, operates just on top
level product Ignores dependencies, operates just on top
level product
-k -k Prevents execution of unsetup files prior to
(subsequent) setup Prevents execution of unsetup files prior to
(subsequent) setup
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.7.4 More Detailed
Description

  The ups exist command is used to test whether a setup command
issued with the same command line elements is likely to succeed. As
for all the UPS/UPD commands, if the setup command
finds a corresponding action in the selected table file, it

  1. translates the
    functions listed under the action into shell commands,
  2. writes them to
    a temporary script in $TMPDIR (if $TMPDIR isn't set, the default is /tmp ), and
  3. invokes the
    script to execute the shell commands.

  ups exist checks
for a properly declared matching instance, and verifies that you
have the necessary permissions to create the temporary script. If
so, it creates the script, but it does not execute it.

  ups
exist
sets the $? variable to 0 if it was able to create the
temporary file, or to 1 for error.

  This command is rarely used
from the command line, and is more useful in scripts where a failed
setup could cause the script to abort. When issued from the command
line, it returns no output if the command succeeds.

  Internal Processes

  • Check node
    authorization
  • If necessary, process
    UNSETUP action
  • Simulate SETUP
    action

  23.7.5 ups exist
Examples

  This command is rarely used
from the command line, and is more useful in scripts where a failed
setup could cause the script to abort. When issued from the command
line, it returns no output if the command succeeds.

  ups
exist
sets the $? variable to 0 if it was able to create the
temporary file, or to 1 for error. As an example, we can run ups list and
find that there is a current instance of the product prod1 for the flavor FictionalOS+a but not for FictionalOS+a.b. Running ups
exist
for each flavor, we see that the variables get set
accordingly.

$ ups exist prod1 -f FictionalOS+a; echo $?
0
$ ups exist prod1 -f FictionalOS+a.b; echo $?
1

  23.8 ups flavor

  The ups flavor command with no options returns the flavor of the machine. If a
flavor level is specified (e.g., -0 , -1 ...), it
returns the flavor according to that level. ups flavor generates a flavor table if the -H option is
used. The flavor levels and the term flavor table are defined in section 23.8.4 More Detailed Description .

  23.8.1 Command
Syntax

% ups flavor [<options>]

  23.8.2 Commonly Used
Options

  See section 23.8.3 All Valid Options for descriptions of each option.

 
Table 23.8.2-a:Table 23.8.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number Or a valid number
-H
<flavor>
-H
<flavor>
Alone or together with a valid number Alone or together with a valid number
-l -l

|

  23.8.3 All Valid
Options

 
Table 23.8.3-a:Table 23.8.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen. Prints command description and option usage
information to screen.
-f
<flavor>
-f
<flavor>
Specifies flavor. Specifies flavor.
-H
<flavor>
-H
<flavor>
Specifies host flavor family from which to
build a flavor table. If used with any of -0 , -1 , -2 , -3 , -4 , -5 , specifies
corresponding level of specified host flavor family. Specifies host flavor family from which to
build a flavor table. If used with any of -0 , -1 , -2 , -3 , -4 , -5 , specifies
corresponding level of specified host flavor family.
-l -l Produces a flavor table. Produces a flavor table.
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-Z -Z Times the command. Times the command.
-0 -0 Specifies flavor as NULL Specifies flavor as NULL
-1 -1 Pick flavor for operating system generic to the vendor Pick flavor for operating system generic to the vendor
-2 -2 Pick flavor for operating system to level of major version number Pick flavor for operating system to level of major version number
-3 -3 Pick more specific flavor for operating system (includes start of
minor version numbers) Pick more specific flavor for operating system (includes start of
minor version numbers)
-4 -4 Pick still more specific flavor for operating system (includes more
of minor version numbers) Pick still more specific flavor for operating system (includes more
of minor version numbers)
-5 -5 Pick most specific flavor for operating system (includes all of
minor version numbers) Pick most specific flavor for operating system (includes all of
minor version numbers)

  23.8.4 More Detailed
Description

  The ups flavor command returns flavor information about the machine issuing the
command, or for a flavor requested via the -H option. When
entered with no options, the command returns the full OS
specification of the machine.

  When entered with the -l (long) option, ups flavor returns what we call a flavor table , which is a list including every level of
specificity for a flavor that you could use to find or declare a
product instance. For example, on novagpvm02, it
outputs:

% ups flavor -l
Linux64bit+2.6-2.5
Linux64bit+2.6-2.4
Linux64bit+2.6-2.3
Linux64bit+2.6-2.2
Linux64bit+2.6-2.1
Linux64bit+2.6-2.0
Linux+2.6-2.5
(and many more)
NULL
ANY

  If -H
<flavor>
is used with -l , ups flavor builds a flavor table for the flavor given by -H . This is
useful if you're not sure what levels are allowable for a
particular basic flavor. The flavor table lists flavors starting at
the level you specify. Compare the following two commands and
output:

% ups flavor -lH FictionalOS+a.6
FictionalOS+a.6
FictionalOS+a.5
FictionalOS+a.4
FictionalOS+a.3
FictionalOS+a.b
FictionalOS+a.1
FictionalOS+a.0
FictionalOS+a
FictionalOS
NULL
ANY
% ups flavor -lH FictionalOS
FictionalOS
NULL
ANY

  You can specify a particular
level using the number options, with the highest number being the
most specific.

  23.8.5 ups flavor
Examples

  Find full flavor
specification of machine

% ups flavor

  This command returns the full
OS specification of the machine up to the build number for the patch
(when these levels of specification exist), for example:

Linux64bit+2.6-2.5

  Create a flavor table
for machine's OS

% ups flavor -l

  This command returns a flavor
table for the flavor of the machine. For example, on a (fictional)
Linux+2.6 machine it outputs:

Linux+2.6.1-4
Linux+2.6.1
Linux+2.6
Linux+2
Linux
NULL
ANY

  Find flavor
specification of machine, at different levels

% ups flavor -4

  The -4 option
requests the machine's flavor as the most significant OS
specification or the full specification, e.g.,:

Linux+2.6.1
% ups flavor -3

  The -3 option
requests the machine's flavor as basic OS and version and release, e.g.,:

Linux+2.6

  The -2 option
requests the machine's flavor as basic OS and version, e.g.,:

Linux+2.6
% ups flavor -1

  The -1 option
requests the machine's flavor as the OS value up to the generic OS,
e.g.,:

Linux
% ups flavor -0

  This always returns the NULL
string.

  Create a flavor table
for host flavor, at different levels

% ups flavor -lH FictionalOS+a.6

  This creates a flavor table
listing flavors starting at the level specified via -H , in this case
"level 3":

FictionalOS+a.6
FictionalOS+a
FictionalOS
NULL
ANY
% ups flavor -lH FictionalOS+a

  This creates a flavor table
listing flavors starting at the level specified via -H , in this case
"level 2":

FictionalOS+a
FictionalOS
NULL
ANY

  23.9 ups get

  The ups get command
is rarely used by anyone except product developers/maintainers. It
t just scans the all actions for a product (setup, etc. in the table file) and looks
for things that are files, and lists them.

  The ups get command
was designed primarily for use by UPD , which calls it internally. As such it is rarely used
outside of that context.

  23.9.1 Command
Syntax

% ups get -F [<other_options>] <product> [<version>]

  23.9.2 All valid
options

 
Table 23.9.2-a:Table 23.9.2-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list. Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list.
-F -F Prints to screen a list of files that are
associated with the product but which are maintained external to
the products area (excluding table file) Prints to screen a list of files that are
associated with the product but which are maintained external to
the products area (excluding table file)
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list. Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.9.3 ups get
Example

% ups get -F ups

  In the database on the machine
used, the UPS product has a few files maintained outside of the
product root directory. This command returns the output:

/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/current/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/uncurrent/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/unconfigure

  23.10 ups help

  The ups help command
lists all the UPS commands with brief definitions. There are no options
for this command.

  23.10.1 ups help
Example

% ups help
UPS commands:

for specific command options use "ups COMMAND -?"configure   : Environmentally configure a product instance.
          copy        : Allow one instance of a product to be declared "like" another.
          declare     : Add a product instance or a chain to a UPS Database.
          depend      : List (for a specified UPS product instance) UPS product 
                        requirements or all UPS product instances that have the 
                        specified UPS product instance as a requirement.
          exist       : Determine if a setup command with the same options
                        would likely succeed.
          flavor      : Print flavor of a machine, optionally by level, or table 
                        generated for searchingget         : Return a list of all files that are needed  by a product
                        instance and do not live under the product root directory.
          help        : Output help information for all UPS commands
          list        : List UPS Database information about product instances.
          modify      : Allow editor modification of the UPS Database files.
                        The altered files are verified before being rewritten.
          setup       : Prepare the environment in order to be able to use a product
                        instance.
          start       : Perform any necessary actions for a product instance at system 
                        boot.
          stop        : Perform any necessary actions for a product instance at 
                        system shutdown.
          tailor      : Perform any product instance tailoring that needs to be done 
                        once (specify hardware device location) or needs user input.
          touch       : Will change a ups file modify time (MODIFIED) to current time
                        (it will probaly also change the modifier (MODIFIER)).
          unconfigure : Undo any actions performed by the configure command.
          undeclare   : Remove a product instance from a UPS Database.
                        if chain(s) are specified ONLY the chain(s) will version will
                        be removed
          unsetup     : Return the environment to a pre-setup state.
          verify      : Check the specified instances for correct formatting and
                        information.

  23.11 ups list

  The ups list command
returns information about the declared product instances in a UPS database. Two output styles are provided: a formatted
one that is easy for users to read, and a condensed one for parsing
by a subsequent command or a script.

  23.11.1 Command
Syntax

% ups list [<options>] [<product>] [<version>]

  23.11.2 Commonly Used
Options

  See section 23.11.3 All Valid Options for descriptions of each option.

 
Table 23.11.2-a:Table 23.11.2-a:

-a -a
-f
<flavorList>
-f
<flavorList>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-K
<keywordList>
-K
<keywordList>
-l -l
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.11.3 All Valid
Options

Table 23.11.3-b:Table 23.11.3-b:
-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-a -a Includes all instances. Includes all instances.
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-K -K keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN
-l -l produce a long listing produce a long listing
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Specifies product instance chained to
"test" Specifies product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups (relative to the product root directory) Specifies location of ups directory; default value is ups (relative to the product root directory)
-v ( vv ) -v ( vv ) Prints out extra debugging information.
(-vv for more, -vvv for even more) Prints out extra debugging information.
(-vv for more, -vvv for even more)
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup ) Times the command (does not include time for
sourcing of temp file for setup )
-. -. shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace} shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace}
|

  23.11.4 More Detailed
Description

  ups list is
useful for finding out what products are in the database that you
use, what the current version of a product is for your machine's
flavor, and other information. Product installers and other
administrative users can use it to get detailed information about a
product's installation and to find product files.

  You can specify the information
you want contained in the output by including various options in
the command. As is standard in UPS , if no chain, version or flavor is specified, and -a (for all instances) is not specified, UPS returns only the instance declared as current for the
best-matched flavor of the requesting machine.

  Formatted Output
Style

  One output style is for visual
parsing (this is the default output, which we call formatted ), with output that looks like:

%  ups list git

DATABASE=/nusoft/app/externals 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

  Notice that the product name,
version, flavor, qualifiers and chain(s) are the default fields
that get returned. The database (first line of the output) is
included as a header, not as part of the per-instance data. Each
piece of data returned for an instance is preceded by its keyword
for identification.

  You cannot choose arbitrary
output fields for the selected instances using this output format.
However, you can use the -l option to
give an exhaustive listing of information contained in the UPS database about the requested product.

  If $PRODUCTS contains multiple
databases, output is returned for each one and labelled
accordingly, for example:

% ups list git

DATABASE=/nusoft/app/externals 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

DATABASE=/grid/fermiapp/products/common/db 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

    Product=git    Version=v1_8_0_1    Flavor=Linux+2
        Qualifiers=""    Chain=current

  Notice that more than one instance
of the product may exist for a given database.

  Condensed Output
Style

  The other output format is a
script-readable (or condensed ) format, provided to allow parsing by a subsequent
command. Use the -K option to
request output in the condensed format. The -K option
requires an argument list specifying which fields to include in the
output, for example:

% ups list -K product:version:flavor git
"git" "v1_8_0_1" "Linux64bit+2" 
"git" "v1_8_0_1" "Linux64bit+2" 
"git" "v1_8_0_1" "Linux+2" 

  The plus sign ( ) argument,
e.g., -K , is a
shorthand for requesting the default fields product:version:flavor:qualifiers:chain ,
for example:

% ups list -K+ git
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux+2" "" "current" 

  Some common keyword arguments
used with the -K option
are:

 
Table 23.11.4-a:Table 23.11.4-a:

PRODUCT PRODUCT product name product name
FLAVOR FLAVOR product instance flavor product instance flavor
VERSION VERSION product version product version
QUALIFIERS QUALIFIERS additional instance specification information
often used to indicate compilation options used by developer additional instance specification information
often used to indicate compilation options used by developer
CHAIN CHAIN product instance chain product instance chain
+ + all of the above all of the above
DATABASE (or DB) DATABASE (or DB) the UPS database path; useful if more than one on system the UPS database path; useful if more than one on system
DECLARER DECLARER logon id of person who declared the
instance logon id of person who declared the
instance
DECLARED DECLARED date/time that product instance was
declared date/time that product instance was
declared
MODIFIER MODIFIER logon id of person who modified/updated the
instance logon id of person who modified/updated the
instance
MODIFIED MODIFIED date/time that product instance was
modified/updated date/time that product instance was
modified/updated

  If $PRODUCTS contains multiple
databases, output is returned for selected products in all of them.
However, the database is identified for each output line only if
the keyword DATABASE or DB is included in the argument string
(e.g., -K+:DB requests
the standard output fields followed by the database path).

  A few of the keywords allow
the "at" symbol, @ to be prepended, which provides a sort of
shorthand for long path names:

 
Table 23.11.4-b:Table 23.11.4-b:

@PROD_DIR @PROD_DIR entire path for the directory where the
product is installed (usually equivalent to
PROD_DIR_PREFIX/PROD_DIR) entire path for the directory where the
product is installed (usually equivalent to
PROD_DIR_PREFIX/PROD_DIR)
@TABLE_FILE @TABLE_FILE entire path for the table file entire path for the table file
@UPS_DIR @UPS_DIR product's ups directory; if it is not an
absolute path, then it is taken relative to @PROD_DIR product's ups directory; if it is not an
absolute path, then it is taken relative to @PROD_DIR

  The full list of keywords that
can be used with ups list -K and upd list
-K
follows, with descriptions:

Keyword Keyword Description Description
ARCHIVE_FILE ARCHIVE_FILE archive file name/location; useful with upd
list
archive file name/location; useful with upd
list
AUTHORIZED_NODES AUTHORIZED_NODES authorized nodes; "all nodes" represented by
an asterisk () in output authorized nodes; "all nodes" represented by
an asterisk (
) in output
CATMAN_SOURCE_DIR CATMAN_SOURCE_DIR location of catman files (formatted man page
files) included with instance location of catman files (formatted man page
files) included with instance
CATMAN_TARGET_DIR CATMAN_TARGET_DIR directory into which catman files are to be
copied directory into which catman files are to be
copied
CHAIN CHAIN chain name chain name
COMPILE_DIR COMPILE_DIR directory in which the compile file
resides directory in which the compile file
resides
COMPILE_FILE COMPILE_FILE the name of the file containing compiled
functions (see Chapter 38: Use of Compile Scripts in Table Files ) the name of the file containing compiled
functions (see Chapter 38: Use of Compile Scripts in Table Files )
@COMPILE_FILE @COMPILE_FILE entire path to the file containing compiled
functions entire path to the file containing compiled
functions
DECLARED DECLARED the date/time that the instance was declared
to UPS or declared with a chain the date/time that the instance was declared
to UPS or declared with a chain Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations) Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations)
DECLARER DECLARER userid of user that performed the
declaration userid of user that performed the
declaration Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations) Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations)
DESCRIPTION DESCRIPTION product description product description
FLAVOR FLAVOR product instance flavor product instance flavor
INFO_SOURCE_DIR INFO_SOURCE_DIR location of Info files included with
instance location of Info files included with
instance
INFO_TARGET_DIR INFO_TARGET_DIR directory into which Info files are to be
copied directory into which Info files are to be
copied
MAN_SOURCE_DIR MAN_SOURCE_DIR location of unformatted man page files
included with instance location of unformatted man page files
included with instance
MAN_TARGET_DIR MAN_TARGET_DIR directory into which formatted man pages are
to be copied directory into which formatted man pages are
to be copied
MODIFIED MODIFIED last time the associated instance was
changed last time the associated instance was
changed Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations) Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations)
MODIFIER MODIFIER userid of user that modified the
instance userid of user that modified the
instance Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations) Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations)
ORIGIN ORIGIN master source file; see option -D in Chapter 25: Generic Command Option Descriptions master source file; see option -D in Chapter 25: Generic Command Option Descriptions
PRODUCT PRODUCT product name product name
PROD_DIR PROD_DIR product root directory (usually defined
relative to PROD_DIR_PREFIX, below) product root directory (usually defined
relative to PROD_DIR_PREFIX, below)
@PROD_DIR @PROD_DIR entire path to product root directory entire path to product root directory
PROD_DIR_PREFIX PROD_DIR_PREFIX product root directory prefix (area where all
or most product instances are maintained) product root directory prefix (area where all
or most product instances are maintained)
QUALIFIERS QUALIFIERS additional instance specification information
often used to indicate compilation options used by developer additional instance specification information
often used to indicate compilation options used by developer
SETUPS_DIR SETUPS_DIR location of setups.[c]sh files and other UPS initialization files location of setups.[c]sh files and other UPS initialization files
STATISTICS STATISTICS flag to record statistics for specified
products flag to record statistics for specified
products
TABLE_DIR TABLE_DIR location of table file location of table file
TABLE_FILE TABLE_FILE name of table file name of table file
@TABLE_FILE @TABLE_FILE entire path for the table file. entire path for the table file.
UPD_USERCODE_DIR UPD_USERCODE_DIR Directory where UPD configuration files are maintained Directory where UPD configuration files are maintained
UPS_DIR UPS_DIR location of ups directory (if not absolute
path, then taken relative to PROD_DIR, usually) location of ups directory (if not absolute
path, then taken relative to PROD_DIR, usually)
@UPS_DIR @UPS_DIR entire path to ups directory entire path to ups directory
VERSION VERSION product version product version

  23.11.5 ups list
Examples

  List all current
products

% ups list

  The simplest way to request a
listing of all the current products installed in your default UPS database is to use the ups list command
with no options or arguments. The per-product output spans a few
lines, though, and can be cumbersome, e.g.,:

DATABASE=/nusoft/app/externals 
    Product=allinea_tools    Version=v4_1_1    Flavor=Linux64bit
        Qualifiers=""    Chain=current

    Product=cetpkgsupport    Version=v1_05_03    Flavor=NULL
        Qualifiers=""    Chain=current

    Product=cmake    Version=v2_8_8    Flavor=Linux64bit+2.6-2.5
        Qualifiers=""    Chain=current

...

            Product=ups    Version=v5_0_2    Flavor=Linux+2
        Qualifiers=""    Chain=current

    Product=ups    Version=v5_0_2    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

    Product=ups    Version=v5_0_2    Flavor=Linux+2
        Qualifiers=""    Chain=current

  Use of the -K option with
the + argument,
e.g.,

% ups list -K+

  provides the same information
as the previous example, but condensed to one line per product:

"allinea_tools" "v4_1_1" "Linux64bit" "" "current" 
"cetpkgsupport" "v1_05_03" "NULL" "" "current" 
"cmake" "v2_8_8" "Linux64bit+2.6-2.5" "" "current" 
...
"ups" "v5_0_2" "Linux+2" "" "current" 
"ups" "v5_0_2" "Linux64bit+2" "" "current" 
"ups" "v5_0_2" "Linux+2" "" "current" 

  Instead of using the + argument to get the default fields, you can specify particular
fields:

% ups list -K product:version

  This command outputs a list of
product names and version numbers for all the current products
installed in your default UPS database, e.g.,:

"allinea_tools" "v4_1_1" 
"cetpkgsupport" "v1_05_03" 
"cmake" "v2_8_8" 
...
"ups" "v5_0_2" 
"ups" "v5_0_2" 
"ups" "v5_0_2" 

  List standard
information for default instance of product

% ups list nova

  This command requests the
standard output fields for the default instance of nova , using the formatted output:

DATABASE=/nusoft/app/externals 

DATABASE=/grid/fermiapp/products/common/db 
    Product=nova    Version=v0.1    Flavor=NULL
        Qualifiers=""    Chain=current

  Addition of the -K+ construction, e.g.,

% ups list -K+ nova

  requests the same information
as the previous example, but in condensed format:

"nova" "v0.1" "NULL" "" "current" 

  Using -a for all,
e.g.,

  List standard
information for all instances of product

% ups list -a git

  requests the standard output
fields for all instances of git , using the formatted output:

DATABASE=/nusoft/app/externals 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

DATABASE=/grid/fermiapp/products/common/db 
    Product=git    Version=v1_6_4a    Flavor=Linux+2
        Qualifiers=""    Chain="" 

    Product=git    Version=v1_8_0_1    Flavor=Linux+2
        Qualifiers=""    Chain=current

    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current
...

           Product=git    Version=v1_8_5_3    Flavor=Linxu+2.6-2.12
        Qualifiers=""    Chain="" 

  Use of the -K option with
the + argument,
e.g.,

% ups list -aK+ git

  requests the same information
as the previous example, but in condensed format ( -K+ ):

"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_6_4a" "Linux+2" "" "" 
"git" "v1_8_0_1" "Linux+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.5" "" "" 
"git" "v1_8_5_3" "Linux+2.6-2.5" "" "" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" "" "" 
"git" "v1_8_5_3" "Linxu+2.6-2.12" "" "" 

  List standard
information for all instances of product for your machine's
flavor

% ups list -a2K+ git

  To request information on all
instances of a product limited to the OS of your machine, you can
include the -f option (for
flavor), or enter a command like this one, where -a is for all, -2 is for the "level 2" designation of your machine's OS, and -K+ is for condensed output:

"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 

  List specific keywords
for a product

  If your installation has
multiple databases defined in $PRODUCTS, it is useful to include
the keyword for the database ( DB ) in the -K argument list, e.g.,

% ups list -aK+:DB git

  This example is similar to the
previous one, but the database path is included at the end:

"git" "v1_8_0_1" "Linux64bit+2" "" "current" "/nusoft/app/externals" 
"git" "v1_6_4a" "Linux+2" "" "" "/grid/fermiapp/products/common/db" 
"git" "v1_8_0_1" "Linux+2" "" "current" "/grid/fermiapp/products/common/db" 

  This example specifies particular
fields to be output with the -K option for
the default instance of the product

% ups list -K product:version git
"git" "v1_8_0_1" 
"git" "v1_8_0_1" 
"git" "v1_8_0_1" 

  List all keywords for a
product (long listing)

% ups list minos -l

  This command requests detailed
information ( -l for long
listing) about the default instance of the product. Administrative users may often need this level of
detailed information about a product. The -l option is not
valid with the -K option. The
output looks like this:

DATABASE=/grid/fermiapp/products/common/db 
    Product=minos    Version=v0.1    Flavor=NULL
        Qualifiers=""    Chain=current
        Declared="2013-08-16 18.16.17 GMT:2013-07-17 14.40.54 GMT" 
        Declarer="products:products" 
        Modified="2013-08-16 18.16.17 GMT:2013-07-17 14.40.54 GMT" 
        Modifier="products:products" 
        Home=/grid/fermiapp/products/common/db/../prd/project/v0_1/NULL
        No Compile Directive
        Authorized, Nodes=*
        UPS_Dir="ups" 
        Table_Dir="" 
        Table_File="project.table" 
        Archive_File="" 
        Description="" 
        Action=setup
            If( test -d /grid/fermiapp/products/${UPS_PROD_NAME}/prd/bootstrap_${UPS_PROD_NAME} )
            Execute( source `ups setup bootstrap_${UPS_PROD_NAME} -z /grid/fermiapp/products/${UPS_PROD_NAME}/db`, NO_UPS_ENV)
            Else()
            Execute( source `ups setup ${UPS_PROD_NAME} -z /grid/fermiapp/products/${UPS_PROD_NAME}/db`, NO_UPS_ENV)
            Endif( test -d /grid/fermiapp/products/${UPS_PROD_NAME}/prd/bootstrap_${UPS_PROD_NAME} )

  This gives a fairly long list.
It is often more convenient to use the -K option with a
list of keywords for the specific fields you need.

  Use "ups list -K" to
locate product root directory, table file and ups directory

  ups list -K can
be used to locate a product's root directory, table file, and ups directory when used
with the keywords corresponding to these quantities

  Compare the following three
commands and their output. UPS_DIR represents the location of the product's ups directory. If it is not an
absolute path, then it is taken relative to @PROD_DIR , if
specified (as shown in the second command). @UPS_DIR is the
absolute path.

% ups list -K @PROD_DIR git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux64bit-2" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux-2" 

% ups list -K UPS_DIR git
"ups" 
"ups" 
"ups" 

% ups list -K@UPS_DIR git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2/ups" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux64bit-2/ups" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux-2/ups" 

  Compare the following two
commands and their output. table_file represents only the name of the table file, not its path. @table_file is
the entire path for the table file. See section 29.4 Determination of ups Directory and Table File Locations for information on how UPS determines the table file directory.

% uups list -Ktable_file git
"git.table" 
"v1_8_0_1.table" 
"v1_8_0_1.table" 

% ups list -K@table_file git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2/ups/git.table" 
"/grid/fermiapp/products/common/db/git/v1_8_0_1.table" 
"/grid/fermiapp/products/common/db/git/v1_8_0_1.table" 

  Parse output from "ups
list -K" in perl

  Here we provide guidance on
parsing ups
list
output in perl , with all the appropriate quoting and spacing. The
following example first defines the file handle UPS_LIST_OUTPUT to contain the
piped output of the command $UPS_DIR/bin/ups list
-aK+
(where $UPS_DIR is
translated inside of perl via the $ENV{UPS_DIR} statement, which is the translation of the environmental variable UPS_DIR ). It then defines the array @fields , and parses the output into
a set of five variables.

open(UPS_LIST_OUTPUT, "| $ENV{UPS_DIR}/bin/ups list -aK+");while (<UPS_LIST_OUTPUT> ) {
# break into the array @fields:
@fields = m/\"((?:[^\"\\]|\\.)*)\"/g;
# then do things with $field[0] $field[1] ...
# (in this case,
# $field[0] = product name
# $field[1] = version
# $field[2] = flavor
# $field[3] = qualifiers (colon-separated list)# $field[4] = chains (colon-separated list)
}

  Say the output from your ups list
-K
command looks like this:

"ups" "v4_4" "Linux+2" "" "current" 

  then the @fields array contains the
variables:

$field[0] = ups
$field[1] = v4_4
$field[2] = Linux+2
$field[3] = 
$field[4] = current

  Alternatively, you could parse
the output this way:

($product, $version, $flavor, $qualifiers, $chains) = m/\"((?:[^\"\\]|\\.)*)\"/g;

  and then you'd have:

$product = ups
$version = v4_4
$flavor = Linux+2
$qualifiers = 
$chains = current

  Parsing output from "ups
list -K" in a sh script

  You can parse the output from a
command of the form ups list -K by
piping it into a " while loop" sh script. Here is an example; explanations follow the
code:

ups list -K... |
while read line
do
     eval set : $line
     shift
# now do things with $1 $2 $3... 
done

  As the condition of the while loop, the read line command reads the lines of output into the variable line . To get rid of the quotes, the loop runs eval set : $line on each line (this syntax ensures that the set command
actually sets the variables $1 , $2 , and so on, instead of setting
shell behavior in case the first argument starts with a dash). The shift that
follows then gets rid of the colon.

  23.12 ups modify

  The ups modify command allows you to manually edit any of the database product
files. It performs syntax and content validation before and after
the editing session.

  23.12.1 Command
Syntax

% ups modify [<options>] <product> [<version>]

  23.12.2 Commonly Used
Options

  See section 23.12.3 All Valid Options for descriptions of each option.

 
Table 23.12.2-a:Table 23.12.2-a:

-E
<editor>
-E
<editor>
-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-N
<fileName>
-N
<fileName>
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.12.3 All Valid
Options

 
Table 23.12.3-a:Table 23.12.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-A -A authorized nodes authorized nodes
-c -c current chain current chain
-d -d development chain development chain
-E
<editor>
-E
<editor>
Invokes the specified editor. If not given,
uses the editor specified by $EDITOR. If not set, uses vi by default. Invokes the specified editor. If not given,
uses the editor specified by $EDITOR. If not set, uses vi by default.
-f
<flavor>
-f
<flavor>
Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list. Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list.
-H
<flavor>
-H
<flavor>
Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list. Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-N
<fileName>
-N
<fileName>
Specifies file to be checked and edited Specifies file to be checked and edited
-p
"<description>"
-p
"<description>"
Specifies product description Specifies product description
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t test chain test chain
-T <path or
URL>
-T <path or
URL>
Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format.
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product Specifies the database(s) in which to look
for the product
-Z -Z Times the command Times the command

  23.12.4 More Detailed
Description

  ups modify performs the following steps (if you specify the file using -N ,
the menu will not appear):

  • presents menu of files
    that you can edit and asks you to either select one or quit
  • verifies
    pre-modification contents of file (runs ups verify )
  • starts up the editor
    given by -E
    <editor>
    or, if that is not specified, then $EDITOR,
    if set. If neither is specified, it starts up vi by default.
  • makes a copy of the file
    to be edited
  • pulls copy of file into
    the editor
  • after user exits the
    editor, runs ups verify on
    the edited file
  • if the validation
    succeeds, writes the new file over the old one and quits
  • if the validation does
    not succeed, provides informational messages, and quits
  • if no changes made to
    file, again presents menu of files

  Internal Processes

  • Bring up requested file
    in specified editor
  • Verify the pre-edited
    file
  • Verify the edited file
    before overwriting
  • Process MODIFY
    action
  • Execute the temp
    file

  23.12.5 ups modify
Example

% ups modify git v1_8_5_3 -N $MYDB/git/v1_8_5_3.version

Pre modification verification pass complete.

  In this example, we select the
version file (via -N ) for the
product git v1_8_5_3. Since -E is not given, UPS will use the editor set in $EDITOR, or vi if that variable is not set. First, UPS runs ups verify and
produces the output:

Pre modification verification pass complete.

  No errors were detected. The
version file is next displayed in the editor.

  1. To illustrate
    an unsuccessful validation, we add a bogus line:
TESTKEYWORD = value
and save and quit. %{font-weight: bold;color: #000000}UPS% returns the following messages, and we opt to save the erroneous change:

INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
Post modification verification pass complete.
Do you wish to save this modification [y/n] ? %{font-weight: bold;color: #000000}y% 
 %{font-weight: bold;color: #000000}UPS% quits, saving the file as we requested.
  1. To illustrate
    successful validation, we'll correct the error introduced above. We
    run the same ups modify command. UPS finds the error during the pre-edit validation:
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
Pre modification verification pass complete.
We remove the incorrect line from the version file, then save and quit. %{font-weight: bold;color: #000000}UPS% displays the following message, and we elect to save the change ( %{font-weight: bold;font-family: monospace}y% ):

Post modification verification pass complete.
Do you wish to save this modification [y/n] ? %{font-weight: bold;color: #000000}y% 
 %{font-weight: bold;color: #000000}UPS% quits, saving the file as requested.

  23.13 ups parent

  The ups parent command can be used to determine which products depend on the
specified product instance(s) as declared in the (local) database.
This command is useful when deciding whether a product instance can
be removed without causing problems for other products. If you need to look things
up frequently, you might want to run the command with the -a option, dump
the output to a file, and search in there.

  23.13.1 Command
Syntax

% ups parent [<options>] <product> [<version>]

  23.13.2 Commonly Used
Options

  See section 23.11.3 All Valid Options for descriptions of each option.

 
Table 23.13.2-a:Table 23.13.2-a:

-a -a
-f
<flavorList>
-f
<flavorList>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-K
<keywordList>
-K
<keywordList>
-l -l
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.13.3 All Valid Options

Table 23.13.3:Table 23.13.3:
-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-a -a Include all instances Include all instances
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-K -K keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN
-l -l Produce a long listing Produce a long listing
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n new chain new chain
-o -o old chain old chain
-q
<qualifierList>
-q
<qualifierList>
colon separated list of required or optional qualifiers
that are to be part of the instance colon separated list of required or optional qualifiers
that are to be part of the instance
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t test chain test chain
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.13.4 More Detailed
Description

  The ups parent command can be slow. The ups
parent
command runs:

% ups depend product version -f flavor -q qualifiers -H hostflavor

  for every product version -f flavor -q
qualfiers
and for every hostflavor mentioned in the
database. If you look things up frequently, we recommend that you
run:

% ups parent -a

  dump the output to a file, and
search in the file for the information you need.

  23.13.5 ups parent
Example

  If you want to know what
products depend on git , run:

% ups parent git
100% completed.  
git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__redmine v1_4_1 -f NULL -z /fnal/ups/db [via  -g current]

git v1_6_4 -f Linux+2 -z /fnal/ups/db
|__redmine v1_0_1 -f NULL -z /fnal/ups/db 
|__redmine v1_4_1 -f NULL -z /fnal/ups/db [via  -g current]

  23.14 ups start

  The ups start command is used to invoke appropriately configured products at
system boot time. This is used primarily for products that need to
load drivers, start daemons or perform other actions required at
boot time. This command is generally not run manually, rather it
gets executed from within a UPS control file.

  The ups stop command
(see section 23.15 ups stop ) is used to stop products that are started this
way.

  23.14.1 Command
Syntax

% ups start [<options>] <product> [<version>]

  23.14.2 Commonly Used
Options

  See section 23.14.3 All Valid Options for descriptions of each option.

 
Table 23.14.2-a:Table 23.14.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-v ( vvv ) -v ( vvv )
-w -w
-z
<databaseList>
-z
<databaseList>

|

  23.14.3 All Valid
Options

 
Table 23.14.3-a:Table 23.14.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-w -w Stops the product first, then restarts
it Stops the product first, then restarts
it
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.14.4 More Detailed
Description

  Please see Chapter 15: Automatic UPS Product Startup and Shutdown for a
detailed description of the use of the ups start command. In brief, it covers:

  • Configuring your machine
    to allow automatic startup/shutdown
  • Installing a UPS product to start and/or stop automatically, for which
    you need to:
    • Determine if auto
      start/stop feature is enabled
    • Determine if product is
      appropriate for autostart
    • Edit control
      file(s)
    • Restart the system

  Internal Processes

  • Check node
    authorization
  • If necessary, process
    STOP action
  • Process START
    action
  • Execute the temp
    file

  23.14.5 ups start
Examples

  Run the command
interactively

  This command first stops
( -w )
the default instance of the product apache , and then restarts it:

% ups start -w apache

  It prints to screen messages of
the format:

Stopping Apache server for fnkits.fnal.gov on port 8000Stopping Apache server for fnkits.fnal.gov on port 8000 account updadmin

  Run the command from a
control file

  This command starts the default
instance of the product ObjectCenter for the flavor Linux, and requests verbose
output ( -v ).

% ups start -v -f Linux ObjectCenter

  If the logon id is root , the line in the control file may look like:

ups start -v -f Linux ObjectCenter

  If the logon id is other than root , the line in the control file must look like:

/bin/su - products -c "ups start -v -f Linux ObjectCenter" 

  23.15 ups stop

  The ups stop command
is used to stop appropriately configured products at system
shutdown. This command is generally not run manually, rather it
gets executed from within a UPS control file, and operates on products that were invoked
using ups
start
(see section 23.14 ups start ). Typically, these products are ones which
need to load drivers, start daemons or perform other actions
required at boot time.

  23.15.1 Command
Syntax

% ups stop [<options>] <product> [<version>]

  23.15.2 Commonly Used
Options

  See section 23.15.3 All Valid Options for descriptions of each option.

 
Table 23.15.2-a:Table 23.15.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-v ( vvv ) -v ( vvv )
-z
<databaseList>
-z
<databaseList>

|

  23.15.3 All Valid
Options

 
Table 23.15.3-a:Table 23.15.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.15.4 More Detailed
Description

  Please see Chapter 15: Automatic UPS Product Startup and Shutdown for a
detailed description of the use of the ups stop command. In brief, it covers:

  • Configuring your machine
    to allow automatic startup/shutdown
  • Installing a UPS product to start and/or stop automatically, for which
    you need to:
    • Determine if auto
      start/stop feature is enabled
    • Determine if product is
      appropriate for autostart
    • Edit control
      file(s)
    • Restart the system

  Internal Processes

  • Check node
    authorization
  • Process STOP
    action
  • Execute the temp
    file

  23.15.5 ups stop
Examples

  Run the command
interactively

  This command stops the default
instance of the product apache :

% ups stop apache

  It prints to screen a message
of the format:

Stopping Apache server for fnkits.fnal.gov on port 8000

  Run the command from a
control file

  This command stops the default
instance of the product ObjectCenter for the flavor Linux, and requests verbose
output ( -v ).

% ups stop -v -f Linux ObjectCenter

  If the logon id is root , the line in the control file may look like:

ups stop -v -f Linux ObjectCenter

  If the logon id is other than root , the line in the control file must look like:

/bin/su - products -c "ups stop -v -f Linux ObjectCenter" 

  23.16 ups tailor

  For any product instance whose
table file includes a TAILOR action, the ups tailor command must be run manually at product installation time after the
product is declared to the database in order to execute this
action. A TAILOR action typically includes installation functions
which require input from the installer.

  23.16.1 Command
Syntax

% ups tailor [<options>] <product> [<version>]

  23.16.2 Commonly Used
Options

  See section 23.16.3 All Valid Options for descriptions of each option.

 
Table 23.16.2-a:Table 23.16.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-v ( vvv ) -v ( vvv )
-z
<databaseList>
-z
<databaseList>

|

  23.16.3 All Valid
Options

 
Table 23.16.3-a:Table 23.16.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-K
<keywordList>
-K
<keywordList>
Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )
-. -. shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace} shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace}

  23.16.4 More Detailed
Description

  Tailoring is the aspect of the
product implementation that requires input from the product
installer (e.g., specifying the location of hardware devices for a
software driver package). If the product requires tailoring, a file
is usually supplied in the format of an interactive executable
(script or compiled binary), and it is run via a function under the
ACTION=TAILOR line in the table file. Configure, tailor and other
supplemental installation scripts are usually maintained in the
product's $<PRODUCT>_DIR/ups directory.
You must explicitly tailor the product instance using the UPS command ups tailor ;
tailoring is not performed automatically.

  Tailoring is generally allowed
on any node of a cluster, however we strongly recommend that you
perform any node-specific tailoring from that node, or
flavor-specific tailoring from a node of that flavor to avoid
mismatches.

  Internal Processes

  • Check node
    authorization
  • Process TAILOR
    action
  • Execute the temp
    file

  23.16.5 ups tailor
Example

  As an example, we show the
tailor process for the product apache :

% ups tailor apache
Current configuration nicknames are:
kits    kits8k
You can:
    a)dd a new server configuration
    q)uit the tailor script
Which would you like? [aq]? a
Webserver alias/name (e.g. www-xx.fnal.gov)? www-demo.fnal.gov
Webserver nickname [demo]? 
Webserver port number [80]? 
Webserver effective user-id [wwwsrv]? 
Webserver effective group-id [www]? 
Webserver admin id [wwwadm]? 
Mail address for admin stuff [mengel@fnal.gov]? demo-admin@fnal.gov
Directory for CGI executables [/fnal/www/demo/cgi-bin]?Directory /fnal/www/demo/cgi-bin doesn't exist, make it [y]? y
Root of served files [/fnal/www/demo/html]? 
Directory /fnal/www/demo/html doesn't exist, make it [y]? yRaw Log file directory [/var/adm/www/demo]? /tmp/demoLog file Summary directory [/fnal/www/demo/html/logs]?Directory /fnal/www/demo/html/logs doesn't exist, make it [y]? y
Current configuration nicknames are:
demo    kits    kits8k
You can:
    a)dd a new server configuration
    q)uit the tailor script
Which would you like? [aq]? q

  23.17 ups touch

  The ups touch command changes the values of the keywords MODIFIED and MODIFIER in
the version file to the current time and the current user,
respectively.

  If you make any changes to a
product's database files by hand (e.g., not via ups modify ), you
should run ups touch afterwards.
You can also run it to prevent an update if you choose to run upd
update
on several product instances at a time.

  23.17.1 Command
Syntax

% ups touch [<options>] <product> [<version>]

  23.17.2 Commonly Used
Options

  See section 23.17.3 All Valid Options for descriptions of each option.

 
Table 23.17.2-a:Table 23.17.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (with a valid number) Or a valid number or -H (with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.17.3 All Valid
Options

 
Table 23.17.3-a:Table 23.17.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-z
<databases>
-z
<databases>
Specifies the database(s) to use Specifies the database(s) to use
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )

  23.17.4 ups touch
Example

  To illustrate this command, we
first run a ups list showing
the modified date/time and the modifier(s) for a product:

% ups list prod1 -aKproduct:modified:modifier
"prod1" "2013-09-08 21.44.04 GMT:2013-09-08 21.38.23 GMT" "olduser:olduser" 

  Now run ups touch to
change these values:

% ups touch prod1

  And verify that they have
changed, by rerunning the ups list command:

% ups list prod1 -aKproduct:modified:modifier
"prod1" "2013-11-19 18.43.00 GMT:2013-09-08 21.38.23 GMT" newuser:olduser" 

  23.18 ups
unconfigure

  For any product instance whose
table file includes an UNCONFIGURE action, the ups unconfigure command executes this action. An UNCONFIGURE action usually
includes functions that reverse, approximately or fully, the
functions run by the CONFIGURE action. The ups unconfigure command gets run by default by ups undeclare when the product is removed from a database (see section 23.19 ups undeclare , in particular the -C option), but
can be run manually as needed.

  23.18.1 Command
Syntax

% ups unconfigure [<options>] <product> [<version>]

  23.18.2 Commonly Used
Options

  See section 23.18.3 All Valid Options for descriptions of each option.

 
Table 23.18.2-a:Table 23.18.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.18.3 All Valid
Options

 
Table 23.18.3-a:Table 23.18.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )

  23.18.4 More Detailed
Description

  A product's configuration may
involve creating links to the product root directory from other
areas (see section 16.1.3 Third-Party Products Requiring a Hard-Coded Path ). If
the area is not identical for each node accessing the UPS database in which the product instance has been declared
(i.e., same path but separate areas), then the ups configure command needs to be run manually on each node that mounts a unique
area. Similarly, when removing such a product from a database, you
will need to run the ups unconfigure command manually on each node. If you are not sure whether you need
to unconfigure a product instance on each node, look through the
ACTION=UNCONFIGURE steps in the table file to see what they do.

  Internal Processes

  • Check node
    authorization
  • Process the UNCONFIGURE
    action
  • Execute the temp
    file

  23.18.5 ups unconfigure
Example

  The sample command runs the UNCONFIGURE action in the table file
associated with the product prod1 . If that action is
not present, it undoes all the reversible functions included under
the CONFIGURE action, by default.

% ups unconfigure prod1 v5 -f Linux+2

  This command should take care
of the "unconfiguration" on all the machines of flavor Linux+2 in the cluster. A
command like this, but with the appropriate flavor, must be run for
each machine flavor represented in the cluster.

  23.19 ups undeclare

  The ups undeclare command is used for two separate purposes:

  1. to remove an
    instance from a database (and optionally remove its product root
    directory); the information that gets removed includes:
    • the version file, or the
      portion of the version file, that pertains to the instance
    • any chain files, or the
      portions of any chain files, that pertain to the instance
    • to remove a
      chain from an instance

  23.19.1 Command
Syntax

  For removing an
instance

% ups undeclare <flavor_option> [<other_options>] <product> \ 
<version>

  For removing a
chain

% ups undeclare <chain_option> [<other_options>] <product>

  23.19.2 Commonly Used
Options

  See section 23.18.3 All Valid Options for descriptions of each option.

  For removing an
instance

 
Table 23.19.2-a:Table 23.19.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number of -H (with a valid number) Or a valid number of -H (with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-y -y
-Y -Y
-z
<databaseList>
-z
<databaseList>

|

  For removing a
chain

 
Table 23.19.2-b:Table 23.19.2-b:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (with a valid number) Or a valid number or -H (with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.19.3 All Valid
Options

  Valid only for removing
an instance (not for removing a chain)

 
Table 23.19.3-a:Table 23.19.3-a:

-y -y Deletes product root directory, provides
confirmation prompt Deletes product root directory, provides
confirmation prompt
-Y -Y Deletes product root directory, does not
provide confirmation prompt Deletes product root directory, does not
provide confirmation prompt

  Valid for both
functions

 
Table 23.19.3-b:Table 23.19.3-b:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-C -C When removing a product: Prevents execution
of the UNCONFIGURE action When removing a product: Prevents execution
of the UNCONFIGURE action When removing a chain: Prevents execution of
the corresponding "unchain" action When removing a chain: Prevents execution of
the corresponding "unchain" action
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databases>
-z
<databases>
Specifies the database(s) to use Specifies the database(s) to use
-Z -Z Times the command Times the command

  23.19.4 More Detailed
Description

  Removing a Product
Instance

  % %{font-weight: bold;color: #000000}Using ups undeclare is the recommended procedure for removing product instances.
Removing them manually does not ensure that all the files get
deleted or that chains get updated properly, which can lead to a
fragmented products area.

  To undeclare a product
instance, you must specify the version of the instance, not its chain , in the ups undeclare command. Specifying the chain removes only that chain, not the instance
itself.
When an instance gets "undeclared", all information
pertaining to it is removed from the UPS database in question; this includes:

  • the version file, or the
    portion of the version file, that pertains to the instance
  • any chain files, or the
    portions of any chain files, that pertain to the instance

  You can also opt to remove the
product instance's directory tree starting from its root directory.
To do so, use one of the options -y or -Y ( -y queries you for confirmation, -Y does
not).

  Before removing anything, you
should find out if any other products have the product instance in
question declared as a dependency. If so, you may want to reconsider removing
it. Removal of the product instance may affect the operation of its
parent products.

  We recommend always including a
flavor option if you have a multi-flavor database.

  The ups undeclare command executes ups unconfigure by default (the UNCONFIGURE process can be suppressed by using the -C option, however normally you want this process to execute).

  Special case: If a product has a CONFIGURE action that modifies
files outside of its product root directory, and if this instance
is used by more than one node, flavor or file system, then you may
need to run ups undeclare or ups
unconfigure
on all of the nodes before removing the product
files on any node. Check the product's table file.

  Removing a Chain from an
Instance

  To remove a chain, include the
chain specification in the ups undeclare command, but do not include the version. Including both the chain
and version is bound to be either redundant or incompatible, and
may result in removing the product declaration! We recommend always
including the -f
<flavor>
option if you have a multi-flavored
database.

  Internal Processes

  • Find database to
    use
  • If necessary process
    all appropriate `UNCHAIN' actions
  • Process the UNCONFIGURE
    action
  • Process the UNDECLARE
    action
  • If necessary delete the
    product's home area
  • Execute the temp
    file

  23.19.5 ups undeclare
Examples

  Undeclare an
instance

% ups undeclare -f Linux+2 tcl v8 -y

  In this example, we undeclare
and remove current instance (by default) of the product tcl v8 for the flavor Linus+2 ( -f option) from
the default database. Notice that the version is included for
instance identification as required. We opt to remove the product
root directory after query (lowercase -y option):

Product home directory -
        /export/home/t1/aheavey/upsII/products/tcl/v8/Delete this directory? %{font-weight: bold;color: #000000}y% 

  We respond "y" for yes. To
respond no, we would enter "n".

  Undeclare a chain

% ups undeclare -c ximagetools -f NULL

  In this command, we remove the
"current" chain ( -c option) from
the instance of ximagetools declared as current for the flavor NULL
( -f option). Notice that the version is not included!

  If multiple flavor/qualifier pairs share the chain file in question
(in which case you need to specify the flavor/qualifier information
on the command line), only the portion of the chain file pertaining
to the specified instance will get removed; the file itself will
not be deleted.

  23.20 ups verify

  The ups verify command checks the integrity of the database files for the
specified product(s), and lists any errors and inconsistencies that
it finds.

  The ups verify command gets run by ups modify before and after file editing (see section 23.12 ups modify ). ups verify can
also be run manually as needed.

  23.20.1 Command
Syntax

% ups verify [<options>] [<product>] [<version>]

  23.20.2 Commonly Used
Options

  See section 23.20.3 All Valid Options for descriptions of each option.

 
Table 23.20.2-a:Table 23.20.2-a:

-f
<flavorList>
-f
<flavorList>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.20.3 All Valid
Options

 
Table 23.20.3-a:Table 23.20.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-a -a Verifies files for all instances that match
the other options given on command line Verifies files for all instances that match
the other options given on command line
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavorList>
-f
<flavorList>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavorList>
-H
<flavorList>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )

  23.20.4 ups verify
Example

% ups verify -z $MYDB prod1

  For this example, we have given
an erroneous value to the TABLE_FILE keyword in the version file
for this product. The command output shows:

ERROR: No instance matches were made between theversion file (/home/t1/aheavey/upsII/declared/prod1/v1_0.version) and the
table file (v1_1.table) for flavor (NULL) and qualifiers ()ERROR: Possible UPS database (/home/t1/aheavey/upsII/declared) corruption in pro
duct 'prod1'.
ERROR: No instance matches were made between the chain file (/home/t1/aheavey/up
sII/declared/prod1/current.chain) and the version file (v1_0.version)
ERROR: Possible UPS database (/home/t1/aheavey/upsII/declared) corruption in pro
duct 'prod1'.

 

TOC PREV NEXT

This page last revised May
2014

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

Chapter Contents

Chapter 23: UPS Command Reference
   23.1 setup
     23.1.1 Command
Syntax

     23.1.2 Commonly Used
Options

     23.1.3 All Valid
Options

     23.1.4 More Detailed
Description

     23.1.5 setup
Examples

   23.2 unsetup
     23.2.1 Command
Syntax

     23.2.2 All Valid
Options

     23.2.3 More Detailed
Description

     23.2.4 unsetup
Examples

   23.3 ups configure
     23.3.1 Command
Syntax

     23.3.2 Commonly Used
Options

     23.3.3 All Valid
Options

     23.3.4 More Detailed
Description

     23.3.5 ups configure
Examples

   23.4 ups copy
     23.4.1 Command
Syntax

     23.4.2 Commonly Used
Options

     23.4.3 All Valid
Options

     23.4.4 Options Valid with
-G

     23.4.5 More Detailed
Description

     23.4.6 ups copy
Examples

   23.5 ups declare
     23.5.1 Command
Syntax

     23.5.2 Commonly Used
Options

     23.5.3 All Valid
Options

     23.5.4 More Detailed
Description

     23.5.5 ups declare
Examples

   23.6 ups depend
     23.6.1 Command
Syntax

     23.6.2 Commonly Used
Options

     23.6.3 All Valid
Options

     23.6.4 ups depend
Examples

   23.7 ups exist
     23.7.1 Command
Syntax

     23.7.2 Commonly Used
Options

     23.7.3 All Valid
Options

     23.7.4 More Detailed
Description

     23.7.5 ups exist
Examples

   23.8 ups flavor
     23.8.1 Command
Syntax

     23.8.2 Commonly Used
Options

     23.8.3 All Valid
Options

     23.8.4 More Detailed
Description

     23.8.5 ups flavor
Examples

   23.9 ups get
     23.9.1 Command
Syntax

     23.9.2 All valid
options

     23.9.3 ups get
Example

   23.10 ups help
     23.10.1 ups help
Example

   23.11 ups list
     23.11.1 Command
Syntax

     23.11.2 Commonly Used
Options

     23.11.3 All Valid
Options

     23.11.4 More Detailed
Description

     23.11.5 ups list
Examples

   23.12 ups modify
     23.12.1 Command
Syntax

     23.12.2 Commonly Used
Options

     23.12.3 All Valid
Options

     23.12.4 More Detailed
Description

     23.12.5 ups modify
Example

   23.13 ups parent
     23.13.1 Command
Syntax

     23.13.2 Commonly Used
Options

     23.13.3 All Valid
Options

     23.13.4 More Detailed
Description

     23.13.5 ups parent
Example

   23.14 ups start
     23.14.1 Command
Syntax

     23.14.2 Commonly Used
Options

     23.14.3 All Valid
Options

     23.14.4 More Detailed
Description

     23.14.5 ups start
Examples

   23.15 ups stop
     23.15.1 Command
Syntax

     23.15.2 Commonly Used
Options

     23.15.3 All Valid
Options

     23.15.4 More Detailed
Description

     23.15.5 ups stop
Examples

   23.16 ups tailor
     23.16.1 Command
Syntax

     23.16.2 Commonly Used
Options

     23.16.3 All Valid
Options

     23.16.4 More Detailed
Description

     23.16.5 ups tailor
Example

   23.17 ups touch
     23.17.1 Command
Syntax

     23.17.2 Commonly Used
Options

     23.17.3 All Valid
Options

     23.17.4 ups touch
Example

   23.18 ups unconfigure
     23.18.1 Command
Syntax

     23.18.2 Commonly Used
Options

     23.18.3 All Valid
Options

     23.18.4 More Detailed
Description

     23.18.5 ups unconfigure
Example

   23.19 ups undeclare
     23.19.1 Command
Syntax

     23.19.2 Commonly Used
Options

     23.19.3 All Valid
Options

     23.19.4 More Detailed
Description

     23.19.5 ups undeclare
Examples

   23.20 ups verify
     23.20.1 Command
Syntax

     23.20.2 Commonly Used
Options

     23.20.3 All Valid
Options

     23.20.4 ups verify
Example

  Chapter 23: UPS Command
Reference

  This chapter contains full
usage information on all the UPS commands. In particular, for each command you will
find:

  • a statement of the
    purpose and/or function of the command
  • the command syntax
  • a listing of commonly
    used options, without descriptions
  • a listing of all valid
    options, with command-specific descriptions
  • (as needed) a section
    called "Options Valid with -G"
  • (as needed) a section
    called "More Detailed Description" which typically includes:
    • detailed
      command-specific usage information
    • information on
      environment variables that affect execution of the command or are
      affected by it
    • a list of internal
      functions the command performs (if more extensive than suggested by
      the command description)
  • command examples

  23.1 setup

  Issue the setup command
for a product prior to invoking the product. The setup command
performs the necessary operations in your login environment to make
an installed, declared product instance accessible to you.
Typically, the operations include modifying environment variables
or adding to your $PATH.

  23.1.1 Command
Syntax

% setup [<options>] <product> [<version>]

  23.1.2 Commonly Used
Options

  See section 23.1.3 All Valid Options for descriptions of each option.

 
Table 23.1.2-a:Table 23.1.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.1.3 All Valid
Options

 
Table 23.1.3-a:Table 23.1.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-B <depProdName>=
"<options>"
-B <depProdName>=
"<options>"
Specifies options to prepend to the setupRequired line (in
table file) for the dependent product <depProdName> Specifies options to prepend to the setupRequired line (in
table file) for the dependent product <depProdName>
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-e -e Sets $UPS_EXTENDED (to the value 1 ). This is
useful for SETUP actions which call scripts. Sets $UPS_EXTENDED (to the value 1 ). This is
useful for SETUP actions which call scripts.
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores dependencies, sets up just specified
top-level product Ignores dependencies, sets up just specified
top-level product
-k -k Prevents execution of unsetup files prior to
(subsequent) setup Prevents execution of unsetup files prior to
(subsequent) setup
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> .
This is useful for SETUP actions which call scripts. Sets the value of $UPS_OPTIONS to <flags> .
This is useful for SETUP actions which call scripts.
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-R -R Sets up only the required (non-optional)
dependencies. Sets up only the required (non-optional)
dependencies.
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Specifies product instance chained to
"test" Specifies product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups (relative to the product root directory) Specifies location of ups directory; default value is ups (relative to the product root directory)
-v ( vv ) -v ( vv ) Prints out extra debugging information.
(-vv for more, -vvv for even more) Prints out extra debugging information.
(-vv for more, -vvv for even more)
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup ) Times the command (does not include time for
sourcing of temp file for setup )
-. -. shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace} shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace}

|

h4.

The flavor options
p<>.   Flavor may be specified using -f ,
using -H by itself or
in combination with any of the valid numbers or just using one of the valid
numbers.
These options are not valid with each other (except -H with a number
option).

  If a dependency is specified
in the table file with a particular flavor, the flavor specified on
the command line is ignored for that dependency.

 
Table 23.1.3-b:Table 23.1.3-b:

-f
<flavor>
-f
<flavor>
Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list. Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list.
-H
<flavor>
-H
<flavor>
Useful to set the host to a different type, such as when
installing products for another platform. Can be used in combination
with the valid flavor numbers, 0, 1, 2, ...
p<>. If it is used without an accompanying
number, UPS finds the best match instance for the specified flavor
family. (The first one that matches in the ups flavor -l command.)
Useful to set the host to a different type, such as when
installing products for another platform. Can be used in combination
with the valid flavor numbers, 0, 1, 2, ...
p<>. If it is used without an accompanying
number, UPS finds the best match instance for the specified flavor
family. (The first one that matches in the ups flavor -l command.)
-0 -0 Specifies flavor for operating system generic to NULL. {font-weight: bold;font-family: monospace} Specifies flavor for operating system generic to NULL. {font-weight: bold;font-family: monospace}
-1, -2, -3, -4, -5 -1, -2, -3, -4, -5 Specifies flavor for operating
system generic, starting with basic OS, and adding details with each
increase in number for Basic OS + version + release + patch + build. Specifies flavor for operating
system generic, starting with basic OS, and adding details with each
increase in number for Basic OS + version + release + patch + build.
(no number) (no number) Specifies flavor for operating system to the highest
detail defied, basic OS + version + release + patch + build. Specifies flavor for operating system to the highest
detail defied, basic OS + version + release + patch + build.

  23.1.4 More Detailed
Description

  In general, UPS products require that the setup command be
issued on a product instance before invoking it (unless it is a
dependent product of one that is already setup). The setup
processes are intended to make the appropriate changes to the user's
software environment to make the requested product
available for use.

  Only one instance of a product
can be setup at a time. Each time you run setup on an
additional instance of the same product, the previously active
instance is automatically unsetup first.

  Internal Processes

  • Check node
    authorization
  • If necessary, process
    UNSETUP action
  • Process SETUP
    action
  • Source the temp
    file

  Environment Variables
Set by Default During setup

  When an instance is setup,
either or both of the two environment variables
$<PRODUCT>_DIR and $SETUP_<PRODUCT> may get defined. By
default, both do.
$<PRODUCT>_DIRpoints to the root directory of the product instance selected
by the setup command$SETUP_<PRODUCT>a string containing all the information that the unsetup command
needs in order to identify the instance when it is time to remove
access to the product
p<>.   In both of them,
<PRODUCT> is the name of the product in upper case. Using
the product upd (on the fermicloud050) as an example:

% setup upd
% echo $UPD_DIR
/fnal/ups/db/../prd/upd/v4_8_0/NULL
% echo $SETUP_UPD
upd v4_8_0 -f NULL -z /fnal/ups/db

  Use of the
$SETUP_<PRODUCT> Variable by unsetup

  unsetup uses the
environment variable $SETUP_<PRODUCT>, by default, to
determine which instance to unsetup. If this variable was not set during product setup (i.e., the setup default
functions were not run, or setupEnv() was not run), then when you run unsetup , you
must specify on the command line which instance to unsetup; running
simply unsetup
<product>
causes no action to be taken. See Use of the $SETUP_<PRODUCT> Variable under section 23.2 unsetup for more information regarding the unsetup command.

  23.1.5 setup
Examples

  In the following examples, when we say that all dependencies of a
product get set up, we mean all except optional dependencies that
are unavailable.

  Setup default instance
of product

% setup git

  This sets up the current
instance of the product git for the best match flavor of your OS. If the product
has any dependencies, they get setup too, by default.

% setup -v git

  This command sets up the same
instance as above, but displays verbose information (usually used
for debugging, but useful to see what's going on). If any file that
is "opened for read" does not exist, you'll see ERROR at the end of the line. This
is often but not always a fatal error. The output looks like
this:

UPSMAT: Searching UPS database - /fnal/ups/db
UPSFIL: /fnal/ups/db/.upsfiles/dbconfig - Open file for read
UPSFIL: /fnal/ups/db/.upsfiles/dbconfig - Read 6 item(s)
UPSMAT: Looking for Product = git
UPSMAT: Matching with Chain - current
UPSFIL: /fnal/ups/db/git/current.chain - Open file for read
UPSFIL: /fnal/ups/db/git/current.chain - Read 2 item(s)
UPSMAT:  get_instance: flavor Linux64bit+2.6-2.12 quals
Found one!
First post!
UPSMAT: Found 1 instances in /fnal/ups/db/git/current.chain
UPSMAT: Matching with Version v1_8_5_3 in Product git
UPSMAT: Using Flavor = Linux64bit+2.6-2.12, and Qualifiers =
(and much more)

  Restrict the setup of
dependent products

% setup -R ruby

  Use of the -R option sets
up the specified product and its required dependencies only.

% setup -j ruby

  Use of the -j option sets
up only the specified product; none of its dependencies get
setup.

  Setup a chained instance
(other than the default "current")

% setup -t prod1
% setup -g test prod1

  Either of these commands sets
up the instance of prod1 chained to "test" (for the default flavor). To setup any
chained instance other than current, include the chain flag in the
command.

  Setup a product
specifying its version

% setup prod1 v5_23a

  This command sets up version
v5_23a of prod1 whether or not it has a chain. Run a ups list command
to get the version information.

  Setup a product declared
with qualifiers

% setup -q BUILD prod1

  This command sets up the
current instance of prod1 for the operating system on which you're working,
along with its build dependencies (assuming the qualifier BUILD has
been implemented in the product files in the standard way, see
section 17.2.3 Products Requiring Build (In-House and
Third-Party)
).

  Remember that qualifiers are case-sensitive.

  Setup a product and
activate extended functionality

  To setup the instance of
product prod1 chained to development, and all of prod1 's dependencies, and to activate extended setup
actions, enter:

% setup -d -e prod1

  The -e option sets
$UPS_EXTENDED on for prod1 and for any of its UPS product requirements that were declared with the -e option. This is used to activate any extended functionality the
product provider may have included in the setup action for this
instance (e.g., defining extra environment variables).

  23.2 unsetup

  The unsetup command
makes the specified product no longer available for use. It undoes
the changes made to the environment by setup . You may
need to explicitly unsetup a UPS product if you are short on environment variable space
and want to get rid of extra environment variables or shorten the
$PATH variable length; otherwise you typically don't need to run
this command.

  23.2.1 Command
Syntax

% unsetup [<options>] <product> [<version>]

  23.2.2 All Valid
Options

  Typically, this command is
issued with no options.

 
Table 23.2.2-a:Table 23.2.2-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-e -e Sets $UPS_EXTENDED (to the value 1 ). Sets $UPS_EXTENDED (to the value 1 ).
-f
<flavor>
-f
<flavor>
Described in "The flavor
options"
. Described in "The flavor
options"
.
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores dependencies, runs unsetup on just
on top level product Ignores dependencies, runs unsetup on just
on top level product
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<options>"
-O
"<options>"
Sets the value of $UPS_OPTIONS to <options> . Sets the value of $UPS_OPTIONS to <options> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
qualifiers : colon separated list of required or optional qualifiers
that are to be part of the instance qualifiers : colon separated list of required or optional qualifiers
that are to be part of the instance
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vv ) -v ( vv ) Prints out extra debugging information, vv for more, vvv for more. Prints out extra debugging information, vv for more, vvv for more.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which the
product(s) are declared Specifies the database(s) in which the
product(s) are declared
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )
shorthand for -r `pwd` -M ups -m ${UPS_PRODUCT}.table shorthand for -r `pwd` -M ups -m ${UPS_PRODUCT}.table

  23.2.3 More Detailed
Description

  unsetup is
intended to undo the changes to your software environment made
during product setup. It makes the product no longer available for
use. You may need to explicitly unsetup a UPS product if you are short on environment variable space
and want to get rid of extra environment variables or shorten the
$PATH variable length. Unsetup gets done automatically for you when
you setup a different instance of the same product.

  When you no longer need to
access a product, in most cases you can simply type:

% unsetup <product>

  for example:

% unsetup prod1

  Sometimes this isn't
sufficient. The $SETUP_<PRODUCT> variable governs the
behavior, as described below.

  Use of the
$SETUP_<PRODUCT> Variable

  unsetup uses the
environment variable $SETUP_<PRODUCT>, by default, to
determine which instance to unsetup. If this variable was not set during product setup (i.e., the setup default
functions were not run, or setupEnv() was not run), then you must specify on the
command line which instance to unsetup; running simply unsetup
<product>
causes no action to be taken.

  If $SETUP_<PRODUCT> has
been set (the usual case), it is best to run unsetup with no
options (except possibly -j as discussed
below). If any instance-identifying information besides product
name is specified on the unsetup command
line, this information gets ignored.

  Behavior of unsetup for
Product Dependencies

  The behavior of unsetup as
regards product dependencies depends upon a couple of factors:

  • whether an UNSETUP
    action exists in the main product's table file
  • whether
    $SETUP_<PRODUCT> has been defined for the product
    dependency

  If ACTION=UNSETUP is defined
for the main product, then:

  1. if it includes
    the function unsetupRequired for the dependency with no instance-identifying information (e.g., unsetupRequired
    (<dep_product>)
    only; no options or version), and if
    $SETUP_<PRODUCT> is defined for the dependency, unsetup will be
    run on the instance identified by $SETUP_<PRODUCT>.
  2. if it includes
    the function unsetupRequired for the dependency with no instance-identifying information (e.g., unsetupRequired
    (<dep_product>)
    only; no options or version), and if
    $SETUP_<PRODUCT> is not defined for the dependency, no unsetup will be
    performed for the dependency.
  3. if it includes
    the function unsetupRequired for the dependency with some instance-identifying information
    (e.g., unsetupRequired -q
    "build" <dep_product>
    ), then unsetup is run
    on this specified instance of the product dependency; if
    $SETUP_<PRODUCT> is defined for the dependency, it is
    ignored.

  If ACTION=UNSETUP is not defined for the main product, then:

  1. if
    $SETUP_<PRODUCT> is defined for the product dependency, then unsetup will be
    run on the instance identified by $SETUP_<PRODUCT>.
  2. if
    $SETUP_<PRODUCT> is not defined for the dependency, no unsetup will be
    performed for the dependency.

  If you use the -j option in the unsetup command
of the main product, only the main product gets unsetup; its
product dependencies are left untouched.

  Internal Processes

  • Check node
    authorization
  • Process UNSETUP
    action
  • Source the temp
    file

  The UNSETUP default functions
are to undo the default SETUP functions (i.e., unset
$<PRODUCT>_DIR and $SETUP_<PRODUCT>).

  Note: If there is no UNSETUP
action, then unsetup undoes
everything done in SETUP action. However, if SETUP includes
non-reversible functions, these cannot be undone by unsetup .

  23.2.4 unsetup
Examples

% unsetup lxr

  This command unsets the product lxr . When you no longer need to access a product, in most
cases you can simply use the product name to identify it.

% unsetup -j ruby

  The -j option in
this command causes UPS to unsetup the product, while leaving all its dependencies setup.

  23.3 ups configure

  For any product instance whose
table file includes a CONFIGURE action, the ups configure command executes this action. A CONFIGURE action usually includes
functions to construct symbolic links, copy files, or perform
automatic local customization of the product. The ups configure command gets run by default by ups declare when
the product is initially declared to a database (see section 23.5 ups declare , in particular the -C option), but
can be run manually as needed (e.g., on nodes of different
flavors).

  23.3.1 Command
Syntax

% ups configure [<options>] <product> [<version>]

  23.3.2 Commonly Used
Options

 
Table 23.3.2-a:Table 23.3.2-a:

-f
<flavor>
-f
<flavor>
A valid number or -H (alone or with a valid number) A valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
colon separated list of required or optional qualifiers
that are to be part of the instance
-z
<databaseList>
-z
<databaseList>
database : use this database to get instance information
database : use this database to get instance information

|

  23.3.3 All Valid
Options

 
Table 23.3.3-a:Table 23.3.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )
. . shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table

  23.3.4 More Detailed
Description

  Installation/configuration
procedures that can be completely automated are typically collected
in the table file in a CONFIGURE action ( actions are described in Chapter 34: Actions and ACTION Keyword Values ), or in a script
called configure which
is called from the table file. The configuration may involve
creating links to the product root directory from other areas. If
the area is not identical for each machine flavor accessing the UPS database in which the product instance has been declared
(i.e., the same path but separate areas), then you will need to run
the ups
configure
command manually once per flavor, on a node of
that flavor. If each node mounts a unique area, you generally have
to run special commands (e.g., ups install , ups
initialize
, etc.) that are documented in the product's INSTALL_NOTE file. If
you are not sure whether you need to configure a product instance
on each flavor/node, look through the configuration steps in the
table file to see what they do.

  Internal Processes

  • Check node
    authorization
  • Process CONFIGURE
    action
  • Execute temp file

  23.3.5 ups configure
Examples

  Assuming prod1
is a product that requires ups configure to
be run manually for each machine flavor in a cluster. The sample
command, which should be issued from a machine of flavor Linux+2
runs the CONFIGURE action in the table file associated with the
product prod1 , version v1_6_4 for flavor Linux+2.

% ups configure prod1 v1_6_4 -f Linux+2

  A
command like this, but with the appropriate flavor, must be run for
each machine flavor represented in the cluster.

  23.4 ups copy

  The ups copy command
was designed as a UPS product development tool allowing a new instance of a
product to be declared "like" another.

  23.4.1 Command
Syntax

% ups copy -G "<ups_declare_options> <product> <version>" \ [<options>] <product> <version>

  23.4.2 Commonly Used
Options

  See section 23.4.3 All Valid Options for descriptions of each option.

 
Table 23.4.2-a:Table 23.4.2-a:

-f
<flavor>
-f
<flavor>
A valid number of -H (alone or with a valid number) A valid number of -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-G
"<options>"
-G
"<options>"
-q
<qualifierList>
-q
<qualifierList>
-r
<prodRootDir>
-r
<prodRootDir>
-T <path or
URL>
-T <path or
URL>
-W -W
-X -X
-z
<databaseList>
-z
<databaseList>

|

  23.4.3 All Valid
Options

 
Table 23.4.3-a:Table 23.4.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-A nodes -A nodes Authorized nodes Authorized nodes
-b compileFile -b compileFile compile file name (.sh and .csh will be added
automatically) compile file name (.sh and .csh will be added
automatically)
-c -c Finds source product instance chained to
"current" Finds source product instance chained to
"current"
-C -C don't do configure don't do configure
-d -d Finds source product instance chained to
"development" Finds source product instance chained to
"development"
-D origin -D origin products' master source file products' master source file
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-G
"<options>"
-G
"<options>"
Specifies options to be passed to the ups
declare
command for target product instance; see below Specifies options to be passed to the ups
declare
command for target product instance; see below
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name of source product
instance Specifies table file name of source product
instance
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory of source
product instance Specifies table file directory of source
product instance
-n -n Finds source product instance chained to
"new" Finds source product instance chained to
"new"
-o -o Finds source product instance chained to
"old" Finds source product instance chained to
"old"
-O
"<options>"
-O
"<options>"
Sets the value of $UPS_OPTIONS to <options> . Sets the value of $UPS_OPTIONS to <options> .
-p
"description"
-p
"description"
product description product description
-q
<qualifierList>
-q
<qualifierList>
Finds product instance on distribution node
with the specified qualifiers (required and/or optional) Finds product instance on distribution node
with the specified qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory of
source product instance Specifies the product root directory of
source product instance
-t -t Finds source product instance chained to
"test" Finds source product instance chained to
"test"
-T <path or
URL>
-T <path or
URL>
Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format.
-u
<compileDir>
-u
<compileDir>
directory of file to put compiled information into directory of file to put compiled information into
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory of source product
instance; default value is ups Specifies location of ups directory of source product
instance; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-W -W Uses environment variables (e.g.,
$SETUP_<PRODUCT>) to identify dependent product instances for
target product (that is, it uses instances that are already setup
in preference to what is listed in table file) Uses environment variables (e.g.,
$SETUP_<PRODUCT>) to identify dependent product instances for
target product (that is, it uses instances that are already setup
in preference to what is listed in table file)
-X -X Executes the ups declare command instead of just echoing it Executes the ups declare command instead of just echoing it
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.4.4 Options Valid
with -G

  In order to distinguish the
target product instance from the source, the declarations for the
two instances must differ by at least one instance-identifying
element. The -G option
provides the means to specify the target instance identifiers; it
takes a list of ups declare command line elements as an argument. Any identifier not specified
via -G retains the
value of the source instance. The elements valid for use with -G include <product> , <version> and the following subset of the ups declare options:

  -A
<nodeList>
, -c , -d , -D
<origin>
, -f
<flavor>
, -g
<chainName>
, -n , -o , -O
"<flagList>"
, -p
"<description>"
, -q
<qualifierList>
, -t , -z
<databaseList>
, -0 , -1 , -2 , -3 , -4

  See section 23.5 ups declare for details on each option. If the argument
to -G includes the
product version, the product name must be included ahead of the
version; the first unflagged element is always interpreted as the
product name and the second as the version.

  23.4.5 More Detailed
Description

  The command ups copy is
intended mainly for product developers declaring new instances on
their development systems. It simplifies declaration of new
instances of products that already exist in a UPS database. There is no restriction against using ups
copy
to copy the installation of a different product,
however it's usually not particularly helpful in that
situation.

  Notes:

  • ups copy runs ups
    declare
    if you use the -X (uppercase -x )
    option; if not used, the declare command is just echoed.
  • Use the -G option to
    specify declaration information that is to be different from the
    installation you're using as a model. At least one
    instance-identifying element must be specified using -G to
    distinguish the source from the target instance.
  • If you use the option -W ,
    you will pick up the current environment. For example, if the
    previously declared instance depends on v1_0 of some product (e.g., joe v1_0), but the new instance should have joe v2_0 as a dependency, first run setup joe v2_0 ,
    then run ups copy with -W .

  Internal Processes

  • Process COPY
    action
  • Create a table file
    entry for new instance (may use environment for UPS product requirements)
  • If simulation only,
    write table file entry to temp and echo appropriate declare
    command
  • Otherwise, write/merge
    in table file and declare new instance (see ups declare internals)
  • Execute temp file

  23.4.6 ups copy
Examples

% ups copy dog v1 -G "dog v3 -f Linux+2 -q test -m v3.table -M ups\ 
-r /path/to/dog/v3" 

  This command runs a ups
copy
command for dog version v3, without the -X option so
that the ups declare command just gets echoed, not executed. The -G argument here
gives the product name and version plus options to be used by the ups
declare
command: the flavor ( -f Linux+2 ), a
qualifier ( -q test ), the
table file name and location (given via -m and -M ),
and the product root directory (given via -r ). The command
output looks like this:

/var/tmp/baaa006ni_table_dog 
ups declare dog v3 -f "Linux+2" -q "test" -r "/path/to/dog/v3"\
 -U "ups" -m "v3.table" -M "ups" 

  The second command is
identical to the first example except that the -X option
instructs it to execute the ups declare command:

% ups copy dog v1 -G "dog v3 -f Linux+2 -q test -r /path/to/dog/v3 \ 
-M ups -m v3.table" -X

  23.5 ups declare

  The ups declare command is used for two separate purposes:

  1. to initially
    declare an instance to a database (and optionally add a chain at
    the same time)
  2. to add a chain
    to a previously declared instance

  23.5.1 Command
Syntax

  For initially declaring
an instance

% ups declare <flavor_option> %{font-weight: bold;font-family: monospace}-r <prodRootDir>% [<other_options>] \ 
<product> <version>

  For declaring a
chain

% ups declare <chain_option> [<other_options>] <product> \ 
<version>

  23.5.2 Commonly Used
Options

  See section 23.5.3 All Valid Options for descriptions of each option.

  For initially declaring
an instance

 
Table 23.5.2-a:Table 23.5.2-a:

-f
<flavor>
-f
<flavor>
A valid number or -H (alone or with a valid number) A valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-m
<tableFileName>
-m
<tableFileName>
-q
<qualifierList>
-q
<qualifierList>
-r
<prodRootDir>
-r
<prodRootDir>
-z
<databaseList>
-z
<databaseList>

|

  For declaring a
chain

 
Table 23.5.2-b:Table 23.5.2-b:

-f
<flavor>
-f
<flavor>
A valid number or -H (alone or with a valid number) A valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.5.3 All Valid
Options

 
Table 23.5.3:Table 23.5.3:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen. Prints command description and option usage
information to screen.
-A
<nodeList>
-A
<nodeList>
Specifies nodes authorized to access the
product; sets the keyword AUTHORIZED_NODES Specifies nodes authorized to access the
product; sets the keyword AUTHORIZED_NODES
-b
<compileFile>
-b
<compileFile>
Specifies name of the output file for the ups
compile
command (described in Chapter 38: Use of Compile Scripts in Table Files ); sets the keyword
COMPILE_FILE Specifies name of the output file for the ups
compile
command (described in Chapter 38: Use of Compile Scripts in Table Files ); sets the keyword
COMPILE_FILE
-c -c Chains the product instance to "current";
when this chain gets declared, the corresponding ACTION=CURRENT in
the table file gets executed, if it exists. Chains the product instance to "current";
when this chain gets declared, the corresponding ACTION=CURRENT in
the table file gets executed, if it exists.
-C -C When initially declaring a product, -C prevents execution of the CONFIGURE action. When initially declaring a product, -C prevents execution of the CONFIGURE action. When declaring a chain, -C prevents
execution of the corresponding chain action. When declaring a chain, -C prevents
execution of the corresponding chain action.
-d -d Chains the product instance to "development";
when this chain gets declared, the corresponding ACTION=DEVELOPMENT
in the table file gets executed, if it exists. Chains the product instance to "development";
when this chain gets declared, the corresponding ACTION=DEVELOPMENT
in the table file gets executed, if it exists.
-D
"<origin>"
-D
"<origin>"
Specifies the product's master source file;
sets the keyword ORIGIN (all spaces get removed from <origin> for the keyword value) Specifies the product's master source file;
sets the keyword ORIGIN (all spaces get removed from <origin> for the keyword value)
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Chains the product instance to <chainName> (this is useful for user-defined chains). When any chain gets
declared, the corresponding ACTION=<CHAIN_NAME> in the table
file gets executed. Chains the product instance to <chainName> (this is useful for user-defined chains). When any chain gets
declared, the corresponding ACTION=<CHAIN_NAME> in the table
file gets executed.
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-L -L Adds the STATISTICS keyword to the version
file, thereby instructing UPS to keep statistics on this product instance. Adds the STATISTICS keyword to the version
file, thereby instructing UPS to keep statistics on this product instance.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name; when initially
declaring a product, sets the keyword TABLE_FILE. Specifies table file name; when initially
declaring a product, sets the keyword TABLE_FILE.
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory; when
initially declaring a product, sets the keyword TABLE_DIR. Specify
only if file is not in one of the two default locations, namely
under $PRODUCTS/<product> or in the ups directory. Specifies table file directory; when
initially declaring a product, sets the keyword TABLE_DIR. Specify
only if file is not in one of the two default locations, namely
under $PRODUCTS/<product> or in the ups directory.
-n -n Chains the product instance to "new"; when
this chain gets declared, the corresponding ACTION=NEW in the table
file gets executed, if it exists. Chains the product instance to "new"; when
this chain gets declared, the corresponding ACTION=NEW in the table
file gets executed, if it exists.
-o -o Chains the product instance to "old"; when
this chain gets declared, the corresponding ACTION=OLD in the table
file gets executed, if it exists. Chains the product instance to "old"; when
this chain gets declared, the corresponding ACTION=OLD in the table
file gets executed, if it exists.
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-q
<qualifiers>
-q
<qualifiers>
When initially declaring a product, -q specifies required and/or optional qualifiers to include in the
declaration, and sets the keyword QUALIFIERS. When initially declaring a product, -q specifies required and/or optional qualifiers to include in the
declaration, and sets the keyword QUALIFIERS. When adding a chain, -q specifies
required and/or optional qualifiers to identify the instance. When adding a chain, -q specifies
required and/or optional qualifiers to identify the instance.
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory; when
initially declaring a product, sets the keyword PROD_DIR. Specifies the product root directory; when
initially declaring a product, sets the keyword PROD_DIR. A note for developers: you may find it
convenient to use the construction -r \pwd\ if
you're working in the product root directory. A note for developers: you may find it
convenient to use the construction -r \pwd\ if
you're working in the product root directory.
-t -t Chains the product instance to "test"; when
this chain gets declared, the corresponding ACTION=TEST in the
table file gets executed, if it exists. Chains the product instance to "test"; when
this chain gets declared, the corresponding ACTION=TEST in the
table file gets executed, if it exists.
-T <path or
URL>
-T <path or
URL>
Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. When
initially declaring a product, it sets the keyword
ARCHIVE_FILE. Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. When
initially declaring a product, it sets the keyword
ARCHIVE_FILE.
-u
<compileDir>
-u
<compileDir>
Specifies the directory for the output file
(which is named via the -b option) for
the ups
compile
command; sets the keyword COMPILE_DIR. Specifies the directory for the output file
(which is named via the -b option) for
the ups
compile
command; sets the keyword COMPILE_DIR.
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups ;
when initially declaring a product, sets the keyword UPS_DIR Specifies location of ups directory; default value is ups ;
when initially declaring a product, sets the keyword UPS_DIR
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database in which to declare
the product (see section 27.1 Database Selection Algorithm ); or, if adding a chain,
specifies the database(s) in which product is declared Specifies the database in which to declare
the product (see section 27.1 Database Selection Algorithm ); or, if adding a chain,
specifies the database(s) in which product is declared
-Z -Z Times the command Times the command

  23.5.4 More Detailed
Description

  Declaring an Instance
for the First Time

  In the ups declare command:

  • -C prevents
    execution of the CONFIGURE action, if any, and is normally not
    included. The default (and usually desired) behavior is to execute
    the CONFIGURE action.
  • You must include a
    flavor specification, there is no default flavor when a product is
    first declared. It sets the value of the FLAVOR keyword.
  • Most products require a table file. The table
    file must exist before running ups declare . In
    most cases you need to include the table file name ( -m ). (Since in a
    very few cases a table file isn't required, -m is not a
    strictly required option.)
  • If the product's table
    file was placed in either of the two default locations (under /path/to/database/<product> or in the product's ups directory), then -M
    <table_file_dir>
    is not needed. Only use the -M option if you have moved the table file to a separate location
    where UPS won't otherwise find it.
  • In most cases you need
    to include product root directory ( -r ). Exceptions
    include wrapper products which consist only of a table file, and
    thus have no product root directory.
  • If the product's ups directory tar file
    was unwound in the default location ( $<PRODUCT>_DIR/ups ), then -U
    <ups_dir>
    is not needed. If the ups directory is located elsewhere
    (or named differently), this specification must be included. In
    general, you should not include this qualifier.
  • If you choose not to
    specify the target database explicitly ( -z
    <database>
    ), UPS chooses it automatically via the $PRODUCTS variable. If
    $PRODUCTS points to multiple databases, you need to be a little
    careful about database selection. The database matching algorithm
    is described in section 27.1 Database Selection Algorithm .
    p<>.   If the product has
    dependencies that are declared in different databases, UPS must be able to find all of them in order to resolve the
    dependencies. You can rely on $PRODUCTS if all the necessary
    databases are included in it. Otherwise specify them on the command
    line (e.g., -z
    <database1>:<database2>:...>
    or -z
    $PRODUCTS:<database1>:<database2>:...
    ).
  • You may include chain
    information on this command. See the description below.

  Adding Chains to an
Existing Instance

  When you add one or more chains
to an existing instance, UPS doesn't allow you to change anything else about that
instance. Regarding the options to specify:

  • You of course need to
    specify the chain or chains to add using either -g
    <chain_name>
    or one of -c , -d , -n , -o , -t .
  • -C prevents the
    corresponding chain action(s) in the table file from being
    executed.
  • You do not strictly need
    to specify flavor. UPS will default to the best flavor match (described in
    section 27.2.4 Flavor and Qualifier Matching Algorithm ). You can
    override the default using -f or a valid number
    (.
  • Specify qualifiers
    ( -q )
    as necessary to select the appropriate instance.
  • Specify the database
    ( -z )
    as necessary to select the appropriate instance.

  Internal Processes

  • Find database to
    use
  • If necessary, process
    `UNCHAIN' action
  • Process DECLARE
    action
  • If necessary, process
    CONFIGURE action
  • If necessary, warn if
    there is a TAILOR action
  • If necessary, process
    the `CHAIN' action
  • If necessary, warn if
    there are START/STOP actions
  • If current chain, try
    to copyman, copycatman and copyInfo files
  • Execute the temp
    file
  • If successful, modify
    all appropriate files on disk

  23.5.5 ups declare
Examples

  Declare a product with
no chain using defaults where possible

% ups declare myprod v1_0 -f Linux+2 -m myprod.table \ 
            -r /path/to/myprod/v1_0/Linux+2

  UPS finds the product in the directory given by the -r option, and
declares it to a database in $PRODUCTS according to the selection
algorithm discussed in 27.1 Database Selection Algorithm . The product instance gets
declared with the specified name, version and flavor, and no
qualifiers. UPS looks for the table file, called myprod.table in the two default
locations (command fails if table file doesn't exist, or is not
found in either location).

  Declare a product with
no chain using defaults where possible

% ups declare myprod2 v1_0 -2 -g test -m myprod2.table \
           -r myprod2/v1_0/FictionalOS+a -z /my/local/db:$PRODUCTS

  For this example, we assume the
local machine flavor is FictionalOS+a.b. UPS finds the product in the directory given by the -r option. The specified path is taken relative to PROD_DIR_PREFIX. UPS declares the product to one of the listed databases
according to the selection algorithm discussed in 27.1 Database Selection Algorithm . Each of the dependencies,
if any, must exist in at least one of the listed databases.

  The product instance gets
declared with the specified name, version, no qualifiers, and the
chain "test". The flavor declaration is the level -2 specification
of the machine, namely FictionalOS+a. UPS looks for the table file, called myprod2.table in the two default
locations (command fails if table file doesn't exist, or is not
found in either location).

  Add a chain to a
previously declared instance

% ups declare myprod2 v1_0 -2 -g test -m myprod2.table \  
         -r myprod2/v1_0/FictionalOS+a -z /my/local/db:$PRODUCTS
% ups declare myprod2 v1_0 -2 -c -z /my/local/db:$PRODUCTS

  This command declares the
product instance of the previous example "current" (via the -c option). Generally, a product is first declared as "test", and then
after a "debugging period" (often several weeks), an updated
release is cut and chained to "current". Notes:

  • In most UPS/UPD commands you specify either chain (often defaulted
    to "current") or version. Here you need both: the version is
    required to identify the instance, and the chain is required
    because it is being assigned.
  • You should specify the
    database /my/local/db first since that's how it was initially declared. UPS will traverse the databases in the same order to find
    the right instance.

  23.6 ups depend

  The ups depend command lists product dependencies of the specified product
instance(s) as declared in the (local) database. On user nodes it
is generally used to determine what products will get setup along
with the "parent" product. UPD uses it on product servers to determine what
dependencies to install.

  23.6.1 Command
Syntax

% ups depend [<options>] <product> [<version>]

  23.6.2 Commonly Used
Options

  See section 23.6.3 All Valid Options for descriptions of each option.

 
Table 23.6.2-a:Table 23.6.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-j -j
-K
<keywordList>
-K
<keywordList>
-l -l
-q
<qualifierList>
-q
<qualifierList>
-R -R
-z
<databaseList>
-z
<databaseList>

|

  23.6.3 All Valid
Options

 
Table 23.6.3-a:Table 23.6.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores lower level dependencies, finds
direct dependencies of top level product only Ignores lower level dependencies, finds
direct dependencies of top level product only
-K
<keywordList>
-K
<keywordList>
Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords
-l -l Produces a long listing including all the
table file functions that would be executed in a setup command. Produces a long listing including all the
table file functions that would be executed in a setup command.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-R -R Lists only the required (non-optional)
dependencies. Lists only the required (non-optional)
dependencies.
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databases>
-z
<databases>
Specifies the database(s) to search Specifies the database(s) to search
-Z -Z Times the command Times the command

  ups depend
Examples

  Execute command with qualifiers

  The first example requests
information for art v1_08_10 with qualifiers for art

% ups depend art v1_08_10 -q debug:e4:nu
art v1_08_10 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|__cetpkgsupport v1_04_02 -f NULL -z /nusoft/app/externals -g current
|__messagefacility v1_10_26 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |__fhiclcpp v2_17_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|     |__cetlib v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|        |__cpp0x v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|           |__boost v1_53_0 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|              |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__root v5_34_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|  |__geant4 v4_9_6_p02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__clhep v2_1_3_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__xerces_c v3_1_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__g4emlow v6_32 -f NULL -z /nusoft/app/externals
|  |  |__g4neutron v4_2 -f NULL -z /nusoft/app/externals
|  |  |__g4neutronxs v1_2 -f NULL -z /nusoft/app/externals
|  |  |__g4nucleonxs v1_1 -f NULL -z /nusoft/app/externals
|  |  |__g4photon v2_3 -f NULL -z /nusoft/app/externals
|  |  |__g4pii v1_3 -f NULL -z /nusoft/app/externals
|  |  |__g4radiative v3_6 -f NULL -z /nusoft/app/externals
|  |  |__g4surface v1_0 -f NULL -z /nusoft/app/externals
|  |__fftw v3_3_3 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__gsl v1_16 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__pythia v6_4_28 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:gcc48
|  |__postgresql v9_1_5b -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__python v2_7_5c -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |     |__sqlite v3_08_00_02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__mysql_client v5_5_27 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q e4
|  |__xrootd v3_3_4 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |__libxml2 v2_9_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|__cppunit v1_12_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|__gccxml v0_9_20130621 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__cmake v2_8_8 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -g current
|__tbb v4_1_3 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4

  The next example requests
information for redmine

% ups depend redmine
redmine v1_4_1 -f NULL -z /fnal/ups/db -g current
|__ruby v1_9_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__cvs v1_12_13 -f Linux+2 -z /fnal/ups/db
|__git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current
|__subversion local -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current

  The -R option
requests only the dependencies listed as "required." In both examples, all
dependencies are required so the output is the same.

% ups depend -R redmine
redmine v1_4_1 -f NULL -z /fnal/ups/db -g current
|__ruby v1_9_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__cvs v1_12_13 -f Linux+2 -z /fnal/ups/db
|__git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current
|__subversion local -f Linux64bit+2.6-2.12 -z /fnal/ups/db -g current

  23.7 ups exist

  The ups exist command is used to test whether a setup command
issued with the same command line elements is likely to succeed. It
was designed primarily for use in scripts.

  23.7.1 Command
Syntax

% ups exist [<options>] <product> [<version>]

  23.7.2 Commonly Used
Options

  See section 23.7.3 All Valid Options for descriptions of each option.

 
Table 23.7.2-a:Table 23.7.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid
number) Or a valid number or -H (alone or with a valid
number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-j -j
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.7.3 All Valid
Options

 
Table 23.7.3-a:Table 23.7.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-B <depProdName>=
"<options>"
-B <depProdName>=
"<options>"
Specifies options to prepend to the setupRequired line (in
table file) for the dependent product <depProdName> Specifies options to prepend to the setupRequired line (in
table file) for the dependent product <depProdName>
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-e -e Sets $UPS_EXTENDED (to the value 1 ). Sets $UPS_EXTENDED (to the value 1 ).
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-j -j Ignores dependencies, operates just on top
level product Ignores dependencies, operates just on top
level product
-k -k Prevents execution of unsetup files prior to
(subsequent) setup Prevents execution of unsetup files prior to
(subsequent) setup
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.7.4 More Detailed
Description

  The ups exist command is used to test whether a setup command
issued with the same command line elements is likely to succeed. As
for all the UPS/UPD commands, if the setup command
finds a corresponding action in the selected table file, it

  1. translates the
    functions listed under the action into shell commands,
  2. writes them to
    a temporary script in $TMPDIR (if $TMPDIR isn't set, the default is /tmp ), and
  3. invokes the
    script to execute the shell commands.

  ups exist checks
for a properly declared matching instance, and verifies that you
have the necessary permissions to create the temporary script. If
so, it creates the script, but it does not execute it.

  ups
exist
sets the $? variable to 0 if it was able to create the
temporary file, or to 1 for error.

  This command is rarely used
from the command line, and is more useful in scripts where a failed
setup could cause the script to abort. When issued from the command
line, it returns no output if the command succeeds.

  Internal Processes

  • Check node
    authorization
  • If necessary, process
    UNSETUP action
  • Simulate SETUP
    action

  23.7.5 ups exist
Examples

  This command is rarely used
from the command line, and is more useful in scripts where a failed
setup could cause the script to abort. When issued from the command
line, it returns no output if the command succeeds.

  ups
exist
sets the $? variable to 0 if it was able to create the
temporary file, or to 1 for error. As an example, we can run ups list and
find that there is a current instance of the product prod1 for the flavor FictionalOS+a but not for FictionalOS+a.b. Running ups
exist
for each flavor, we see that the variables get set
accordingly.

$ ups exist prod1 -f FictionalOS+a; echo $?
0
$ ups exist prod1 -f FictionalOS+a.b; echo $?
1

  23.8 ups flavor

  The ups flavor command with no options returns the flavor of the machine. If a
flavor level is specified (e.g., -0 , -1 ...), it
returns the flavor according to that level. ups flavor generates a flavor table if the -H option is
used. The flavor levels and the term flavor table are defined in section 23.8.4 More Detailed Description .

  23.8.1 Command
Syntax

% ups flavor [<options>]

  23.8.2 Commonly Used
Options

  See section 23.8.3 All Valid Options for descriptions of each option.

 
Table 23.8.2-a:Table 23.8.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number Or a valid number
-H
<flavor>
-H
<flavor>
Alone or together with a valid number Alone or together with a valid number
-l -l

|

  23.8.3 All Valid
Options

 
Table 23.8.3-a:Table 23.8.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen. Prints command description and option usage
information to screen.
-f
<flavor>
-f
<flavor>
Specifies flavor. Specifies flavor.
-H
<flavor>
-H
<flavor>
Specifies host flavor family from which to
build a flavor table. If used with any of -0 , -1 , -2 , -3 , -4 , -5 , specifies
corresponding level of specified host flavor family. Specifies host flavor family from which to
build a flavor table. If used with any of -0 , -1 , -2 , -3 , -4 , -5 , specifies
corresponding level of specified host flavor family.
-l -l Produces a flavor table. Produces a flavor table.
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-Z -Z Times the command. Times the command.
-0 -0 Specifies flavor as NULL Specifies flavor as NULL
-1 -1 Pick flavor for operating system generic to the vendor Pick flavor for operating system generic to the vendor
-2 -2 Pick flavor for operating system to level of major version number Pick flavor for operating system to level of major version number
-3 -3 Pick more specific flavor for operating system (includes start of
minor version numbers) Pick more specific flavor for operating system (includes start of
minor version numbers)
-4 -4 Pick still more specific flavor for operating system (includes more
of minor version numbers) Pick still more specific flavor for operating system (includes more
of minor version numbers)
-5 -5 Pick most specific flavor for operating system (includes all of
minor version numbers) Pick most specific flavor for operating system (includes all of
minor version numbers)

  23.8.4 More Detailed
Description

  The ups flavor command returns flavor information about the machine issuing the
command, or for a flavor requested via the -H option. When
entered with no options, the command returns the full OS
specification of the machine.

  When entered with the -l (long) option, ups flavor returns what we call a flavor table , which is a list including every level of
specificity for a flavor that you could use to find or declare a
product instance. For example, on novagpvm02, it
outputs:

% ups flavor -l
Linux64bit+2.6-2.5
Linux64bit+2.6-2.4
Linux64bit+2.6-2.3
Linux64bit+2.6-2.2
Linux64bit+2.6-2.1
Linux64bit+2.6-2.0
Linux+2.6-2.5
(and many more)
NULL
ANY

  If -H
<flavor>
is used with -l , ups flavor builds a flavor table for the flavor given by -H . This is
useful if you're not sure what levels are allowable for a
particular basic flavor. The flavor table lists flavors starting at
the level you specify. Compare the following two commands and
output:

% ups flavor -lH FictionalOS+a.6
FictionalOS+a.6
FictionalOS+a.5
FictionalOS+a.4
FictionalOS+a.3
FictionalOS+a.b
FictionalOS+a.1
FictionalOS+a.0
FictionalOS+a
FictionalOS
NULL
ANY
% ups flavor -lH FictionalOS
FictionalOS
NULL
ANY

  You can specify a particular
level using the number options, with the highest number being the
most specific.

  23.8.5 ups flavor
Examples

  Find full flavor
specification of machine

% ups flavor

  This command returns the full
OS specification of the machine up to the build number for the patch
(when these levels of specification exist), for example:

Linux64bit+2.6-2.5

  Create a flavor table
for machine's OS

% ups flavor -l

  This command returns a flavor
table for the flavor of the machine. For example, on a (fictional)
Linux+2.6 machine it outputs:

Linux+2.6.1-4
Linux+2.6.1
Linux+2.6
Linux+2
Linux
NULL
ANY

  Find flavor
specification of machine, at different levels

% ups flavor -4

  The -4 option
requests the machine's flavor as the most significant OS
specification or the full specification, e.g.,:

Linux+2.6.1
% ups flavor -3

  The -3 option
requests the machine's flavor as basic OS and version and release, e.g.,:

Linux+2.6

  The -2 option
requests the machine's flavor as basic OS and version, e.g.,:

Linux+2.6
% ups flavor -1

  The -1 option
requests the machine's flavor as the OS value up to the generic OS,
e.g.,:

Linux
% ups flavor -0

  This always returns the NULL
string.

  Create a flavor table
for host flavor, at different levels

% ups flavor -lH FictionalOS+a.6

  This creates a flavor table
listing flavors starting at the level specified via -H , in this case
"level 3":

FictionalOS+a.6
FictionalOS+a
FictionalOS
NULL
ANY
% ups flavor -lH FictionalOS+a

  This creates a flavor table
listing flavors starting at the level specified via -H , in this case
"level 2":

FictionalOS+a
FictionalOS
NULL
ANY

  23.9 ups get

  The ups get command
is rarely used by anyone except product developers/maintainers. It
t just scans the all actions for a product (setup, etc. in the table file) and looks
for things that are files, and lists them.

  The ups get command
was designed primarily for use by UPD , which calls it internally. As such it is rarely used
outside of that context.

  23.9.1 Command
Syntax

% ups get -F [<other_options>] <product> [<version>]

  23.9.2 All valid
options

 
Table 23.9.2-a:Table 23.9.2-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list. Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list.
-F -F Prints to screen a list of files that are
associated with the product but which are maintained external to
the products area (excluding table file) Prints to screen a list of files that are
associated with the product but which are maintained external to
the products area (excluding table file)
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list. Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.9.3 ups get
Example

% ups get -F ups

  In the database on the machine
used, the UPS product has a few files maintained outside of the
product root directory. This command returns the output:

/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/current/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/uncurrent/fnal/ups/db/.upsfiles/configure/v4_4a_OSF1+V4_/unconfigure

  23.10 ups help

  The ups help command
lists all the UPS commands with brief definitions. There are no options
for this command.

  23.10.1 ups help
Example

% ups help
UPS commands:

for specific command options use "ups COMMAND -?"configure   : Environmentally configure a product instance.
          copy        : Allow one instance of a product to be declared "like" another.
          declare     : Add a product instance or a chain to a UPS Database.
          depend      : List (for a specified UPS product instance) UPS product 
                        requirements or all UPS product instances that have the 
                        specified UPS product instance as a requirement.
          exist       : Determine if a setup command with the same options
                        would likely succeed.
          flavor      : Print flavor of a machine, optionally by level, or table 
                        generated for searchingget         : Return a list of all files that are needed  by a product
                        instance and do not live under the product root directory.
          help        : Output help information for all UPS commands
          list        : List UPS Database information about product instances.
          modify      : Allow editor modification of the UPS Database files.
                        The altered files are verified before being rewritten.
          setup       : Prepare the environment in order to be able to use a product
                        instance.
          start       : Perform any necessary actions for a product instance at system 
                        boot.
          stop        : Perform any necessary actions for a product instance at 
                        system shutdown.
          tailor      : Perform any product instance tailoring that needs to be done 
                        once (specify hardware device location) or needs user input.
          touch       : Will change a ups file modify time (MODIFIED) to current time
                        (it will probaly also change the modifier (MODIFIER)).
          unconfigure : Undo any actions performed by the configure command.
          undeclare   : Remove a product instance from a UPS Database.
                        if chain(s) are specified ONLY the chain(s) will version will
                        be removed
          unsetup     : Return the environment to a pre-setup state.
          verify      : Check the specified instances for correct formatting and
                        information.

  23.11 ups list

  The ups list command
returns information about the declared product instances in a UPS database. Two output styles are provided: a formatted
one that is easy for users to read, and a condensed one for parsing
by a subsequent command or a script.

  23.11.1 Command
Syntax

% ups list [<options>] [<product>] [<version>]

  23.11.2 Commonly Used
Options

  See section 23.11.3 All Valid Options for descriptions of each option.

 
Table 23.11.2-a:Table 23.11.2-a:

-a -a
-f
<flavorList>
-f
<flavorList>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-K
<keywordList>
-K
<keywordList>
-l -l
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.11.3 All Valid
Options

Table 23.11.3-b:Table 23.11.3-b:
-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-a -a Includes all instances. Includes all instances.
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-K -K keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN
-l -l produce a long listing produce a long listing
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Specifies product instance chained to
"test" Specifies product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups (relative to the product root directory) Specifies location of ups directory; default value is ups (relative to the product root directory)
-v ( vv ) -v ( vv ) Prints out extra debugging information.
(-vv for more, -vvv for even more) Prints out extra debugging information.
(-vv for more, -vvv for even more)
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup ) Times the command (does not include time for
sourcing of temp file for setup )
-. -. shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace} shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace}
|

  23.11.4 More Detailed
Description

  ups list is
useful for finding out what products are in the database that you
use, what the current version of a product is for your machine's
flavor, and other information. Product installers and other
administrative users can use it to get detailed information about a
product's installation and to find product files.

  You can specify the information
you want contained in the output by including various options in
the command. As is standard in UPS , if no chain, version or flavor is specified, and -a (for all instances) is not specified, UPS returns only the instance declared as current for the
best-matched flavor of the requesting machine.

  Formatted Output
Style

  One output style is for visual
parsing (this is the default output, which we call formatted ), with output that looks like:

%  ups list git

DATABASE=/nusoft/app/externals 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

  Notice that the product name,
version, flavor, qualifiers and chain(s) are the default fields
that get returned. The database (first line of the output) is
included as a header, not as part of the per-instance data. Each
piece of data returned for an instance is preceded by its keyword
for identification.

  You cannot choose arbitrary
output fields for the selected instances using this output format.
However, you can use the -l option to
give an exhaustive listing of information contained in the UPS database about the requested product.

  If $PRODUCTS contains multiple
databases, output is returned for each one and labelled
accordingly, for example:

% ups list git

DATABASE=/nusoft/app/externals 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

DATABASE=/grid/fermiapp/products/common/db 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

    Product=git    Version=v1_8_0_1    Flavor=Linux+2
        Qualifiers=""    Chain=current

  Notice that more than one instance
of the product may exist for a given database.

  Condensed Output
Style

  The other output format is a
script-readable (or condensed ) format, provided to allow parsing by a subsequent
command. Use the -K option to
request output in the condensed format. The -K option
requires an argument list specifying which fields to include in the
output, for example:

% ups list -K product:version:flavor git
"git" "v1_8_0_1" "Linux64bit+2" 
"git" "v1_8_0_1" "Linux64bit+2" 
"git" "v1_8_0_1" "Linux+2" 

  The plus sign ( ) argument,
e.g., -K , is a
shorthand for requesting the default fields product:version:flavor:qualifiers:chain ,
for example:

% ups list -K+ git
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux+2" "" "current" 

  Some common keyword arguments
used with the -K option
are:

 
Table 23.11.4-a:Table 23.11.4-a:

PRODUCT PRODUCT product name product name
FLAVOR FLAVOR product instance flavor product instance flavor
VERSION VERSION product version product version
QUALIFIERS QUALIFIERS additional instance specification information
often used to indicate compilation options used by developer additional instance specification information
often used to indicate compilation options used by developer
CHAIN CHAIN product instance chain product instance chain
+ + all of the above all of the above
DATABASE (or DB) DATABASE (or DB) the UPS database path; useful if more than one on system the UPS database path; useful if more than one on system
DECLARER DECLARER logon id of person who declared the
instance logon id of person who declared the
instance
DECLARED DECLARED date/time that product instance was
declared date/time that product instance was
declared
MODIFIER MODIFIER logon id of person who modified/updated the
instance logon id of person who modified/updated the
instance
MODIFIED MODIFIED date/time that product instance was
modified/updated date/time that product instance was
modified/updated

  If $PRODUCTS contains multiple
databases, output is returned for selected products in all of them.
However, the database is identified for each output line only if
the keyword DATABASE or DB is included in the argument string
(e.g., -K+:DB requests
the standard output fields followed by the database path).

  A few of the keywords allow
the "at" symbol, @ to be prepended, which provides a sort of
shorthand for long path names:

 
Table 23.11.4-b:Table 23.11.4-b:

@PROD_DIR @PROD_DIR entire path for the directory where the
product is installed (usually equivalent to
PROD_DIR_PREFIX/PROD_DIR) entire path for the directory where the
product is installed (usually equivalent to
PROD_DIR_PREFIX/PROD_DIR)
@TABLE_FILE @TABLE_FILE entire path for the table file entire path for the table file
@UPS_DIR @UPS_DIR product's ups directory; if it is not an
absolute path, then it is taken relative to @PROD_DIR product's ups directory; if it is not an
absolute path, then it is taken relative to @PROD_DIR

  The full list of keywords that
can be used with ups list -K and upd list
-K
follows, with descriptions:

Keyword Keyword Description Description
ARCHIVE_FILE ARCHIVE_FILE archive file name/location; useful with upd
list
archive file name/location; useful with upd
list
AUTHORIZED_NODES AUTHORIZED_NODES authorized nodes; "all nodes" represented by
an asterisk () in output authorized nodes; "all nodes" represented by
an asterisk (
) in output
CATMAN_SOURCE_DIR CATMAN_SOURCE_DIR location of catman files (formatted man page
files) included with instance location of catman files (formatted man page
files) included with instance
CATMAN_TARGET_DIR CATMAN_TARGET_DIR directory into which catman files are to be
copied directory into which catman files are to be
copied
CHAIN CHAIN chain name chain name
COMPILE_DIR COMPILE_DIR directory in which the compile file
resides directory in which the compile file
resides
COMPILE_FILE COMPILE_FILE the name of the file containing compiled
functions (see Chapter 38: Use of Compile Scripts in Table Files ) the name of the file containing compiled
functions (see Chapter 38: Use of Compile Scripts in Table Files )
@COMPILE_FILE @COMPILE_FILE entire path to the file containing compiled
functions entire path to the file containing compiled
functions
DECLARED DECLARED the date/time that the instance was declared
to UPS or declared with a chain the date/time that the instance was declared
to UPS or declared with a chain Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations) Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations)
DECLARER DECLARER userid of user that performed the
declaration userid of user that performed the
declaration Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations) Note: often has multiple values, one for each
declaration (e.g., for subsequent chain declarations)
DESCRIPTION DESCRIPTION product description product description
FLAVOR FLAVOR product instance flavor product instance flavor
INFO_SOURCE_DIR INFO_SOURCE_DIR location of Info files included with
instance location of Info files included with
instance
INFO_TARGET_DIR INFO_TARGET_DIR directory into which Info files are to be
copied directory into which Info files are to be
copied
MAN_SOURCE_DIR MAN_SOURCE_DIR location of unformatted man page files
included with instance location of unformatted man page files
included with instance
MAN_TARGET_DIR MAN_TARGET_DIR directory into which formatted man pages are
to be copied directory into which formatted man pages are
to be copied
MODIFIED MODIFIED last time the associated instance was
changed last time the associated instance was
changed Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations) Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations)
MODIFIER MODIFIER userid of user that modified the
instance userid of user that modified the
instance Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations) Note: often has multiple values, one for each
declaration/modification (e.g., for subsequent chain
declarations)
ORIGIN ORIGIN master source file; see option -D in Chapter 25: Generic Command Option Descriptions master source file; see option -D in Chapter 25: Generic Command Option Descriptions
PRODUCT PRODUCT product name product name
PROD_DIR PROD_DIR product root directory (usually defined
relative to PROD_DIR_PREFIX, below) product root directory (usually defined
relative to PROD_DIR_PREFIX, below)
@PROD_DIR @PROD_DIR entire path to product root directory entire path to product root directory
PROD_DIR_PREFIX PROD_DIR_PREFIX product root directory prefix (area where all
or most product instances are maintained) product root directory prefix (area where all
or most product instances are maintained)
QUALIFIERS QUALIFIERS additional instance specification information
often used to indicate compilation options used by developer additional instance specification information
often used to indicate compilation options used by developer
SETUPS_DIR SETUPS_DIR location of setups.[c]sh files and other UPS initialization files location of setups.[c]sh files and other UPS initialization files
STATISTICS STATISTICS flag to record statistics for specified
products flag to record statistics for specified
products
TABLE_DIR TABLE_DIR location of table file location of table file
TABLE_FILE TABLE_FILE name of table file name of table file
@TABLE_FILE @TABLE_FILE entire path for the table file. entire path for the table file.
UPD_USERCODE_DIR UPD_USERCODE_DIR Directory where UPD configuration files are maintained Directory where UPD configuration files are maintained
UPS_DIR UPS_DIR location of ups directory (if not absolute
path, then taken relative to PROD_DIR, usually) location of ups directory (if not absolute
path, then taken relative to PROD_DIR, usually)
@UPS_DIR @UPS_DIR entire path to ups directory entire path to ups directory
VERSION VERSION product version product version

  23.11.5 ups list
Examples

  List all current
products

% ups list

  The simplest way to request a
listing of all the current products installed in your default UPS database is to use the ups list command
with no options or arguments. The per-product output spans a few
lines, though, and can be cumbersome, e.g.,:

DATABASE=/nusoft/app/externals 
    Product=allinea_tools    Version=v4_1_1    Flavor=Linux64bit
        Qualifiers=""    Chain=current

    Product=cetpkgsupport    Version=v1_05_03    Flavor=NULL
        Qualifiers=""    Chain=current

    Product=cmake    Version=v2_8_8    Flavor=Linux64bit+2.6-2.5
        Qualifiers=""    Chain=current

...

            Product=ups    Version=v5_0_2    Flavor=Linux+2
        Qualifiers=""    Chain=current

    Product=ups    Version=v5_0_2    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

    Product=ups    Version=v5_0_2    Flavor=Linux+2
        Qualifiers=""    Chain=current

  Use of the -K option with
the + argument,
e.g.,

% ups list -K+

  provides the same information
as the previous example, but condensed to one line per product:

"allinea_tools" "v4_1_1" "Linux64bit" "" "current" 
"cetpkgsupport" "v1_05_03" "NULL" "" "current" 
"cmake" "v2_8_8" "Linux64bit+2.6-2.5" "" "current" 
...
"ups" "v5_0_2" "Linux+2" "" "current" 
"ups" "v5_0_2" "Linux64bit+2" "" "current" 
"ups" "v5_0_2" "Linux+2" "" "current" 

  Instead of using the + argument to get the default fields, you can specify particular
fields:

% ups list -K product:version

  This command outputs a list of
product names and version numbers for all the current products
installed in your default UPS database, e.g.,:

"allinea_tools" "v4_1_1" 
"cetpkgsupport" "v1_05_03" 
"cmake" "v2_8_8" 
...
"ups" "v5_0_2" 
"ups" "v5_0_2" 
"ups" "v5_0_2" 

  List standard
information for default instance of product

% ups list nova

  This command requests the
standard output fields for the default instance of nova , using the formatted output:

DATABASE=/nusoft/app/externals 

DATABASE=/grid/fermiapp/products/common/db 
    Product=nova    Version=v0.1    Flavor=NULL
        Qualifiers=""    Chain=current

  Addition of the -K+ construction, e.g.,

% ups list -K+ nova

  requests the same information
as the previous example, but in condensed format:

"nova" "v0.1" "NULL" "" "current" 

  Using -a for all,
e.g.,

  List standard
information for all instances of product

% ups list -a git

  requests the standard output
fields for all instances of git , using the formatted output:

DATABASE=/nusoft/app/externals 
    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current

DATABASE=/grid/fermiapp/products/common/db 
    Product=git    Version=v1_6_4a    Flavor=Linux+2
        Qualifiers=""    Chain="" 

    Product=git    Version=v1_8_0_1    Flavor=Linux+2
        Qualifiers=""    Chain=current

    Product=git    Version=v1_8_0_1    Flavor=Linux64bit+2
        Qualifiers=""    Chain=current
...

           Product=git    Version=v1_8_5_3    Flavor=Linxu+2.6-2.12
        Qualifiers=""    Chain="" 

  Use of the -K option with
the + argument,
e.g.,

% ups list -aK+ git

  requests the same information
as the previous example, but in condensed format ( -K+ ):

"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_6_4a" "Linux+2" "" "" 
"git" "v1_8_0_1" "Linux+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.5" "" "" 
"git" "v1_8_5_3" "Linux+2.6-2.5" "" "" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" "" "" 
"git" "v1_8_5_3" "Linxu+2.6-2.12" "" "" 

  List standard
information for all instances of product for your machine's
flavor

% ups list -a2K+ git

  To request information on all
instances of a product limited to the OS of your machine, you can
include the -f option (for
flavor), or enter a command like this one, where -a is for all, -2 is for the "level 2" designation of your machine's OS, and -K+ is for condensed output:

"git" "v1_8_0_1" "Linux64bit+2" "" "current" 
"git" "v1_8_0_1" "Linux64bit+2" "" "current" 

  List specific keywords
for a product

  If your installation has
multiple databases defined in $PRODUCTS, it is useful to include
the keyword for the database ( DB ) in the -K argument list, e.g.,

% ups list -aK+:DB git

  This example is similar to the
previous one, but the database path is included at the end:

"git" "v1_8_0_1" "Linux64bit+2" "" "current" "/nusoft/app/externals" 
"git" "v1_6_4a" "Linux+2" "" "" "/grid/fermiapp/products/common/db" 
"git" "v1_8_0_1" "Linux+2" "" "current" "/grid/fermiapp/products/common/db" 

  This example specifies particular
fields to be output with the -K option for
the default instance of the product

% ups list -K product:version git
"git" "v1_8_0_1" 
"git" "v1_8_0_1" 
"git" "v1_8_0_1" 

  List all keywords for a
product (long listing)

% ups list minos -l

  This command requests detailed
information ( -l for long
listing) about the default instance of the product. Administrative users may often need this level of
detailed information about a product. The -l option is not
valid with the -K option. The
output looks like this:

DATABASE=/grid/fermiapp/products/common/db 
    Product=minos    Version=v0.1    Flavor=NULL
        Qualifiers=""    Chain=current
        Declared="2013-08-16 18.16.17 GMT:2013-07-17 14.40.54 GMT" 
        Declarer="products:products" 
        Modified="2013-08-16 18.16.17 GMT:2013-07-17 14.40.54 GMT" 
        Modifier="products:products" 
        Home=/grid/fermiapp/products/common/db/../prd/project/v0_1/NULL
        No Compile Directive
        Authorized, Nodes=*
        UPS_Dir="ups" 
        Table_Dir="" 
        Table_File="project.table" 
        Archive_File="" 
        Description="" 
        Action=setup
            If( test -d /grid/fermiapp/products/${UPS_PROD_NAME}/prd/bootstrap_${UPS_PROD_NAME} )
            Execute( source `ups setup bootstrap_${UPS_PROD_NAME} -z /grid/fermiapp/products/${UPS_PROD_NAME}/db`, NO_UPS_ENV)
            Else()
            Execute( source `ups setup ${UPS_PROD_NAME} -z /grid/fermiapp/products/${UPS_PROD_NAME}/db`, NO_UPS_ENV)
            Endif( test -d /grid/fermiapp/products/${UPS_PROD_NAME}/prd/bootstrap_${UPS_PROD_NAME} )

  This gives a fairly long list.
It is often more convenient to use the -K option with a
list of keywords for the specific fields you need.

  Use "ups list -K" to
locate product root directory, table file and ups directory

  ups list -K can
be used to locate a product's root directory, table file, and ups directory when used
with the keywords corresponding to these quantities

  Compare the following three
commands and their output. UPS_DIR represents the location of the product's ups directory. If it is not an
absolute path, then it is taken relative to @PROD_DIR , if
specified (as shown in the second command). @UPS_DIR is the
absolute path.

% ups list -K @PROD_DIR git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux64bit-2" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux-2" 

% ups list -K UPS_DIR git
"ups" 
"ups" 
"ups" 

% ups list -K@UPS_DIR git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2/ups" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux64bit-2/ups" 
"/grid/fermiapp/products/common/db/../prd/git/v1_8_0_1/Linux-2/ups" 

  Compare the following two
commands and their output. table_file represents only the name of the table file, not its path. @table_file is
the entire path for the table file. See section 29.4 Determination of ups Directory and Table File Locations for information on how UPS determines the table file directory.

% uups list -Ktable_file git
"git.table" 
"v1_8_0_1.table" 
"v1_8_0_1.table" 

% ups list -K@table_file git
"/nusoft/app/externals/git/v1_8_0_1/Linux64bit-2/ups/git.table" 
"/grid/fermiapp/products/common/db/git/v1_8_0_1.table" 
"/grid/fermiapp/products/common/db/git/v1_8_0_1.table" 

  Parse output from "ups
list -K" in perl

  Here we provide guidance on
parsing ups
list
output in perl , with all the appropriate quoting and spacing. The
following example first defines the file handle UPS_LIST_OUTPUT to contain the
piped output of the command $UPS_DIR/bin/ups list
-aK+
(where $UPS_DIR is
translated inside of perl via the $ENV{UPS_DIR} statement, which is the translation of the environmental variable UPS_DIR ). It then defines the array @fields , and parses the output into
a set of five variables.

open(UPS_LIST_OUTPUT, "| $ENV{UPS_DIR}/bin/ups list -aK+");while (<UPS_LIST_OUTPUT> ) {
# break into the array @fields:
@fields = m/\"((?:[^\"\\]|\\.)*)\"/g;
# then do things with $field[0] $field[1] ...
# (in this case,
# $field[0] = product name
# $field[1] = version
# $field[2] = flavor
# $field[3] = qualifiers (colon-separated list)# $field[4] = chains (colon-separated list)
}

  Say the output from your ups list
-K
command looks like this:

"ups" "v4_4" "Linux+2" "" "current" 

  then the @fields array contains the
variables:

$field[0] = ups
$field[1] = v4_4
$field[2] = Linux+2
$field[3] = 
$field[4] = current

  Alternatively, you could parse
the output this way:

($product, $version, $flavor, $qualifiers, $chains) = m/\"((?:[^\"\\]|\\.)*)\"/g;

  and then you'd have:

$product = ups
$version = v4_4
$flavor = Linux+2
$qualifiers = 
$chains = current

  Parsing output from "ups
list -K" in a sh script

  You can parse the output from a
command of the form ups list -K by
piping it into a " while loop" sh script. Here is an example; explanations follow the
code:

ups list -K... |
while read line
do
     eval set : $line
     shift
# now do things with $1 $2 $3... 
done

  As the condition of the while loop, the read line command reads the lines of output into the variable line . To get rid of the quotes, the loop runs eval set : $line on each line (this syntax ensures that the set command
actually sets the variables $1 , $2 , and so on, instead of setting
shell behavior in case the first argument starts with a dash). The shift that
follows then gets rid of the colon.

  23.12 ups modify

  The ups modify command allows you to manually edit any of the database product
files. It performs syntax and content validation before and after
the editing session.

  23.12.1 Command
Syntax

% ups modify [<options>] <product> [<version>]

  23.12.2 Commonly Used
Options

  See section 23.12.3 All Valid Options for descriptions of each option.

 
Table 23.12.2-a:Table 23.12.2-a:

-E
<editor>
-E
<editor>
-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-N
<fileName>
-N
<fileName>
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.12.3 All Valid
Options

 
Table 23.12.3-a:Table 23.12.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-A -A authorized nodes authorized nodes
-c -c current chain current chain
-d -d development chain development chain
-E
<editor>
-E
<editor>
Invokes the specified editor. If not given,
uses the editor specified by $EDITOR. If not set, uses vi by default. Invokes the specified editor. If not given,
uses the editor specified by $EDITOR. If not set, uses vi by default.
-f
<flavor>
-f
<flavor>
Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list. Finds product instance of specified flavor.
If specified and no exact match is found, the command fails.
Multiple values are accepted, but UPS looks only at the first in the list.
-H
<flavor>
-H
<flavor>
Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list. Specifies flavor and builds a flavor list for
that family starting at the level specified. UPS finds the best match instance for the specified flavor
family. Multiple values are accepted, but UPS looks only at the first in the list.
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-N
<fileName>
-N
<fileName>
Specifies file to be checked and edited Specifies file to be checked and edited
-p
"<description>"
-p
"<description>"
Specifies product description Specifies product description
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t test chain test chain
-T <path or
URL>
-T <path or
URL>
Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format. Specifies archive file path or URL. This is
used only for declarations in distribution databases for which
products are maintained in tar or gzip (archived) format.
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product Specifies the database(s) in which to look
for the product
-Z -Z Times the command Times the command

  23.12.4 More Detailed
Description

  ups modify performs the following steps (if you specify the file using -N ,
the menu will not appear):

  • presents menu of files
    that you can edit and asks you to either select one or quit
  • verifies
    pre-modification contents of file (runs ups verify )
  • starts up the editor
    given by -E
    <editor>
    or, if that is not specified, then $EDITOR,
    if set. If neither is specified, it starts up vi by default.
  • makes a copy of the file
    to be edited
  • pulls copy of file into
    the editor
  • after user exits the
    editor, runs ups verify on
    the edited file
  • if the validation
    succeeds, writes the new file over the old one and quits
  • if the validation does
    not succeed, provides informational messages, and quits
  • if no changes made to
    file, again presents menu of files

  Internal Processes

  • Bring up requested file
    in specified editor
  • Verify the pre-edited
    file
  • Verify the edited file
    before overwriting
  • Process MODIFY
    action
  • Execute the temp
    file

  23.12.5 ups modify
Example

% ups modify git v1_8_5_3 -N $MYDB/git/v1_8_5_3.version

Pre modification verification pass complete.

  In this example, we select the
version file (via -N ) for the
product git v1_8_5_3. Since -E is not given, UPS will use the editor set in $EDITOR, or vi if that variable is not set. First, UPS runs ups verify and
produces the output:

Pre modification verification pass complete.

  No errors were detected. The
version file is next displayed in the editor.

  1. To illustrate
    an unsuccessful validation, we add a bogus line:
TESTKEYWORD = value
and save and quit. %{font-weight: bold;color: #000000}UPS% returns the following messages, and we opt to save the erroneous change:

INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
Post modification verification pass complete.
Do you wish to save this modification [y/n] ? %{font-weight: bold;color: #000000}y% 
 %{font-weight: bold;color: #000000}UPS% quits, saving the file as we requested.
  1. To illustrate
    successful validation, we'll correct the error introduced above. We
    run the same ups modify command. UPS finds the error during the pre-edit validation:
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl
ared/prod1/v1_0.version', line 17
Pre modification verification pass complete.
We remove the incorrect line from the version file, then save and quit. %{font-weight: bold;color: #000000}UPS% displays the following message, and we elect to save the change ( %{font-weight: bold;font-family: monospace}y% ):

Post modification verification pass complete.
Do you wish to save this modification [y/n] ? %{font-weight: bold;color: #000000}y% 
 %{font-weight: bold;color: #000000}UPS% quits, saving the file as requested.

  23.13 ups parent

  The ups parent command can be used to determine which products depend on the
specified product instance(s) as declared in the (local) database.
This command is useful when deciding whether a product instance can
be removed without causing problems for other products. If you need to look things
up frequently, you might want to run the command with the -a option, dump
the output to a file, and search in there.

  23.13.1 Command
Syntax

% ups parent [<options>] <product> [<version>]

  23.13.2 Commonly Used
Options

  See section 23.11.3 All Valid Options for descriptions of each option.

 
Table 23.13.2-a:Table 23.13.2-a:

-a -a
-f
<flavorList>
-f
<flavorList>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-K
<keywordList>
-K
<keywordList>
-l -l
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.13.3 All Valid Options

Table 23.13.3:Table 23.13.3:
-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-a -a Include all instances Include all instances
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-K -K keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN keywords : return information from these (colon-separated)
keywords,
"+" means PRODUCT:VERSION:FLAVOR:QUALIFIERS:CHAIN
-l -l Produce a long listing Produce a long listing
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n new chain new chain
-o -o old chain old chain
-q
<qualifierList>
-q
<qualifierList>
colon separated list of required or optional qualifiers
that are to be part of the instance colon separated list of required or optional qualifiers
that are to be part of the instance
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t test chain test chain
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.13.4 More Detailed
Description

  The ups parent command can be slow. The ups
parent
command runs:

% ups depend product version -f flavor -q qualifiers -H hostflavor

  for every product version -f flavor -q
qualfiers
and for every hostflavor mentioned in the
database. If you look things up frequently, we recommend that you
run:

% ups parent -a

  dump the output to a file, and
search in the file for the information you need.

  23.13.5 ups parent
Example

  If you want to know what
products depend on git , run:

% ups parent git
100% completed.  
git v1_8_5_3 -f Linux64bit+2.6-2.12 -z /fnal/ups/db
|__redmine v1_4_1 -f NULL -z /fnal/ups/db [via  -g current]

git v1_6_4 -f Linux+2 -z /fnal/ups/db
|__redmine v1_0_1 -f NULL -z /fnal/ups/db 
|__redmine v1_4_1 -f NULL -z /fnal/ups/db [via  -g current]

  23.14 ups start

  The ups start command is used to invoke appropriately configured products at
system boot time. This is used primarily for products that need to
load drivers, start daemons or perform other actions required at
boot time. This command is generally not run manually, rather it
gets executed from within a UPS control file.

  The ups stop command
(see section 23.15 ups stop ) is used to stop products that are started this
way.

  23.14.1 Command
Syntax

% ups start [<options>] <product> [<version>]

  23.14.2 Commonly Used
Options

  See section 23.14.3 All Valid Options for descriptions of each option.

 
Table 23.14.2-a:Table 23.14.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-v ( vvv ) -v ( vvv )
-w -w
-z
<databaseList>
-z
<databaseList>

|

  23.14.3 All Valid
Options

 
Table 23.14.3-a:Table 23.14.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-w -w Stops the product first, then restarts
it Stops the product first, then restarts
it
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.14.4 More Detailed
Description

  Please see Chapter 15: Automatic UPS Product Startup and Shutdown for a
detailed description of the use of the ups start command. In brief, it covers:

  • Configuring your machine
    to allow automatic startup/shutdown
  • Installing a UPS product to start and/or stop automatically, for which
    you need to:
    • Determine if auto
      start/stop feature is enabled
    • Determine if product is
      appropriate for autostart
    • Edit control
      file(s)
    • Restart the system

  Internal Processes

  • Check node
    authorization
  • If necessary, process
    STOP action
  • Process START
    action
  • Execute the temp
    file

  23.14.5 ups start
Examples

  Run the command
interactively

  This command first stops
( -w )
the default instance of the product apache , and then restarts it:

% ups start -w apache

  It prints to screen messages of
the format:

Stopping Apache server for fnkits.fnal.gov on port 8000Stopping Apache server for fnkits.fnal.gov on port 8000 account updadmin

  Run the command from a
control file

  This command starts the default
instance of the product ObjectCenter for the flavor Linux, and requests verbose
output ( -v ).

% ups start -v -f Linux ObjectCenter

  If the logon id is root , the line in the control file may look like:

ups start -v -f Linux ObjectCenter

  If the logon id is other than root , the line in the control file must look like:

/bin/su - products -c "ups start -v -f Linux ObjectCenter" 

  23.15 ups stop

  The ups stop command
is used to stop appropriately configured products at system
shutdown. This command is generally not run manually, rather it
gets executed from within a UPS control file, and operates on products that were invoked
using ups
start
(see section 23.14 ups start ). Typically, these products are ones which
need to load drivers, start daemons or perform other actions
required at boot time.

  23.15.1 Command
Syntax

% ups stop [<options>] <product> [<version>]

  23.15.2 Commonly Used
Options

  See section 23.15.3 All Valid Options for descriptions of each option.

 
Table 23.15.2-a:Table 23.15.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-v ( vvv ) -v ( vvv )
-z
<databaseList>
-z
<databaseList>

|

  23.15.3 All Valid
Options

 
Table 23.15.3-a:Table 23.15.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command Times the command

  23.15.4 More Detailed
Description

  Please see Chapter 15: Automatic UPS Product Startup and Shutdown for a
detailed description of the use of the ups stop command. In brief, it covers:

  • Configuring your machine
    to allow automatic startup/shutdown
  • Installing a UPS product to start and/or stop automatically, for which
    you need to:
    • Determine if auto
      start/stop feature is enabled
    • Determine if product is
      appropriate for autostart
    • Edit control
      file(s)
    • Restart the system

  Internal Processes

  • Check node
    authorization
  • Process STOP
    action
  • Execute the temp
    file

  23.15.5 ups stop
Examples

  Run the command
interactively

  This command stops the default
instance of the product apache :

% ups stop apache

  It prints to screen a message
of the format:

Stopping Apache server for fnkits.fnal.gov on port 8000

  Run the command from a
control file

  This command stops the default
instance of the product ObjectCenter for the flavor Linux, and requests verbose
output ( -v ).

% ups stop -v -f Linux ObjectCenter

  If the logon id is root , the line in the control file may look like:

ups stop -v -f Linux ObjectCenter

  If the logon id is other than root , the line in the control file must look like:

/bin/su - products -c "ups stop -v -f Linux ObjectCenter" 

  23.16 ups tailor

  For any product instance whose
table file includes a TAILOR action, the ups tailor command must be run manually at product installation time after the
product is declared to the database in order to execute this
action. A TAILOR action typically includes installation functions
which require input from the installer.

  23.16.1 Command
Syntax

% ups tailor [<options>] <product> [<version>]

  23.16.2 Commonly Used
Options

  See section 23.16.3 All Valid Options for descriptions of each option.

 
Table 23.16.2-a:Table 23.16.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-v ( vvv ) -v ( vvv )
-z
<databaseList>
-z
<databaseList>

|

  23.16.3 All Valid
Options

 
Table 23.16.3-a:Table 23.16.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-K
<keywordList>
-K
<keywordList>
Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords Returns values of specified keywords only;
valid keywords are listed in section 28.4 List of Supported Keywords
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )
-. -. shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace} shorthand for "-r `pwd` -M ups -m ${UPS_PRODUCT}.table" {font-weight: bold;font-family: monospace}

  23.16.4 More Detailed
Description

  Tailoring is the aspect of the
product implementation that requires input from the product
installer (e.g., specifying the location of hardware devices for a
software driver package). If the product requires tailoring, a file
is usually supplied in the format of an interactive executable
(script or compiled binary), and it is run via a function under the
ACTION=TAILOR line in the table file. Configure, tailor and other
supplemental installation scripts are usually maintained in the
product's $<PRODUCT>_DIR/ups directory.
You must explicitly tailor the product instance using the UPS command ups tailor ;
tailoring is not performed automatically.

  Tailoring is generally allowed
on any node of a cluster, however we strongly recommend that you
perform any node-specific tailoring from that node, or
flavor-specific tailoring from a node of that flavor to avoid
mismatches.

  Internal Processes

  • Check node
    authorization
  • Process TAILOR
    action
  • Execute the temp
    file

  23.16.5 ups tailor
Example

  As an example, we show the
tailor process for the product apache :

% ups tailor apache
Current configuration nicknames are:
kits    kits8k
You can:
    a)dd a new server configuration
    q)uit the tailor script
Which would you like? [aq]? a
Webserver alias/name (e.g. www-xx.fnal.gov)? www-demo.fnal.gov
Webserver nickname [demo]? 
Webserver port number [80]? 
Webserver effective user-id [wwwsrv]? 
Webserver effective group-id [www]? 
Webserver admin id [wwwadm]? 
Mail address for admin stuff [mengel@fnal.gov]? demo-admin@fnal.gov
Directory for CGI executables [/fnal/www/demo/cgi-bin]?Directory /fnal/www/demo/cgi-bin doesn't exist, make it [y]? y
Root of served files [/fnal/www/demo/html]? 
Directory /fnal/www/demo/html doesn't exist, make it [y]? yRaw Log file directory [/var/adm/www/demo]? /tmp/demoLog file Summary directory [/fnal/www/demo/html/logs]?Directory /fnal/www/demo/html/logs doesn't exist, make it [y]? y
Current configuration nicknames are:
demo    kits    kits8k
You can:
    a)dd a new server configuration
    q)uit the tailor script
Which would you like? [aq]? q

  23.17 ups touch

  The ups touch command changes the values of the keywords MODIFIED and MODIFIER in
the version file to the current time and the current user,
respectively.

  If you make any changes to a
product's database files by hand (e.g., not via ups modify ), you
should run ups touch afterwards.
You can also run it to prevent an update if you choose to run upd
update
on several product instances at a time.

  23.17.1 Command
Syntax

% ups touch [<options>] <product> [<version>]

  23.17.2 Commonly Used
Options

  See section 23.17.3 All Valid Options for descriptions of each option.

 
Table 23.17.2-a:Table 23.17.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (with a valid number) Or a valid number or -H (with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.17.3 All Valid
Options

 
Table 23.17.3-a:Table 23.17.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-z
<databases>
-z
<databases>
Specifies the database(s) to use Specifies the database(s) to use
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )

  23.17.4 ups touch
Example

  To illustrate this command, we
first run a ups list showing
the modified date/time and the modifier(s) for a product:

% ups list prod1 -aKproduct:modified:modifier
"prod1" "2013-09-08 21.44.04 GMT:2013-09-08 21.38.23 GMT" "olduser:olduser" 

  Now run ups touch to
change these values:

% ups touch prod1

  And verify that they have
changed, by rerunning the ups list command:

% ups list prod1 -aKproduct:modified:modifier
"prod1" "2013-11-19 18.43.00 GMT:2013-09-08 21.38.23 GMT" newuser:olduser" 

  23.18 ups
unconfigure

  For any product instance whose
table file includes an UNCONFIGURE action, the ups unconfigure command executes this action. An UNCONFIGURE action usually
includes functions that reverse, approximately or fully, the
functions run by the CONFIGURE action. The ups unconfigure command gets run by default by ups undeclare when the product is removed from a database (see section 23.19 ups undeclare , in particular the -C option), but
can be run manually as needed.

  23.18.1 Command
Syntax

% ups unconfigure [<options>] <product> [<version>]

  23.18.2 Commonly Used
Options

  See section 23.18.3 All Valid Options for descriptions of each option.

 
Table 23.18.2-a:Table 23.18.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.18.3 All Valid
Options

 
Table 23.18.3-a:Table 23.18.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-P -P Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database) Requires UPS to rely only on information supplied on the command line
to locate the product instance (prevents UPS from searching in a database)
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-s -s Lists what command would do; but does not
execute the command Lists what command would do; but does not
execute the command
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )

  23.18.4 More Detailed
Description

  A product's configuration may
involve creating links to the product root directory from other
areas (see section 16.1.3 Third-Party Products Requiring a Hard-Coded Path ). If
the area is not identical for each node accessing the UPS database in which the product instance has been declared
(i.e., same path but separate areas), then the ups configure command needs to be run manually on each node that mounts a unique
area. Similarly, when removing such a product from a database, you
will need to run the ups unconfigure command manually on each node. If you are not sure whether you need
to unconfigure a product instance on each node, look through the
ACTION=UNCONFIGURE steps in the table file to see what they do.

  Internal Processes

  • Check node
    authorization
  • Process the UNCONFIGURE
    action
  • Execute the temp
    file

  23.18.5 ups unconfigure
Example

  The sample command runs the UNCONFIGURE action in the table file
associated with the product prod1 . If that action is
not present, it undoes all the reversible functions included under
the CONFIGURE action, by default.

% ups unconfigure prod1 v5 -f Linux+2

  This command should take care
of the "unconfiguration" on all the machines of flavor Linux+2 in the cluster. A
command like this, but with the appropriate flavor, must be run for
each machine flavor represented in the cluster.

  23.19 ups undeclare

  The ups undeclare command is used for two separate purposes:

  1. to remove an
    instance from a database (and optionally remove its product root
    directory); the information that gets removed includes:
    • the version file, or the
      portion of the version file, that pertains to the instance
    • any chain files, or the
      portions of any chain files, that pertain to the instance
    • to remove a
      chain from an instance

  23.19.1 Command
Syntax

  For removing an
instance

% ups undeclare <flavor_option> [<other_options>] <product> \ 
<version>

  For removing a
chain

% ups undeclare <chain_option> [<other_options>] <product>

  23.19.2 Commonly Used
Options

  See section 23.18.3 All Valid Options for descriptions of each option.

  For removing an
instance

 
Table 23.19.2-a:Table 23.19.2-a:

-f
<flavor>
-f
<flavor>
Or a valid number of -H (with a valid number) Or a valid number of -H (with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-y -y
-Y -Y
-z
<databaseList>
-z
<databaseList>

|

  For removing a
chain

 
Table 23.19.2-b:Table 23.19.2-b:

-f
<flavor>
-f
<flavor>
Or a valid number or -H (with a valid number) Or a valid number or -H (with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.19.3 All Valid
Options

  Valid only for removing
an instance (not for removing a chain)

 
Table 23.19.3-a:Table 23.19.3-a:

-y -y Deletes product root directory, provides
confirmation prompt Deletes product root directory, provides
confirmation prompt
-Y -Y Deletes product root directory, does not
provide confirmation prompt Deletes product root directory, does not
provide confirmation prompt

  Valid for both
functions

 
Table 23.19.3-b:Table 23.19.3-b:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-C -C When removing a product: Prevents execution
of the UNCONFIGURE action When removing a product: Prevents execution
of the UNCONFIGURE action When removing a chain: Prevents execution of
the corresponding "unchain" action When removing a chain: Prevents execution of
the corresponding "unchain" action
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavor>
-f
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavor>
-H
<flavor>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-O
"<flags>"
-O
"<flags>"
Sets the value of $UPS_OPTIONS to <flags> . Sets the value of $UPS_OPTIONS to <flags> .
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-V -V Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen Does not delete the temporary script files or
partially installed products when command finishes; instead lists
them on the screen
-z
<databases>
-z
<databases>
Specifies the database(s) to use Specifies the database(s) to use
-Z -Z Times the command Times the command

  23.19.4 More Detailed
Description

  Removing a Product
Instance

  % %{font-weight: bold;color: #000000}Using ups undeclare is the recommended procedure for removing product instances.
Removing them manually does not ensure that all the files get
deleted or that chains get updated properly, which can lead to a
fragmented products area.

  To undeclare a product
instance, you must specify the version of the instance, not its chain , in the ups undeclare command. Specifying the chain removes only that chain, not the instance
itself.
When an instance gets "undeclared", all information
pertaining to it is removed from the UPS database in question; this includes:

  • the version file, or the
    portion of the version file, that pertains to the instance
  • any chain files, or the
    portions of any chain files, that pertain to the instance

  You can also opt to remove the
product instance's directory tree starting from its root directory.
To do so, use one of the options -y or -Y ( -y queries you for confirmation, -Y does
not).

  Before removing anything, you
should find out if any other products have the product instance in
question declared as a dependency. If so, you may want to reconsider removing
it. Removal of the product instance may affect the operation of its
parent products.

  We recommend always including a
flavor option if you have a multi-flavor database.

  The ups undeclare command executes ups unconfigure by default (the UNCONFIGURE process can be suppressed by using the -C option, however normally you want this process to execute).

  Special case: If a product has a CONFIGURE action that modifies
files outside of its product root directory, and if this instance
is used by more than one node, flavor or file system, then you may
need to run ups undeclare or ups
unconfigure
on all of the nodes before removing the product
files on any node. Check the product's table file.

  Removing a Chain from an
Instance

  To remove a chain, include the
chain specification in the ups undeclare command, but do not include the version. Including both the chain
and version is bound to be either redundant or incompatible, and
may result in removing the product declaration! We recommend always
including the -f
<flavor>
option if you have a multi-flavored
database.

  Internal Processes

  • Find database to
    use
  • If necessary process
    all appropriate `UNCHAIN' actions
  • Process the UNCONFIGURE
    action
  • Process the UNDECLARE
    action
  • If necessary delete the
    product's home area
  • Execute the temp
    file

  23.19.5 ups undeclare
Examples

  Undeclare an
instance

% ups undeclare -f Linux+2 tcl v8 -y

  In this example, we undeclare
and remove current instance (by default) of the product tcl v8 for the flavor Linus+2 ( -f option) from
the default database. Notice that the version is included for
instance identification as required. We opt to remove the product
root directory after query (lowercase -y option):

Product home directory -
        /export/home/t1/aheavey/upsII/products/tcl/v8/Delete this directory? %{font-weight: bold;color: #000000}y% 

  We respond "y" for yes. To
respond no, we would enter "n".

  Undeclare a chain

% ups undeclare -c ximagetools -f NULL

  In this command, we remove the
"current" chain ( -c option) from
the instance of ximagetools declared as current for the flavor NULL
( -f option). Notice that the version is not included!

  If multiple flavor/qualifier pairs share the chain file in question
(in which case you need to specify the flavor/qualifier information
on the command line), only the portion of the chain file pertaining
to the specified instance will get removed; the file itself will
not be deleted.

  23.20 ups verify

  The ups verify command checks the integrity of the database files for the
specified product(s), and lists any errors and inconsistencies that
it finds.

  The ups verify command gets run by ups modify before and after file editing (see section 23.12 ups modify ). ups verify can
also be run manually as needed.

  23.20.1 Command
Syntax

% ups verify [<options>] [<product>] [<version>]

  23.20.2 Commonly Used
Options

  See section 23.20.3 All Valid Options for descriptions of each option.

 
Table 23.20.2-a:Table 23.20.2-a:

-f
<flavorList>
-f
<flavorList>
Or a valid number or -H (alone or with a valid number) Or a valid number or -H (alone or with a valid number)
-g
<chainName>
-g
<chainName>
Or one of -c , -d , -n , -o , -t Or one of -c , -d , -n , -o , -t
-q
<qualifierList>
-q
<qualifierList>
-z
<databaseList>
-z
<databaseList>

|

  23.20.3 All Valid
Options

 
Table 23.20.3-a:Table 23.20.3-a:

-? ( "-?" for csh ) -? ( "-?" for csh ) Prints command description and option usage
information to screen Prints command description and option usage
information to screen
-a -a Verifies files for all instances that match
the other options given on command line Verifies files for all instances that match
the other options given on command line
-c -c Finds product instance chained to
"current" Finds product instance chained to
"current"
-d -d Finds product instance chained to
"development" Finds product instance chained to
"development"
-f
<flavorList>
-f
<flavorList>
Described in "The flavor
options."
Described in "The flavor
options."
-g
<chainName>
-g
<chainName>
Finds product instance chained to <chainName> Finds product instance chained to <chainName>
-H
<flavorList>
-H
<flavorList>
Described in "The flavor
options."
Described in "The flavor
options."
-m
<tableFileName>
-m
<tableFileName>
Specifies table file name Specifies table file name
-M
<tableFileDir>
-M
<tableFileDir>
Specifies table file directory Specifies table file directory
-n -n Finds product instance chained to "new" Finds product instance chained to "new"
-o -o Finds product instance chained to "old" Finds product instance chained to "old"
-q
<qualifierList>
-q
<qualifierList>
Finds product instance with the specified
qualifiers (required and/or optional) Finds product instance with the specified
qualifiers (required and/or optional)
-r
<prodRootDir>
-r
<prodRootDir>
Specifies the product root directory Specifies the product root directory
-t -t Finds product instance chained to
"test" Finds product instance chained to
"test"
-U
<upsDir>
-U
<upsDir>
Specifies location of ups directory; default value is ups Specifies location of ups directory; default value is ups
-v ( vvv ) -v ( vvv ) Prints out extra debugging information. Prints out extra debugging information.
-z
<databaseList>
-z
<databaseList>
Specifies the database(s) in which to look
for the product and its dependencies Specifies the database(s) in which to look
for the product and its dependencies
-Z -Z Times the command (does not include time for
sourcing of temp file for setup/unsetup ) Times the command (does not include time for
sourcing of temp file for setup/unsetup )

  23.20.4 ups verify
Example

% ups verify -z $MYDB prod1

  For this example, we have given
an erroneous value to the TABLE_FILE keyword in the version file
for this product. The command output shows:

ERROR: No instance matches were made between theversion file (/home/t1/aheavey/upsII/declared/prod1/v1_0.version) and the
table file (v1_1.table) for flavor (NULL) and qualifiers ()ERROR: Possible UPS database (/home/t1/aheavey/upsII/declared) corruption in pro
duct 'prod1'.
ERROR: No instance matches were made between the chain file (/home/t1/aheavey/up
sII/declared/prod1/current.chain) and the version file (v1_0.version)
ERROR: Possible UPS database (/home/t1/aheavey/upsII/declared) corruption in pro
duct 'prod1'.

 

TOC PREV NEXT

This page last revised May
2014