Project

General

Profile

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

Chapter Contents

Chapter 3: UPS Operations for the End User
   3.1 Determining your Machine's
Flavor

   3.2 Listing Product Information in a
Database

     3.2.1 Formatted Output
Style

     3.2.2 Condensed Output
Style

     3.2.3 Examples
   3.3 Finding a Product's
Dependencies

   3.4 Setting up a Product
     3.4.1 The setup Command
Without Options

     3.4.2 The setup Command with the -q Option

  Chapter 3: UPS Operations
for the End User

  The software for experiments rely on external tools.
These packages and tools are referred to as external products, or simply products.
Access to external products is provided by a Fermilab-developed product-management
package called Unix Product Support (UPS).
This chapter describes how to
get information about UPS products that are installed on a user system and
declared to a UPS database, and how to access them.

Since the target
audience includes all levels of UPS users, the information and examples
are relatively uncomplicated. See Chapter 23: UPS Command Reference for command descriptions and
command-specific option descriptions, and Chapter 26: UPS/UPD Command Usage for a complete description of
command syntax.

  This chapter first shows
how to find information about
machines and the available products, and then how
to access the products. The topics covered include:

  • determining the flavor
    of your machine ( ups flavor )
  • finding what products
    are installed in the UPS database on your system, and finding information about
    them ( ups
    list
    )and ups list -K which provides output in script-readable format.
  • determining what a
    product's dependencies are ( ups depend )
  • accessing (running setup on) a
    product

 

|
p<>.  

  • To get on-line usage information or help, run the command with "-?" , e.g., ups list
    "-?"
    , to get an option listing. The double quotes are
    necessary for C shell users; -? is
    interpreted by sh .
  • Mistyping a word may result in an unhelpful error message or nothing being done.
    e.g.,
    ups flavors%
    ERROR: Need unique instance but multiple "products" found
    It should be 'ups flavor'
    |

  3.1 Determining your
Machine's Flavor

  The ups flavor command returns flavor information about the machine issuing the
command, or for a flavor requested via the -H
<flavor>
option. The full command description for ups
flavor
is given in the reference section 23.8 ups flavor . When entered with no options, the command
returns the full OS specification of the machine, for example:

% ups flavor
Linux64bit+2.6-2.12

  When entered with the -l (long) option, it returns a flavor table , which takes the basic flavor and
lists it at every level of specificity to find
or declare a product instance. For example:

% ups flavor -l
Linux64bit+2.6-2.12
Linux64bit+2.6-2.11
Linux64bit+2.6-2.10
(many more)
Linux+2.6
(many more)
Linux
NULL
ANY

  The ups flavor command
can also be used with numbers, starting with 0 which gives NULL, -1 is basic Operating
System only, -2 is basic Operating System plus the version, with higher numbers
giving more details about release, patch, and build. No number gives the greatest
level of detail defined.
For example:

% ups flavor
Linux64bit+2.6-2.12
% ups flavor -4
Linux64bit+2.6-2.12

  3.2 Listing Product
Information in a Database

  The ups list command
returns information about the declared product instances in a UPS database. It finds
what products are in the database, what the current version of a
product is for a machine's flavor and what other versions might
be available. Two output styles are provided: a
formatted one easy for users to read, and a condensed one
for parsing by a subsequent command or a script.

  Information required is specified
by including options and
arguments 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
requesting machine. The
command syntax, including several of the commonly-used options, is:

% ups list [-a] [-f <flavorList>] [<chainFlag>] [-K <keywordList>]\
 [-l] [-q <qualifierList>] [<product>] [<version>]

  The full command description
for ups
list
is given in the reference section 23.11 ups list .

  3.2.1 Formatted Output
Style

  One output style is for visual
parsing (this is the default output, which we call formatted ), with multi-line output, e.g.:

% ups list ups
DATABASE=/fnal/ups/db
        Product=ups     Version=v5_0_4  Flavor=Linux64bit+2
                Qualifiers=""   Chain=current

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

  3.2.2 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 (upper
case) to request output in the condensed format.

