Packaging your software applications

9. Creating the prototype file

The prototype file is a list of package contents and is a required package component.

You can create the prototype file by using any editor and following the format described in the section ``prototype'' and in the prototype(4) manual page. You can also use the pkgproto(1) command to create one automatically.

Creating the file manually

While creating the prototype file, you must at the very least supply the following three pieces of information about an object:

The object's type
All of the possible object types are defined in the prototype(4) manual page. f (for a data file), l (for a linked file), and d (for a directory) are examples of object types.
The object's class
All objects must be assigned a class. If no special handling is required, you can assign the class none.
The object`s pathname
The pathname can define a fixed pathname such as /mypkg/src/filename, a collectively relocatable pathname such as src/filename, and an individually relocatable pathname such as $BIN/filename or /opt/$PKGINST/filename.

Creating links

To define links, you must do the following in the prototype entry for the linked object:

Define its ftype as l (a link) or s (a symbolic link).
Define its pathname with the format path1=path2 where path1 is the destination and path2 is the source file.

Mapping development pathnames to installation pathnames

If your development area is in a different structure than you want the package to be in on the installation machine, use the prototype entry to map one pathname to the other. You use the path1=path2 format for the pathname as is used to define links. However, because the ftype is not defined as l or s, path1 is interpreted as the pathname you want the object to have on the installation machine, and path2 is interpreted as the pathname the object has on your development machine.

For example, your project might require a development structure that includes a project root directory and numerous src directories. However, on the installation machine you might want all files to go under a package root directory and for all src files to be in one directory. So, a file on your machine might be named /projdir/srcA/filename. If you want that file to be named /pkgroot/src/filename on the installation machine, your prototype entry for this file might look like this:

   f class1 /pkgroot/src/filename=/projdir/srcA/filename

Defining objects for pkgadd to create

You can use the prototype(4) file to define objects that are not actually delivered on the installation medium. pkgadd(1M) creates objects with the following ftypes if they do not already exist at the time of installation:

d (directories)
x (exclusive directories)
l (linked files)
s (symbolically linked files)
p (named pipes)
c (character special device)
b (block special device)

To request that one of these objects be created on the installation machine, add an entry for it in the prototype file using the appropriate ftype.

For example, if you want a directory created on the installation machine, but do not want to deliver it on the installation medium, an entry for the directory in the prototype file is sufficient. An entry such as the one shown below causes the directory to be created on the installation machine, even if it does not exist on the installation medium.

   d none /directoryA 644 root other

Using the command lines

The four types of commands that you can put into your prototype(4) file allow you to:

Nest prototype files (the include command).
Define directories for pkgmk(1) to look in when attempting to locate objects as it creates the package (the search command).
NOTE: This will not work if pkgmk is instructed to compress the package.
Set a default value for mode owner group (the default command). If all or most of your objects have the same values, using the default command keeps you from having to define these values for every entry in the prototype file.
Assign a temporary value for variable pathnames to tell pkgmk where to locate these relocatable objects on your machine (with param="value").

Creating the file using pkgproto

The pkgproto(1) command scans your directories and generates a prototype(4) file. pkgproto cannot assign ftypes of v (volatile files), e (editable files), or x (exclusive directories). You can edit the prototype file and add these ftypes, as well as perform any other fine-tuning you require (for example, adding command lines or classes).

pkgproto(1) writes its output to the standard output. To create a file, redirect the output to a file. The examples shown in this section do not perform redirection to show you what the contents of the file would like.

Creating a basic prototype

The standard format of pkgproto(1) is:

   pkgproto path [ . . . ]

where path is the name of one or more paths to be included in the prototype(4) file. If path is a directory, entries are created for the contents of that directory as well (everything below that directory).

With this form of the command, all objects are placed into the none class and are assigned the same mode owner group as exists on your machine. The following example shows pkgproto being executed to create a file for all objects in the directory /home/pkg:

   $ pkgproto /home/pkg
   d none /home/pkg 755 bin bin
   f none /home/pkg/file1 755 bin bin
   f none /home/pkg/file2 755 bin bin
   f none /home/pkg/file3 755 bin bin
   f none /home/pkg/file4 755 bin bin
   f none /home/pkg/file5 755 bin bin
   $

To create a prototype file that contains the output of the example above, you would execute pkgproto /home/pkg > prototype.

NOTE: If no pathnames are supplied when executing pkgproto standard input (stdin) is assumed to be a list of paths. Refer to the pkgproto(1) manual page for details on this usage.

Assigning objects to a class

You can use the -c class option of pkgproto(1) to assign objects to a class other than none. When using this option, you can only name one class. To define multiple classes in a prototype(4) file created by pkgproto, you must edit the file after its creation.

The following example is the same as above except the objects have been assigned to class1:

   $ pkgproto -c class1 /home/pkg
   d class1 /home/pkg 755 bin bin
   f class1 /home/pkg/file1 755 bin bin
   f class1 /home/pkg/file2 755 bin bin
   f class1 /home/pkg/file3 755 bin bin
   f class1 /home/pkg/file4 755 bin bin
   f class1 /home/pkg/file5 755 bin bin
   $

Renaming pathnames with pkgproto

Use a path1=path2 format on the pkgproto(1) command line to give an object a different pathname in the prototype(4) file than it has on your machine. You can, for example, use this format to define relocatable objects in a prototype file created by pkgproto.

The following example is like the others shown in this section, except that the objects are now defined as bin (instead of /usr/bin) and are thus relocatable:

   $ pkgproto -c class1 /home/pkg=bin
   d class1 bin 755 bin bin
   f class1 bin/file1 755 bin bin
   f class1 bin/file2 755 bin bin
   f class1 bin/file3 755 bin bin
   f class1 bin/file4 755 bin bin
   f class1 bin/file5 755 bin bin
   $

pkgproto and links

pkgproto(1) detects linked files and creates entries for them in the prototype(4) file. If multiple files are linked together, it considers the first path encountered the source of the link.

If you have symbolic links established on your machine, but want to generate an entry for that file with an ftype of f (file), use the -i option of pkgproto(1). This option creates a file entry for all symbolic links.