.. CDDL HEADER START
.. 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
or http://www.opensolaris.org/os/licensing.
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]
.. CDDL HEADER END
.. Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
Tags and attributes
-------------------
Definitions
~~~~~~~~~~~
Both packages and actions within a package can carry metadata, which
we informally refer to as attributes and tags. Both attributes and
tags have a name and one or more values.
Attributes
settings that apply to an entire package. Introduction
of an attribute that causes different deliveries by the client could
cause a conflict with the versioning algebra, so we attempt to avoid
them.
Tags
settings that affect individual files within a package.
Attribute and tag syntax and namespace
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syntax
``````
Naming
^^^^^^
The syntax for attributes and tags is similar to that used for
|pkg5| and |smf5| FMRIs.
[org_prefix,][name][:locale]
The organizational prefix is a forward-ordered or reverse-ordered
domain name, followed by a comma. The name field is an identifier
which may have a prefix ending in a period to allocate the namespace.
If the locale field is omitted, the default locale is "C", a 7-bit
ASCII locale.
Each of these fields is [A-Za-z][A-Za-z0-9\_-.]*.
Manifests
^^^^^^^^^
In package manifests, the syntax for an attribute is:
set name=<attribute name> value=<value> [value=<value2> ...]
In package manifests, tags are included in the action line
for the action they apply to:
<action> [...] <tag name>=<tag value> [<tag name>=<tag value2> ...]
Unprefixed attributes and tags
``````````````````````````````
All unprefixed attributes and tags are reserved for use by the
framework.
Generally, unprefixed tags are introduced in the definition of an
action.
Attributes and tags common to all packages
``````````````````````````````````````````
Attributes and tags starting with "pkg." or "info." are for attributes
common to all packages, regardless of which particular OS platforms that
a specific package may target. "pkg" attributes are used by the
packaging system itself, while "info" attributes are purely informational,
possibly for use by other software.
Common attributes
^^^^^^^^^^^^^^^^^
pkg.summary
A short, descriptive name for the package.
pkg.summary:fr would be the descriptive name in French.
Exact numerical version strings are discouraged in the
descriptive name.
Example: "Apache HTTPD Web Server 2.x"
pkg.description
A descriptive paragraph for the package. Exact numerical version
strings can be embedded in the paragraph.
pkg.detailed-url
One or more URLs to pages or sites with further information about
the package. pkg.detailed-url:fr would be the URL to a page with
information in French.
pkg.renamed
A value of "true" indicates the package has been renamed or split
into the packages listed in the depend actions.
pkg.obsolete
A value of "true" indicates the package is obsolete and should be
removed on upgrade.
pkg.human-version
For components whose upstream version isn't a dot-separated sequence
of nonnegative integers (OpenSSL's 0.9.8r, for example), this
attribute can be set to that string, and will be displayed when
appropriate. It cannot be used in an FMRI to install a particular
version; package authors must still convert the version into a
sequence of integers.
variant.*
See facets.txt
Common tags
^^^^^^^^^^^
disable_fmri
See "Actuators" section of |pkg5|
facet.*
See facets.txt
reboot-needed
See "Actuators" section of |pkg5|
refresh_fmri
See "Actuators" section of |pkg5|
restart_fmri
See "Actuators" section of |pkg5|
suspend_fmri
See "Actuators" section of |pkg5|
variant.*
See facets.txt
Informational attributes
^^^^^^^^^^^^^^^^^^^^^^^^
The following attributes are not necessary for correct package installation,
but having a shared convention lowers confusion between publishers and
users.
info.classification
A list of labels classifying the package into the categories
shared among |pkg5| graphical clients.
Values currently used for OpenSolaris are prefixed with
``org.opensolaris.category.2008:`` and must match one of the
categories listed in ``src/gui/data/opensolaris.org.sections``
info.keyword
A list of additional terms that should cause this package to be
returned by a search.
info.maintainer
A human readable string describing the entity providing the
package. For an individual, this string is expected to be their
name, or name and email.
info.maintainer-url
A URL associated with the entity providing the package.
info.upstream
A human readable string describing the entity that creates the
software. For an individual, this string is expected to be
their name, or name and email.
info.upstream-url
A URL associated with the entity that creates the
software delivered within the package.
info.source-url
A URL to the source code bundle, if appropriate, for the package.
info.repository-url
A URL to the source code repository, if appropriate, for the
package.
info.repository-changeset
A changeset ID for the version of the source code contained in
info.repository-url.
Attributes common to all packages for an OS platform
````````````````````````````````````````````````````
Each OS platform is expected to define a string representing that
platform. For example, the |OS_Name| platform is represented by
the string "opensolaris".
OpenSolaris attributes
^^^^^^^^^^^^^^^^^^^^^^
org.opensolaris.arc-caseid
One or more case identifiers (e.g., PSARC/2008/190) associated with
the ARC case or cases associated with the component(s) delivered by
the package.
org.opensolaris.smf.fmri
One or more FMRI's representing SMF services delivered by this
package. Automatically generated by |pkgdepend1| for packages
containing SMF service manifests.
opensolaris.zone
Obsolete - replaced by variant.opensolaris.zone.
variant.opensolaris.zone
See facets.txt
OpenSolaris tags
^^^^^^^^^^^^^^^^
opensolaris.zone
Obsolete - replaced by variant.opensolaris.zone.
variant.opensolaris.zone
See facets.txt
Organization specific attributes
````````````````````````````````
Organizations wishing to provide a package with additional metadata
or to amend an existing package's metadata (in a repository that
they have control over) must use an organization-specific prefix.
For example, a service organization might introduce
``service.example.com,support-level`` or
``com.example.service,support-level`` to describe a level of support
for a package and its contents.
Attributes specific to certain types of actions
```````````````````````````````````````````````
Each type of action also has specific attributes covered in the
documentation of those actions. These are generally documented
in the section of the |pkg5| manual page for that action.
Attributes specific to certain types of file
````````````````````````````````````````````
These would generally appear on file actions for files in a specific
format.
elfarch, elfbits, elfhash
Data about ELF format binary files (may be renamed in the future
to info.file.elf.*). Automatically generated during package
publication. See the "File Actions" section of |pkg5|.
info.file.font.name
The name of a font contained in a given file. There may be multiple
values per file for formats which collect multiple typefaces into a
single file, such as .ttc (TrueType Collections), or for font aliases.
May also be provided in localized variants, such as a Chinese font
providing both info.file.font.name:en and info.file.font.name:zh for
the English and Chinese names for the font.
info.file.font.xlfd
An X Logical Font Description (XLFD) for a font contained in a
given file. Should match an XLFD listed in fonts.dir or fonts.alias
for the file. There may be multiple values per file due to font
aliases.
.. 3.3. Attributes best avoided
.. built-on release
.. One problem we may run into is packages that have been built on a
release newer than that on the image. These packages should be
evaluated as unsuitable for the image, and not offered in the graph.
There are a few ways to handle this case:
.. 1. Separate repository. All packages offered by a repository were
built on a known system configuration. This change requires
negotiation between client and server for a built-on match
condition. It also means that multiple repositories are needed
for a long lifecycle distribution.
.. 2. Attributes. Each package comes with a built-on attribute. This
means that clients move from one built-on release to another
triggered by conditions set by the base package on the client.
Another drawback is that it becomes impossible to request a
specific package by an FMRI, without additional knowledge.
.. 3. Additional version specifier. We could extend
release,branch:timestamp to release,built,branch:timestamp--or
fold the built and branch version together. Since the built
portion must reserve major.minor.micro, that means we move to a
package FMRI that looks like
.. [email protected],5.11.0.1:timestamp
.. This choice looks awkward. We could instead treat the built
portion as having a default value on a particular client. Then
the common specifier would be
.. name@release[,build]-branch:timestamp
.. build would be the highest available valid release for the
image.
.. The meaning of the built-on version could be controversial. A
simple approach would be to base it on base/minimal's release,
rather than uname(1) output.