% ups list -K+ ups
"ups" "v5_0_4" "Linux64bit+2" "" "current" 

The -K option
requires an argument list specifying which fields to include in the
output. For guidance on parsing the condensed output in perl or in a sh script, see the reference section 23.11 ups list .

  -K Usage Notes

  • The arguments for -K are not case-sensitive.
  • The plus sign
    ( )
    argument, e.g., -K , is a
    shorthand for requesting the default fields product:version:flavor:qualifiers:chain .
  • Leaving a space
    immediately after the -K is
    optional.
  • Separate the keywords
    using colons (:)

  Commonly Used Keyword
Arguments

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

  PRODUCT

  product name

  FLAVOR

  product flavor

  VERSION

  product version

  QUALIFIERS

  additional instance
specification information often used to indicate compilation
options used by developer

  CHAIN

  product instance
chain

  +

  all of the
above

  The full list of keywords and
their definitions can be found in section 23.11.4 More Detailed Description .

  3.2.3 Examples

  For many of the examples that
follow, the output is edited for brevity.

  List All Current
Products

  The simplest way to request a
listing of all the current product instances in your default UPS database is to use the ups list command
with no options or arguments:

% ups list
DATABASE=/fnal/ups/db
        Product=cvs     Version=v1_11_17        Flavor=Linux+2
                Qualifiers=""   Chain=current

        Product=cvsh    Version=v1_12   Flavor=Linux+2Qualifiers=""   Chain=current

        Product=fnal_git_notifier       Version=v0_11_2 Flavor=Linux64bit+2Qualifiers=""   Chain=current

...

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

        Product=wu_ftpd Version=v2_6_2p2        Flavor=Linux+2Qualifiers=""   Chain=current

  Use of the -K option with
the + argument
provides the same information as the previous example, but
condensed to one line per product instance, e.g.,:

% ups list -K+
"cvs" "v1_11_17" "Linux+2" "" "current" 
"cvsh" "v1_12" "Linux+2" "" "current" 
"fnal_git_notifier" "v0_11_2" "Linux64bit+2" "" "current" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" "" "current" 
...
"upd_libs" "v5_8_5" "Linux+2" "" "current" 
"ups" "v5_0_4" "Linux64bit+2" "" "current" 
"wu_ftpd" "v2_6_2p2" "Linux+2" "" "current" 

  If $PRODUCTS contains multiple databases, output is returned for
the selected products in all of them. However, when using -K 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):

% ups list -aK+:DB
"cvs" "v1_12_13p1" "Linux+2" "" "" "/fnal/ups/db" 
"cvs" "v1_12_13" "Linux+2" "" "" "/fnal/ups/db" 
...

  List All Product
Instances

  Use the -a option to
list all instances ( -a for all) of
the product ups :

% ups list -a ups
DATABASE=/fnal/ups/db
        Product=ups     Version=v4_9_6  Flavor=Linux+2
                Qualifiers=""   Chain="" 

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

        Product=ups     Version=v4_9_5  Flavor=Linux+2
                Qualifiers=""   Chain="" 

...

  List the same information as
the previous example in condensed format:

% ups list -aK+ ups
"ups" "v4_9_6" "Linux+2" "" "" 
"ups" "v5_0_4" "Linux64bit+2" "" "current" 
"ups" "v4_9_5" "Linux+2" "" "" 

  Taking this example one step
further, pipe the output to the grep command,
for example:

% ups list -aK+ ups | grep 64
"ups" "v5_0_4" "Linux64bit+2" "" "current" 

  Specify Output
Fields

  Instead of using the + argument with -K to get the
default fields, particular fields can be specified. For example, to
output a list of product names and version numbers for all the
current products, use the command:

% ups list -K product:version

  This (on novagpvm02) produces:

