Delivering Multiple Implementations of an Application

You might want to deliver multiple implementations of a given application with characteristics such as the following:

• All implementations are available in the image.

• One of the implementations is specified as the preferred implementation.

• The preferred implementation has symbolic links to its binaries installed to a common directory such as /usr/bin for ease of discovery.

• The administrator can change the preferred implementation as required, without adding or removing any packages.

One example of delivering multiple implementations of an application is GCC. Oracle Solaris provides multiple versions of GCC, with each version in its own package, and /usr/bin/gcc points to the preferred version.

IPS uses mediated links to manage multiple implementations of an application in a single image. A mediated link is a symbolic link that is controlled by the pkg set-mediator and pkg unset-mediator commands. The link actions in the packages that deliver different implementations of an application are said to participate in a mediation. The pkg mediator command lists the mediations in the image. See the pkg(1) man page for information about the mediator commands.

The following attributes can be set on link actions to control how mediated links are delivered:

mediator

Specifies the entry in the mediation namespace shared by all path names participating in a given mediation group (for example python).

Link mediation can be performed based on mediator-version and mediator-implementation. All mediated links for a given path name must specify the same mediator. However, not all mediator versions and implementations need to provide a link at a given path. If a mediation does not provide a link, then the link is removed when that mediation is selected.

A mediator, in combination with a specific version and/or implementation represents a mediation that can be selected for use by the packaging system.

mediator-version

Specifies the version (expressed as a dot-separated sequence of non-negative integers) of the interface described by the mediator attribute. This attribute is required if mediator is specified and mediator-implementation is not specified. A local system administrator can explicitly set the version to use. The value specified generally should match the version of the package that is delivering the link. For example, runtime/python-26 should use mediator-version=2.6, although this is not required.

mediator-implementation

Specifies the implementation of the mediator. The attribute can be specified in addition to or instead of the mediator-version attribute. Implementation strings are not considered to be ordered. A string is arbitrarily selected by pkg(5) if not explicitly specified by a system administrator.

The value of mediator-implementation can be a string of arbitrary length composed of alphanumeric characters and spaces. If the implementation itself can be or is versioned, then the version should be specified at the end of the string, after an @ symbol. The version is a dot-separated sequence of non-negative integers. If multiple versions of an implementation exist, the default behavior is to select the implementation with the highest version.

If only one instance of an implementation-mediation link at a particular path is installed on a system, then that one is chosen automatically. If future links at the path are installed, the link will not be switched unless a vendor, site, or local override applies, or if one of the links is version-mediated.

mediator-priority

When resolving conflicts in mediated links, pkg(5) chooses the link with the greatest value of mediator-version if possible. If that is not possible, pkg(5) chooses the link based on mediator-implementation. The mediator-priority attribute is used to specify an override for the normal conflict resolution process. If the mediator-priority attribute is not specified, the default mediator selection logic is applied.

The mediator-priority attribute can have one of the following values:

vendor

The link is preferred over those that do not have a mediator-priority specified.

site

The link is preferred over those that have a value of vendor or that do not have a mediator-priority specified.

A local system administrator can override the selection logic described above.

The following two excerpts from sample manifests participate in a mediation for the link /usr/bin/myapp. Implementation 1 is version 5.8.4:

set name=pkg.fmri value=pkg://test/myapp-impl-1@1.0,5.11:20120721T035233Z
file path=usr/myapp/5.8.4/bin/myapp group=sys mode=0755 owner=root
link path=usr/bin/myapp target=usr/myapp/5.8.4/bin/myapp mediator=myapp mediator-version=5.8.4

Implementation 2 is version 5.12:

set name=pkg.fmri value=pkg://test/myapp-impl-2@1.0,5.11:20120721T035239Z
file path=usr/myapp/5.12/bin/myapp group=sys mode=0755 owner=root
link path=usr/bin/myapp target=usr/myapp/5.12/bin/myapp mediator=myapp mediator-version=5.12

Both of these packages can be installed in the same image:

$ pkg list myapp-impl-1 myapp-impl-2
NAME (PUBLISHER)                  VERSION      IFO
myapp-impl-1                      1.0          i--
myapp-impl-2                      1.0          i--

Use the pkg mediator command to see the mediations in use:

$ pkg mediator
MEDIATOR VER. SRC. VERSION IMPL. SRC. IMPLEMENTATION
myapp    local     5.12    system
$ ls -al usr/bin/myapp
lrwxrwxrwx 1 root sys 23 Jul 21 16:58 usr/bin/myapp -> usr/myapp/5.12/bin/myapp

Use the pkg search command to see which other packages participate in the myapp mediation:

$ pkg search -ro path,target,mediator,mediator-version,pkg.shortfmri ::mediator:myapp
PATH          TARGET                    MEDIATOR MEDIATOR-VERSION PKG.SHORTFMRI
usr/bin/myapp usr/myapp/5.12/bin/myapp  myapp    5.12             pkg:/myapp-impl-2@1.0
usr/bin/myapp usr/myapp/5.8.4/bin/myapp myapp    5.8.4            pkg:/myapp-impl-1@1.0

Use the pkg set-mediator command to change the mediation. The following example changes which version of myapp is the preferred version:

# pkg set-mediator -V 5.8.4 myapp
            Packages to update: 2
           Mediators to change: 1
       Create boot environment: No
Create backup boot environment: No

PHASE                                   ITEMS
Removing old actions                      2/2
Updating modified actions                 2/2
Updating image state                     Done
Creating fast lookup database            Done
Reading search index                     Done
Updating search index                     2/2
# ls -al usr/bin/myapp
lrwxrwxrwx  1 root    sys    24 Jul 21 17:02 usr/bin/myapp -> usr/myapp/5.8.4/bin/myapp