openSolaris 2008 - Creating Class Archive Packages - Application Packaging Developer's Guide

Creating Class Archive Packages

A class archive package, which is an enhancement to the Application Binary Interface (ABI), is one in which certain sets of files have been combined into single files, or archives, and optionally compressed or encrypted. Class archive formats increase initial install speed by up to 30% and improves reliability during installation of packages and patches onto potentially active file systems.

The following sections provide information about the archive package directory structure, keywords, and faspac utility.

Structure of the Archive Package Directory

The package entry shown in the figure below represents the directory containing the package files. This directory must be the same name as the package.

Figure 6-1 Package Directory Structure

Diagram shows five subdirectories directly under the package directory: pkginfo, pkgmap, reloc, root, and install. Also shows their subdirectories.

The following lists the functions of the files and directories contained within the package directory.

Item	Description
`pkginfo`	File describing the package as a whole including special environment variables and installation directives
`pkgmap`	File describing each object (file, directory, pipe, etc.) to be installed
`reloc`	Optional directory containing the files to be installed relative to the base directory (the relocatable objects)
`root`	Optional directory containing the files to be installed relative to the `root` directory (the root objects)
`install`	Optional directory containing scripts and other auxiliary files (except for `pkginfo` and `pkgmap`, all `ftype i` files to here)

The class archive format allows the package builder to combine files from the reloc and root directories into archives which can be compressed, encrypted, or otherwise processed in any desired way in order to increase install speed, reduce package size, or increase package security.

The ABI allows any file within a package to be assigned to a class. All files within a specific class may be installed to the disk using a custom method defined by a class action script. This custom method may make use of programs available on the target system or programs delivered with the package. The resulting format looks much like the standard ABI format. As shown in the following illustration, another directory is added. Any class of files intended for archive is simply combined into a single file and placed into the archive directory. All archived files are removed from the reloc and root directories and an install class action script is placed into the install directory.

Figure 6-2 Archive Package Directory Structure

Diagram shows the same package directory structure in Figure 6-1 with the addition of the archive subdirectory.

Keywords to Support Class Archive Packages

In order to support this new class archive format, three new interfaces in the form of keywords have special meaning within the pkginfo file. These keywords are used to designate classes requiring special treatment. The format of each keyword statement is: keyword=class1[class2 class3 ...]. Each keyword values are defined in the following table.

Keyword	Description
`PKG_SRC_NOVERIFY`	This tells `pkgadd` not to verify the existence and properties of the files in the delivered package's `reloc` or `root` directories if they belong to the named class. This is required for all archived classes, because those files are no longer in a `reloc` or `root` directory. They are a private format file in the `archive` directory.
`PKG_DST_QKVERIFY`	The files in these classes are verified after installation using a quick algorithm with little to no text output. The quick verify first sets each file's attributes correctly and then checks to see if the operation succeeded. There is then a test of the file size and modification time against the `pkgmap`. No `checksum` verification is performed and there is poorer error recovery than that provided by the standard verification mechanism. In the event of a power outage or disk failure during installation, the contents file may be inconsistent with the installed files. This inconsistency can always be resolved with a `pkgrm`.
`PKG_CAS_PASSRELATIVE`	Normally the install class action script receives from `stdin` a list of source and destination pairs telling it which files to install. The classes assigned to `PKG_CAS_PASSRELATIVE` do not get the source and destination pairs. Instead they receive a single list, the first entry of which is the location of the source package and the rest of which are the destination paths. This is specifically for the purpose of simplifying extraction from an archive. From the location of the source package, you can find the archive in the `archive` directory. The destination paths are then passed to the function responsible for extracting the contents of the archive. Each destination path provided is either absolute or relative to the base directory depending on whether the path was located in `root` or `reloc` originally. If this option is chosen, it may be difficult to combine both relative and absolute paths into a single class.

For each archived class a class action script is required. This is a file containing Bourne shell commands which is executed by pkgadd to actually install the files from the archive. If a class action script is found in the install directory of the package, pkgadd turns all responsibility for installation over to that script. The class action script is run with root permissions and can place its files just about anywhere on the target system.

Note - The only keyword that is absolutely necessary in order to implement a class archive package is PKG_SRC_NOVERIFY. The others may be used to increase installation speed or conserve code.

The `faspac` Utility

The faspac utility converts a standard ABI package into a class archive format used for bundled packages. This utility archives using cpio and compresses using compress. The resulting package has an additional directory in the top directory called archive. In this directory will be all of the archives named by class. The install directory will contain the class action scripts necessary to unpack each archive. Absolute paths are not archived.

The faspac utility has the following format:

faspac [-m Archive Method] -a -s -q [-d Base Directory] /
[-x Exclude List] [List of Packages]

Each faspac command option is described in the following table.