2    Creating the Kit Directory Structure

When engineers finish developing a product, they give the product files to you, the kit developer, 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 and how to create a kit-building directory structure to fit within the standard directory structure for user, kernel, and hardware product kits.

2.1    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-1.

Figure 2-1:  Kit Directory Hierarchy

The following 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:

  • 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, such as the product name and version and whether the subsets are in compressed or uncompressed format.

  • A subdirectory named scps contains any subset control programs that the product requires.

  The kits utility is run from the directory in which these files are located. 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. Additional files may be required, depending on the kit type.

• 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 ./kit/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.

Follow these steps to create the kit-building directory structure:

1. Issue the appropriate mkdir commands for each of the directories and subdirectories that you need. Refer to the mkdir(1) reference page if you need more information.

2. Populate the src directory with all the files that are to be part of the finished kit.

   • Section 2.2.1 describes the directory file structure you need for a user product

   • Section 2.2.2 describes the directory file structure you need for a kernel product

   • Section 2.2.2 and Section 5.1 describe the directory file structure you need for a hardware product

   You can choose any appropriate method for populating the source hierarchy. For example, you could create a Makefile file for use with the make command.

Caution

File attributes (ownership and permissions) for files and directories in the kit's source hierarchy must be set exactly as they should be on the customer's system. This means that you must be 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 their original values in the kit's master inventory files.

2.2    Populating the Source Directory

It is possible to 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 system directory structure is set up for efficient organization. It separates files by function and use.

You should install product files in subdirectories of /opt, /usr/opt, and /usr/var/opt, as follows:

• Boot files reside in /opt

  Files that are required at bootstrap time, such as device drivers, are installed in a product-specific subdirectory of /opt. This also includes any files accessed before file systems other than root ( / ) are mounted.

• Read-only files reside in /usr/opt

  Files that are usually 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 reside in /usr/var/opt

  Files that users can read and write, such as lists of data that any user is allowed to change, are installed in a product-specific subdirectory of /usr/var/opt.

The first thing you will need to get is a three letter product code from Compaq Computer Corporation for your product kit name. To obtain a product code, send mail to the Product@DSSR.enet.dec.com electronic mail address. You use this product code and a product version number that you assign to name the product-specific subdirectories of your product.

Examples in this book use OAT as the prefix for the product-specific subdirectory names for the Orpheus Document Builder (ODB) product kit. Assuming this is the first release of the product, the kit developer chose 100 as the version number. As such, directories are named /opt/OAT100, /usr/opt/OAT100, and /usr/var/opt/OAT100. OAT is the code assigned to Orpheus Authoring Tools, Inc., the ficticious company who developed the ODB product, and 100 is the product version number.

Using a 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 /usr/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.

• Name space conflicts are avoided. When a layered product installs a file that overwrites a file shipped by another product, it is known as a name space conflict. Shipping the files in the /opt, /usr/opt and /usr/var/opt avoids this conflict because each three letter product code is unique to a particular original equipment manufacturer (OEM).

For users to make effective use of your product after it is installed, they should add the directories that contain your product commands to the normal search path in their .profile or .login files. For example, the Orpheus Document Builder (ODB) product is installed in the standard directory structure under /opt, /usr/opt and /usr/var/opt. The commands for the product are located in the /opt/OAT100/bin and /usr/opt/OAT100/bin directories. To be able to use ODB commands without specifying the full path on the command line, the user can add the product path to the PATH environment variable.

It is possible to ship a symbolic link to make commands accessible through the standard directories. For example, the ODB kit contains the command /usr/opt/OAT100/bin/attr. A symbolic link can be created from /usr/bin/attr to /usr/opt/OAT100/bin/attr. This would also make the attr command available to the user as a part of their normal search path, since /usr/bin is part of the standard path.

Shipping a symbolic link can be done if:

• The symbolic link does not conflict with any base operating system file. Using our example, it means that you could create the /usr/bin/attr link only if the operating system does not already contain a /usr/bin/attr file. If the operating system did contain a /usr/bin/attr file, you could not ship the symbolic link, because installing the link would overwrite an operating system file.

