Skip to main content

Source code file content

Revision: 2948

17477111 resync manpages from docs group
» Project Revision History

» Checkout URL

pkg-gate / doc / dev-guide / chpt7.txt

Size: 12397 bytes, 1 line

.. The contents of this file are subject to the terms of the
   Common Development and Distribution License (the "License").
   You may not use this file except in compliance with the License.

.. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   See the License for the specific language governing permissions
   and limitations under the License.

.. When distributing Covered Code, include this CDDL HEADER in each
   file and include the License file at usr/src/OPENSOLARIS.LICENSE.
   If applicable, add the following below this CDDL HEADER, with the
   fields enclosed by brackets "[]" replaced with your own identifying
   information: Portions Copyright [yyyy] [name of copyright owner]


.. Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.

Chapter 7

Allowing Variations

In this chapter we explore how variants and facets are used in
IPS to provide different installation options to the end user.


Since Oracle Solaris supports multiple architectures, one common error
made with the SVR4 packaging system was the accidental installation
of packages for an incorrect architecture. With the introduction of
software repositories, the prospect of maintaining a separate
repository for each supported architecture seemed unappealing
to ISVs and error prone for customers.  As a result,  IPS supports
installation of a single package on multiple architectures.

The mechanism that implements this feature is called a
*variant*.  A variant enables the properties of the target image
to determine which software components are actually installed.

A variant has two parts: its name, and the list of possible values.
The variants defined in Oracle Solaris 11 are:

    ========================    =================
    Name	     	      	Values
    ========================    =================
    variant.arch                sparc, i386    global, nonglobal
    variant.debug.*             true, false
    ========================    =================

Variants appear in two places in a package:

  * A ``set`` action names the variant and defines the values that
    apply to this package.

  * Any action that can only be installed for a subset of the
    variant values has a tag that specifies the name of the
    variant and the value on which it is installed.

For example, a package that delivers the symbolic link ``/var/ld/64``
might include::

    set name=variant.arch value=sparc value=i386
    dir group=bin mode=0755 owner=root path=var/ld
    dir group=bin mode=0755 owner=root path=var/ld/amd64 \
    dir group=bin mode=0755 owner=root path=var/ld/sparcv9 \
    link path=var/ld/32 target=.
    link path=var/ld/64 target=sparcv9 variant.arch=sparc
    link path=var/ld/64 target=amd64 variant.arch=i386

Note that components that are delivered on both sparc and i386 receive
no variant tag, but those delivered to one architecture or the other
receive the appropriate tag.  It is perfectly reasonable for actions
to contain multiple tags for different variant names; there might be
debug and nondebug binaries for both sparc and i386.

In Oracle Solaris, kernel components are commonly elided from packages
installed in zones, as they serve no useful purpose.  Thus, they are
marked with the ```` variant set to ``global`` so that they
are not installed in non-global zones.  This is typically done in the
manifest during publication with a |pkgmogrify| rule.  Thus the packages
from the i386 and sparc builds are already marked for zones.  We then
use the |pkgmerge| command to take the packages from the sparc and i386
builds and merge them together.  This is far more reliable and faster 
than attempting to construct such packages manually.

In general, it is not practical to define new variants without
modifying the packaging system as no practical means currently exists
for defining a default value for variants in general.  Package developers
cannot define new variants at present.

However, the ``variant.debug.*`` portion of the variant namespace is predefined
to have a default version of ``false``; thus, developers can provide debug
versions of their components, tagged with the appropriate variant, and
users can select that variant if problems arise.  Remember that
variants are set per image, so selecting a suitable name that
is unique at the appropriate resolution for that piece of software 
is important.

Note that variant tags are applied to any actions that differ between
architectures during merging; this includes dependencies, ``set`` actions,
etc.  Packages that are marked as not supporting one of the variant values
of the current image are not considered for installation.

The |pkgmerge| man page provides several examples of merging packages. Note
that it will merge across multiple different variants at the same time if


Often, package developers have optional portions of their software
that actually belong with the main body, but some people might not
want to install.  Some examples are localization files for different
locales, man pages and other documentation, header files needed 
only by developers or DTrace users.

Traditionally, such optional content has been placed in separate
packages with an arbitrarily selected naming convention (such as
appending ``-dev`` or ``-devel`` to the package name) enabling administrators
to select the optional content.

This has led to various problems, such as adding a new locale
for all the software on a system being a rather irritating task,
as the admin has to discover all the necessary packages by examining
the lists of available packages.

IPS has implemented a mechanism similar to variants called *facets*
to deal with this problem.  Like variants, facets have a name and
a value. The value is either set to ``true`` or ``false`` in the
image.  The default value is ``true``. The facet namespace is hierarchal,
with matching rules such that the longest match wins.

For example, the default value for all facets is ``true``; the |pkg| client
implicitly sets ``facet.*`` to ``true``.
Documentation in Oracle Solaris packages is tagged with the type of 
documentation.  For example, man pages are tagged with 
```` in the package manifests.