"allinea_tools" "v4_1_1" 
"cetpkgsupport" "v1_04_02" 
"cmake" "v2_8_8" 
"git" "v1_8_0_1" 
"sam_web_client" "v1_3" 
"totalview" "v8_11_0" 
"upd" "v4_7_5" 
(and many more)

  Request Detailed
Information for a Product Instance

  Administrative users may need
detailed information about a product which the -l option (lower
case -L ) provides. A
request for information on the current instance of a single product
using the long output format (not available with the -K option) gives
the following:

% ups list art v1_08_10 -q debug:e4:nu -l
DATABASE=/nusoft/app/externals
        Product=art     Version=v1_08_10        Flavor=Linux64bit+2.6-2.5
                Qualifiers="debug:e4:nu"        Chain="" 
                Declared="Tue Dec 03 23:10:24 CST 2013" 
                Declarer="CET" 
                Modified="Tue Dec 03 23:10:24 CST 2013" 
                Modifier="CET" 
                Home=/nusoft/app/externals/art/v1_08_10
                No Compile Directive
                Authorized, Nodes=*
                UPS_Dir="ups" 
                Table_Dir="" 
                Table_File="art.table" 
                Archive_File="" 
                Description="" 
                Action=GetFQDir
                        envSet( ${UPS_PROD_NAME_UC}_FQ, "" )
                        execute( "get-directory-name subdir nu.e4.debug ${UPS_PROD_FLAVOR}", NO_UPS_ENV, ${UPS_PROD_NAME_UC}_FQ )
                        fileTest( ${UPS_PROD_DIR}/${${UPS_PROD_NAME_UC}_FQ}, -d, "${UPS_PROD_DIR}/${${UPS_PROD_NAME_UC}_FQ} directory not found: SETUP ABORTED")
                Action=GetProducts
                        envSet( ${UPS_PROD_NAME_UC}_CXXFLAGS, "" )
                        envSet( ${UPS_PROD_NAME_UC}_CFLAGS, "" )
                        setupRequired( messagefacility v1_10_26 -q +e4:+debug )
                        setupRequired( root v5_34_12 -q +e4:+nu:+debug )
                        setupRequired( clhep v2_1_3_1 -q +e4:+debug )
                        setupRequired( cppunit v1_12_1 -q +e4:+debug )
                        setupRequired( gccxml v0_9_20130621 )
                        setupRequired( python v2_7_5c )
                        setupRequired( sqlite v3_08_00_02 )
                        setupRequired( gcc v4_8_1 )
                        setupRequired( tbb v4_1_3 -q +e4:+debug )
(and much more)

  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 needed.

  3.3 Finding a Product's
Dependencies

  The ups depend command lists dependencies of specified product instance(s) as
declared in the local database. It can be used to determine what
products will get set up along with the main product, or to
determine what products need to be available in order to
successfully set up the main one. Shown with some commonly-used
options, the command syntax is:

% ups depend [-f <flavorList>] [<chainFlag>] [-j] \
[-K <keywordList>] [-q <qualifierList>] [-R] <product> [<version>]

  The full command description
for ups
depend
is given in the reference section 23.6 ups depend .

  Dependency information is also
included in the output of the ups list -l command. When using ups list -l ,
the dependencies must be inferred by looking at the setupRequired and setupOptional functions under the SETUP action. It does not provide information on lower level
dependencies.

  Examples

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

% ups depend art v1_08_10 -B -q debug:e4:nu
art v1_08_10 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|__cetpkgsupport v1_05_03 -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
|  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |__fhiclcpp v2_17_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |  |__cetlib v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |  |  |__cpp0x v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |  |  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |  |  |  |__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
|  |  |  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__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
|  |  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__xerces_c v3_1_1 -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
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__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
|  |__clhep v2_1_3_1 -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
|  |__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
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__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
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__xrootd v3_3_4 -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
|  |__libxml2 v2_9_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__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
|  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__clhep v2_1_3_1 -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
|__cppunit v1_12_1 -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
|__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
|__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
|__sqlite v3_08_00_02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__tbb v4_1_3 -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

  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

  The ups depend command accepts the -K option