• The command name does not conflict with any standard operating system command. For example, the /usr/opt/OAT100/bin/attr command is shipped in the ODB kit and as part of the standard operating system in /bin/attr. When the user enters the attr command, there would be a command name conflict and, depending upon which directory is first in the search path, /bin or /usr/bin, the user could be getting the operating system version or the symbolically linked ODB product version.

Figure 2-2 shows how the Orpheus Document Builder (ODB) product is installed in the standard directory structure, under /opt, /usr/opt, and /usr/var/opt. The directories shown above the OAT* directories are the existing directories on the customer's system. All directories and files created by the layered product ship under the OAT* directories. In this example, directory names begin with OAT because OAT is the three letter product code assigned to Orpheus Authoring Tools, Inc..

Figure 2-2:  Layered Product Standard Directories

Caution

Shipping any file outside of the /opt, /usr/opt, and /usr/var/opt directories is not recommended and could cause a name space conflict with the base operating system or another layered product.

Overwriting base operating system files can cause the following problems:

• Your product will be corrupted during an Update Installation of the operating system. The Update Installation will overwrite any file that was shipped as part of the old version with the new version of the file.

• Overwriting a base operating system file can prevent an Update Installation from completing successfully and may render the system unusable.

• The user could be forced to remove your product from the system as a part of an Update Installation process. The user would then have to reinstall your product after the Update Installation has been completed.

2.2.1    Directory Structure for a User Product Kit

The files are installed in directories under /opt, /usr/opt, and /usr/var/opt so that the files are centrally located and easy to find. The ODB kit contains files to be installed in the following directories:

• /usr/opt/OAT100/bin

• /usr/opt/OAT100/lib/br

• /usr/opt/OAT100/lib/doclib/templates

Figure 2-3 illustrates the complete directory structure for the ODB kit. In this figure, the top level directory (drawn with dashed lines), dcb_tools, represents an existing directory under which a kit developer created the hierarchy directories.

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 three-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. Version numbers cannot be lower than 100.

If the ODB kit included user-writable files, they would be placed under the /usr/var/opt/OAT100 directory. It is recommended that this convention be used for consistency among user products.

Figure 2-3:  Directory Hierarchy for the ODB Kit

2.2.2    Directory Structure for Kernel Product and Hardware Product Kits

You set up a kit directory structure for a kernel product and hardware product in the same way as you would for a user product. You create three directory hierarchies -- src, 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 /usr/var/opt as appropriate. Unlike a user product, the kit for a kernel product or hardware 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 first introduced in Writing Device Drivers: Tutorial.

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

The top-level directory (which is drawn with dashed lines) 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 statically linked into the kernel at build (or bootlink) time. It is configured at boot time. A static driver can be built from source files, binary objects, modules, or all three.

• A dynamically configured driver is loaded into a running kernel after it has been booted. It is not part of the permanent kernel, and must be reloaded after each boot of the system. It is configured when it is loaded. A dynamic driver can be built from source files, binary objects, modules, or all three.

Note:

A module that is capable of being loaded dynamically also can be linked statically. The only difference is the call to configure the driver (for more information on static or dynamic drivers, see Writing Device Drivers: Tutorial).

The following list describes the files that go into a kernel or hardware kit for a device driver, 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 a product directory, such as /opt/ESA100/etc. 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.

  Note

  The files file fragment must be in the same directory as the kernel modules or the kreg and doconfig utilities will not work properly.

  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 or hardware product kit, the driver's sysconfigtab file fragment gets appended to the /etc/sysconfigtab database. You should place this file fragment in a product directory, such as /opt/ESA100/etc. 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 a product directory, such as /opt/ESA100/sys/BINARY which must be in the root ( / ) file system. The kernel will not allow two kernel modules to have the same name. To avoid kernel module naming conflicts with other OEMs and the base operating system, it is recommended that you prepend your three letter product code to your module names.

  Note

  Module files for hardware products must be compressed using the objZ utility. Do not use the compress or gzip utilities to compress module files.

• *.c (source) and *.h (header) files

  Contain the source code for the device driver. You should include these files in a product directory, such as /usr/opt/ESA100, when the driver is statically configured and distributed in source form.

• device.mth method files

  Contain driver methods that are called during auto configuration to create device special files for dynamically configured drivers. These files are on the distribution media, but are not installed onto the customer's system as part of 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 developer 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.