![]() |
![]() |
![]() |
![]() |
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.
![]() |
![]() |
![]() |
This page last revised in June
2014
![]() |
![]() |
![]() |
![]() |
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.
![]() |
![]() |
![]() |
This page last revised in June
2014