Constraints and Freezing

Through the careful use of the various types of depend actions described above, packages can define the ways in which they are allowed to be upgraded.

Constraining Installable Package Versions

Typically, you want a set of packages installed on a system to be supported and upgraded together: Either all packages in the set are updated, or none of the packages in the set are updated. This is the reason for using the incorporate dependency.

The following three partial package manifests show the relationship between the foo and bar packages and the myincorp incorporation package.

The following excerpt is from the foo package manifest:

set name=pkg.fmri value=foo@1.0
dir path=foo owner=root group=bin mode=0755
depend fmri=myincorp type=require

The following excerpt is from the bar package manifest:

set name=pkg.fmri value=bar@1.0
dir path=bar owner=root group=bin mode=0755
depend fmri=myincorp type=require

The following excerpt is from the myincorp package manifest:

set name=pkg.fmri value=myincorp@1.0
depend fmri=foo@1.0 type=incorporate
depend fmri=bar@1.0 type=incorporate

The foo and bar packages both have a require dependency on the myincorp incorporation. The myincorp package has incorporate dependencies that constrain the foo and bar packages in the following ways:

• The foo and bar packages can be upgraded to at most version 1.0: to the level of granularity defined by the version number specified in the dependency.

• If the foo and bar packages are installed, they must be at least at version 1.0 or greater.

The incorporate dependency on version 1.0 allows version 1.0.1 or 1.0.2.1, for example, but does not allow version 1.1, 2.0, or 0.9, for example. When an updated incorporation package is installed that specifies incorporate dependencies at a higher version, the foo and bar packages are allowed to update to those higher versions.

Because foo and bar both have require dependencies on the myincorp package, the incorporation package must always be installed.

Relaxing Constraints on Installable Package Versions

In some situations, you might want to relax an incorporation constraint.

Perhaps bar can function independently of foo, but you want foo to remain within the series of versions defined by the incorporate dependency in the incorporation.

You can use facets to relax incorporation constraints, allowing the administrator to effectively disable certain incorporate dependencies. Facets are discussed in more detail in Chapter 5, Allowing Variations. Briefly, facets are special attributes that can be applied to actions within a package to enable authors to mark those actions as optional.

When actions are marked with facet attributes in this manner, the actions that contain those facets can be enabled or disabled using the pkg change-facet command.

By convention, facets that optionally install incorporate dependencies are named facet.version-lock.name, where name is the name of the package that contains that depend action.

Using the example above, the myincorp package manifest could contain the following lines:

set name=pkg.fmri value=myincorp@1.0
depend fmri=foo@1.0 type=incorporate
depend fmri=bar@1.0 type=incorporate facet.version-lock.bar=true

By default, this incorporation includes the depend action on the bar package, constraining bar to version 1.0. The following command relaxes this constraint:

# pkg change-facet version-lock.bar=false

After successful execution of this command, the bar package is free from the incorporation constraints and can be upgraded to version 2.0 if necessary.

Freezing Installable Package Versions

So far, the discussion has been around constraints applied during the package authoring process by modifying the package manifests. The administrator can also apply constraints to the system at runtime.

Using the pkg freeze command, the administrator can prevent a given package from being changed from either its current installed version, including time stamp, or a version specified on the command line. This capability is effectively the same as an incorporate dependency.

See the pkg(1) man page for more information about the freeze command.

To apply more complex dependencies to an image, create and install a package that includes those dependencies.