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.
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.
Files that users can read and write, such as lists of employee telephone
numbers, are installed in a product-specific subdirectory of
/var/opt.
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:
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.
The following list describes each directory 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:
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:
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.
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:
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-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.
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:
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:
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.
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.
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.
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.
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.
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.
The following sections describe the contents of the name.kit and kitname.kk files.
Commands in the name.kit
file have the following form:
+[device:] [/path/]file.mod
-file.mod
file.mod=[device:][/path/]new.mod
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:
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.
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.
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:
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: 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
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.Caution
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.
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: Directory Structure for the /dev/none Driver Kit
Figure 2-5: Editing the files File Fragment
Figure 2-6: Editing the sysconfigtab File Fragment
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:
Note
Figure 2-7: Directory Structure for the /dev/edgd Foreign Device Kit
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.
Adds file.mod from the
root or the specified device. You can specify a full path or accept the default.
Deletes file.mod from
the module list on the default path for file.mod.
Replaces file.mod on
the default path with the module you specify.
+/sys/BINARY/edgd.mod
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.