described in section 3.2.2 Condensed Output Style to return a subset of the output
fields. Using the -R option again
with the same product instance, with -K to specify
output fields:

% ups depend -RK product:version:flavor redmine
"redmine" "v1_4_1" "NULL" 
"ruby" "v1_9_3" "Linux64bit+2.6-2.12" 
"cvs" "v1_12_13" "Linux+2" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" 
"subversion" "local" "Linux64bit+2.6-2.12" 

  Use the -j option to
request "just" the direct dependencies of the specified product,
omitting dependencies of dependencies (again, the same instance is
used to allow comparison):

% ups depend -j redmine
redmine v1_4_1 -f NULL -z /fnal/ups/db -j -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

  3.4 Setting up a
Product

  An installed, declared UPS product instance requires that the setup command be
issued prior to use, unless it has already been set up as a
dependency of another product. The setup command
performs the necessary operations in your login environment to make
an installed, declared product accessible to you. Typically, the
operations include modifying environment variables or adding to
your $PATH. Many options are available for the setup command,
as listed in the reference section 23.1 setup . Here we show the syntax with a few of the more
commonly-used options:

 %{font-weight: normal;color: #000000} !images/pointb.gif!  % % setup [-f <flavor>] [<chainFlag>] [-q <qualifierList>] \
[-z <databaseList>] <product> [<version>]

  Note that you can only have one
instance of a product 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. If you want to be extra careful, you can log
out and log back in.

  3.4.1 The setup Command Without Options

  Current Instance

  Often users want
the default current version of a product. In some projects, the only thing that needs
to be specified is the product name.

% setup upd

This is useful, for example, when the user has scripts that require some version of
a product, but it doesn't matter which one. Then the default behavior is useful.
When run, the UPS system automatically inserts the version and qualifiers of the version
that has been declared current. Having a current version is a handy convenience for products
that add features; as improvements are added, you
automatically get them.

But, if the exact version must be specified, please see the next section.

  3.4.2 The setup Command with -q Option

  Without strict dependencies, if the dependencies for a package involve different
versions of the same package, UPS chooses the first one it sees. With the -B flag, it is
an error to have conflicts in dependencies. This is to ensure that the exact version and
qualifiers are requested to avoid having a default qualifier change in a poorly documented
fashion, making it difficult to reproduce results.

To set up a product instance
that has been declared with qualifiers, the -q option is specified
on the command line.
Qualifiers are case-sensitive, and must be entered on the command
line exactly as they appear in the product declaration. A qualifier
may be preceded by one of two operators ( -q
[+|?]qualifier
) which explicitly makes the qualifier mandatory ( + ) or optional ( ? ).

A qualifier
not preceded by either operator is variable , and means
that the qualifier is:

  • mandatory when used with
    a command that sets a qualifier, e.g., ups declare , upd
    addproduct
  • optional when used with
    a command that must find a product instance and then do something with the product
    instance, e.g., setup , ups
    list
    , ups depend , upd
    install
    , and so on.

For example, to set up an instance of art, the command is:

% setup -B art v1_08_09 -q+e4:+mu2e:+prof

The version is specified as v1_08_09. The qualifier "e4" is shorthand defined by the art team
for a compiler version and other specifics. When another product is built with the "e4"
qualifier, it can be linked against a version of art that was also built with the "e4"
qualifier. The qualifier "prof" requests a version that was built with maximum optimization
and with some, but not all, debugger symbols retained. Qualifiers are used to keep the
bookkeeping straight for multiple builds of one version of a product.

  For more examples, see the
reference section 23.1 setup .

  See the reference section 25.2.4 -q for more information on specifying qualifiers on the
command line.

 

TOC PREV NEXT

This page last revised in June
2014

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

Chapter Contents

Chapter 3: UPS Operations for the End User
   3.1 Determining your Machine's
Flavor

   3.2 Listing Product Information in a
Database

     3.2.1 Formatted Output
Style

     3.2.2 Condensed Output
Style

     3.2.3 Examples
   3.3 Finding a Product's
Dependencies

   3.4 Setting up a Product
     3.4.1 The setup Command
Without Options

     3.4.2 The setup Command with the -q Option

  Chapter 3: UPS Operations
for the End User

  The software for experiments rely on external tools.
These packages and tools are referred to as external products, or simply products.
Access to external products is provided by a Fermilab-developed product-management
package called Unix Product Support (UPS).
This chapter describes how to
get information about UPS products that are installed on a user system and
declared to a UPS database, and how to access them.

Since the target
audience includes all levels of UPS users, the information and examples
are relatively uncomplicated. See Chapter 23: UPS Command Reference for command descriptions and
command-specific option descriptions, and Chapter 26: UPS/UPD Command Usage for a complete description of
command syntax.

  This chapter first shows
how to find information about
machines and the available products, and then how
to access the products. The topics covered include:

  • determining the flavor
    of your machine ( ups flavor )
  • finding what products
    are installed in the UPS database on your system, and finding information about
    them ( ups
    list
    )and ups list -K which provides output in script-readable format.
  • determining what a
    product's dependencies are ( ups depend )
  • accessing (running setup on) a
    product

 

|
p<>.  

  • To get on-line usage information or help, run the command with "-?" , e.g., ups list
    "-?"
    , to get an option listing. The double quotes are
    necessary for C shell users; -? is
    interpreted by sh .
  • Mistyping a word may result in an unhelpful error message or nothing being done.
    e.g.,
    ups flavors%
    ERROR: Need unique instance but multiple "products" found
    It should be 'ups flavor'
    |

  3.1 Determining your
Machine's Flavor

  The ups flavor command returns flavor information about the machine issuing the
command, or for a flavor requested via the -H
<flavor>
option. The full command description for ups
flavor
is given in the reference section 23.8 ups flavor . When entered with no options, the command
returns the full OS specification of the machine, for example:

% ups flavor
Linux64bit+2.6-2.12

  When entered with the -l (long) option, it returns a flavor table , which takes the basic flavor and
lists it at every level of specificity to find
or declare a product instance. For example:

% ups flavor -l
Linux64bit+2.6-2.12
Linux64bit+2.6-2.11
Linux64bit+2.6-2.10
(many more)
Linux+2.6
(many more)
Linux
NULL
ANY

  The ups flavor command
can also be used with numbers, starting with 0 which gives NULL, -1 is basic Operating
System only, -2 is basic Operating System plus the version, with higher numbers
giving more details about release, patch, and build. No number gives the greatest
level of detail defined.
For example:

% ups flavor
Linux64bit+2.6-2.12
% ups flavor -4
Linux64bit+2.6-2.12

  3.2 Listing Product
Information in a Database

  The ups list command
returns information about the declared product instances in a UPS database. It finds
what products are in the database, what the current version of a
product is for a machine's flavor and what other versions might
be available. Two output styles are provided: a
formatted one easy for users to read, and a condensed one
for parsing by a subsequent command or a script.

  Information required is specified
by including options and
arguments 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
requesting machine. The
command syntax, including several of the commonly-used options, is:

% ups list [-a] [-f <flavorList>] [<chainFlag>] [-K <keywordList>]\
 [-l] [-q <qualifierList>] [<product>] [<version>]

  The full command description
for ups
list
is given in the reference section 23.11 ups list .

  3.2.1 Formatted Output
Style

  One output style is for visual
parsing (this is the default output, which we call formatted ), with multi-line output, e.g.:

% ups list ups
DATABASE=/fnal/ups/db
        Product=ups     Version=v5_0_4  Flavor=Linux64bit+2
                Qualifiers=""   Chain=current

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

  3.2.2 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 (upper
case) to request output in the condensed format.

% ups list -K+ ups
"ups" "v5_0_4" "Linux64bit+2" "" "current" 

The -K option
requires an argument list specifying which fields to include in the
output. For guidance on parsing the condensed output in perl or in a sh script, see the reference section 23.11 ups list .

  -K Usage Notes

  • The arguments for -K are not case-sensitive.
  • The plus sign
    ( )
    argument, e.g., -K , is a
    shorthand for requesting the default fields product:version:flavor:qualifiers:chain .
  • Leaving a space
    immediately after the -K is
    optional.
  • Separate the keywords
    using colons (:)

  Commonly Used Keyword
Arguments

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

  PRODUCT

  product name

  FLAVOR

  product flavor

  VERSION

  product version

  QUALIFIERS

  additional instance
specification information often used to indicate compilation
options used by developer

  CHAIN

  product instance
chain

  +

  all of the
above

  The full list of keywords and
their definitions can be found in section 23.11.4 More Detailed Description .

  3.2.3 Examples

  For many of the examples that
follow, the output is edited for brevity.

  List All Current
Products

  The simplest way to request a
listing of all the current product instances in your default UPS database is to use the ups list command
with no options or arguments:

% ups list
DATABASE=/fnal/ups/db
        Product=cvs     Version=v1_11_17        Flavor=Linux+2
                Qualifiers=""   Chain=current

        Product=cvsh    Version=v1_12   Flavor=Linux+2Qualifiers=""   Chain=current

        Product=fnal_git_notifier       Version=v0_11_2 Flavor=Linux64bit+2Qualifiers=""   Chain=current

...

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

        Product=wu_ftpd Version=v2_6_2p2        Flavor=Linux+2Qualifiers=""   Chain=current

  Use of the -K option with
the + argument
provides the same information as the previous example, but
condensed to one line per product instance, e.g.,:

% ups list -K+
"cvs" "v1_11_17" "Linux+2" "" "current" 
"cvsh" "v1_12" "Linux+2" "" "current" 
"fnal_git_notifier" "v0_11_2" "Linux64bit+2" "" "current" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" "" "current" 
...
"upd_libs" "v5_8_5" "Linux+2" "" "current" 
"ups" "v5_0_4" "Linux64bit+2" "" "current" 
"wu_ftpd" "v2_6_2p2" "Linux+2" "" "current" 

  If $PRODUCTS contains multiple databases, output is returned for
the selected products in all of them. However, when using -K 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):

