Building a Package
This chapter describes a process, as well as the tasks, on how to build a package. Some of these tasks are required and some are optional. The required tasks are the minimum of what you must do to create a package, and are discussed in detail in this chapter. For information on the optional tasks, which enable you to add more features to your package, see Chapter 3, Enhancing the Functionality of a Package and Chapter 6, Advanced Package Creation Techniques.
This is a list of the overview information in this chapter.
The Process of Building a Package Task Map
The table below describes a process for you to follow when building packages, especially if you are inexperienced at building them. Although it is not mandatory for you to complete the first four tasks in the exact order listed, it will make your package building experience easier if you do. Once you are an experienced package designer, you can shuffle the sequence of these tasks to your preference.
As an experienced package designer, you can automate the package building process using the make command and makefiles. For more information, see make(1S).
Table 2-1 The Process of Building a Package Task Map
Task | Description | For Instructions, Go To ... |
|---|---|---|
1. Create a pkginfo File | You must create the pkginfo file to describe the characteristics of your package. | |
2. Organize Package Contents | You should arrange your package components into a hierarchical directory structure. | |
3. Create Information Files | Optional. Define package dependencies, include a copyright message, and reserve additional space on a target system. | |
4. Create Installation Scripts | Optional. Customize the installation and removal processes of a package. | |
5. Create a prototype File | Describe each object in your package in a prototype file. | |
6. Build the Package | Build your package using the pkgmk command. | |
7. Verify and Transfer the Package | Verify the integrity of a package before copying it to a distribution medium. |
Package Environment Variables
You can use variables in the required information files, pkginfo and prototype, as well as an option to the pkgmk command (which is used to build a package). As each of these files and commands are discussed in this chapter, more context-sensitive information on variables is provided. However, before you begin building your package, you should understand the different types of variables and how they can affect a package's successful creation.
There are two types of variables:
-
Build variables begin with a lowercase letter and are evaluated at build time (as the package is being built with the pkgmk command).
-
Install variables begin with an uppercase letter and are evaluated at install time (as the package is being installed with the pkgadd command).
General Rules on Using Environment Variables
In the pkginfo file, a variable definition is of the form PARAM=value, where the first letter of PARAM is an uppercase letter. These variables are evaluated only at install time, and if any cannot be evaluated, the pkgadd command will abort with an error.
In the prototype file, a variable definition can take the form !PARAM=value or $variable. Both PARAM and variable can begin with either an uppercase or lowercase letter; however, only variables whose values are known at build time will be evaluated. This means that if PARAM or variable is a build or install variable whose value is not known at build time, the pkgmk command will abort with an error.
You can also include the option PARAM=value as an option to the pkgmk command. This option works the same as in the prototype file, except that its scope is global to the entire package. The !PARAM=value definition in a prototype file is local to that file and the part of the package it defines.
If PARAM is an install variable, and variable is an install or build variable with a known value, the pkgmk command inserts the definition into the pkginfo file so that it will be available at install time. However, it will not evaluate PARAM in any path names specified in the prototype file.
Package Environment Variables Summary
The table below summarizes variable specification formats, location, and scope.
Table 2-2 Package Environment Variables Summary
Variable Defined In The ... | Variable Definition Format | Variable Type Being Defined | When The Variable Is Resolved | Where The Variable Is Resolved | The Variable May Be Used As Part Of The ... |
|---|---|---|---|---|---|
pkginfo file | PARAM=value | Build | Ignored at build time | N/A | None |
Install | Install time | In the pkgmap file | owner, group, path, or link target | ||
prototype file | !PARAM=value | Build | Build time | In the prototype file and any included files | mode, owner, group, or path |
Install | Build time | In the prototype file and any included files | !search and !command commands only | ||
pkgmk command line | PARAM=value | Build | Build time | In the prototype file | mode, owner, group, or path |
Install | Build time | In the prototype file | !search command only | ||
Install time | In the pkgmap file | owner, group, path, or link target |
Creating a pkginfo File
The pkginfo file is an ASCII file that describes the characteristics of a package along with information that helps control the flow of installation.
Each entry in the pkginfo file is a line that establishes the value of a parameter using the format PARAM=value. PARAM can be any of the standard parameters described in pkginfo(4), and there is no required order in which the parameters must be specified.
Note - Each value can be enclosed with single or double quotation marks (for example, 'value' or "value"). If value contains any characters that are considered special to a shell environment, you should use quotation marks. The examples and case studies in this book do not use quotation marks. See pkginfo(4) for an example that uses double quotation marks.
You can also create your own package parameters by assigning a value to them in the pkginfo file. Your parameters must begin with a capital letter followed by either uppercase or lowercase letters. An uppercase letter indicates that the parameter (variable) will be evaluated at install time (as opposed to build time). For information on the difference between install and build variables, see "Package Environment Variables".
Note - Trailing whitespace after any parameter value is ignored.
There are five parameters that you must define in a pkginfo file: PKG, NAME, ARCH, VERSION, and CATEGORY. Three additional parameters: PATH, PKGINST, and INSTDATE are inserted automatically when the package is built. These eight parameters should not be modified. For information on the remaining parameters, see the pkginfo(4) man page.
Defining a Package Instance
The same package can have different versions, be compatible with different architectures, or both. Each variation of a package is known as a package instance. A package instance is determined by combining the definitions of the PKG, ARCH, and VERSION parameters in the pkginfo file.
The pkgadd command assigns a package identifier to each package instance at installation time. The package identifier is the package abbreviation with a numerical suffix, for example SUNWadm.2. This identifier distinguishes a package instance from any other package, including instances of the same package.
Defining a Package Abbreviation (PKG)
A package abbreviation is a short name for a package that is defined via the PKG parameter in the pkginfo file, and must:
Be nine or fewer characters.
Not be one of the reserved abbreviations install, new, and all.
Note - The first four characters should be unique to your company, such as your company's stock symbol. For example, packages built by Sun Microsystems™ all have "SUNW" as the first four characters of their package abbreviation.
An example package abbreviation entry in a pkginfo file might be:
PKG=SUNWcadap