2 Creating the Kit Directory Structure

When engineers finish developing a product, they give the product files to you for packaging and processing into a kit. Your first task is to organize these files by function and use, then to place them in a kit-building directory structure. When designing the kit-building directory structure, you must consider where you want to place the product files on the customer's system. You then create a kit directory structure on the development system that closely mirrors the customer's directory structure.

This chapter describes the standard directory structure of Digital UNIX systems and how to create a kit-building directory structure to fit within the standard directory structure.

2.1 Designing the Customer's Directory Structure

You can install the components of a kit in any directory on the customer's system. However, guidelines exist for deciding where to place kit files. The standard Digital UNIX system directory structure is set up for efficient organization. It separates files by function and use. You should install product files in subdirectories of /usr/opt, /var/opt, and /opt, as follows:

Read-only files
Files that are nominally read-only, such as commands, startup files (which can be modified, but not by individual users), or data files are installed in a product-specific subdirectory of /usr/opt.

Read/write files
Files that users can read and write, such as lists of employee telephone numbers, are installed in a product-specific subdirectory of /var/opt.

Boot files
Files that are required at bootstrap time, such as device drivers, are installed in a product-specific subdirectory of /opt.

The name of the product-specific subdirectory should consist of a 3-character product or company code and a 3-digit version code, as specified in the key file (see Chapter 4). For example, the product-specific subdirectory names for the ODB product kit are /opt/OAT100, /usr/opt/OAT100, and /usr/var/opt/OAT100.

Using this standard directory structure has the following advantages:

If disk partition restructuring or product maintenance becomes necessary, it is easier to find all of your kit if its components are in the /opt directories rather than scattered throughout the standard directories.

Exporting software to share across a network is simplified and more secure; you need to export only the specific directories under /opt, /usr/opt, and /var/opt that contain the product you want, then create links on the importing system. You can set up a server with multiple versions of a given product, using the links created on the client systems to determine which version a given client uses. In this way, you can maintain software for multiple dissimilar hardware platforms on the same server.

For users to make effective use of the file system after they install your product, files should be in directories that are in the normal search path as specified by the user's .profile or .login files, as appropriate. Your product directories would not ordinarily be in the user's search path. Therefore, the installation procedure must create links from the directory where your product files reside and the directory where users will search for them. The subset control programs create these links during product installation.

Figure 2-1 shows how the Orpheus Document Builder (ODB) product is installed in the standard directory structure, under /opt, /usr/opt, and /var/opt. A symbolic link makes each file accessible through the standard directories. For example, the ODB kit's /usr/bin/attr command is a symbolic link to /usr/opt/OAT100/bin/attr.

Figure 2-1: Linking Product Files to Standard Digital UNIX Directories

2.2 Creating a Kit-Building Directory Structure

To create a kit, you need three separate directory hierarchies on the kit development system, as shown in Figure 2-2.

Figure 2-2: Kit Directory Structure

The following list describes each directory hierarchy:

Source hierarchy
The source hierarchy is a directory structure that exactly mirrors the directory structure into which customers install your finished kit. You must place each file that is to become part of your kit into the appropriate directory in the source hierarchy. You can create the source hierarchy under any directory you choose.

Data hierarchy
The data hierarchy is a directory structure that contains the following files to specify the contents of the kit and how it is organized:
There is no specific requirement for the location of the data hierarchy, but it is good practice to place it under the same directory as the source hierarchy.

Output hierarchy
The output hierarchy is a directory structure that contains the subsets that are placed on the kit. The subset control files that are needed during installation are stored in the instctrl subdirectory. There is no specific requirement for the location of the output hierarchy, but it is good practice to place it under the same directory as the source and data hierarchies.

Create the kit-building directory structure as follows:

Issue the appropriate mkdir commands for each of the directories and subdirectories that you need.

Populate the src directory with all the files that are to be part of the finished kit. Section 2.2.1 describes the files you need for a user product. Section 2.2.2 describes the files you need for a kernel product. Section 2.2.3 describes the files you need for a foreign device kit. You can choose any appropriate method for populating the source hierarchy. For example, you could create a makefile for use with the make command.

Caution
File attributes, such as ownership and permissions, for all the files and directories in the source hierarchy must be exactly as they should be on the customer's system. Usually, this requirement means that you must be a superuser when populating the source hierarchy so that you can change these file attributes. Do not attempt to circumvent this requirement by setting file attributes in your subset control programs. If a superuser on the customer's system runs the fverify command on your subsets, attributes that the subset control programs have modified are reset to the values they have in the kit's master inventory files.
Under most circumstances, your kit should not include any files whose pathnames exactly match those of existing system files. If you do, the kit's files are installed in place of the existing files.

