2    Creating the Kit Directory Structure

When engineers have finished developing a product, they hand over 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 it describes how to create a kit-building directory structure to fit within the standard directory structure.

Note

Foreign device products 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 the osfboot utility.

2.1    Designing the Customer's Directory Structure

For kit-building purposes, you can consider a product as consisting of various types of files. 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, 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 prototype data files are installed under /usr/opt in a product directory. The name of the product directory should consist of the 3-character product code and 3-digit version code. For example, the directory for the ODB product is /usr/opt/OAT100.

• Read/write files

  Files that can be read and written by users, such as lists of employee telephone numbers, are installed under /var/opt.

• Boot files

  Files that are required at boot time, such as file system drivers, are installed under the /opt directory.

Figure 2-1 illustrates how a kit is installed and made available in the traditional directories.

Figure 2-1: How Layered Products Are Installed

Digital recommends that you design your product to be installed in the /opt directories. Using this standard directory structure has the following advantages:

• Standardized product design and location.

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

• Exporting software to share across a network is simplified and more secure; you need only export the specific directories under /opt, /usr/opt, and /var/opt that contain the product you want and 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. This architecture also permits maintaining 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-2 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 traditional directories. For example, the ODB kit's /usr/bin/attr command is a symbolic link to /usr/opt/OAT100/bin/attr.

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

2.2    Kit-Building Directory Structure

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

Figure 2-3: Kit Directory Structure

• Source hierarchy

  The source hierarchy is a directory structure that exactly mirrors the directory structure into which your finished kit is installed by customers. 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:

  • A master inventory file lists each of the files in the kit and defines which subset contains each file.

  • A key file specifies the kit's attributes for the kits command, such as the product name and version and whether the subsets are in compressed or uncompressed format.

  The data hierarchy also contains a subdirectory named scps; if your product includes subset control programs, these programs are stored in the scps directory.

  There is no specific requirement for the location of the data hierarchy, but it is good practice to place it under the same directory in which you create 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 in which you create the source and data hierarchies.

Create the directory structure as follows:

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

2. 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 product. You can choose any appropriate method for populating the source hierarchy. For example, you could create a makefile for use with the make command.

Note

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 subset 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    Kit Directory Structure for a User Product

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, programs such as commands and utilities should be placed in directories that are part of the normal search path, such as /usr/bin. Similarly, libraries should be placed 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 Digital UNIX system provides special locations (the opt directories) for optional products. 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-4 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; likewise, the usr directory represents /usr on the customer's system, and 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-4: Directory Hierarchy for the ODB Kit

2.2.2    Kit Directory Structure for a Kernel Product

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-5 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-5: 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 how the driver product will be configured on the customer's system, as follows:

• 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. A foreign device is one type of statically configured driver. 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-6 shows which fields within the files file fragment need to change.

  Figure 2-6: 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 frament in the product directory, such as ESA100.

  You do not need to change the sysconfigtab file fragment unless you change the module name. The module name appears in three places within the file, as shown in Figure 2-7.

  Figure 2-7: Editing the sysconfigtab File Fragment

  

  In this 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.

• 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    Kit Directory Structure for a Foreign Device Product

A kit for a foreign device product contains all the same files as a kit for a kernel product kit, but 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. This file 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 boot 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 products on the same distribution media. A single media may contain several product kits and several name.kit files.

• An /etc/sysconfigtab file. This file 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 setld portion of the kit. The osfboot utility references these linked files.

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

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

Figure 2-8 shows the directory structure for the /dev/edgd graphics device driver kit.

Figure 2-8: 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 boot-link process to build this kit. When booting 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 foreign 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.

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

+/sys/BINARY/edgd.mod

Figure 2-9 shows how the name.kit file works with the osfboot software when installing a foreign device.

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 prior to the installation of the Digital UNIX operating system.

Figure 2-9: 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 product 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 driver kit exists.