Project

General

Profile

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

Chapter Contents

Chapter 30: Chain Files
   30.1 About Chain Files
   30.2 Keywords Used in Chain Files
   30.3 Chain File Examples
     30.3.1 Sample chain file for exmh v1_6_6
     30.3.2 Sample chain file for foo v2_0

  Chapter 30: Chain Files

  UPS/UPD supports chains to product versions, and chain information is maintained in chain files. In this chapter we describe chain files and how they interact with version files.

  30.1 About Chain Files

  Chains for a product are maintained in chain files which reside in the product-specific directory under the UPS database directory. There is one chain file for each chain name, and it is named according to the chain name, with a suffix of .chain , e.g., current.chain . A chain file is automatically created by UPS the first time an instance of a product is declared with some chain. When any other instances of the same product (regardless of version) get declared with the same chain, one of two things happens:

  • a new entry is created in the same chain file, or
  • if an entry with the same flavor and qualifiers already exists, the pre-existing entry gets unchained and the new one is chained in its place.

  Chain files get created and modified via the ups declare <chainFlag> command. A chain file's contents are simply a formatted list of the product instances that were declared with that chain, where each product instance is specified via a set of keywords. When a chain is used in a UPS/UPD command, UPS looks in the corresponding chain file to match the instance and thus locate the appropriate version file. As discussed in section 27.2 Instance Matching within Selected Database , the version file entry locates the product root directory and table file to retrieve the instance.

  In UPS/UPD commands, the command line option associated with a particular chain can be used in specifying the product instance to match. Using chains is optional, but recommended. Both chained and unchained instances of a product may be declared to UPS ; the user can still retrieve any instance, chained or not, by specifying its version number.

  30.2 Keywords Used in Chain Files

  This is a subset of the list given in section 28.4 List of Supported Keywords .

Keyword and Keyword and Default Value (if any) Default Value (if any) Description and Description and Notes (if any) Notes (if any)
CHAIN CHAIN chain name chain name
DECLARED DECLARED Default: current date and time Default: current date and time 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 Default: current user Default: current user 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
FILE FILE type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE) type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE)
FLAVOR FLAVOR product instance flavor product instance flavor Note: To easily accommodate flavor-neutral setup functions in a table file, FLAVOR can take the value ANY, but only in a table file. Note: To easily accommodate flavor-neutral setup functions in a table file, FLAVOR can take the value ANY, but only in a table file.
MODIFIED MODIFIED Default: Current date/time Default: Current date/time 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 Default: Current user Default: Current user 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)
PRODUCT PRODUCT product name product name
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 Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see 27.2.3 Qualifiers: Use in Instance Matching ) Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see 27.2.3 Qualifiers: Use in Instance Matching )
UPS_DB_VERSION UPS_DB_VERSION UPS database version UPS database version
VERSION VERSION product version product version

  30.3 Chain File Examples

  30.3.1 Sample chain file for exmh v1_6_6

  This file points to the instance used in the version file of section 29.3.1 Sample Version File for exmh v1_6_6 . The file $PRODUCTS/exmh/current.chain contains the text:

FILE = chain
PRODUCT = exmh
CHAIN = current

#*************************************************
#
FLAVOR = Linux+2
QUALIFIERS = "" 
  VERSION = v1_6_6
  DECLARED = 2013-03-30 21.06.59 GMT
  DECLARER = stolz
  MODIFIED = 2013-03-30 21.06.59 GMT
  MODIFIER = stolz

  If the given instance hadn't been initially declared as current (as in the command in section 29.3.1 ), then to create this chain file you would need to declare the instance current, e.g.,:

% ups declare -c exmh v1_6_6

  30.3.2 Sample chain file for foo v2_0

  This example illustrates the use of qualifiers. It points to both of the instances in the version file for foo in section 29.3.2 Sample version file for foo v2_0 . That version file will also get modified when these chains are declared. The DECLARER, DECLARED, MODIFIER and MODIFIED fields will include information for the chain declarations.

  Making the "current" Chain Declarations

  In order for this chain file to have the contents shown below, the following two commands need to be issued:

% ups declare -cq superoptimize -f Linux+2 foo v2_0
% ups declare -cf OSF6 foo v2_0

  The file $PRODUCTS/foo/current.chain contains the text:

FILE = CHAIN
PRODUCT = foo
CHAIN = CURRENT
#----------------------------------------
#
FLAVOR = Linux+2
QUALIFIERS = "superoptimize" 
  VERSION = v2_0
  DECLARER = aheavey
  DECLARED = 2013-04-15 16.37.58 GMT
  MODIFIED = 2013-05-19 21.06.59 GMT
  MODIFIER = aheavey

FLAVOR = OSF6
QUALIFIERS = "" 
  VERSION = V2_0
  DECLARER = aheavey
  DECLARED = 2013-04-15 16.39.58 GMT
  MODIFIED = 2013-05-24 21.06.59 GMT
  MODIFIER = aheavey

  Sequence of Events at Setup Time

  For this example in the Linux+2 case, the sequence of events upon issuing the command:

% setup -q superoptimize foo

  would be as follows:

  1. match the FLAVOR (Linux+2) and the QUALIFIERS (superoptimize) in this chain file
  2. find the version (v2_0) and open the corresponding version file ( v2_0.version )
  3. locate the table file ( $FOO_DIR/ups/v2_0.table ) and open it
  4. find the ACTION=SETUP line in the table file and execute the listed functions (if no ACTION=SETUP line is present, UPS executes the default setup functions)

 

 

TOC PREV NEXT