% ups list -aK+:DB
"cvs" "v1_12_13p1" "Linux+2" "" "" "/fnal/ups/db" 
"cvs" "v1_12_13" "Linux+2" "" "" "/fnal/ups/db" 
...

  List All Product
Instances

  Use the -a option to
list all instances ( -a for all) of
the product ups :

% ups list -a ups
DATABASE=/fnal/ups/db
        Product=ups     Version=v4_9_6  Flavor=Linux+2
                Qualifiers=""   Chain="" 

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

        Product=ups     Version=v4_9_5  Flavor=Linux+2
                Qualifiers=""   Chain="" 

...

  List the same information as
the previous example in condensed format:

% ups list -aK+ ups
"ups" "v4_9_6" "Linux+2" "" "" 
"ups" "v5_0_4" "Linux64bit+2" "" "current" 
"ups" "v4_9_5" "Linux+2" "" "" 

  Taking this example one step
further, pipe the output to the grep command,
for example:

% ups list -aK+ ups | grep 64
"ups" "v5_0_4" "Linux64bit+2" "" "current" 

  Specify Output
Fields

  Instead of using the + argument with -K to get the
default fields, particular fields can be specified. For example, to
output a list of product names and version numbers for all the
current products, use the command:

% ups list -K product:version

  This (on novagpvm02) produces:

