Creating a prototype File
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.
Format of the prototype File
Here is the format for each line in the prototype file:
partftypeclasspathmajorminormodeownergroup
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.
These fields are described in the following sections. See the prototype(4) man page for
additional information on these fields.
The ftype Field
The ftype, or file type, field is a one-character field that specifies a
package object's file type. Valid file types are described in the following table
Table 2-3 Valid File Types in the prototype File
File
type field value |
File Type Description |
|---|
f |
Standard executable file 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, such as 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
The class field names the class to which an object belongs. Using
classes is an optional package design feature. This feature is discussed in detail
in Writing Class Action Scripts.
If you do not use classes, an object belongs to the none
class. When you execute the pkgmk command to build your package, the command
inserts the CLASSES=none parameter in the pkginfo file. Files with file type
i must have a blank class field.
The path Field
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 does not need an absolute path location on the target system.
Instead, the object's location is determined during the installation process.
All or some of a package's objects can be defined as relocatable.
Before writing any installation scripts or creating the prototype file, decide if package objects
will have fixed locations (such as start-up scripts in /etc) or be
relocatable .
There are two kinds of relocatable objects, collectively relocatable and individually relocatable.
Collectively Relocatable Objects
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 example means that when the object is installed, it will be
located in the /opt/tests/generic directory.
Note - The /opt directory is the only directory to which software that is not
part of the base Solaris software 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 files in
/etc or /var) specified as absolute. However, if a package contains many different
relocations, consider dividing the package into multiple packages with distinct BASEDIR values in
their pkginfo files.
Individually Relocatable Objects
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. After specifying the
install variable, 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.
Caution - Individually relocatable objects are difficult to manage. Use of individually relocatable objects might
result in widely scattered package components that are difficult to isolate when installing
multiple versions or architectures of the package. Use collectively relocatable objects whenever possible.
Parametric Path Names
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 script or
a checkinstall script.
A variable specification in a path must begin or end the path
name, or be bounded by slashes (/). Valid parametric path names take the
following form:
$PARAM/tests
tests/$PARAM/generic
/tests/$PARAM
The variable specification, once defined, may cause the path to be evaluated as
absolute or relocatable. In the following example, the prototype file contains this entry:
f none $DIRLOC/tests/generic
The pkginfo file contains this entry:
DIRLOC=/myopt
The path name $DIRLOC/tests/generic evaluates to the absolute path name /myopt/tests/generic, regardless of
whether the BASEDIR parameter is set in the pkginfo file.
In this example, the prototype file is identical to the one in the
previous example and the pkginfo file contains the following entries:
DIRLOC=firstcut
BASEDIR=/opt
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.
A Brief Word on an Object's Source and Destination Locations
The path field in the prototype file defines where the object will
be located on the target system. Specify the present location of the package's
objects in the prototype file if their directory structure does not mimic the
intended structure on the target system. See Organizing a Package's Contents for more information on structuring objects
in a package.
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. In this format, path1 is the location the object should have on
the target system, and path2 is the location the object has on your
system.
You can also use the path1=path2 path name format with path1 as a
relocatable object name and path2 as a full path name to that
object on your system.
Note - path1 may not contain undefined build variables, but may contain undefined install variables.
path2 may not contain any undefined variables, although both build variables and install
variables may be used. For information on the difference between install variables and
build variables, see Package Environment Variables.
Links must use the path1= path2 format because 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
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 variables 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
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 by a request
script. For information on the difference between install variables and build variables, see
Package Environment Variables.
Files with file type i (information file) and lb (hard link) should
leave this field blank.
The group Field
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 by a request
script. For information on the difference between install variables and build variables, see
Package Environment Variables.
Files with file type i (information file) and l (hard link) should
leave this field blank.
Creating a prototype File From Scratch
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
Format of the prototype File and the prototype(4) man page for more information on the format of
this 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.
Example—Creating a prototype File With the pkgproto Command
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 as
follows:
$ cd /home/jane
$ pkgproto ./SUNWcadap > InfoFiles/prototype
The prototype file looks like the following:
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
Note - 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 example prototype file is not complete. See the following section for information
on completing this file.
Fine-Tuning a prototype File Created With the pkgproto Command
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.
This command does not make complete entries. The pkgproto command does not do
any of the following:
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
Creating Object Entries With File Types v, e, x, and i
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 the following:
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 Format of the prototype File, or refer to the prototype(4) man page.
Note - 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.
Using Multiple Class Definitions
If you use the pkgproto command to create your basic prototype file,
you can assign all the package objects to the none class or
to one, specific class. As shown in Example--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 might 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. Using classes is an optional feature and is
discussed in detail in Writing Class Action Scripts.
Example—Fine-Tuning a prototype File Created Using the pkgproto Command
Given the prototype file created by the pkgproto command in Example--Creating a prototype File With the pkgproto Command, several
modifications need to be made.
There needs to be an entry for the pkginfo file.
The path fields need to be changed to the path1=path2 format because the package source is in /home/jane. Since the package source is a hierarchical directory, and the !search command does not search recursively, it might 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 because this owner is not part of the SunOSTM operating system.
The modified prototype file looks like the following:
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
Adding Functionality to a prototype File
Besides defining every package object in the prototype file, you can also do
the following:
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.
Defining Additional Objects to Be Created at Install Time
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, add 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 the
following:
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.
Creating Links at Install Time
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).
The linked object's 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 that defines a symbolic link could be as follows:
s none etc/mount=../usr/etc/mount
Relative links would be specified in this manner whether the package is
installed as absolute or relocatable.
Distributing Packages Over Multiple Volumes
When you build your package with the pkgmk command, the command 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 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 a one-to-one correspondence
exists between parts and volumes for removable media formatted as file systems. If
the volumes are preassigned by the developer, the pkgmk command issues an error
if there is insufficient space on any volume.
Nesting prototype Files
You can create multiple prototype files and then include them by using the
!include command in the prototype file. You might want to nest files
for easier maintenance.
In the following example there are three prototype files. The main file (prototype)
is being edited. The other two files (proto2 and proto3) are being included.
!include /source-dir/proto2
!include /source-dir/proto3
Setting Default Values for the mode, owner, and group Fields
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
Note - The !default command's range starts from where it is inserted and extends to
the end of the file. The command's range 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.
Providing a Search Path for the pkgmk Command
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 this directory be searched when the package is built with the
pkgmk command.
The command in the prototype file would look like the following:
!search /home-dir/pkgfiles
Note - Search requests do not span to included files. In addition, a search
is limited to the specific directories listed and does not search recursively.
Setting Environment Variables
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 letter or an uppercase
letter. If the value of the PARAM variable is not known at
build time, the pkgmk command aborts with an error. For more information on
the difference between build variables and install variables, see Package Environment Variables.
How to Create a prototype File by Using the pkgproto Command
Note - It is easier to create information files and installation scripts before you create
a prototype file. However, this order is not required. 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 (Tasks).
- Determine which package objects will be absolute and which package objects will be
relocatable, if not done already.
For information that will help you complete this step, 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
might 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.
If you do not organize your package, 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. Alternatively, create a checkinstall script to determine
the appropriate path from file system data.
The following list gives page numbers for your reference regarding common tasks:
- 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
The prototype file can be located anywhere on your system. Keeping your information
files and installation scripts in one place simplifies access and maintenance. For additional
information on the pkgproto command, see the pkgproto(1) man page.
- Edit the prototype file by using your favorite text editor, and add entries
for files of type v, e, x, and i.
For information on the specific changes you might 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.
Use your favorite text editor to make the necessary changes, and create corresponding class
action scripts.
For information on the specific changes you might need to make, see Fine-Tuning a prototype File Created With the pkgproto Command
and Writing Class Action Scripts.
- Edit the prototype file by 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 by 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.
See Also
If you are ready for the next task, see How to Build a Package.
