Add Any Facets or Actuators That Are Needed

Facets and actuators are discussed in more detail in Chapter 5, Allowing Variations and Chapter 7, Automating System Change as Part of Package Installation. A facet denotes an action that is not required but can be optionally installed. An actuator specifies system changes that must occur when the associated action is installed, updated, or removed

This example package delivers a man page in /opt/mysoftware/man/man1. This section shows how to add a facet to indicate that man pages are optional. The user could choose to install all of the package except the man page. (If the user sets the facet to false, no man pages are installed from any package if their file actions are tagged with that facet.)

To include the man page in the index, the svc:/application/man-index:default SMF service must be restarted when the package is installed. This section shows how to add the restart_fmri actuator to perform that task. The man-index service looks in /usr/share/man/index.d for symbolic links to directories that contain man pages, adding the target of each link to the list of directories it scans. To include the man page in the index, this example package includes a link from /usr/share/man/index.d/mysoftware to /opt/mysoftware/man. Including this link and this actuator is a good example of the self-assembly discussed in Software Self-Assembly and used throughout the packaging of the Oracle Solaris OS.

A set of pkgmogrify transforms that you can use are available in /usr/share/pkg/transforms. These transforms are used to package the Oracle Solaris OS, and are discussed in more detail in Chapter 6, Modifying Package Manifests Programmatically.

The file /usr/share/pkg/transforms/documentation contains transforms similar to the transforms needed in this example to set the man page facet and restart the man-index service. Since this example delivers the man page to /opt, the documentation transforms must be modified as shown below. These modified transforms include the regular expression opt/.+/man(/.+)? which matches all paths beneath opt that contain a man subdirectory. Save the following modified transforms to /tmp/doc-transform:

<transform dir file link hardlink path=opt/.+/man(/.+)? -> \
    default facet.doc.man true>
<transform file path=opt/.+/man(/.+)? -> \
    add restart_fmri svc:/application/man-index:default>

Use the following command to apply these transforms to the manifest:

$ pkgmogrify mypkg.p5m.3.res /tmp/doc-transform | pkgfmt > mypkg.p5m.4.res

The input mypkg.p5m.3.res manifest contains the following three man-page-related actions:

dir  path=opt/mysoftware/man owner=root group=bin mode=0755
dir  path=opt/mysoftware/man/man1 owner=root group=bin mode=0755
file opt/mysoftware/man/man1/mycmd.1 path=opt/mysoftware/man/man1/mycmd.1 \
    owner=root group=bin mode=0644

After the transforms are applied, the output mypkg.p5m.4.res manifest contains the following modified actions:

dir  path=opt/mysoftware/man owner=root group=bin mode=0755 facet.doc.man=true
dir  path=opt/mysoftware/man/man1 owner=root group=bin mode=0755 \
    facet.doc.man=true
file opt/mysoftware/man/man1/mycmd.1 path=opt/mysoftware/man/man1/mycmd.1 \
    owner=root group=bin mode=0644 \
    restart_fmri=svc:/application/man-index:default facet.doc.man=true