Controlling Installation of Optional Components

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 and debug or non-debug binaries. In IPS, optional components are called facets and mutually exclusive components are called variants.

Facets and variants are special properties set on the image and are tags set on actions within a package. Most variant tags can have various values. Facet tags set on an action can only have the value true. The values of facet and variant tags on an action compared with the values of facets and variants set in the image determine whether that package action can be installed. For example, if you set a particular locale facet to false, any files or other actions that specify that facet will not be installed, and currently installed files that specify that facet are uninstalled.

To view the current values of the facets and variants set on the image, use the pkg facet and pkg variant commands. To modify the values of the facets and variants set on the image, use the pkg change-facet and pkg change-variant commands. See the pkg(1) man page and the examples below.

Each facet and variant tag has a name and a value. A single action can have multiple facet and variant tags. An example of a component with multiple facet and variant tags is an architecture-specific header file that is used by developers, or a component that is only for a SPARC global zone.

An example of a variant tag is variant.arch=sparc. An example of a facet tag is facet.devel=true. Facets and variants are often referred to without the leading facet. and variant..

Facets are boolean: They can be set only to true (enabled) or false (disabled). By default, all facets are considered to be set to true in the image. A facet tag on an action should only have the value true; other values have undefined behavior. 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 it. For example, you could disable all locales and then only enable one or two specific locales, as shown in the following example:

$ pfexec pkg change-facet 'locale.*=false'
[output about packages being updated]
$ pfexec pkg change-facet locale.en_US=true
[output about packages being updated]

Most variants can have any number of values. For example, the arch variant can be set to i386, sparc, ppc, arm, or whatever architectures the distribution supports. (Only i386 and sparc are used in Oracle Solaris.) The exception are the debug variants. The debug variants can only be set to true or false; other values have undefined behavior. If a file action has both non-debug and debug versions, both versions must have the applicable debug variant explicitly set, as shown in the following example:

file group=sys mode=0644 overlay=allow owner=root \
  path=etc/motd pkg.csize=115 pkg.size=103 preserve=true \
  variant.debug.osnet=true

file group=sys mode=0644 overlay=allow owner=root \
  path=etc/motd pkg.csize=68 pkg.size=48 preserve=true \
  variant.debug.osnet=false 

The variant value must be set on the image in order for a package using the variant to be installed. The arch and zone variants are set by the program that creates the image and installs its initial contents. The debug.* variants are false in the image by default.

The following algorithm describes how the facets and variants set on the image affect whether a particular action is installed.

• Actions with no facet or variant tags are always installed.

• Actions with facet tags are installed unless all of the facets or facet patterns matching the tags are set to false on the image. If any facet is set to true or is not explicitly set (true is the default), then the action is installed.

• Actions with variant tags are installed only if the values of all the variant tags are the same as the values set in the image.

• Actions with both facet and variant tags are installed if both the facets and the variants allow the action to be installed.

You can create your own facet and variant tags. The following tags are in common use in Oracle Solaris.

The following list shows a small sample of the facet tags that are used in Oracle Solaris:

facet.devel             facet.doc
facet.doc.html          facet.doc.info
facet.doc.man           facet.doc.pdf
facet.locale.de         facet.locale.en_GB
facet.locale.en_US      facet.locale.fr
facet.locale.ja_JP      facet.locale.zh_CN

You can display the values of variants and facets that are set on the current image, and you can change variants and facets in the current image. Changing variants and facets might update a large number of packages and might require a new BE. Use -nv to review what changes will be made before you make any changes.

Showing and Changing Variant Values

Use the pkg variant command to display the values of variants that are set.

/usr/bin/pkg variant [-H] [variant_nsmr ...]

$ pkg variant
VARIANT                  VALUE
variant.opensolaris.zone global
variant.arch             i386
$ pkg variant -H variant.arch
variant.arch i386

Use the pkg change-variant command to change the value of a variant.

/usr/bin/pkg change-variant [-nvq] [-C n] [-g path_or_uri ...]
    [--accept] [--licenses] [--no-be-activate]
    [--no-backup-be | --require-backup-be] [--backup-be-name name]
    [--deny-new-be | --require-new-be] [--be-name name]
    variant_name=value ...

The following command produces a large amount of output since so many packages would be affected. Notice that a new BE would not be created by default, but a backup BE would be created. See Boot Environment Policy Image Properties for information about when BEs are created.

Use the -C option to change variants in n non-global zones concurrently with the global zone. See Updating Multiple Non-Global Zones Concurrently for an example of using the -C option.

Use the -n option to see what would change if you performed the operation without -n, but make no actual changes.

$ pfexec pkg change-variant -nv --accept 'variant.debug.*=true'
            Packages to update:       851
     Variants/Facets to change:         3
     Estimated space available:  49.88 GB
Estimated space to be consumed: 270.57 MB
       Create boot environment:        No
Create backup boot environment:       Yes
          Rebuild boot archive:        No

Changed variants/facets:
  variant variant.debug.*: true
    facet facet.locale.en_US: None
    facet facet.locale.*: None
Changed packages:
solaris
  ...

Showing and Changing Facet Values

Use the pkg facet command to display the values of facets that are set.

/usr/bin/pkg facet [-H] [facet_name ...]

$ pkg facet
FACETS             VALUE
facet.locale.en_US True
facet.locale.en    True
facet.locale.*     False
$ pkg facet -H 'facet.locale.*'
facet.locale.* False

Use the pkg change-facet command to change the value of a facet.

/usr/bin/pkg change-facet [-nvq] [-C n] [-g path_or_uri ...]
    [--accept] [--licenses] [--no-be-activate]
    [--no-backup-be | --require-backup-be] [--backup-be-name name]
    [--deny-new-be | --require-new-be] [--be-name name] 
    facet_name=[True|False|None] ...

Use the -C option to change facets in n non-global zones concurrently with the global zone. See Updating Multiple Non-Global Zones Concurrently for an example of using the -C option.

Use the -n option to see what would change if you performed the operation without -n, but make no actual changes.

If the facet value is set to None, the facet specification is removed from the current image.

The following command produces a large amount of output since so many packages would be affected. This operation might require a large amount of time and cause a large amount of network traffic between this image and the package repository. Notice that a new BE would not be created by default, but a backup BE would be created. See Boot Environment Policy Image Properties for information about when BEs are created.

$ pfexec pkg change-facet -nv 'facet.locale.*=true'
            Packages to update:      851
     Variants/Facets to change:        1
     Estimated space available: 49.88 GB
Estimated space to be consumed:  3.13 GB
       Create boot environment:       No
Create backup boot environment:      Yes
          Rebuild boot archive:       No

Changed variants/facets:
    facet facet.locale.*: True
Changed packages:
solaris
  ...