"allinea_tools" "v4_1_1" 
"cetpkgsupport" "v1_04_02" 
"cmake" "v2_8_8" 
"git" "v1_8_0_1" 
"sam_web_client" "v1_3" 
"totalview" "v8_11_0" 
"upd" "v4_7_5" 
(and many more)

  Request Detailed
Information for a Product Instance

  Administrative users may need
detailed information about a product which the -l option (lower
case -L ) provides. A
request for information on the current instance of a single product
using the long output format (not available with the -K option) gives
the following:

% ups list art v1_08_10 -q debug:e4:nu -l
DATABASE=/nusoft/app/externals
        Product=art     Version=v1_08_10        Flavor=Linux64bit+2.6-2.5
                Qualifiers="debug:e4:nu"        Chain="" 
                Declared="Tue Dec 03 23:10:24 CST 2013" 
                Declarer="CET" 
                Modified="Tue Dec 03 23:10:24 CST 2013" 
                Modifier="CET" 
                Home=/nusoft/app/externals/art/v1_08_10
                No Compile Directive
                Authorized, Nodes=*
                UPS_Dir="ups" 
                Table_Dir="" 
                Table_File="art.table" 
                Archive_File="" 
                Description="" 
                Action=GetFQDir
                        envSet( ${UPS_PROD_NAME_UC}_FQ, "" )
                        execute( "get-directory-name subdir nu.e4.debug ${UPS_PROD_FLAVOR}", NO_UPS_ENV, ${UPS_PROD_NAME_UC}_FQ )
                        fileTest( ${UPS_PROD_DIR}/${${UPS_PROD_NAME_UC}_FQ}, -d, "${UPS_PROD_DIR}/${${UPS_PROD_NAME_UC}_FQ} directory not found: SETUP ABORTED")
                Action=GetProducts
                        envSet( ${UPS_PROD_NAME_UC}_CXXFLAGS, "" )
                        envSet( ${UPS_PROD_NAME_UC}_CFLAGS, "" )
                        setupRequired( messagefacility v1_10_26 -q +e4:+debug )
                        setupRequired( root v5_34_12 -q +e4:+nu:+debug )
                        setupRequired( clhep v2_1_3_1 -q +e4:+debug )
                        setupRequired( cppunit v1_12_1 -q +e4:+debug )
                        setupRequired( gccxml v0_9_20130621 )
                        setupRequired( python v2_7_5c )
                        setupRequired( sqlite v3_08_00_02 )
                        setupRequired( gcc v4_8_1 )
                        setupRequired( tbb v4_1_3 -q +e4:+debug )
