Chapter 1 Designing a Package

Before you build a package, you need to know which files you need to create and the commands you need to execute. You also need to consider your application software's requirements, and the needs of your customer--the administrators who will be installing your package. This chapter discusses the files, commands, and criteria you should know and think about, before building a package.

This is a list of the overview information in this chapter.

• "Where to Find Packaging Tasks"

• "What Are Packages?"

• "Package Components"

• "Things to Think About Before Building a Package"

• "Packaging Commands, Files, and Scripts"

Where to Find Packaging Tasks

Use these references to find step-by-step instructions for building and verifying packages.

• "The Process of Building a Package Task Map"

• "Creating Information Files and Installation Scripts Task Map"

• "Verifying and Transferring a Package Task Map"

What Are Packages?

Application software is delivered in units called packages. A package is a collection of files and directories required for a software product, and is usually designed and built by the application developer after completing the development of the application code. A software product needs to be built into one or more packages so that it can easily be transferred to a distribution medium, be mass produced, and installed by administrators.

Package Components

The components of a package fall into two categories: package objects, the application files to be installed, and control files, which control how, where, and if the package is installed.

The control files are also divided into two categories: information files and installation scripts. Some of these control files are required and some are optional.

To package your applications, you must first create the required components, and any optional components, that make up your package. Then you can build the package using the pkgmk command.

To build a package, you must provide the following:

• Package objects (the application software files)

• Two required information files (the pkginfo and prototype files)

• Optional information files and installation scripts

Figure 1-1 describes the contents of a package.

Figure 1-1 The Contents of a Package

Required Package Components

You must create the following components before you build your package:

• Package Objects

  These are the components that make up the application. They can be:

  • Files (executable or data)

  • Directories

  • Named pipes

  • Links

  • Devices

• The pkginfo file

  The pkginfo file is a required package information file defining parameter values such as the package abbreviation, the full package name, and the package architecture. For more information, see "Creating a pkginfo File" and the pkginfo(4) man page.

  ---

  Note -

  There are two pkginfo(1) man pages. The first is a section 1 command, which displays information about installed packages. The second is a section 4 file, which describes the characteristics of a package. When accessing the man pages, be sure to specify from which section you want the man page. For example: man -s 4 pkginfo

  ---

• The prototype file

  The prototype file is a required package information file that lists the components of the package. It describes the location, attributes, and file type for each component within a package.

  In the prototype file, there is one entry for each package object, information file, and installation script. An entry consists of several fields of information describing the object. For more information, see "Creating a prototype File" and the prototype(4) man page.

Optional Package Components

Package Information Files

There are four optional package information files you can include in your package:

• The compver file

  Defines previous versions of the package that are compatible with this version.

• The depend file

  Indicates other packages with which this package has special relationships.

• The space file

  Defines disk space requirements for the target environment, beyond what is needed by the objects defined in the prototype file. For example, additional space might be needed for files that are dynamically created at installation time.

• The copyright file

  Defines the text for a copyright message displayed at the time of package installation.

Each package information file should have an entry in the prototype file. See "Creating Information Files" for more information on creating these files.

Package Installation Scripts

Installation scripts are not required. However, you can provide scripts that perform customized actions during the installation of your package. An installation script has the following characteristics.

• It is composed of Bourne shell commands.

• Its file permissions should be set to 0644.

