Skip to content

Latest commit

 

History

History
329 lines (235 loc) · 10.7 KB

guide-metadata-conventions.rst

File metadata and controls

329 lines (235 loc) · 10.7 KB
Raw

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.