4 Producing User Product Kits

This chapter tells you how to produce a user product kit. A user product runs in user space. This includes commands and utilities as well as applications such as text editors and database systems. Users interact directly with user products through commands or window interfaces.

Note

The information in this chapter describes how to produce user product kits.

If you want to create a kernel product kit, go to Chapter 5.

If you want to create a hardware product kit, go to Chapter 6.

Follow these steps to create and test a user product kit:

Read Chapter 1 for an overview of product kits.

Design the kit directory structure as described in Chapter 2.

Create subsets as described in Chapter 3. Subset control programs are optional for user product kits (Section 3.4).

Create the kit distribution media as described in Section 4.2.

Test the distribution media as described in Section 4.3.

No additional installation files are required for user product kits.

4.1 Overview

A user product is a layered product that contains software run directly by users. Commands and utilities are in this category, as are applications such as text editors and database systems. Users interact directly with user products through such means as commands or graphical interfaces.

4.2 Producing Distribution Media

After you have tested the subsets as described in Section 3.6, you can produce the distribution media. Distribution media production consists of the following tasks:

Edit the /etc/kitcap file. (Section 4.2.1)

Build the user product kit on the distribution media:
- Use the gendisk utility to build a kit on disk media (Section 4.2.2)
- Use the gentapes utility to build a tar format kit on magnetic tape (Section 4.2.3)

Produce user product kits in tar format. You can use direct CD-ROM (DCD) format if you require access to kit files before or during installation, but installation time for DCD format kits is slower than for tar format kits.

tar format
In tar format, the product files in each subset are written to the distribution media as a single file. During installation, the setld utility uncompresses the files and moves them onto the target system, preserving the files' original directory structure. Kits distributed in tar format install more quickly and consume less space on the distribution media.

direct CD-ROM (DCD) format
In DCD format, the files are written to the distribution media as a UNIX file system where the product files are organized into a directory structure that mirrors the target system. Subsets distributed in DCD format cannot be compressed.

You can distribute user product kits on diskette, CD-ROM, or magnetic tape, as follows:

Diskette
Diskettes are a good media for testing purposes or for small products. The product must fit on a single diskette; it cannot span multiple diskettes. Use the gendisk utility to produce kits for diskette media.

CD-ROM
CD-ROM media can support large kits or multiple kits on a single media. The kit is first produced on the hard disk, then written onto the CD-ROM. Use the gendisk utility to produce the master kit on hard disk. Follow the CD-ROM manufacturer's instructions for writing the kit onto the CD-ROM media.

Magnetic tape
You can distribute kits for user products on magnetic tape. Tape media does not support DCD format. Use the gentapes utility to produce kits for magnetic tape media.

Figure 4-1 shows the types of file formats and distribution media that are available for user product kits.

Figure 4-1: User Product Kit File Formats

4.2.1 Editing the /etc/kitcap File

The gendisk and gentapes utilities refer to the /etc/kitcap file, a database containing information about the kits to be built on the system. Each record contains a product code and the names of the directories, files, and subsets that make up the product kit. Before you can build your kit, you must add a media descriptor record to the /etc/kitcap database.

Note

If you use the gendisk utility to produce your kit on disk distribution media, you can specify an alternate kit descriptor database. Refer to the gendisk(1) reference page for additional information.

Use the following conventions when you add a record to the /etc/kitcap file:

Separate the first field from the rest of the record by a colon ( : ) for disk media descriptors and by a pipe character ( | ) for tape media descriptors.

Separate all other fields with colons ( : ).

Indicate continuation with a backslash ( \ ) at the end of the line.

