Packaging your software applications

The class action script

The class action script defines a set of actions to be executed during installation or removal of a package. The actions are performed on a group of pathnames based on their class definition. (See the case studies for examples of class action scripts.)

Class action script naming conventions

The name of a class action script is based on which class it should operate and whether those actions should occur during package installation or removal. The two name formats are:

i.class: operates on pathnames in the indicated class during package installation
r.class: operates on pathnames in the indicated class during package removal

For example, the name of the installation script for a class named class1 would be i.class1 and the removal script would be named r.class1.

Class action script usage rules

Class action scripts are executed as uid=root and gid=other.
If a package spans more than one volume, the class action script will be executed once for each volume that contains at least one file belonging to the class. Consequently, each script must be ``multiply executable.'' This means that executing a script any number of times with the same input must produce the same results as executing the script only once.
NOTE: The installation service relies upon this condition being met.
The script is executed only if there are files in the given class existing on the current volume.
pkgadd(1M) (and pkgrm(1M)) creates a list of all objects listed in the pkgmap(4) file that belong to the class. As a result, a class action script can only act upon pathnames defined in the pkgmap(4) and belonging to a particular class.
A class action script should never add, remove, or modify a pathname or system attribute that does not appear in the list generated by pkgadd(1M) unless by use of the installf(1M) or removef(1M) commands.
(See the manual pages for details on these two commands and the case studies for examples of them in use.)
When the class action script executes for the last time (the input pathname is the last path on the last volume containing a file of this class), it is executed with the keyword argument ENDOFCLASS. This flag allows you to include post-processing actions into your script.

Installation of classes

The following steps outline the system actions that occur when a class is installed. The actions are repeated once for each volume of a package as that volume is being installed.

pkgadd(1M) creates a list of pathnames upon which the action script will operate. Each line of this list consists of source and destination pathnames, separated by white space. The source pathname indicates where the object to be installed resides on the installation volume and the destination pathname indicates the location on the installation machine where the object should be installed. The contents of the list is restricted by the following criteria:
- The list contains only pathnames belonging to the associated class.
- Directories, named pipes, character/block devices, and symbolic links are included in the list with the source pathname set to /dev/null. They are automatically created by pkgadd(1M) (if not already in existence) and given proper attributes (mode, owner, and group) as defined in the pkgmap(4) file.
- Linked files are not included in the list, that is, files where ftype is l. (ftype defines the file type defined in the prototype file.) Links in the given class are created in Step 4.
- If a pathname already exists on the target machine and its contents are no different from the one being installed, the pathname will not be included in the list.
  To determine this, pkgadd(1M) compares the cksum, modtime, and size fields in the installation software database with the values for those fields in your pkgmap(4) file. If they are the same, it then checks the actual file on the installation machine to be certain it really has those values. If the field values are the same and are correct, the pathname for this object will not be included in the list.
If there is no class action script, the files associated with the pathnames are copied to the target machine.
If no class action script is provided for installation of a particular class, the files in the generated pathname list will simply be copied from the volume to the appropriate target location.
If there is a class action script, the script is executed.
The class action script is invoked with standard input containing the list generated in Step 1. If this is the last volume of the package and there are no more objects in this class, the script is executed with the single argument of ENDOFCLASS.
pkgadd(1M) performs a content and attribute audit and creates links.
After successfully executing Step 2 or 3, an audit of both content and attribute information is performed on the list of pathnames. pkgadd(1M) creates the links associated with the class automatically. Detected attribute inconsistencies are corrected for all pathnames in the generated list.

Removal of classes

Objects are removed class-by-class. Classes that exist for a package, but are not listed in the CLASSES parameter are removed last (for example, an object installed with the installf(1M) command). Classes that are listed in the CLASSES parameter are removed in reverse order. The following steps outline the system actions that occur when a class is removed:

pkgrm(1M) creates a list of installed pathnames that belong to the indicated class. Pathnames referenced by another package are excluded from the list unless their ftype is e (the file can be edited upon installation or removal).
If a pathname is referenced by another package, it will not be removed from the system. However, if it is of ftype e, it can be modified to remove information placed in it by the package being removed. The modification should be performed by the removal class action script.
If there is no class action script, the pathnames are removed.
If your package has no removal class action script for the class, all of the pathnames in the list generated by pkgrm(1M) will be removed.
NOTE: Always assign a class for files with an ftype of e (editable) and have an associated class action script for that class. Otherwise, they will be removed at this point, even if the pathname is shared with other packages.
If there is a class action script, the script is executed.
pkgrm(1M) invokes the class action script with standard input containing the list generated in Step 1.
pkgrm(1M) performs an audit.
Upon successful execution of the class action script, knowledge of the pathnames is removed from the system unless a pathname is referenced by another package.