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 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. |
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).
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.
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 |
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.
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.
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.
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.
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.
The first four characters should be unique to your company, such as your company's stock symbol. For example, packages built by Sun MicrosystemsTM 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 |
ARCH
)The ARCH
parameter in the pkginfo file identifies which architectures are associated with
the package. The architecture name has a maximum length of 16 alphanumeric
characters. If a package is associated with more than one architecture, specify
them in a comma-separated list.
For example, a package architecture specification in a pkginfo file might be:
ARCH=sparc |
SUNW_ISA
)The SUNW_ISA
parameter in
the pkginfo file identifies which instruction set architecture
is associated with a Sun Microsystems package. The values are:
sparcv9, for a package containing 64–bit objects
sparc, for a package containing 32–bit objects
For example, the SUNW_ISA
value in a pkginfo file for a package containing 64–bit
objects would be:
SUNW_ISA=sparcv9 |
If SUNW_ISA
is not set,
the default instruction set architecture of the package is set to the value
of the ARCH
parameter.
VERSION
)The VERSION
parameter in
the pkginfo file identifies the version of the package.
The version has a maximum length of 256 ASCII characters, and cannot begin
with a left parenthesis.
An example version specification in a pkginfo file might be:
VERSION=release 1.0 |
NAME
)A package name is the full name of the package,
which is defined via the NAME
parameter in the pkginfo file.
Because system administrators often use package names to determine whether or not a package needs to be installed, it is important to write clear, concise, and complete package names. Package names should:
State when a package is needed (for example, to provide certain commands or functionality, or state if it is needed for specific hardware).
State what the package is used for (for example, the development of device drivers).
Include a description of the package abbreviation mnemonic, using key words that indicate the abbreviation is a short form of the description (for example, the package name for the package abbreviation SUNWbnuu is “Basic Networking UUCP Utilities, (Usr)”).
Name the partition into which the package is installed.
Use terms consistently with their industry meaning.
Take advantage of the 256 character limit.
An example package name defined in a pkginfo file might be:
NAME=Chip designers need CAD application software to design abc chips. Runs only on xyz hardware and is installed in the usr partition. |
CATEGORY
)The CATEGORY
parameter in
the pkginfo file specifies in which categories a package
belongs. At a minimum, a package must belong to either the system or application category. Category names:
Are alphanumeric.
Have a maximum length of 16 characters.
Are case insensitive.
If a package belongs to more than one category, specify them in a comma-separated list.
An example CATEGORY
specification
in a pkginfo file might be:
CATEGORY=system |
Using your favorite text editor, create a file named pkginfo.
You can create this file anywhere on your system.
Edit the file and define the five required parameters.
The five required parameters are: PKG
, ARCH
, VERSION
, NAME
, and CATEGORY
.
For more information on these parameters, see Creating a pkginfo File.
Add any other parameters that you like to the file.
Create your own parameters or see pkginfo(4) for information on the standard parameters.
Save your changes and quit the editor.
If you are ready to go to the next task, see How to Organize A Package's Contents.
This example shows the contents of a valid pkginfo
file, with the five required parameters defined, as well as the BASEDIR
parameter. The BASEDIR
parameter is discussed in more detail in The path Field.
PKG=SUNWcadap NAME=Chip designers need CAD application software to design abc chips. Runs only on xyz hardware and is installed in the usr partition. ARCH=sparc VERSION=release 1.0 CATEGORY=system BASEDIR=/opt |
Organize your package objects in a hierarchical directory structure that mimics how you want them to be on the target system after installation. If you do this step before you create a prototype file, you can save yourself some time and effort when creating that file.
Determine how many packages you need to create and determine which package objects shall be located in each package.
For help in completing this step, see Things to Think About Before Building a Package.
For each package you need to build, make a directory.
You can create this directory anywhere on your system and name it anything you like. The examples in this chapter assume that a package directory has the same name as the package abbreviation.
$ cd /home/jane $ mkdir SUNWcadap |
For each package, organize package objects into a directory structure beneath their corresponding package directory, which mimics how they will be located on the target system.
For example, the CAD application package, SUNWcadap, requires the following directory structure.
Decide where you will keep your information files and, if appropriate, make a directory to keep them in one location.
This example assumes that the example pkginfo file from How to Create a pkginfo File was created in Jane's home directory.
$ cd /home/jane $ mkdir InfoFiles $ mv pkginfo InfoFiles |
If you are ready to go to the next task, see How to Create a prototype File Using the pkgproto Command.
The prototype file is an ASCII file used to specify information about the objects in a package. Each entry in the prototype file describes a single object, such as a data file, directory, source file, or executable object. Entries in a prototype file consist of several fields of information separated by white space. Note that the fields must appear in a specific order. Comment lines begin with a pound sign (#) and are ignored.
You can create a prototype file with a text editor or by using the pkgproto command. When you first create this file, it is probably easier to do so with the pkgproto command, because it creates the file based on the directory hierarchy you created previously. If you have not organized your files as described in Organizing a Package's Contents, you have the cumbersome task of creating the prototype file from scratch with your favorite text editor. However, even when you create the prototype file using the pkgproto command, you will most likely need to make modifications to the file with your favorite text editor, so it is important to understand the format and contents of this file.
The format for each line in the prototype file is:
partftypeclasspathmajorminorgroup |
part |
Is an optional, numeric field that enables you to group package objects into parts. The default value is part 1. |
ftype |
Is a one-character field that specifies the object's type. See The ftype Field. |
class |
Is the installation class to which the object belongs. See The class Field. |
path |
Is the absolute or relative path name indicating where the package object will reside on the target system. See The path Field. |
major |
Is the major device number for block or character special devices. |
minor |
Is the minor device number for block or character special devices. |
mode |
Is the octal mode of the object (for example, 0644). See The mode Field. |
owner |
Is the owner of the object (for example, bin or root). See The owner Field. |
group |
Is the group to which the object belongs (for example, bin or sys). See The group Field. |
Usually, only the ftype, class, path, mode, owner, and group fields are defined, and are described in the following sections. See prototype(4) for additional information on these fields.
The ftype, or file type, field is a one-character field that specifies a package object's type. Valid file types are described in the table below.
Table 2–3 Valid File Types in the prototype File
Use ftype ... |
To Define A ... |
---|---|
f |
Standard executable or data file |
e |
File to be edited upon installation or removal (may be shared by several packages) |
v |
Volatile file (whose contents are expected to change, like a log file) |
d |
Directory |
x |
Exclusive directory accessible only by this package (may contain unregistered logs or database information) |
l |
Linked file |
p |
Named pipe |
c |
Character special device |
b |
Block special device |
i |
Information file or installation script |
s |
Symbolic link |
The class field names the class to which an object belongs. Using classes is an optional package design feature, and is discussed in detail in Writing Class Action Scripts.
If you do not use classes, an object belongs to the none
class, and when you execute the pkgmk command to build your
package, it will insert the CLASSES=none
parameter in the pkginfo file for you. Files with file
type i should leave the class
field blank.
The path field is used to define where the package object will reside on the target system. You may indicate the location with either an absolute path name (for example, /usr/bin/mail) or a relative path name (for example, bin/mail). Using an absolute path name means that the object's location on the target system is defined by the package and cannot be changed. Package objects with relative path names indicate that the object is relocatable.
A relocatable object is one that does not need an absolute path location on the target system. Instead, its location is determined during the installation process.
All or some of a package's objects can be defined as relocatable. You should decide if package objects will have fixed locations (such as start-up scripts in /etc) or be relocatable before you write any installation scripts and before you create the prototype file.
There are two kinds of relocatable objects, collectively relocatable and individually relocatable.
Collectively relocatable objects are located relative to a common installation
base called the base directory. A base directory is defined
in the pkginfo file, using the BASEDIR
parameter. For example, a relocatable object in the prototype file named tests/generic requires
that the pkginfo file define the default BASEDIR
parameter. For example:
BASEDIR=/opt |
This means that when the object is installed, it will be located in /opt/tests/generic.
/opt is the only directory to which software that is not part of base Solaris may be delivered.
Use collectively relocatable objects whenever possible. In general,
the major part of a package can be relocatable with a few files (such as those
in /etc or /var) specified as absolute.
However, if a package contains many different relocations, consider dividing
your package into multiple packages, each with a different BASEDIR
value in its pkginfo file.
Individually relocatable objects are not restricted to the same directory location as collectively relocatable objects. To define an individually relocatable object, you need to specify an install variable in the path field in the prototype file, and then create a request script to prompt the installer for the relocatable base directory, or a checkinstall script to determine the path name from file system data. For more information on request scripts, see Writing a request Script and for information on checkinstall scripts, see How to Gather File System Data.
Individually relocatable objects are difficult to manage and should be avoided. This is because they could result in widely scattered package components that may be difficult to isolate when installing multiple versions or architectures of the package. Try to use collectively relocatable objects whenever possible.
A parametric path name is a path name that includes a variable specification. For example, /opt/$PKGINST/filename is a parametric path name because of the $PKGINST variable specification. A default value for the variable specification must be defined in the pkginfo file. The value may then be changed by a request or checkinstall script.
A variable specification in a path must begin or end the path name, or be bounded by slashes (/). For example, valid parametric path names look like:
$PARAM/tests tests/$PARAM/generic /tests/$PARAM |
The variable specification, once defined, may cause the path to be evaluated as absolute or relocatable. For example, given this entry in a prototype file:
f none $DIRLOC/tests/generic |
and this entry in the pkginfo file:
DIRLOC=/myopt |
the path name, $DIRLOC/tests/generic, will evaluate
to the absolute path name /myopt/tests/generic, regardless of whether the BASEDIR
parameter is set in the pkginfo file.
However, if the pkginfo file contains these entries
DIRLOC=firstcut BASEDIR=/opt |
then the path name, $DIRLOC/tests/generic, will evaluate to the relocatable path name /opt/firstcut/tests/generic.
For more information on parametric path names, see Using Parametric Base Directories.
The path name field in the prototype file defines where the object will be located on the target system. However, if you did not organize your package's objects on your system in a directory structure that mimics their location on the target system (see Organizing a Package's Contents, then you also need to specify their present location in the prototype file.
If your development area is not structured in the same way that you want your package structured, you can use the path1=path2 format in the path field, where path1 is the location it should have on the target system, and path2 is the location it has on your system.
You can also use the path1=path2 path name format with path1 as a relocatable object name and path2 a full path name to that object on your system.
path1 may not contain undefined build variables, but may contain undefined install variables. path2 may not contain any undefined variables, although both build and install variables may be used. For information on the difference between install and build variables, see Package Environment Variables.
Links must use the path1= path2 format since they are created by the pkgadd command. As a general rule, path2 of a link should never be absolute, but should instead be relative to the directory portion of path1.
An option to using the path1=path2 format is to use the !search command. For more information, see Providing a Search Path for the pkgmk Command.
The mode field may contain an octal number, a question mark (?), or a variable specification. An octal number specifies the mode of the object when it is installed on the target system. A ? means that the mode will be unchanged as the object is installed, implying that the object of the same name already exists on the target system.
A variable specification of the form $mode, where the first letter of the variable must be a lowercase letter, means that this field will be set as the package is built. Note that this variable must be defined at build time in either the prototype file or as an option to the pkgmk command. For information on the difference between install and build variables, see Package Environment Variables.
Files with file type i (information file), l (hard link), and s (symbolic link), should leave this field blank.
The owner field may contain a user name, a question mark (?), or a variable specification. A user name has a maximum of 14 characters and should be a name that already exists on the target system (such as, bin or root). A ? means that the owner will be unchanged as the object is installed, implying that the object of the same name already exists on the target system.
A variable specification can be of the form $Owner or $owner, where the first letter of the variable is either an uppercase letter or a lowercase letter. If the variable begins with a lowercase letter, it must be defined as the package is built, either in the prototype file or as an option to the pkgmk command. If the variable begins with an uppercase letter, the variable specification will be inserted into the pkginfo file as a default value, and may be redefined at install time via a request script. For information on the difference between install and build variables, see Package Environment Variables.
Files with file type i (information file) and l (hard link) should leave this field blank.
The group field may contain a group name, a question mark (?), or a variable specification. A group name has a maximum of 14 characters and should be a name that already exists on the target system (such as, bin or sys). A ? means that the group will be unchanged as the object is installed, implying that the object of the same name already exists on the target system.
A variable specification can be of the form $Group or $group, where the first letter of the variable is either an uppercase letter or a lowercase letter. If the variable begins with a lowercase letter, it must be defined as the package is built, either in the prototype file or as an option to the pkgmk command. If the variable begins with an uppercase letter, the variable specification will be inserted into the pkginfo file as a default value, and may be redefined at install time via a request script. For information on the difference between install and build variables, see Package Environment Variables.
Files with file type i (information file) and l (hard link) should leave this field blank.
If you want to create a prototype file from scratch, you can do so with your favorite text editor, adding one entry per package object. See The Format of the prototype File andprototype(4) for more information on the format of the file. However, after you have defined each package object, you might want to include some of the features described in Adding Functionality to a prototype File.
You can use the pkgproto command to build a basic prototype file, as long as you have organized your package directory structure as described in Organizing a Package's Contents. For example, using the sample directory structure and pkginfo file described in previous sections, the commands for creating the prototype file are:
$ cd /home/jane $ pkgproto ./SUNWcadap > InfoFiles/prototype |
The prototype file looks like:
d none SUNWcadap 0755 jane staff d none SUNWcadap/demo 0755 jane staff f none SUNWcadap/demo/file1 0555 jane staff d none SUNWcadap/srcfiles 0755 jane staff f none SUNWcadap/srcfiles/file5 0555 jane staff f none SUNWcadap/srcfiles/file6 0555 jane staff d none SUNWcadap/lib 0755 jane staff f none SUNWcadap/lib/file2 0644 jane staff d none SUNWcadap/man 0755 jane staff f none SUNWcadap/man/windex 0644 jane staff d none SUNWcadap/man/man1 0755 jane staff f none SUNWcadap/man/man1/file4.1 0444 jane staff f none SUNWcadap/man/man1/file3.1 0444 jane staff |
The actual owner and group of the person building the package is recorded by the pkgproto command. A good technique is to use the chown -R and the chgrp -R commands, setting the owner and group as intended before running the pkgproto command.
This prototype file is not yet complete. See Fine-Tuning a prototype File Created With the pkgproto Command for information on completing this file.
Although the pkgproto command is useful in creating an initial prototype file, it does not create entries for every package object that needs to be defined, or make complete entries. The pkgproto command does not:
Create complete entries for objects with file types v (volatile files), e (editable files), x (exclusive directories), or i (information files or installation scripts).
Support multiple classes with a single invocation.
Therefore, you probably need to modify the prototype file to include at least some of these object definitions, possibly redefine path names and other field settings, and include some of the features described in Adding Functionality to a prototype File.
At the very least, you need to modify the prototype file to add objects with file type i. If you stored your information files and installation scripts in the first level of your package directory (for example, /home/jane/SUNWcadap/pkginfo), then an entry in the prototype file would look like:
i pkginfo |
If you did not store your information files and installation scripts in the first level of your package directory, then you need to specify their source location. For example:
i pkginfo=/home/jane/InfoFiles/pkginfo |
Or, you can use the !search command to specify the location for the pkgmk command to look when building the package. See Providing a Search Path for the pkgmk Command for more information.
To add entries for objects with file types v, e, and x, follow the format described in The Format of the prototype File, or refer to prototype(4).
Remember to always assign a class to files with a file type of e (editable) and have an associated class action script for that class. Otherwise, the files will be removed during package removal, even if the path name is shared with other packages.
If you use the pkgproto command to create your basic prototype file, you can assign all of the package objects to the none class or one, specific class. As shown in Creating a prototype File With the pkgproto Command, the basic pkgproto command assigns all objects to the none class. To assign all objects to a specific class, you can use the -c option. For example:
$ pkgproto -c classname /home/jane/SUNWcadap > /home/jane/InfoFiles/prototype |
If you use multiple classes, you may need to manually edit the prototype file and modify the class
field for each object. If you use classes, you also need to define the CLASSES
parameter in the pkginfo file and write class action scripts. As mentioned previously,
using classes is an optional feature and is discussed in detail in Writing Class Action Scripts.
Given the prototype file created by the pkgproto command in Creating a prototype File With the pkgproto Command, there are several modifications that need to be made.
There needs to be an entry for the pkginfo file.
The path fields need to be modified to be the path1=path2 format, since the package source is in /home/jane. (Since the package source is a hierarchical directory, and the !search command does not search recursively, it may be easier to use the path1=path2 format.)
The owner and group fields should contain the names of existing users and groups on the target system. That is, the owner jane will result in an error since this owner is not part of the SunOSTM operating system.
The modified prototype file looks like:
i pkginfo=/home/jane/InfoFiles/pkginfo d none SUNWcadap=/home/jane/SUNWcadap 0755 root sys d none SUNWcadap/demo=/home/jane/SUNWcadap/demo 0755 root bin f none SUNWcadap/demo/file1=/home/jane/SUNWcadap/demo/file1 0555 root bin d none SUNWcadap/srcfiles=/home/jane/SUNWcadap/srcfiles 0755 root bin f none SUNWcadap/srcfiles/file5=/home/jane/SUNWcadap/srcfiles/file5 0555 root bin f none SUNWcadap/srcfiles/file6=/home/jane/SUNWcadap/srcfiles/file6 0555 root bin d none SUNWcadap/lib=/home/jane/SUNWcadap/lib 0755 root bin f none SUNWcadap/lib/file2=/home/jane/SUNWcadap/lib/file2 0644 root bin d none SUNWcadap/man=/home/jane/SUNWcadap/man 0755 bin bin f none SUNWcadap/man/windex=/home/jane/SUNWcadap/man/windex 0644 root other d none SUNWcadap/man/man1=/home/jane/SUNWcadap/man/man1 0755 bin bin f none SUNWcadap/man/man1/file4.1=/home/jane/SUNWcadap/man/man1/file4.1 0444 bin bin f none SUNWcadap/man/man1/file3.1=/home/jane/SUNWcadap/man/man1/file3.1 0444 bin bin |
Besides defining every package object in the prototype file, you can also:
Define additional objects to be created at install time.
Create links at install time.
Distribute packages over multiple volumes.
Nest prototype files.
Set a default value for the mode, owner, and group fields.
Provide a search path for the pkgmk command.
Set environment variables.
See the following sections for information on making these changes.
You can use the prototype file to define objects that are not actually delivered on the installation medium. During installation, using the pkgadd command, these objects are created with the required file types, if they do not already exist at the time of installation.
To specify that an object be created on the target system, add an entry for it in the prototype file with the appropriate file type.
For example, if you want a directory created on the target system, but do not want to deliver it on the installation medium, make the following entry for the directory in the prototype file:
d none /directory 0644 root other |
If you want to create an empty file on the target system, an entry for the file in the prototype file might look like:
f none filename=/dev/null 0644 bin bin |
The only objects that must be delivered on the installation medium are regular files and edit scripts (file types e, v, f) and the directories required to contain them. Any additional objects are created without reference to the delivered objects, directories, named pipes, devices, hard links, and symbolic links.
To create links during package installation, define the following in the prototype file entry for the linked object:
Its file type as l (a link) or s (a symbolic link).
Its path name with the format path1=path2 where path1 is the destination and path2 is the source file. As a general rule, path2 of a link should never be absolute, but should instead be relative to the directory portion of path1. For example, a prototype file entry defining a symbolic link could be:
s none etc/mount=../usr/etc/mount |
Relative links would be specified in this manner whether the package is installed as absolute or relocatable.
When you build your package with the pkgmk command, it performs the calculations and actions necessary to organize a multiple volume package. A multiple volume package is called a segmented package.
However, you can use the optional part field in the prototype file to define in which part you want an object to be located. A number in this field overrides the pkgmk command and forces the placement of the component into the part given in the field. Note that there is a one-to-one correspondence between parts and volumes for removable media formatted as file systems. If the volumes are preassigned by the developer, the pkgmk command will issue an error if there is insufficient space on any volume.
You can create multiple prototype files and then include them, using the !include command in the prototype file. You might want to do this for easier maintenance.
In the following example there are three prototype files, the main one (prototype) being edited, and the two (proto2 and proto3) that are being included.
!include /source-dir/proto2 !include /source-dir/proto3 |
To set default values for the mode, owner, and group fields for specific package objects, you can insert the !default command into the prototype file. For example,
!default 0644 root other |
This command's range starts from where it is inserted and extends to the end of the file, but does not span to included files.
However, for directories (file type d) and editable files (file type e) that you know exist on target systems (like /usr or /etc/vfstab), make sure that the mode, owner, and group fields in the prototype file are set to question marks (?). That way you will not destroy existing settings that a site administrator may have modified.
If the source location for package objects is different than their destination location, and you do not want to use the path1=path2 format as described in A Brief Word on an Object's Source and Destination Locations, then you can use the !search command in the prototype file. For example, if you created a directory, pkgfiles, in your home directory, and it contains all of your information files and installation scripts, you can specify that that directory be searched when the package is built with the pkgmk command.
The command in the prototype file would look like:
!search /home-dir/pkgfiles |
Search requests do not span to included files. In addition, a search is limited to the specific directories listed, and will not search recursively.
You can also add commands to the prototype file of the form !PARAM=value. Commands of this form define variables in the current environment. If you have multiple prototype files, the scope of this command is local to the prototype file where it is defined.
The variable PARAM can begin with either a lowercase or uppercase letter, but its value must be known at build time, or the pkgmk command will abort with an error. For more information on the difference between build and install variables, see Package Environment Variables.
It is easier to create information files and installation scripts before creating a prototype file. However, this is not required, and you can always edit the prototype file after changing your package contents. For more information on information files and installation scripts, see Chapter 3, Enhancing the Functionality of a Package.
Determine which package objects will be absolute and which will be relocatable, if not done already.
For information that will help you complete this task, see The path Field.
Organize your package's objects to mimic their location on the target system.
If you already organized your packages as described in Organizing a Package's Contents, note that you may need to make some changes based on your decisions in Step 1. If you have not organized your package yet, you should do so now (otherwise you cannot use the pkgproto command to create a basic prototype file).
If your package has collectively relocatable objects, edit the pkginfo file to set the BASEDIR
parameter to the appropriate value.
For example:
BASEDIR=/opt |
For information on collectively relocatable objects, see Collectively Relocatable Objects.
If your package has individually relocatable objects, create a request script to prompt the installer for the appropriate path name or a checkinstall script to determine the appropriate path from file system data.
For Information On ... |
See ... |
---|---|
Creating a request script | |
Creating a checkinstall script | |
Individually relocatable objects |
Change the owner and group on all of your package components to be the intended owner and group on the target systems.
Use the chown -R and the chgrp -R commands on your package directory and information files directory.
Execute the pkgproto command to create a basic prototype file.
The pkgproto command scans your directories to create a basic file. For example:
$ cd package-directory $ pkgproto ./package-directory > prototype |
Like the pkginfo file, the prototype file can be located anywhere on your system. However, it might be a good idea to keep your information files and installation scripts in one place, for easy access and maintenance. For additional information on the pkgproto command, see the pkgproto(1) man page.
Edit the prototype file using your favorite text editor, and add entries for files of type v, e, x, and i.
For information on the specific changes you may need to make, see Fine-Tuning a prototype File Created With the pkgproto Command.
Optional. If you are using multiple classes, edit the prototype and pkginfo files using your favorite text editor to make the necessary changes, and create corresponding class action scripts.
For information on the specific changes you may need to make, see Fine-Tuning a prototype File Created With the pkgproto Command and Writing Class Action Scripts.
Edit the prototype file using your favorite text editor to redefine path names and change other field settings.
For more information, see Fine-Tuning a prototype File Created With the pkgproto Command.
Optional. Edit the prototype file using your favorite text editor to add functionality to your prototype file.
For more information, see Adding Functionality to a prototype File.
Save your changes and quit the editor.
If you are ready to go to the next task, see How to Build a Package.
Use the pkgmk command to build your package. This command takes all of the objects defined in the prototype file, puts them into directory format, creates the pkgmap file (replacing the prototype file), and produces an installable package to be used as input to the pkgadd command.
The simplest form of this command is the pkgmk command itself, without any options. Before using the pkgmk command without options, make sure your current working directory contains the package's prototype file. The output of the command, files and directories, are written to the /var/spool/pkg directory.
When you build a package with the pkgmk command, it creates a pkgmap file that replaces the prototype file. The pkgmap file from the previous example looks like:
$ more pkgmap : 1 3170 1 d none SUNWcadap 0755 root sys 1 d none SUNWcadap/demo 0755 root bin 1 f none SUNWcadap/demo/file1 0555 root bin 14868 45617 837527496 1 d none SUNWcadap/lib 0755 root bin 1 f none SUNWcadap/lib/file2 0644 root bin 1551792 62372 837527499 1 d none SUNWcadap/man 0755 bin bin 1 d none SUNWcadap/man/man1 0755 bin bin 1 f none SUNWcadap/man/man1/file3.1 0444 bin bin 3700 42989 837527500 1 f none SUNWcadap/man/man1/file4.1 0444 bin bin 1338 44010 837527499 1 f none SUNWcadap/man/windex 0644 root other 157 13275 837527499 1 d none SUNWcadap/srcfiles 0755 root bin 1 f none SUNWcadap/srcfiles/file5 0555 root bin 12208 20280 837527497 1 f none SUNWcadap/srcfiles/file6 0555 root bin 12256 63236 837527497 1 i pkginfo 140 10941 837531104 $ |
The format of this file is very similar to that of the prototype file. However, the pkgmap file includes the following information.
The first line indicates the number of volumes that the package spans, and the approximate size the package will be when installed.
For example, : 1 3170 indicates that the package spans one volume and will use approximately 3170 512-byte blocks when it is installed.
There are three additional fields defining the size, checksum, and modification time for each package object.
The package objects are listed in alphabetical order by class and by path name to enhance the time it takes to install the package.
Create a pkginfo file, if not done already.
For step-by-step instructions, see How to Create a pkginfo File.
Create a prototype file, if not done already.
For step-by-step instructions, see How to Create a prototype File Using the pkgproto Command.
Make your current working directory the same directory that contains your package's prototype file.
Build the package.
$ pkgmk [-o] [-a arch] [-b base-src-dir] [-d device] [-f filename] [-l limit] [-p pstamp] [-r rootpath] [-v version] [PARAM=value] [pkginst] |
-o |
Overwrites the existing version of the package. |
-a arch |
Overrides the architecture information in the pkginfo file. |
-b base-src-dir |
Requests that base-src-dir be added to the beginning of relocatable path names when the pkgmk command is searching for objects on the development system. |
-d device |
Specifies that the package should be copied onto device, which may be a an absolute directory path name, diskette, or removable disk. |
-f filename |
Names a file, filename, that is used as your prototype file. The default names are prototype or Prototype. |
-l limit |
Specifies the maximum size, in 512-byte blocks, of the output device. |
-p pstamp |
Overrides the production stamp definition in the pkginfo file. |
-r rootpath |
Requests that the root directory rootpath be used to locate objects on the development system. |
-v version |
Overrides the version information in the pkginfo file. |
PARAM=value |
Sets global environment variables. Variables beginning with lowercase letters are resolved at build time. Those beginning with uppercase letters are placed into the pkginfo file for use at install time. |
pkginst |
Specifies a package by its package abbreviation or a specific instance (for example, SUNWcadap.4). |
For more information, see pkgmk(1).
Verify the contents of the package.
$ pkgchk -d pkg-dir pkg-abbrev Checking uninstalled directory format package pkg-abbrev from pkg-dir ## Checking control scripts. ## Checking package objects. ## Checking is complete. $ |
The pkgchk command prints what aspects of the package are being checked and displays warnings or errors, as appropriate. For more information on the pkgchk command, see Verifying the Integrity of a Package.
Errors should be considered very seriously; it may mean that a script needs fixing. However, a warning may just be a comment on the style of a script. Check it and move on if you disagree with the output from the pkgchk command.
If you want to add any optional information files and installation scripts to your package, see Chapter 3, Enhancing the Functionality of a Package. Otherwise, after you build the package, you should verify its integrity. Chapter 4, Verifying and Transferring a Package explains how to do this, and provides step-by-step instructions on how to transfer your verified package to a distribution medium.
This example uses the prototype file created in Fine-Tuning a prototype File Created With the pkgproto Command.
$ cd /home/jane/InfoFiles $ pkgmk ## Building pkgmap from package prototype file. ## Processing pkginfo file. WARNING: parameter set to "system990708093144" WARNING: parameter set to "none" ## Attempting to volumize 13 entries in pkgmap. part 1 -- 3170 blocks, 17 entries ## Packaging one part. /var/spool/pkg/SUNWcadap/pkgmap /var/spool/pkg/SUNWcadap/pkginfo /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/demo/file1 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/lib/file2 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file3.1 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file4.1 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/windex /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file5 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file6 ## Validating control scripts. ## Packaging complete. $ |
If your package contains relocatable files, you can use the -b base-src-dir option to the pkgmk command to specify a path name to be added to the beginning of the relocatable path names while the package is being created. This is useful if you haven't used the path1=path2 format for relocatable files or specified a search path with the !search command in the prototype file.
For example, to build a package using the sample prototype file created by the pkgproto command (see Creating a prototype File With the pkgproto Command), without modifying the path fields, and just adding an entry for the pkginfo file, the pkgmk command is:
$ cd /home/jane/InfoFiles $ pkgmk -o -b /home/jane ## Building pkgmap from package prototype file. ## Processing pkginfo file. WARNING: parameter set to "system960716102636" WARNING: parameter set to "none" ## Attempting to volumize 13 entries in pkgmap. part 1 -- 3170 blocks, 17 entries ## Packaging one part. /var/spool/pkg/SUNWcadap/pkgmap /var/spool/pkg/SUNWcadap/pkginfo /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/demo/file1 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/lib/file2 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file3.1 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/man1/file4.1 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/man/windex /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file5 /var/spool/pkg/SUNWcadap/reloc/SUNWcadap/srcfiles/file6 ## Validating control scripts. ## Packaging complete. |
In this example, the package is built in the default directory, /var/spool/pkg, by specifying the -o option (to overwrite the package we created in Example—Building a Package).
If you put package information files (such as pkginfo and prototype) and the package objects in two different directories, you can create your package by using the -b base-src-dir and -r rootpath options to the pkgmk command. If you have your package objects in a directory called /product/pkgbin and the other package information files in a directory called /product/pkgsrc, you could use the following command to place the package in the /var/spool/pkg directory:
$ pkgmk -b /product/pkgbin -r /product/pkgsrc -f /product/pkgsrc/prototype |
Optionally, you could use this command to do the same:
$ cd /product/pkgsrc $ pkgmk -o -b /product/pkgbin |
In this example, the pkgmk command uses the current working directory to find the remaining parts of the package (like the prototype and pkginfo information files).