Software can have components that are optional and components that are mutually exclusive. Examples of optional components include locales and documentation. Examples of mutually exclusive components include SPARC or x86 architecture. Optional components are called facets and mutually exclusive components are called variants.
Both facets and variants are comprised of the following two components:
A property set on the image
Tags set on actions in a package manifest
Facet and variant tag values set on an action in a package manifest compared with the corresponding facet and variant property values set in the image determine whether that action can be installed.
Each facet and variant property and tag has a name and a value. A single package action can have multiple facet and variant tags.
Values of facet and variant properties and tags do not need to be set explicitly. Values can be default values or inherited values. For example, a non-global zone can inherit values from its parent global zone. Some variant property values are set in the image at initial system installation and cannot be changed.
The following algorithm describes how the facet and variant property values set on the image affect whether a particular action is installed. Values are described in more detail in the following sections.
An action that has no facet or variant tags in the package manifest is always installed.
An action that has facet tags in the package manifest is installed if the following conditions exist in the image:
All facet tags on the action that have a value of all have a facet property value of true in the image, either by default or by being set explicitly.
If any facet tag on the action has a value of true, at least one of those facet property values is also true in the image, either by default or by being set explicitly.
In the following example, the file test.txt is installed only if both devel and optional.test are true in the image and either doc.info or doc.help is true in the image.
file path=usr/share/doc/test.txt facet.devel=all facet.optional.test=all facet.doc.info=true facet.doc.help=true
An action with variant tags in the package manifest is installed only if the values of all the variant tags are the same as the values of the corresponding variant properties set in the image.
In the following example, the file x86test.txt will not be installed. The following package manifest excerpt shows two variant tags set on the file x86test.txt:
file path=usr/share/doc/x86test.txt variant.arch=i386 variant.debug.osnet=true
The following command shows the values of these variant properties in the image:
$ pkg variant arch debug.osnet VARIANT VALUE arch i386 debug.osnet false
An action with both facet and variant tags is installed if both the facet and the variant property values allow the action to be installed.
Most variants have descriptive values. For example, the value of variant.arch can be i386 or sparc. The value of a variant tag on an action in a package manifest must match the value of the corresponding variant property in the image in order for that action to be installed. The arch and zone variant property values are set by the program that creates the image and installs its initial content; these values cannot be changed.
Values of variant.debug.* variants and values of unknown variants can only be true or false and are false in the image by default. An unknown variant is a variant that is introduced as a variant tag on an action in a package manifest, not known at the time the image was created.
If both debug and non-debug versions of an action are delivered, both versions must have the applicable debug variant tag explicitly set, as shown in the following example. In this example, if debug.osnet is false in the image, then the non-debug version of this file is installed; if debug.osnet is true in the image, then the debug version of this file is installed. Usually debug versions of a file also have variant.arch tags.
file payload chash=hash group=sys mode=0644 overlay=allow owner=root path=etc/motd pkg.csize=116 pkg.size=106 preserve=true variant.debug.osnet=true file payload chash=hash group=sys mode=0644 overlay=allow owner=root path=etc/motd pkg.csize=70 pkg.size=50 preserve=true variant.debug.osnet=false
Use the pkg variant command to display the values of variant properties that are set in the image.
$ pkg variant VARIANT VALUE arch i386 opensolaris.zone global
Use the -a option to display the values of all variants that are explicitly set in the image and all variants that are set in installed packages.
$ pkg variant -a VARIANT VALUE arch i386 debug.container false debug.osnet false opensolaris.zone global
Use the -v option to display all possible variant values that can be set for installed packages.
$ pkg variant -v VARIANT VALUE arch i386 arch sparc debug.container false debug.container true debug.osnet false debug.osnet true opensolaris.zone global opensolaris.zone nonglobal
Use the pkg change-variant command to change the value of a variant property. Use the pkg variant -v command to select a value to set.
In the following command, a new BE would be created. See Boot Environment Policy Image Properties for information about when BEs are created. When a new BE is created, the current BE is not changed; boot to the new BE to use the debug files in this example. The -n option shows what would change if you performed the operation without -n, but the command makes no actual changes. No new BE was created in this example.
$ pkg change-variant -nv variant.debug.osnet=true
Packages to change: 232
Variants/Facets to change: 1
Estimated space available: 306.74 GB
Estimated space to be consumed: 1.49 GB
Create boot environment: Yes
Activate boot environment: Yes
Create backup boot environment: No
Rebuild boot archive: Yes
Changed variants/facets:
variant debug.osnet: true
Changed packages:
solaris
...
Editable files to change:
Update:
etc/motd
Facet properties have default values in the image and are not required to be explicitly set. Facet properties whose names begin with facet.debug or facet.optional have the value false by default. All other facet properties have the value true by default.
A facet tag on an action in a package manifest can only have the value true or all. See How Facet and Variant Values Affect Package Installation for a description and example. Actions tagged with facets whose names begin with facet.debug or facet.optional will not be installed by default. To install such actions, you must change the facet property value in the image to true. Actions tagged with any other facet will be installed by default. To avoid installing such actions, you must change the facet property value in the image to false.
Changing the value of a version-lock facet (version-lock.package-name) does not cause actions to be installed or uninstalled. Instead, version-lock facets enable or disable an incorporate type depend action. See Updating a Package Constrained by a Constraint Package.
Facet property values have one of the following three sources. These source names appear in the SRC column of pkg facet command output.
system – Values assigned by the system. These values usually are values of facet tags specified in system packages.
local – Values set by using the pkg change-facet command or by using IPS APIs.
parent – Values inherited from a parent image. For example, a non-global zone inherits facet settings from the global zone.
Use the pkg facet command to display the current value and source of that value of all facet properties that either have been set locally in this image or have been inherited from a parent image.
Use the pkg facet -a command to display the values of all facets that are explicitly set in the image and all facets that are set in installed packages.
The following pkg facet commands show that no doc. facet properties are set locally or inherited:
$ pkg facet doc.* FACET VALUE SRC pkg facet: no matching facets found $ pkg facet -a doc.* FACET VALUE SRC doc.help True system doc.html True system doc.info True system doc.man True system doc.pdf True system doc.ps True system
Use the pkg change-facet command to change the value of a facet property. You can set a facet property value to true, false, or none. Setting a facet property to none applies the system default value to that facet (either true or false), and the source is shown as system.
A facet set on the image can be a full facet such as doc.man or a pattern such as locale.*. This flexibility is useful when you want to disable a portion of the facet namespace and only enable individual facets within that namespace. For example, you could disable all locales and then only enable one or two specific locales, as shown in the following example:
$ pkg change-facet locale.*=false locale.en_US=true
In the following pkg change-facet command, a new BE was not created, but a backup BE was created. See Boot Environment Policy Image Properties for information about when BEs are created. When a backup BE is created, the original image is saved in the backup, and the current BE is changed. The original value of None under “Changed variants/facets” indicates that no local setting existed prior to this command execution; only the system settings existed, as shown by the pkg facet commands above.
$ pkg change-facet -v doc.*=false doc.man=true
Packages to change: 97
Variants/Facets to change: 2
Services to change: 1
Estimated space available: 306.34 GB
Estimated space to be consumed: 936.87 MB
Create boot environment: No
Create backup boot environment: Yes
Rebuild boot archive: No
Changed variants/facets:
facet doc.* (local): None -> False
facet doc.man (local): None -> True
Changed packages:
solaris
...
Services:
restart_fmri:
svc:/application/texinfo-update:default
PHASE ITEMS
...
The following pkg facet commands show the doc. facet property changes that resulted from the pkg change-facet command:
$ pkg facet doc.* FACET VALUE SRC doc.* False local doc.man True local $ pkg facet -a doc.* FACET VALUE SRC doc.* False local doc.help False local doc.html False local doc.info False local doc.man True local doc.pdf False local doc.ps False local