4 Creating Subsets

A subset is the smallest installable entity in a kit 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, message libraries should be together in a subset to allow for easy localization and translation to other languages.

You specify the subsets and the files that each subset contains in a master inventory file. It is also up to you to specify the product attributes, such as the product name and version, and the subset definitions. You create a key file for this purpose. 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. You perform the same steps when creating subsets for user products, kernel products, and foreign device products.

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. The ODB product is used as an example throughout the chapter to illustrate these tasks.

4.1 Creating the Master Inventory File

You can create a master inventory file with any text editor you like, or you can 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, you can create the master inventory for the ODB kit as follows:

% cd data % 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 the 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.

Cautions

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 alternative 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 traditional 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 containing 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 attempting to overwrite 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

.
.
.

For subsequent updates to the kit, use the existing version of the master inventory file for the input file. The newinv utility performs these 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 containing pathnames only, representing files now present that were not in the previous inventory
- Records representing 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 which no longer belong in the kit
Lets you edit the group of new records by adding the flag and subset 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 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 the following two sections separated by a line containing two percent signs (%%):

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; OATODBDOC100, which contains the documentation, is optional.

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 any spaces.
`CODE`	A unique product code consisting of three numbers or uppercase letters, for example, OAT; the first character must be a letter
	The following codes are reserved by Digital: 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 consisting 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, this optional attribute is reserved by Digital for the base operating system. For that use, it has a string value that names the root image file. Do not assign the `ROOT` 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 zero (0). 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 zero (`0`).

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 reserves the use of the lower 8 bits. You set bit 0, the sticky bit, to indicate that the subset cannot be removed. You set bit 1 to indicate that the subset is optional. The remaining bits are reserved; possible values for this field are therefore, 0, 2.
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 command from the data directory. This command requires three arguments:

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

For example, the ODB kit is built with the following command:

% 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 containing 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 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.2 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 information:

Descriptive product name and subset identifier.
Descriptive subset identifier.
Space required by the subset in the root file system, specified in bytes.
Amount of the usr file system required by the subset specified in bytes.
Amount of the var file system required by the subset specified in bytes.
Disk volume identification information, consisting of two colon-separated integers (the volume number of the disk containing the subset archive and the number of diskettes required to contain the subset archive).
Tape volume number and the subset's location on the tape, consisting of two colon-separated integers (the volume number of the tape containing 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, containing the kit's installation control files (listed in Table 4-4).
Dependency list (reserved - see Table 4-3).
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.3 Subset Inventory Files

The subset inventory file describes each file in the subset, listing its size, checksum, permissions, and other information. This information is generated by the kits command and reflects the exact state of the files as they were in the source hierarchy from which the kit was built. It is used by setld 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 it is 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 it is set, the `STL_LinkCreate()` function 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 containing the file.

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