Skip to main content

Source code file content

Revision: 3009

18116510 operation planning ignores removed facets if new are set at same time
» Project Revision History

» Checkout URL

pkg-gate / doc / tags-and-attributes.txt

Size: 10277 bytes, 1 line
PSARC/2008/190
pkg(5): image packaging system

TAGS AND ATTRIBUTES

1.  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.

2.  Attribute and tag syntax and namespace

2.1.  Syntax

2.1.1 Naming

    The syntax for attributes and tags is similar to that used for
    pkg(5) and smf(5) 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_-.]*.

2.1.2 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> ...]

2.2.  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.

2.3.  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.

2.3.1.  Common attributes

    pkg.summary
       A short, descriptive name for the package.  In accordance with
       2.1.1 above, 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

2.3.2.  Common tags

    disable_fmri
       See "Actuators" section of pkg(5)

    facet.*
       See facets.txt

    reboot-needed
       See "Actuators" section of pkg(5)

    refresh_fmri
       See "Actuators" section of pkg(5)

    restart_fmri
       See "Actuators" section of pkg(5)

    suspend_fmri
       See "Actuators" section of pkg(5)

    variant.*
       See facets.txt

2.3.3 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 pkg(5) 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.


2.4.  Attributes & tags common to all packages for an OS platform

    Each OS platform is expected to define a string representing that
    platform.  For example, the OpenSolaris platform is represented by
    the string "opensolaris".

2.4.1.  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 pkgdepend(1) for packages
	containing SMF service manifests.

    opensolaris.zone
	Obsolete - replaced by variant.opensolaris.zone.

    variant.opensolaris.zone
	See facets.txt

2.4.1.  OpenSolaris tags

    opensolaris.zone
	Obsolete - replaced by variant.opensolaris.zone.

    variant.opensolaris.zone
	See facets.txt

2.5.  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.

2.5.1   Sun/Oracle attributes

    These are listed simply to record the currently used attributes in
    the OpenSolaris /support repository and are subject to change as 
    Sun integrates into Oracle.

    com.sun.service.incorporated-changes
	A space-separated list of Change Requests ids in the Sun bugtraq 
	database for the changes incorporated in this revision of the 
	package that were not in the previous revision on the same branch.

    com.sun.service.keywords
	Keywords for the type of change included, such as "security"
	for security fixes.

2.6   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 pkg(5) manual page for that action.

2.7   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 pkg(5).

    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

	coreutils@6.7,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.



 
 
Close
loading
Please Confirm
Close