Lines starting with a pound sign ( # ) are comments and are ignored.

Comments within the record start with pound sign ( # ) and end with a colon ( : ). Use this feature sparingly.

The contents of a kitcap record differ depending on whether you are producing disk or tape media. You must add one record for each media type on which you plan to distribute your kit.

The contents of the record also can depend on the product type you are delivering. Refer to the kitcap(4) reference page for more information about the contents of the /etc/kitcap file.

4.2.1.1 Disk Media Descriptor

Create a disk media kitcap record when you produce kits for distribution on diskette or CD-ROM. The kitcap record for disk media contains the following elements:

The kit name, consisting of two parts:
- The product code, consisting of the product code and version number specified in the CODE and VERS fields of the kit's key file. Refer to Section 3.3 for information about the key file.
- The media code HD to indicate disk media. This element is followed by a colon ( : ).

The partition on the disk media where the product should be placed. The partition is a letter between a and h. Partition c is used most often, as it spans the entire disk.

The destination directory for the subsets on the disk media. This allows a hierarchical structure so you can put multiple products on one disk, or put parts of one product on different areas of the same disk. You can use multiple destination directories in a kitcap record.

The product description. This entry is taken from key file NAME field. Replace any spaces with an underscore ( _ ) character, for example: Product Description becomes Product_Description.

The name of the output directory where you created the kit, where the gendisk utility can find the product subsets.

The instctrl directory, relative to the output directory specification.

The names of the subsets that make up the kit.

Refer to the kitcap(4) reference page for more detailed information about the disk media record format.

Refer to Section 3.3 for information about the key file.

Example 4-1 shows the record to be added to the /etc/kitcap file to produce the ODB kit on disk media:

Example 4-1: Sample Disk Media Descriptor for User Product

OAT100HD:c:/:\
  dd=/OAT100:Orpheus_Document_Builder:/mykit/output:\
  instctrl:OATODB100:OATODBTEMPS100

Based on the information shown in Example 4-1, the gendisk utility places the kit on the c partition in the / (root) directory of the disk media. The product description is Orpheus_Document_Builder and the output directory where you created the kit is /mykit/output. The kit consists of two subsets: OATODB100 and OATODBTEMPS100.

4.2.1.2 Tape Media Descriptor

The kitcap record for tape media contains the following elements:

The kit name, consisting of two parts:
- Product code, consisting of the product code and version number specified in the CODE and VERS fields of the kit's key file. Refer to Section 3.3 for information about the key file.
- The media code, either TK for TK50 tapes or MT for 9-track magnetic tape. This element is followed by a pipe character ( | ).

Product description. This entry is taken from the NAME field of the key file.

Name of the output directory where you created the kit, where the gentapes utility can find the subsets.
Since the gentapes utility can take subsets from multiple products and merge them on tape as a combined product, you can specify multiple directories where the gentapes utility can find the subsets. There must be one directory entry for each kitcap descriptor.

Three empty SPACE files to ensure compatibility with operating system kits. To create the SPACE file in the output area of the kit directory structure, use comments similar to the following:
```
# cd /mykit/output
# touch space
# tar -cf SPACE space
```

The INSTCTRL image in the output directory containing setld control information.

The names of the subsets that make up the kit. Each subset listed must be stored in one of the specified directories.

Optional volume identifiers %%N, followed by the names of the subsets to be placed on that volume. You can use multiple tapes.

Refer to the kitcap(4) reference page for more detailed information about the tape media record format.

Example 4-2 shows the record to be added to the /etc/kitcap file to produce the ODB kit on TK50 tapes:

Example 4-2: Sample Tape Media Descriptor

OAT100TK|Orpheus Document Builder: \
    /mykit/output:SPACE:SPACE:SPACE: \
    INSTCTRL:OATODB100:OATODBTEMPS100

The product name, OAT100, is the same name that appears in the key file. The product description, Orpheus Document Builder, also appears in the key file. The name of the output directory is /mykit/output, and three SPACE files are included for compatibility with operating system kits. The last line of the record contains the INSTCTRL file in tar format and the names of the subsets that make up the kit: OATODB100 and OATODBTEMPS100.

4.2.2 Building a User Product Kit on Disk Media

After the product subsets are located in the output area of the kit directory structure, use the gendisk utility to produce the kit on a disk.

Note

The gendisk utility supports diskettes but does not let you create a chained diskette kit. A kit written to diskette must fit on a single diskette or be packaged as a set of kits on separate diskettes.

Use the following syntax for the gendisk command:

gendisk [-d] [-i] [-k filename] [-w] [-v] [hostname:] prodID devname

Note

If you do not use either the -w or -v options, the gendisk utility writes and then verifies the product media.

-d

Creates a distribution disk in direct CD format. This means that the distribution disk contains uncompressed file systems that are laid out just as the software is installed on the system.

Note

Do not use the -d option when you use the gendisk utility to produce user product kits.

-i

Creates a distribution disk in ISO 9660 format. This means that the distribution disk contains an ISO 9660-compliant CD-ROM file system (CDFS).

-k filename

Uses an alternate kit descriptor database, filename, on the local system. You may use either a full absolute pathname or a relative pathname from the directory where you run the gendisk utility. The file does not have to be named kitcap.

-w

Writes the product media without verification, if used without the -v option. If used with the -w option, the gendisk utility writes and then verifies the product media.

-v

Verifies the product media without writing it first, if used without the -w option. This assumes that you already have written kit files to the distribution media. If used with the -w option, the gendisk utility writes and then verifies the product media.

hostname:

The optional hostname: operand is the name of a remote machine that contains the kit descriptor database. The gendisk utility searches the kit descriptor database on the remote machine for the kit identifier (prodIDHD) and uses it to create the distribution media. The colon (:) is a required delimiter for TCP/IP networks, and space is permitted between the colon and the prodID. For example, if the product code is OAT100 and you are using the kit descriptor database on node mynode, use mynode:OAT100 for this option.

prodID

The mandatory prodID operand is a kit identifier consisting of the product code and version number specified in the CODE and VERS fields of the kit's key file. Refer to Section 3.3 for information about the key file.

devname

The mandatory devname operand specifies the device special file name for a raw or character disk device such as /dev/rdisk/dsk1. The gendisk utility uses the disk partition specified in the kit descriptor and ignores any partition specified on the command line.

The command shown in Example 4-3 creates a tar format user product kit for OAT100 on the c partition of dsk0:

Example 4-3: Sample gendisk Command

# gendisk OAT100 /dev/rdisk/dsk0c

Refer to the gendisk(1) reference page for more information about this utility.

4.2.3 Building a User Product Kit on Magnetic Tape

After the product subsets are located in the output area of the kit directory structure, use the gentapes utility to build the kit on magnetic tape.

Use the following syntax for the gentapes command:

/usr/bin/gentapes [ -w | -v ] [hostname:] prodID devname

-w: Writes the product media without verification. Do not use the -w option with the -v option.
-v: Verifies the product media without writing it first. Do not use the -v option with the -w option.
hostname:: The optional hostname: argument is the name of a remote network machine that contains the kit descriptor database. The gentapes utility searches the kit descriptor database on the remote machine for the kit identifier (prodID[TK|MT]) and uses it to create the media. The colon (:) is a required delimiter for TCP/IP networks, and space is permitted between the colon and the prodID. For example, if the product code is OAT100, and the kitcap file to be used is on node mynode, use mynode:OAT100 for this option.
prodID: The mandatory prodID operand is a kit identifier consisting of the product code and version number specified in the CODE and VERS fields of the kit's key file. Refer to Section 3.3 for information about the key file.
devname: The mandatory devname operand specifies the device special file name for a no-rewind tape device such as /dev/ntape/tape0l. The gentapes utility uses the default tape density for the device and ignores any suffix specified on the command line.

Note

If you do not use either the -w or -v option, the gentapes utility writes the tape, rewinds it, and then verifies the files in the kit descriptor.

The command shown in Example 4-4 creates a tar format user product kit for OAT100 on the magnetic tape in /dev/ntape/dat:

Example 4-4: Sample gentapes Command

# gentapes OAT100 /dev/ntape/dat

Refer to the gentapes(1) reference page for more information about this utility.

4.3 Testing the Distribution Media

Before shipping a user product kit to customers, you should test the kit with the same procedures that your customers will use on configurations that resemble your customers' systems.

Use the setld utility to test a user product kit as described in the following procedure for the OAT100 kit:

Log in to the system as root or use the su command to gain superuser privileges.

Place the CD-ROM in the drive.

Create a directory to be the media mount point, such as /cdrom:
```
# mkdir /cdrom
```

Mount the CD-ROM on /cdrom. For example, if the CD-ROM device is located on the c partition of cdrom0, enter the following command:
```
# mount -r /dev/disk/cdrom0c /cdrom
```
After mounting the CD-ROM, you can change to the /cdrom directory and view the directories on the CD-ROM.

Install the user product subsets:


# setld -l /cdrom/OAT100/kit

*** Enter subset selections ***
 
The following subsets are mandatory and will be installed automatically
unless you choose to exit without installing any subsets:
 
      * Document Builder Tools
 
The subsets listed below are optional:
 
 - Other:
     1) Document Builder Templates
 
Or you may choose one of the following options:
 
     2) ALL mandatory and all optional subsets
     3) MANDATORY subsets only
     4) CANCEL selections and redisplay menus
     5) EXIT without installing any subsets
 