2.2.1 Directory Structure for a User Product Kit

A user product should be designed so that the user sees it as an integral part of the system. This means that, as with base-system software, you should place programs such as commands and utilities in directories that are part of the normal search path, such as /usr/bin. Similarly, you should place libraries in directories where users would expect to find them, such as /usr/lib.

The example ODB kit places command files in the standard system directory (/usr/bin), the product's documentation in a directory created by another user product (/usr/lib/br), and template files for users employing the product in a directory unique to the ODB product (/usr/share/doclib/templates).

The actual files for the ODB kit, however, are not physically located in any of the directories listed in the preceding paragraph. The files are installed in directories under /opt, /usr/opt, and /var/opt so that the files are centrally located and easy to find. Then a symbolic link is created for each file that makes the file accessible through the standard system directories.

The ODB kit contains files to be installed in the following directories:

/usr/opt/OAT100/bin

/usr/opt/OAT100/lib/br

/usr/opt/OAT100/share/doclib/templates

Figure 2-3 illustrates the complete directory structure for the ODB kit. In this figure, the dashed directory, dcb_tools, represents the existing directory under which you would create the source hierarchy's directories as shown.

The src directory represents the root directory on the customer's system; the usr directory represents /usr on the customer's system. All the other directories in the source hierarchy are mapped to the customer's system in the same way.

The name of the top-level product-specific directory, under the source hierarchy's opt directory, is made up of the product code and a 3-digit version number, where the first digit identifies the major version number, the second digit identifies the minor version number, and the third digit identifies the update level. For example, the product code for the ODB kit is OAT and its version number is 100, indicating major version 1, minor version 0, update 0.

File names in the standard directory structure, where users would usually expect the files to appear, are linked symbolically to the actual files installed on the customer's system. For example, the command named /usr/bin/attr exists as a link to /usr/opt/OAT100/bin/attr.

If the ODB kit included user-writable files, they would be placed under /var, and there would also be a /var/opt/OAT100 directory to contain those files. Digital recommends this convention for consistency among user products.

Figure 2-3: Directory Hierarchy for the ODB Kit

2.2.2 Directory Structure for a Kernel Product Kit

You set up a kit directory structure for a kernel product in the same way as you would for a user product. You create three directory hierarchies -- source, data, and output -- and populate the source hierarchy with the product files. Under the src directory, create a directory structure similar to the one on the customer's system and place the product files in /opt, /usr/opt, and /var/opt, as appropriate. Unlike a user product, the kit for a kernel product (such as a device driver) requires certain files to be present in specific directory locations.

Figure 2-4 shows the directory structure of a device driver product as it would appear in the kit development area. The driver shown here is the /dev/none driver produced by the fictitious company called EasyDriver, Inc. This driver is introduced in Writing Device Drivers: Tutorial.

Figure 2-4: Directory Structure for the /dev/none Driver Kit

The top-level directory (easy) represents the working area for all kit development at EasyDriver, Inc. The src directory corresponds to the customer's root directory (/). Directories under src have a one-to-one relationship to directories on the customer's system. The ESA100 directory represents the top-level product directory for the /dev/none driver.

The files needed for building a kit depend on whether the driver product will be statically or dynamically configured on the customer's system. For example:

A statically configured driver is configured in the bootpath. It is built into the kernel. The kit for a statically configured driver can contain either driver source files, single binary modules, or both. For example, a device driver for a foreign device is statically configured into the kernel. However, it cannot be distributed in source form, only single binary (.mod) form.

A dynamically configured driver is configured at run time. It is added into an existing kernel but is not a permanent part of the kernel. Whenever the system restarts, the system manager must reconfigure the driver. Kits for dynamically configured drivers contain only single binary modules, not the source files for the driver.

The following list describes the files that go into a device driver kit, the directories where they reside, and the types of drivers that use them:

files file fragment
Contains information about the location of the source code and modules associated with the driver, tags indicating when the driver is loaded into the kernel, and whether the source or binary form of the driver is supplied to the customer. For both statically and dynamically configured drivers, place this file in the product directory, such as ESA100. You need to edit this file if the kit development directory structure differs from the driver development directory structure or if you must change the driver name for any reason. Figure 2-5 shows which fields within the files file fragment need to change.
Figure 2-5: Editing the files File Fragment
sysconfigtab file fragment
Contains device special file information, bus option data information, and information on contiguous memory usage for statically and dynamically configured drivers. When the user installs a kernel product kit, the driver's sysconfigtab file fragment gets appended to the /etc/sysconfigtab database. You should place this file fragment in the product directory, such as ESA100. You do not need to change the sysconfigtab file fragment unless you change the driver (subsystem) name. The driver name appears in three places within the file, as shown in Figure 2-6. In the example, the driver runs on a TURBOchannel bus (indicated by the TC_Option entry), but a similar set of bus options would be specified for other bus types.
Figure 2-6: Editing the sysconfigtab File Fragment
driver.mod object module file
Contains the single binary module for both statically and dynamically configured drivers. You should include this file in the product directory, such as ESA100. The subset control program references or copies this file into the customer's BINARY and subsys directories when the driver is installed.