(and much more)

  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 needed.

  3.3 Finding a Product's
Dependencies

  The ups depend command lists dependencies of specified product instance(s) as
declared in the local database. It can be used to determine what
products will get set up along with the main product, or to
determine what products need to be available in order to
successfully set up the main one. Shown with some commonly-used
options, the command syntax is:

% ups depend [-f <flavorList>] [<chainFlag>] [-j] \
[-K <keywordList>] [-q <qualifierList>] [-R] <product> [<version>]

  The full command description
for ups
depend
is given in the reference section 23.6 ups depend .

  Dependency information is also
included in the output of the ups list -l command. When using ups list -l ,
the dependencies must be inferred by looking at the setupRequired and setupOptional functions under the SETUP action. It does not provide information on lower level
dependencies.

  Examples

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

% ups depend art v1_08_10 -B -q debug:e4:nu
art v1_08_10 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4:nu
|__cetpkgsupport v1_05_03 -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
|  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |__fhiclcpp v2_17_12 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |  |__cetlib v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |  |  |__cpp0x v1_03_25 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug:e4
|  |  |  |  |__cetpkgsupport v1_05_03 -f NULL -z /nusoft/app/externals -g current
|  |  |  |  |__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
|  |  |  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__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
|  |  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__xerces_c v3_1_1 -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
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |  |__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
|  |__clhep v2_1_3_1 -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
|  |__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
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__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
|  |  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|  |__xrootd v3_3_4 -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
|  |__libxml2 v2_9_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals -q debug
|  |__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
|  |__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__clhep v2_1_3_1 -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
|__cppunit v1_12_1 -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
|__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
|__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
|__sqlite v3_08_00_02 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__gcc v4_8_1 -f Linux64bit+2.6-2.5 -z /nusoft/app/externals
|__tbb v4_1_3 -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

  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

  The ups depend command accepts the -K option