The following commands include man pages but exclude all other documentation
from being installed in this image::

    # pkg change-facet facet.doc.*=false
    # pkg change-facet

Similarly, the following commands install only the German localization in this

    # pkg change-facet facet.locale.*=false
    # pkg change-facet

If an action contains multiple facet tags, the action is installed if the value
of any of the facet tags is ``true``.

The ``pkg facet`` command is useful in determining which facets are
set in the image.

The package developer can use |pkgmogrify| to quickly tag his
man pages, localizations, etc. using regular expressions to
match the different types of files.  This is described in detail
in *Chapter 8*.

Facets can also be used to manage dependencies, essentially turning
dependencies on and off, depending on whether the facet is set.  See
*Chapter 6* for a discussion of ``facet.version-lock.*``.

Oracle Solaris facets that might be of use for software developers include:

========================  ==================        ==================
facet.devel               facet.locale.es_BO        facet.locale.lt_LT
facet.doc                 facet.locale.es_CL             facet.locale.es_CO        facet.locale.lv_LV
facet.doc.pdf             facet.locale.es_CR            facet.locale.es_DO        facet.locale.mk_MK
facet.doc.html            facet.locale.es_EC
facet.locale              facet.locale.es_ES        facet.locale.ml_IN           facet.locale.es_GT
facet.locale.af_ZA        facet.locale.es_HN        facet.locale.mr_IN           facet.locale.es_MX
facet.locale.ar_AE        facet.locale.es_NI        facet.locale.ms_MY
facet.locale.ar_BH        facet.locale.es_PA
facet.locale.ar_DZ        facet.locale.es_PE        facet.locale.mt_MT
facet.locale.ar_EG        facet.locale.es_PR        facet.locale.nb
facet.locale.ar_IQ        facet.locale.es_PY        facet.locale.nb_NO
facet.locale.ar_JO        facet.locale.es_SV
facet.locale.ar_KW        facet.locale.es_US        facet.locale.nl_BE
facet.locale.ar_LY        facet.locale.es_UY        facet.locale.nl_NL
facet.locale.ar_MA        facet.locale.es_VE        facet.locale.nn
facet.locale.ar_OM           facet.locale.nn_NO
facet.locale.ar_QA        facet.locale.et_EE
facet.locale.ar_SA           facet.locale.or
facet.locale.ar_TN           facet.locale.or_IN
facet.locale.ar_YE        facet.locale.fi_FI            facet.locale.pa_IN
facet.locale.as_IN        facet.locale.fr_BE           facet.locale.fr_CA        facet.locale.pl_PL
facet.locale.az_AZ        facet.locale.fr_CH           facet.locale.fr_FR        facet.locale.pt_BR
facet.locale.be_BY        facet.locale.fr_LU        facet.locale.pt_PT  
facet.locale.bg_BG           facet.locale.ro_RO  
facet.locale.bn_IN        facet.locale.gu_IN        facet.locale.ru_RU           facet.locale.he           facet.locale.ru_UA
facet.locale.bs_BA        facet.locale.he_IL           facet.locale.hi 
facet.locale.ca_ES        facet.locale.hi_IN        facet.locale.sa_IN
facet.locale.cs_CZ        facet.locale.hr_HR        facet.locale.sk_SK
facet.locale.da_DK        facet.locale.hu_HU        facet.locale.sl_SI           facet.locale.hy           facet.locale.sq
facet.locale.de_AT        facet.locale.hy_AM        facet.locale.sq_AL
facet.locale.de_CH        facet.locale.id_ID        facet.locale.sr_ME
facet.locale.de_DE           facet.locale.sr_RS
facet.locale.de_LI        facet.locale.is_IS
facet.locale.de_LU           facet.locale.sv_SE
facet.locale.el           facet.locale.it_CH        facet.locale.ta
facet.locale.el_CY        facet.locale.it_IT        facet.locale.ta_IN
facet.locale.el_GR        facet.locale.ja           facet.locale.te
facet.locale.en           facet.locale.ja_JP        facet.locale.te_IN
facet.locale.en_AU        facet.locale.ka 
facet.locale.en_BW        facet.locale.ka_GE        facet.locale.th_TH
facet.locale.en_CA        facet.locale.kk 
facet.locale.en_GB        facet.locale.kk_KZ        facet.locale.tr_TR
facet.locale.en_IE        facet.locale.kn_IN        facet.locale.uk_UA
facet.locale.en_IN        facet.locale.ko 
facet.locale.en_MT        facet.locale.ko_KR        facet.locale.vi_VN
facet.locale.en_NZ        facet.locale.ks           facet.locale.zh
facet.locale.en_PH        facet.locale.ks_IN        facet.locale.zh_CN
facet.locale.en_SG        facet.locale.ku           facet.locale.zh_HK
facet.locale.en_US        facet.locale.ku_TR        facet.locale.zh_HK
facet.locale.en_ZW           facet.locale.zh_SG
facet.locale.eo           facet.locale.ky_KG        facet.locale.zh_TW
facet.locale.es_AR        facet.locale.lg     
========================  ==================        ==================

Please Confirm