*.c (source) and *.h (header) files
Contain the source code for the device driver. You should include these files in the product directory, such as ESA100, when the driver is statically configured and distributed in source form.

driver.mth method files
Contain driver methods that are called during autoconfiguration to create device special files for dynamically configured drivers. These files do not appear on the driver kit. The subset control program creates links to these files in the customer's subsys directory when the driver is installed. The device driver writer can tell you which method files the subset control program should link to, typically /subsys/device.mth. You need to link the method in a device driver kernel kit only if the driver needs to have device special files created for its devices.

2.2.3 Directory Structure for a Foreign Device Kit

A foreign device kit contains all the files for a kernel product, but it requires the following additional files on the media to make the media accessible during initial system installation and bootstrap:

A name.kit file, where name is based on the device name. You provide this file on the foreign device kit to control the actions of the osfboot utility. The osfboot utility configures device drivers into a temporary kernel so that system managers can use devices that would not otherwise be available during the initial installation and bootstrap of the operating system. You place this file on the foreign device kit media after creating the kit media with the gendisk utility. Because this file is not part of the product and not installed on the system, it does not belong in the kit directory structure.

Additional name.kit files for any other foreign device kits on the same distribution media. A single media may contain several kits and several name.kit files.

An /etc/sysconfigtab database. This database defines attributes of the modules that osfboot configures. Like the name.kit file, this file does not belong in the kit directory structure.

Links to modules in the kit directory structure. Remember that a foreign device kit is shipped as a UNIX file system, so it contains the entire kit-building directory structure, not only the subsets. By creating links, you save space because you do not create duplicate copies of files.

Possibly a kitname.kk file, where kitname is the product name. If the foreign device kit will be installed on a RIS server, you must supply this file in the instctrl subdirectory.

Note
Foreign device kits require several files that are not part of the kit directory structure. These files are not installed on the customer's system, but are used by the osfboot utility.

Neither the name.kit file, the kitname.kk file, the /etc/sysconfigtab database, nor the links are placed on the customer's system when setld runs; the osfboot utility and the Remote Installation Services (RIS) procedure use them at installation time.

Figure 2-7 shows the directory structure for the /dev/edgd graphics device driver product.

Figure 2-7: Directory Structure for the /dev/edgd Foreign Device Kit

The following sections describe the contents of the name.kit and kitname.kk files.

2.2.3.1 The name.kit File

Commands in the name.kit file describe how osfboot needs to modify the bootstrap link process to build this kit. When bootstrap linking from a foreign device kit, osfboot sets the default directory to the kit root directory. (Ordinarily, the default is /sys/BINARY on the system disk.) Commands in the name.kit file indicate which modules should be added, removed, or replaced in the kernel. When you specify the modules for the device driver, the directory path is relative to the kit directory by default.

Commands in the name.kit file have the following form:

+[device:] [/path/]file.mod

Adds file.mod from the root or the specified device. You can specify a full path or accept the default.

-file.mod

Deletes file.mod from the module list on the default path for file.mod.

file.mod=[device:][/path/]new.mod

Replaces file.mod on the default path with the module you specify.

The foreign device kit for the /dev/edgd driver supplies one name.kit file, which adds the edgd.mod single binary module to the kernel. In the following example, /sys/BINARY refers to the directory on the kit, not the system disk:

+/sys/BINARY/edgd.mod

Figure 2-8 shows how the name.kit file works with the osfboot software during installation of a foreign device kit.

In the figure, the driver kit contains a name.kit file called edgd.kit. The edgd.kit file instructs the osfboot utility to build and configure a temporary /vmunix kernel that includes the /dev/edgd driver. Upon completion, this temporary /vmunix kernel makes the /dev/edgd driver available to handle user and system requests of a specific hardware device during the installation of Digital UNIX.

Figure 2-8: Using a name.kit File During System Installation

2.2.3.2 The kitname.kk File

The Remote Installation Services (RIS) utility provides the ability to install foreign device kits into a RIS area for subsequent installation on a client. For more information about this feature, see Sharing Software on a Local Area Network.

If you want to allow the device driver product to use this feature, create a kitname.kk file in the instctrl directory. The file may be empty, but it must exist. It indicates to RIS that a foreign device kit exists.