described in section 3.2.2 Condensed Output Style to return a subset of the output
fields. Using the -R option again
with the same product instance, with -K to specify
output fields:

% ups depend -RK product:version:flavor redmine
"redmine" "v1_4_1" "NULL" 
"ruby" "v1_9_3" "Linux64bit+2.6-2.12" 
"cvs" "v1_12_13" "Linux+2" 
"git" "v1_8_5_3" "Linux64bit+2.6-2.12" 
"subversion" "local" "Linux64bit+2.6-2.12" 

  Use the -j option to
request "just" the direct dependencies of the specified product,
omitting dependencies of dependencies (again, the same instance is
used to allow comparison):

% ups depend -j redmine
redmine v1_4_1 -f NULL -z /fnal/ups/db -j -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

  3.4 Setting up a
Product

  An installed, declared UPS product instance requires that the setup command be
issued prior to use, unless it has already been set up as a
dependency of another product. The setup command
performs the necessary operations in your login environment to make
an installed, declared product accessible to you. Typically, the
operations include modifying environment variables or adding to
your $PATH. Many options are available for the setup command,
as listed in the reference section 23.1 setup . Here we show the syntax with a few of the more
commonly-used options:

 %{font-weight: normal;color: #000000} !images/pointb.gif!  % % setup [-f <flavor>] [<chainFlag>] [-q <qualifierList>] \
[-z <databaseList>] <product> [<version>]

  Note that you can only have one
instance of a product 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. If you want to be extra careful, you can log
out and log back in.

  3.4.1 The setup Command Without Options

  Current Instance

  Often users want
the default current version of a product. In some projects, the only thing that needs
to be specified is the product name.

% setup upd

This is useful, for example, when the user has scripts that require some version of
a product, but it doesn't matter which one. Then the default behavior is useful.
When run, the UPS system automatically inserts the version and qualifiers of the version
that has been declared current. Having a current version is a handy convenience for products
that add features; as improvements are added, you
automatically get them.

But, if the exact version must be specified, please see the next section.

  3.4.2 The setup Command with -q Option

  Without strict dependencies, if the dependencies for a package involve different
versions of the same package, UPS chooses the first one it sees. With the -B flag, it is
an error to have conflicts in dependencies. This is to ensure that the exact version and
qualifiers are requested to avoid having a default qualifier change in a poorly documented
fashion, making it difficult to reproduce results.

To set up a product instance
that has been declared with qualifiers, the -q option is specified
on the command line.
Qualifiers are case-sensitive, and must be entered on the command
line exactly as they appear in the product declaration. A qualifier
may be preceded by one of two operators ( -q
[+|?]qualifier
) which explicitly makes the qualifier mandatory ( + ) or optional ( ? ).

A qualifier
not preceded by either operator is variable , and means
that the qualifier is:

  • mandatory when used with
    a command that sets a qualifier, e.g., ups declare , upd
    addproduct
  • optional when used with
    a command that must find a product instance and then do something with the product
    instance, e.g., setup , ups
    list
    , ups depend , upd
    install
    , and so on.

For example, to set up an instance of art, the command is:

% setup -B art v1_08_09 -q+e4:+mu2e:+prof

The version is specified as v1_08_09. The qualifier "e4" is shorthand defined by the art team
for a compiler version and other specifics. When another product is built with the "e4"
qualifier, it can be linked against a version of art that was also built with the "e4"
qualifier. The qualifier "prof" requests a version that was built with maximum optimization
and with some, but not all, debugger symbols retained. Qualifiers are used to keep the
bookkeeping straight for multiple builds of one version of a product.

  For more examples, see the
reference section 23.1 setup .

  See the reference section 25.2.4 -q for more information on specifying qualifiers on the
command line.

 

TOC PREV NEXT

This page last revised in June
2014