Last revised on May 2014

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

Chapter Contents

Chapter 30: Chain Files
   30.1 About Chain Files
   30.2 Keywords Used in Chain Files
   30.3 Chain File Examples
     30.3.1 Sample chain file for exmh v1_6_6
     30.3.2 Sample chain file for foo v2_0

  Chapter 30: Chain Files

  UPS/UPD supports chains to product versions, and chain information is maintained in chain files. In this chapter we describe chain files and how they interact with version files.

  30.1 About Chain Files

  Chains for a product are maintained in chain files which reside in the product-specific directory under the UPS database directory. There is one chain file for each chain name, and it is named according to the chain name, with a suffix of .chain , e.g., current.chain . A chain file is automatically created by UPS the first time an instance of a product is declared with some chain. When any other instances of the same product (regardless of version) get declared with the same chain, one of two things happens:

  • a new entry is created in the same chain file, or
  • if an entry with the same flavor and qualifiers already exists, the pre-existing entry gets unchained and the new one is chained in its place.

  Chain files get created and modified via the ups declare <chainFlag> command. A chain file's contents are simply a formatted list of the product instances that were declared with that chain, where each product instance is specified via a set of keywords. When a chain is used in a UPS/UPD command, UPS looks in the corresponding chain file to match the instance and thus locate the appropriate version file. As discussed in section 27.2 Instance Matching within Selected Database , the version file entry locates the product root directory and table file to retrieve the instance.

  In UPS/UPD commands, the command line option associated with a particular chain can be used in specifying the product instance to match. Using chains is optional, but recommended. Both chained and unchained instances of a product may be declared to UPS ; the user can still retrieve any instance, chained or not, by specifying its version number.

  30.2 Keywords Used in Chain Files

  This is a subset of the list given in section 28.4 List of Supported Keywords .

Keyword and Keyword and Default Value (if any) Default Value (if any) Description and Description and Notes (if any) Notes (if any)
CHAIN CHAIN chain name chain name
DECLARED DECLARED Default: current date and time Default: current date and time 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 Default: current user Default: current user 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
FILE FILE type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE) type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE)
FLAVOR FLAVOR product instance flavor product instance flavor Note: To easily accommodate flavor-neutral setup functions in a table file, FLAVOR can take the value ANY, but only in a table file. Note: To easily accommodate flavor-neutral setup functions in a table file, FLAVOR can take the value ANY, but only in a table file.
MODIFIED MODIFIED Default: Current date/time Default: Current date/time 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 Default: Current user Default: Current user 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)
PRODUCT PRODUCT product name product name
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 Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see 27.2.3 Qualifiers: Use in Instance Matching ) Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see 27.2.3 Qualifiers: Use in Instance Matching )
UPS_DB_VERSION UPS_DB_VERSION UPS database version UPS database version
VERSION VERSION product version product version

  30.3 Chain File Examples

  30.3.1 Sample chain file for exmh v1_6_6

  This file points to the instance used in the version file of section 29.3.1 Sample Version File for exmh v1_6_6 . The file $PRODUCTS/exmh/current.chain contains the text:

FILE = chain
PRODUCT = exmh
CHAIN = current

#*************************************************
#
FLAVOR = Linux+2
QUALIFIERS = "" 
  VERSION = v1_6_6
  DECLARED = 2013-03-30 21.06.59 GMT
  DECLARER = stolz
  MODIFIED = 2013-03-30 21.06.59 GMT
  MODIFIER = stolz

  If the given instance hadn't been initially declared as current (as in the command in section 29.3.1 ), then to create this chain file you would need to declare the instance current, e.g.,:

% ups declare -c exmh v1_6_6

  30.3.2 Sample chain file for foo v2_0

  This example illustrates the use of qualifiers. It points to both of the instances in the version file for foo in section 29.3.2 Sample version file for foo v2_0 . That version file will also get modified when these chains are declared. The DECLARER, DECLARED, MODIFIER and MODIFIED fields will include information for the chain declarations.

  Making the "current" Chain Declarations

  In order for this chain file to have the contents shown below, the following two commands need to be issued:

% ups declare -cq superoptimize -f Linux+2 foo v2_0
% ups declare -cf OSF6 foo v2_0

  The file $PRODUCTS/foo/current.chain contains the text:

FILE = CHAIN
PRODUCT = foo
CHAIN = CURRENT
#----------------------------------------
#
FLAVOR = Linux+2
QUALIFIERS = "superoptimize" 
  VERSION = v2_0
  DECLARER = aheavey
  DECLARED = 2013-04-15 16.37.58 GMT
  MODIFIED = 2013-05-19 21.06.59 GMT
  MODIFIER = aheavey

FLAVOR = OSF6
QUALIFIERS = "" 
  VERSION = V2_0
  DECLARER = aheavey
  DECLARED = 2013-04-15 16.39.58 GMT
  MODIFIED = 2013-05-24 21.06.59 GMT
  MODIFIER = aheavey

  Sequence of Events at Setup Time

  For this example in the Linux+2 case, the sequence of events upon issuing the command:

% setup -q superoptimize foo

  would be as follows:

  1. match the FLAVOR (Linux+2) and the QUALIFIERS (superoptimize) in this chain file
  2. find the version (v2_0) and open the corresponding version file ( v2_0.version )
  3. locate the table file ( $FOO_DIR/ups/v2_0.table ) and open it
  4. find the ACTION=SETUP line in the table file and execute the listed functions (if no ACTION=SETUP line is present, UPS executes the default setup functions)

 

 

TOC PREV NEXT

Last revised on May 2014