2573N/A.. The contents of this file are subject to the terms of the
2573N/A Common Development and Distribution License (the "License").
2573N/A You may not use this file except in compliance with the License.
2573N/A See the License for the specific language governing permissions
2573N/A and limitations under the License.
2573N/A.. When distributing Covered Code, include this CDDL HEADER in each
2573N/A If applicable, add the following below this CDDL HEADER, with the
2573N/A fields enclosed by brackets "[]" replaced with your own identifying
2573N/A information: Portions Copyright [yyyy] [name of copyright owner]
2573N/A.. Copyright (c) 2011, Oracle
and/or its affiliates. All rights reserved.
2585N/ADependencies define how packages are related.
2525N/AIPS provide a variety of different dependency types as discussed in
2585N/A*Chapter 3*. In this chapter we go into more detail about how each
2525N/Adependency type can be used to control the software that is installed.
2585N/AIn IPS, a package cannot be installed unless all package dependencies are
2585N/Asatisfied. IPS allows packages to be mutually dependent (to have circular
2585N/Adependencies). IPS also allows packages to have different kinds of
2585N/Adependencies on the same package at the same time.
2585N/AEach section below contains an example ``depend`` action, as it would appear in
2585N/Aa manifest during package creation.
2585N/AThe most basic type of dependency is the ``require`` dependency.
2585N/AIf a package A@1.0 contains a ``require`` dependency on package B@2,
2585N/Ait means that if A@1.0 is installed, a version of B at 2 or higher
2585N/AThis acceptance of higher versioned packages reflects the implicit
2585N/Aexpectation of binary compatibility in newer versions of existing
2585N/AThese dependencies are typically used to express functional dependencies
2585N/Asuch as libraries or interpreters such as Python, Perl, etc. The version
2585N/Aportion of the specified FMRI can be omitted; it indicates that any
2585N/Aversion will suffice. The latter might not be actually true, but
2585N/Aif other dependencies constrain the version adequately, this might
2585N/AAn example ``require`` dependency is::
2573N/AThe ``require-any`` dependency is used if more than one package will
2585N/Asatisfy a functional requirement. IPS will pick one of the packages to
2585N/Ainstall if the dependency is not already satisfied.
2585N/AA typical use might be to ensure that at least one version of Perl
2585N/Awas installed on the system, for example. The versioning is handled
2585N/Ain the same manner as for the ``require`` dependency.
2585N/AAn example ``require-any`` dependency is::
2573N/AThe ``optional`` dependency is similar to the ``require`` dependency, but
2585N/Athe specified package need not be installed. However, if it is present,
2585N/Ait must be at the specified version or greater.
2585N/AThis type of dependency is typically used to handle cases where packages
2585N/AIn this case, each version of the package post-transfer
2525N/Awould contain an optional dependency on the other package's
2525N/Apost-transfer version, so it would be impossible to install
2585N/Aincompatible versions of the two packages.
2585N/AOmitting the version on an optional dependency makes the dependency a no-op,
2585N/AAn example ``optional`` dependency is::
2573N/AThe ``conditional`` dependency is similar to the ``require`` dependency as
2585N/Awell, except that a predicate attribute is present. If the package specified
2585N/Ain the value of the predicate attribute is present on the system at the
2585N/Aspecified or greater version, the conditional dependency is treated as a
2585N/A``require`` dependency, otherwise it is ignored.
2585N/AThis type of dependency is most often used to install optional extensions
2585N/Ato a package if the requisite base packages are present on the system.
2585N/AFor example, an editor package that has both X11 and terminal versions might
2573N/Aplace the X11 version in a separate package, and include a conditional
2525N/Adependency on the X11 version from the text version with the existence
2525N/Aof the requisite X client library package as the predicate.
2585N/AAn example conditional dependency is::
2585N/AThe ``group`` dependency is used to construct groups of packages.
2585N/AThe group dependency will ignore the version specified; any version of the
2585N/Anamed package satisfies this dependency. The named package
2585N/Ais required unless the package has been placed on the avoid list (see |pkg|),
2585N/Athe package is rejected with ``pkg install --reject``, or the package is
2585N/Auninstalled with ``pkg uninstall``.
2585N/AThese three options enable administrators to 'deselect' packages that are the
2585N/Asubject of a group dependency. IPS will remember this and not re-install the
2585N/Apackage during an update unless it becomes required by another dependency.
2585N/AIf the new dependency is removed by another subsequent operation, then the
2585N/Apackage is uninstalled again.
2585N/AA good example of how to use these dependencies is to construct packages
2585N/Acontaining group dependencies on packages that are needed for typical uses
2585N/Aof a system. Some examples might be ``solaris-small-server``,
2585N/A``solaris-desktop`` or ``developer-gnu``. A set of Oracle Solaris packages
2585N/Adelivering group dependencies is shown in *Chapter 13*.
2585N/AThe administrator could install all that apply and know that over subsequent
2585N/Aupdates to newer versions of the OS, the appropriate packages would be added
2585N/AAn example ``group`` dependency is::
2573N/AThe ``origin`` dependency exists to resolve upgrade issues that require
2585N/Aintermediate transitions. The default behavior is to specify the minimum
2585N/Aversion of a package (if installed) that must be present on the system being
2585N/AFor example, a typical use might be a database package version 5 that supports
2585N/Aupgrade from version 3 or greater, but not earlier versions.
2585N/AIn this case, version 5 would have an origin dependency on itself at version 3.
2585N/AThus, if version 5 was being fresh installed, installation would proceed; but
2585N/Aif version 1 of the package was installed, one could not upgrade directly to this
2585N/AThus, ``pkg update database-package`` would not select version 5
2525N/Ain this case but would pick version 3 instead as the latest possible
2585N/Aversion it could upgrade to.
2585N/AThe behavior of this dependency can be modified by the ``root-image`` attribute
2585N/Abeing set to ``true``; in this case the named package must be at the specified
2585N/Aversion or greater if it is present in the running system, rather than the image
2585N/AThis is generally used for operating system issues such as dependencies on boot
2585N/AAn example ``origin`` dependency is::
2573N/AThe ``parent`` dependency is used for zones or other child images. In
2585N/Athis case, the dependency is only checked in the child image, and specifies a
2525N/Apackage and version that must be present in the parent image or global
2525N/Azone. The version specified must match to the level of precision
2585N/AFor example, if the ``parent`` dependency is on A@2.1, then any version of A
2585N/Abeginning with 2.1. will match. This dependency is often used to require that
2585N/Apackages are kept in sync between non-global zones and the global zone, and as
2585N/Aas a synonym for the exact version of the package that contains this dependency.
2585N/AThis is used to keep key operating system components, such as ``
libc.so.1``
2585N/Ainstalled in the zone synchronized with the kernel installed in the global zone.
2585N/AThe ``parent`` dependency is also discussed in *Chapter 12*.
2585N/AAn example ``parent`` dependency is::
2585N/AThe ``incorporate`` dependency is heavily used in Oracle Solaris to ensure that
2585N/Acompatible versions of software are installed together.
2585N/AThe basic mechanism is like that of an ``optional`` dependency, except
2585N/Athat the version matching is that of the ``parent`` dependency: if this package
2525N/Ais present, it must be at the specified version to the level
2585N/AHow these dependencies are typically used is that many of
2525N/Athem are placed in the same package to define a surface in the package
2525N/Aversion space that is compatible. Packages that contain such sets of
2573N/Aincorporate dependencies are often called *incorporations*; it is
2525N/Atypical to define such for sets of software packages that are built
2525N/Atogether and are not separately versioned, like much of the kernel.
2585N/AAn example ``incorporate`` dependency is::
2573N/AThe ``exclude`` dependency is seldom used. It allows the containing
2525N/Apackage to preclude installation with the specified package at the
2585N/Aspecified version or higher.
2585N/ANote that if the version is omitted, no version of the specified package
2585N/Acan be installed with the containing package. These constraints can be
2585N/Afrustrating to administrators, and should be avoided where possible.
2585N/AAn example exclude dependency is::
2585N/AThrough the careful use of the various types of ``depend`` actions described
2585N/Aabove, packages can define the ways in which they are allowed to be upgraded.
2585N/AIn general, we often desire that a group of packages installed on a system
2585N/Abe supported and upgraded as a group: Either all packages in the group are
2585N/Aupdated, or none of the packages in the group are updated. As mentioned earlier,
2585N/Athis is the reason for using the ``incorporate`` dependency in Oracle Solaris.
2585N/AThe following three partial package manifests show the relationship
2585N/Abetween the ``foo`` and ``bar`` packages and the ``myincorp`` incorporation
2585N/A dir path=foo owner=root group=bin mode=0755
2585N/A depend fmri=myincorp type=require
2585N/A dir path=bar owner=root group=bin mode=0755
2585N/A depend fmri=myincorp type=require
2585N/A depend fmri=foo@1.0 type=incorporate
2585N/A depend fmri=bar@1.0 type=incorporate
2585N/AThe ``foo`` and ``bar`` packages both have a ``require`` dependency on the
2585N/A``myincorp`` incorporation. The ``myincorp`` package has ``incorporate``
2585N/Adependencies such that ``foo`` and ``bar`` can be upgraded to
2585N/A**at most** version 1.0, to the level of granularity defined by the version
2585N/Anumber and, if installed, must be **at least** at version 1.0 or greater.
2585N/AThat is, an ``incorporate`` dependency on version 1.0 allows for
2585N/A1.0.1, 1.0.2.1, etc. but doesn't allow version 1.1, version 2.0, version 0.9,
2585N/Aetc. When we deliver a new incorporation package, one that has ``incorporate``
2585N/Adependencies at a higher version, we will allow ``foo`` and ``bar`` to upgrade
2585N/Ato those versions instead (assuming that the incorporation package is also being
2585N/ANote here that because ``foo`` and ``bar`` both have ``require`` dependencies on
2585N/Athe ``myincorp`` package, the incorporation package must always be installed.
2585N/AHowever, conflicting with the requirement we stated at the beginning of this
2585N/Asection, there are some situations where we might want to relax the
2585N/APerhaps ``bar`` can function independently of ``foo``, but we'd like ``foo``
2585N/Ato remain within the series of versions our incorporation constrains it to.
2585N/AWe can relax the incorporation constraints using *facets*, allowing the
2585N/Aadministrator to effectively *disable* certain ``incorporate`` dependencies.
2585N/AFacets are discussed in more detail in *Chapter 7*. Briefly, facets
2585N/Aare special attributes that can be applied to actions within a package to enable
2585N/Aauthors to mark those actions as optional.
2585N/AWhen actions are marked with facet attributes in this manner, the actions
2585N/Acontaining those facets can be enabled or disabled using the
2585N/A``pkg change-facet`` command.
2585N/ABy convention, facets that optionally install ``incorporate`` dependencies are
2585N/ASo, for example, using the example above, we could have the following
2585N/A depend fmri=foo@1.0 type=incorporate
2585N/AThis incorporation includes our ``depend`` action by default, constraining
2585N/A``bar`` to version 1.0. The following command relaxes this constraint::
2585N/AThe ``bar`` package is free from the incorporation constraints, and can be
2585N/Aupgraded to version 2.0 if necessary.
2585N/ASo far, all of the discussion has been around constraints that have been applied
2585N/Aduring the package authoring process, by modifying the package manifests
2585N/A|pkg| also has a means for the administrator to apply constraints to the system
2585N/AUsing the ``pkg freeze`` command, the administrator can prevent a given
2585N/Apackage from being updated past either its current version, or a version
2585N/Aspecified on the command line. This capability is effectively the same as an
2585N/ASee the |pkg| man page for more information on the ``freeze`` command.
2585N/AIn order to apply more complex dependencies to an image, it is necessary to
2585N/Acreate and install a package that includes those dependencies.