4 Building Subsets and Control Files

In a kit, a subset is the smallest installable entity that is compatible with the setld utility. It is up to you, the kit developer, to specify how many subsets your kit has and what files each contains. A good practice is to group files by related function or interdependence. For example, the ODB product defines two subsets. The subset named OATODB100 contains the files needed to run the product. The subset named OATODBDOC100 contains documentation and online help files. By placing the documentation in a separate subset, the system administrator can choose not to install that subset if space is limited on the system.

Figure 4-1 shows how the files that make up the ODB product are grouped into subsets. As the figure shows, the physical location of a file is not necessarily a factor in determining the subset to which it belongs.

You specify the subsets and the files that each subset contains in a master inventory file. In a key file, you specify the product attributes, such as the product name and version, and the subset definitions. With these two files in place -- the master inventory and key file -- you can run the kits utility to create the subsets and control files in the output directory.

Figure 4-2 shows the contents of the output directory after the kits utility has run.

You perform the same steps when creating subsets for user products, kernel products, and foreign device kits. This chapter describes how to create the master inventory and key files, and how to use the kits utility to create subsets and subset control files. This chapter uses the ODB product to illustrate these tasks.

Figure 4-1: Grouping Files into Subsets

Figure 4-2: Contents of the ODB output Directory

4.1 Creating the Master Inventory File

You can create a master inventory file with any text editor you like, or create the file with the touch command. The master inventory file name must consist of the product code and version, with the letters mi as a suffix. For example:

% touch OAT100.mi

The first time you process a kit, the master inventory file is empty. You must enter one record for each file that belongs on the kit. To get an initial list of these files, you can use the newinv command. Specify the file name of the empty master inventory file and the pathname of the source hierarchy's top-level directory. For example:

% newinv OAT100.mi ../src

This command invokes newinv on the master inventory file for the ODB product. It specifies the pathname to the source hierarchy as a relative path from the current directory (data).

The newinv utility produces a list of files that are present in the source hierarchy and places you in the vi editor, or the editor specified by your EDITOR environment variable, so that you can make the required changes. Remove the entries for any files that should not appear on the kit, and add the flags, pathname, and subset identifier for each entry that should appear on the kit.

Caution

Use extreme care when editing the master inventory file; fields in this file must be separated by single tab characters, not by spaces.

The files listed in the master inventory file are given dot-relative pathnames. The setld utility usually works from the system's root directory, but the user can specify an alternate root directory with the -D option. For this reason, you should not use absolute pathnames in the master inventory file.

The master inventory file contains one record for each file in the kit. Each record in the master inventory file consists of three fields, described in Table 4-1.

Table 4-1: Fields in Master Inventory Records
Field	Description
Flags	A 16-bit unsigned integer.
	Bit 1 is the `v` (volatility) bit. When set, changes to the existing copy of the file can occur during kit installation. It is usually set for files such as `usr/spool/mqueue/syslog`.
	Bit 2 is the `1` (link) bit. When set, the `STL_LinkCreate` routine invoked in the subset control program (`.scp`) creates a forward link from the standard system directories to the layered product `opt` areas. The remaining bits are reserved; possible values for this field are therefore 0, 2, 4, or 6.
Pathname	The dot-relative (`./`) pathname of the file.
Subset identifier	The name of the subset that contains the file. Subset names consist of the product code, subset mnemonic, and version number. You must not include standard system directories in your subsets. In the ODB master inventory file, several records specify directories that are part of the standard system hierarchy. Instead of a subset identifier, these records specify `RESERVED`; this keyword prevents `setld` from overwriting existing directories.

Example 4-1 shows that the ODB kit has two subsets. The OATODB100 subset contains utilities and libraries and must be installed if the product is to be used. The OATODBDOC100 subset contains the product's documentation and is not required to make the product work.

Example 4-1: Master Inventory File for the ODB Kit