Estimated free diskspace(MB) in root:54.5 usr:347.0
 
Enter your choices or press RETURN to redisplay menus.
 
Choices (for example, 1 2 4-6): 2
 
You are installing the following mandatory subsets:
 
        Document Builder Kernel Support
        Document Builder Tools
 
You are installing the following optional subsets:
 
 - Other:
        Document Builder Templates
 
Estimated free diskspace(MB) in root:54.5 usr:347.0
 
Is this correct? (y/n): y
 
Checking file system space required to install selected subsets:
 
File system space checked OK.
 
3 subset(s) will be installed.
 
Loading subset 1 of 2 ...
 
Document Builder Tools
   Copying from /mykit/output (disk)
   Verifying
 
Loading subset 2 of 2 ...
 
Document Builder Templates
   Copying from /mykit/output (disk)
   Verifying
 
2 of 2 subset(s) installed successfully.
 
Configuring "Document Builder Tools" (OATODB100)
 
The installation of the Document Builder Tools (OATODB100)
software subset is complete.
 
Please read the /opt/OAT100/README.odb file before
using the Document Builder Tools product.
 
Configuring "Document Builder Templates" (OATODBTEMPS100)
 
#

The setld utility displays prompts and messages to guide you through the process of selecting the subsets you want to install. As each subset is loaded, the setld utility calls the subset control program as needed.

After the installation finishes, unmount the CD-ROM:
```
# umount /cdrom
```

Verify that the installed product functions correctly.

Refer to the Installation Guide and the setld(8) reference page for more information about using the setld utility to install layered products.