 |
 |
 |
 |
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:
- match the FLAVOR (Linux+2) and the QUALIFIERS (superoptimize) in this chain file
- find the version (v2_0) and open the corresponding version file ( v2_0.version )
- locate the table file ( $FOO_DIR/ups/v2_0.table ) and open it
- 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)
| |
|
|
Last revised on May 2014
| |
|
|
| |
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:
- match the FLAVOR (Linux+2) and the QUALIFIERS (superoptimize) in this chain file
- find the version (v2_0) and open the corresponding version file ( v2_0.version )
- locate the table file ( $FOO_DIR/ups/v2_0.table ) and open it
- 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)
| |
|
|
Last revised on May 2014