• It does not need to contain the shell identifier (#! /bin/sh).

The four script types are as follows:

• The request script

  The request script requests input from the administrator installing the package.

• The checkinstall script

  The checkinstall script performs special file system verification.

  ---

  Note -

  The checkinstall script is only available with the Solaris^TM 2.5 and compatible releases.

  ---

• Procedure scripts

  Procedure scripts define actions that occur at particular points during package installation and removal. There are four procedure scripts you can create with these predefined names: preinstall, postinstall, preremove, and postremove.

• Class Action scripts

  Class Action scripts define a set of actions to be performed on a group of objects.

See "Creating Installation Scripts" for a more information on installation scripts.

Things to Think About Before Building a Package

Before building a package, you need to decide whether your product is going to be made up of one or more packages. (Note that many small packages take longer to install than one big package.) Although it is a good idea to create a single package, it is not always possible. If you decide to build more than one package, you need to determine how to segment the application code. This section provides a list of criteria to use when planning to build packages.

Many of the good packaging criteria present trade-offs among themselves. It will often be difficult to satisfy all requirements equally. These criteria are presented in order of importance; however, this sequence is meant to serve as a flexible guide depending on the circumstances. Although each of these criteria is important, it is up to you to optimize these requirements to produce a good set of packages.

For more design ideas, see Chapter 6, Advanced Package Creation Techniques.

Make Packages Installable Remotely

All packages must be installable remotely. Being installable remotely means that the administrator installing your package might be trying to install it on a client system, not necessarily to the root file system where the pkgadd command is being executed.

Optimize for Client-Server Configurations

If you are designing a package for a Solaris 2.5 or compatible release, you should consider the various types of system software configurations (for example, standalone, diskless, and server) when laying out packages. Good packaging design divides the affected files to optimize installation of each configuration type. For example, the contents of root (/) and usr should be segmented so that dataless and server configurations can easily be supported.

Package by Functional Boundaries

Packages should be self-contained and distinctly identified with a set of functionality. For example, a package containing UFS should contain all UFS utilities and be limited to only UFS binaries.

Packages should be organized from a customer's point of view into functional units.

Package Along Royalty Boundaries

Put code that requires royalty payments due to contractual agreements in a dedicated package or group of packages. Do not disperse the code into more packages than necessary.

Package by System Dependencies

Keep system-dependent binaries in dedicated packages. For example, the kernel code should be in a dedicated package with each implementation architecture corresponding to a distinct package instance. This rule also applies to binaries for different architectures. For example, SPARC^TM binaries would be in one package and binaries for an x86 system would be in another.

Eliminate Overlap in Packages

When constructing packages, eliminate duplicate files whenever possible. Unnecessary duplication of files results in support and version difficulties. If your product has multiple packages, repeatedly compare the contents of these packages for redundancies.

Package Along Localization Boundaries

Localization-specific items should be in their own package. An ideal packaging model would have a product's localizations delivered as one package per locale. Unfortunately, in some cases organizational boundaries may conflict with the functional and product boundaries criteria.

International defaults can also be delivered in a package. This would isolate the files necessary for localization changes and standardize delivery format of localization packages.

Packaging Commands, Files, and Scripts

The purpose of this section is to describe the commands, files, and scripts you might use when manipulating packages. They are described in man pages and in detail throughout this book, in relation to the specific task they perform.

Table 1-1 shows the commands available to help you build, verify, install, and obtain information about a package.

Table 1-1 Packaging Commands

Function	Command	Description	For More Information, Go To ...
Create packages	pkgproto(1)	Generate a prototype file for input to the pkgmk command	"Creating a prototype File With the pkgproto Command"
	pkgmk(1)	Create an installable package	"Building a Package"
Install, remove, and transfer packages	pkgadd(1M)	Install a software package onto a system	"Installing Software Packages"
	pkgask(1M)	Store answers to a request script	"Design Rules for request Scripts"
	pkgtrans(1)	Copy packages onto a distribution medium	"Transferring a Package to a Distribution Medium"
	pkgrm(1M)	Remove a package from a system	"Removing a Package"
Obtain information about packages	pkgchk(1M)	Check consistency of a software package	"Verifying the Integrity of a Package"
	pkginfo(1)	Display software package information	"The pkginfo Command"
	pkgparam(1)	Display package parameter values	"The pkgparam Command"
Modify installed packages	installf(1M)	Incorporate a new package object into an already installed package	"Design Rules for Procedure Scripts" and Chapter 5, Package Creation Case Studies
	removef(1M)	Remove a package object from an already installed package	"Design Rules for Procedure Scripts"

Table 1-2 shows the information files available to help you build a package.

Table 1-2 Package Information Files

Files	Description	For More Information, Go To ...
admin(4)	Package installation defaults file	"The Administrative Defaults File"
compver(4)	Package compatibility file	"Defining Package Dependencies"
copyright(4)	Package copyright information file	"Writing a Copyright Message "
depend(4)	Package dependencies file	"Defining Package Dependencies"
pkginfo(4)	Package characteristics file	"Creating a pkginfo File"
pkgmap(4)	Package contents description file	"The pkgmap File"
prototype(4)	Package information file	"Creating a prototype File"
space(4)	Package disk space requirements file	"Reserving Additional Space on a Target System"

Table 1-3 describes optional installation scripts that you can write that affect if and how a package is installed.

Table 1-3 Package Installation Scripts

Scripts	Description	For More Information, Go To ...
request	Solicit information from the installer.	"Writing a request Script"
checkinstall	Gather file system data.	"Gathering Data With the checkinstall Script"
preinstall	Perform any custom installation requirements before class installation.	"Writing Procedure Scripts"
postinstall	Perform any custom installation requirements after all volumes are installed.	"Writing Procedure Scripts"
preremove	Perform any custom removal requirements before class removal.	"Writing Procedure Scripts"
postremove	Perform any custom removal requirements after all classes have been removed.	"Writing Procedure Scripts"
Class Action	Perform a series of actions on a specific group of objects.	"Writing Class Action Scripts"