0       .       RESERVED
0       ./usr/opt       RESERVED
0       ./usr/opt/OAT100/OATODBDOC.Links        OATODBDOC100
0       ./usr/opt/OAT100/bin    OATODB100
4       ./usr/opt/OAT100/bin/attr       OATODB100
4       ./usr/opt/OAT100/bin/dcb.spr    OATODB100
4       ./usr/opt/OAT100/bin/dcb_defaults       OATODB100
4       ./usr/opt/OAT100/bin/dcb_diag.sed       OATODB100
4       ./usr/opt/OAT100/bin/docbld     OATODB100
4       ./usr/opt/OAT100/bin/unstamp    OATODB100
0       ./usr/opt/OAT100/lib    OATODB100
0       ./usr/opt/OAT100/lib/br OATODB100
4       ./usr/opt/OAT100/lib/br/README.dcb      OATODB100
4       ./usr/opt/OAT100/lib/br/attr.1  OATODBDOC100
4       ./usr/opt/OAT100/lib/br/dcb.ps  OATODBDOC100
4       ./usr/opt/OAT100/lib/br/docbld.1        OATODBDOC100
4       ./usr/opt/OAT100/lib/br/unstamp.1       OATODBDOC100
0       ./usr/opt/OAT100/lib/doclib     OATODB100
0       ./usr/opt/OAT100/lib/doclib/templates   OATODB100
4       ./usr/opt/OAT100/lib/doclib/templates/conv.braces       OATODB100

.
.
.

In the example, the ./usr/opt directory has the RESERVED subset identifier, indicating that setld should not allow the directory to be overwritten if it exists on the customer's system. The Flags field is set to 0 (zero), indicating that this directory cannot change and that it is not linked to another directory on the customer's system. On the other hand, the /usr/opt/OAT100/bin/attr file has the OATODB100 subset identifier, indicating that the file belongs in the specified subset. The Flags field is set to 4, indicating that the file may change and that it has a link to another file on the customer's system.

For subsequent updates to the kit, use the existing version of the master inventory file for the input file. The newinv utility performs the following additional steps:

Creates a backup file, inventory-file.bkp.

Finds all the file and directory names in the source hierarchy.

Produces the following sorted groups of records:

Records that contain pathnames only, representing files now present that were not in the previous inventory
Records that represent files now present that were also present in the previous inventory (this list is empty the first time you create the inventory)
Records that were in the previous inventory but are no longer present (also empty the first time you create the inventory)

Lets you edit the third of these groups, deleting records for files that no longer belong in the kit.

Lets you edit the group of new records by adding the flags and subset identification fields (see Table 4-1).
Merges the three groups of records and sorts the result to produce a finished master inventory file that matches the source hierarchy.

4.2 Creating the Key File

The key file identifies the product that the kit represents, such as its name, version number, and the name of the master inventory file for the kit. You create this file in the data directory with any text editor that you like. Its name must consist of the product code and version, with the letter k as a suffix. For example, OAT100.k is the key file for the ODB kit. Example 4-2 illustrates this key file.

Example 4-2: Key File for the ODB Kit

#       Product-level attributes
#
NAME='Orpheus Authoring Tools'
CODE=OAT
VERS=100
MI=OAT100.mi
COMPRESS=1
#
#       Subset definitions
#
%%
OATODB100       .       0       'Document-Building Tools'
OATODBDOC100    .       2       'Document Tools Documentation'

As shown in the example, the key file is divided into two sections separated by a line that contains two percent signs (%%), as follows:

The product attributes section describes the naming conventions for the kit and provides kit-level instructions for the kits command. This section of the key file consists of several lines of attribute-value pairs. Table 4-2 describes the possible attribute-value pairs. Each attribute name is separated from its value by an equal sign (=). You can include comment lines, which begin with a number sign (#).
The subset descriptor section describes each of the subsets in the kit and provides subset-level instructions for the kits command. This section contains one line for each subset in the kit. Each line consists of four fields separated by tab characters. You cannot include comments in this section of the key file. Table 4-3 describes the subset descriptor fields. In Example 4-2, the OATODB100 subset is mandatory; its Flags field is set to 0 (zero). The OATODBDOC100 subset, which contains the documentation, is optional; its Flags field is set to 2.

Table 4-2: Key File Attributes Section
Attribute	Description
`NAME`	The product name; for example, Orpheus Authoring Tools.
	Enclose the product name in single quotation marks (`'`) if it contains spaces.
`CODE`	A unique product code that consists of three numbers or uppercase letters, for example, OAT; the first character must be a letter. Note: The first three letters of the subset name must be the same as the product code. Otherwise, any shell routines that the subset control program calls to create links and `STL_LinkBack` will not work.
	Digital has reserved the following codes: DNP, DNU, EPI, FOR, LSP, ORT, OSF, SNA, UDT, UDW, UDX, ULC, ULT, ULX, UWS.
	Internal Digital product developers should contact the Software New Products Committee (SNPC) through product management to register a unique code.
	Third-party developers should contact their Digital representatives to register a unique product code.
`VERS`	A 3-digit version code; for example, 100. The `setld` utility interprets this version code as 1.0.0. The first digit should reflect the product's major release number, the second the minor release number, and the third the upgrade level, if any.
`MI`	The name of the product's master inventory file, which consists of the product name, code, and version plus the `mi` extension. You create and maintain the master inventory file with the `newinv` utility.
`ROOT`	Not illustrated in the example, Digital has reserved this optional attribute for the base operating system. `ROOT` has a string value that names the root image file. Do not assign this attribute for a layered product.
`COMPRESS`	An optional flag that is set to 1 if you want to create compressed subset files. For kits in Direct CD-ROM (DCD) format, you must set this flag to 0 (zero). Compressed files require less space on the distribution media (sometimes as little as 40% of the space required by uncompressed files), but they take longer to install than uncompressed files. If missing, this flag defaults to 0 (zero).

Table 4-3: Key File Subset Descriptor Fields
Field	Description
Subset identifier	A character string up to 80 characters in length, composed of the product code (for example, `OAT`), a mnemonic identifying the subset (for example, `ODB`), and the 3-digit version code (for example, 100). All letters in the subset identifier must be uppercase.
Reserved	Must be a single period (`.`).
Flags	A 16-bit unsigned integer. Digital defines the use of the lower 8 bits. Set bit 0, the sticky bit, to indicate that the subset cannot be removed. Set bit 1 to indicate that the subset is optional. You can use bits 8 - 15 to relay special subset-related information to your subset control program.
Subset description	A short description of the subset, delimited by single quotation marks ('); for example, `'Document-Building Tools'`. Note: The percent sign character (`%`) is reserved in this field and must not be used for layered products.

4.3 Running the kits Utility

After you create the master inventory and key files, you create subsets by running the kits utility. This command requires three arguments:

Key file name
Pathname for the source hierarchy
Pathname for the output hierarchy

Note
When you run the kits utility, make sure you are in the data directory. If you are not in the data directory, the utility cannot find your subset control files.

For example, the following command builds the subsets for the ODB product kit:

% cd /dcb_tools/data

% kits OAT100.k ../src ../output

The kits utility performs the following steps and reports its progress:

Creates the subsets.

Compresses each subset, if you specify the COMPRESS attribute in the key file.

Creates the installation control files listed in Table 4-4 and places them in the instctrl directory.
Creates the INSTCTRL file, which contains a tar image of all the installation control files. This file is placed in the output directory.

The subset files and the INSTCTRL file are constituents of the final kit.

Table 4-4: Installation Control Files in the instctrl Directory
File	Description
`product-id.comp`	Compression flag file. This empty file is created only if you specified the COMPRESS attribute in the key file. Its presence signals to `setld` that the subset files are compressed. The ODB kit's compression flag file is named `OAT100.comp`.
`product-code.image`	Image data file. This file contains size and checksum information for the subsets.
`subset-id.ctrl`	Subset control file. This file contains `setld` control information. There is one subset control file for each subset.
`subset-id.inv`	Subset inventory file. This file contains an inventory of the files in the subset. Each record describes one file. There is one subset inventory file for each subset.
`subset-id.scp`	Subset control program. If you created subset control programs for your kit, these files are copied from the `scps` directory to the `instctrl` directory. There is one subset control program for each subset; if you have not created a subset control program for a subset, `kits` creates a blank file.

The following sections describe the contents of the installation control files in detail.

4.3.1 Compression Flag File

The setld utility uses the presence of the compression flag file (product-id.comp) to determine whether the subset files are compressed. The compression flag is an empty file whose name consists of the product code and the version number with the string comp as a suffix; for example, OAT100.comp.

4.3.2 Image Data File

The setld utility uses the image data file to verify that the subset images it loads from the installation media are uncorrupted before the actual installation process begins. The image data file name consists of the product's unique three-letter name with the string image for a suffix. The image data file contains one record for each subset in the kit. The following example illustrates OAT.image, the image data file for the ODB kit:

15923    70 OATODB100
24305   400 OATODBDOC100

Table 4-5 describes the three fields in each record.

Table 4-5: Image Data File Fields
Field	Description
Checksum	The modulo-65536 (16-bit) checksum of the subset file (after compression, if the file is compressed)
Size	The size of the subset file in kilobytes (after compression, if the file is compressed)
Subset identifier	The product code, subset mnemonic, and version number

4.3.3 Subset Control Files

The setld utility uses the subset control files as a source of descriptive information about subsets. A control file for each subset contains the following fields:

NAME
Specifies a descriptive product name and subset identifier.

DESC
Specifies a descriptive subset identifier.

ROOTSIZE

Specifies (in bytes) the space the subset requires in the root file system.

USRSIZE

Specifies (in bytes) the amount of the usr file system the subset requires.

VARSIZE

Specifies (in bytes) the amount of the var file system the subset requires.

NVOLS
Specifies disk volume identification information as two colon-separated integers (the volume number of the disk that contains the subset archive and the number of disks required to contain the subset archive).

MTLOC
Specifies the tape volume number and subset's location on the tape as two colon-separated integers (the volume number of the tape that contains the subset archive and the file offset at which the subset archive begins). On tape volumes, the first three files are reserved for a bootable operating system image and are not used by setld. An offset of 0 (zero) indicates the fourth file on the tape. The fourth file is a tar archive named INSTCTRL, which contains the kit's installation control files (listed in Table 4-4).
DEPS
Specifies a dependency list (reserved -- see Table 4-3).
FLAGS
Specifies subset control flag bits.

The following example illustrates OATODBDOC100.ctrl, the control file for the ODB kit's OATODBDOC100 subset:

NAME='Orpheus Authoring Tools OATODBDOC100'
DESC='Document Tools Documentation'
ROOTSIZE=0
USRSIZE=522090
VARSIZE=0
NVOLS=1:2
MTLOC=1:1
DEPS="."
FLAGS=34816

4.3.4 Subset Inventory File

The subset inventory file describes each file in the subset, listing its size, checksum, permissions, and other information. The kits command generates this information, which reflects the exact state of the files in the source hierarchy from which the kit was built. The setld utility uses the information to duplicate that state, thus transferring an exact copy of the source hierarchy to the customer's system. Example 4-3 shows the inventory file, OATODBDOC100.inv, for the ODB kit's OATODBDOC100 subset. The backslashes (\) in this example indicate line continuation and are not present in the actual file.

Example 4-3: Sample Subset Inventory File

4       983     01851   1065    0       100644  3/21/91 100     f\
       ./usr/opt/OAT100/lib/br/attr.1  none    OATODBDOC100
4       424997  63356   1065    10      100644  4/15/91 100     f\
       ./usr/opt/OAT100/lib/br/dcb.ps  none    OATODBDOC100
4       7283    03448   1065    10      100644  4/15/91 100     f\
       ./usr/opt/OAT100/lib/br/docbld.1        none    OATODBDOC100
4       6911    37501   1065    0       100644  3/21/91 100     f\
       ./usr/opt/OAT100/lib/br/docbld.5        none    OATODBDOC100
4       985     41926   1065    0       100644  3/21/91 100     f\
       ./usr/opt/OAT100/lib/br/unstamp.1       none    OATODBDOC100

Each record of the inventory is composed of 12 fields separated by tab characters. Table 4-6 describes the contents of these fields.

Table 4-6: Subset Inventory Field Descriptions
Field	Name	Description
1	Flags	A 16-bit unsigned integer.
		Bit 1 is the `v` (volatility) bit. When set, changes to the existing copy of the file can occur during kit installation. It is usually set for files such as `usr/spool/mqueue/syslog`.
		Bit 2 is the `l` (link) bit. When set, the `STL_LinkCreate` routine creates a forward link from the standard system directories to the layered product areas. The remaining bits are reserved; possible values for this field are therefore 0 2, 4, or 6.
2	Size	The actual number of bytes in the file.
3	Checksum	The modulo-65536 (16-bit) checksum of the file.
4	uid	The user ID of the file's owner.
5	gid	The group ID of the file's owner.
6	Mode	The 6-digit octal representation of the file's mode.
7	Date	The file's last modification date.
8	Revision	The version code of the product that includes the file.
9	Type	A letter that describes the file:
		`b` - Block device.
		`c` - Character device.
		`d` - Directory containing one or more files.
		`f` - Regular file. For regular files with a link count greater than one, see file type `l`.
		`l` - Hard link. Other files in the inventory have the same inode number. The first (in ASCII collating sequence) is listed in the referent field.
		`p` - Named pipe (FIFO).
		`s` - Symbolic link.
10	Pathname	The dot-relative (`./`) pathname of the file.
11	Referent	For file types `l` and `s`, the path to which the file is linked; for types `b` and `c`, the major and minor numbers of the device; for all other types, `none.`
12	Subset identifier	The name of the subset that contains the file.