By carefully using the dependency types described above, you can constrain how your packages are allowed to be upgraded.
The incorporate dependency enables you to define a supported software surface that updates together.
Freezing enables an administrator to keep the surface or other software at a particular version.
Version lock facets enable an administrator to disable version constraints on some components of a surface.
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 is updated. To treat packages as a set in this way, use the incorporate dependency.
Installing a Custom Constraint Package in Updating Systems and Adding Software in Oracle Solaris 11.4 shows an example of creating a custom package to constrain the version of the pkg:/entire constraint package that can be installed. The remainder of this section is a more general discussion of constraint packages.
The following three partial package manifests show the relationship between the pkg-a and pkg-b packages and the myincorp constraint package.
The following excerpt is from the pkg-a package manifest:
set name=pkg.fmri value=pkg-a@1.0 dir path=opt/tool-a owner=root group=bin mode=0755 depend fmri=myincorp type=require
The following excerpt is from the pkg-b package manifest:
set name=pkg.fmri value=pkg-b@1.0 dir path=opt/tool-b 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=pkg-a@1.0 type=incorporate depend fmri=pkg-b@1.0 type=incorporate
The pkg-a and pkg-b packages both have a require dependency on the myincorp constraint package. The myincorp package has incorporate dependencies that constrain the pkg-a and pkg-b packages in the following ways:
The pkg-a and pkg-b 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 pkg-a and pkg-b 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 constraint package is installed that specifies incorporate dependencies at a higher version, the pkg-a and pkg-b packages are allowed to update to those higher versions.
Because pkg-a and pkg-b both have require dependencies on the myincorp package, the constraint package is installed if either pkg-a or pkg-b is installed.
The previous section discussed 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 Updating Systems and Adding Software in Oracle Solaris 11.4 and 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.
An administrator might want to disable a dependency version constraint. You can provide version-lock facet tags to enable administrators to disable those tagged incorporate dependencies. The administrator can use the pkg change-facet command to set the value of the corresponding facet image property to false. For general information about facet tags, see Allowing Variations.
Continuing the previous example, perhaps pkg-b can function independently of pkg-a, but you want pkg-a to remain within the series of versions defined by the incorporate dependency in the constraint package. The myincorp package manifest could contain the following lines, including a version-lock facet tag on the pkg-b dependency. By convention, version-lock facet tags are named facet.version-lock.package-name, where package-name is the name specified in the fmri of that depend action, without the version.
set name=pkg.fmri value=myincorp@1.0 depend fmri=pkg-a@1.0 type=incorporate depend fmri=pkg-b@1.0 type=incorporate facet.version-lock.pkg-b=true
By default, this constraint package includes the depend action on the pkg-b package, constraining pkg-b to version 1.0. The following command relaxes this constraint:
$ pkg change-facet version-lock.pkg-b=false
After successful execution of this command, the pkg-b package is free from the version constraints and can be upgraded to a higher version if necessary.
The following example specifies that this constraint package requires the java-8-incorporation package to be installed, and requires it at version 1.8.0.92.14-0. However, the specified facet.version-lock facet enables an administrator to attempt to install a different version.
depend fmri=consolidation/java-8/java-8-incorporation type=require
depend facet.version-lock.consolidation/java-8/java-8-incorporation=true \
fmri=consolidation/java-8/java-8-incorporation@1.8.0.92.14-0 type=incorporate
Perhaps a higher version of the java-8-incorporation package would also work with this constraint package. The administrator can use the pkg change-facet command to set the version-lock.consolidation/java-8/java-8-incorporation facet property to false and then try to update the java-8-incorporation package separately from updating the constraint package.