--- a/doc/guide-metadata-conventions.rst Thu Jun 24 11:17:27 2010 -0700
+++ b/doc/guide-metadata-conventions.rst Thu Jun 24 07:02:54 2010 -0700
@@ -27,16 +27,17 @@
~~~~~~~~~~~
Both packages and actions within a package can carry metadata, which
- we informally refer to as attributes and tags.
+ 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.
+ 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 are the settings that affect individual files within a package.
- Tags may eventually have values, depending on how many tags are
- required to handle the SPARC-based platform binaries.
+ Tags
+ settings that affect individual files within a package.
Attribute and tag syntax and namespace
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -44,18 +45,34 @@
Syntax
``````
+Naming
+^^^^^^
+
The syntax for attributes and tags is similar to that used for
- pkg(5) and smf(5) FMRIs.
+ |pkg5| and |smf5| FMRIs.
[org_prefix,][name][:locale]
The organizational prefix is a forward-ordered or reverse-ordered
- domain name, followed by a common. The name field is a
- The default locale, if the locale field is omitted is "C", a 7-bit
+ 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
``````````````````````````````
@@ -68,16 +85,18 @@
Attributes and tags common to all packages
``````````````````````````````````````````
- The "pkg" attribute is to be used for attributes common to all
- packages, regardless of which particular OS platforms that a specific
- package may target.
+ 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.name
- A short, descriptive name for the package. In accordance with
- 2.1 above, pkg.name:fr would be the descriptive name in French.
+ 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.
@@ -89,34 +108,63 @@
pkg.detailed_url
One or more URLs to pages or sites with further information about
- the package.
+ 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.
+
+ variant.*
+ See facets.txt
Common tags
^^^^^^^^^^^
- XXX variant/facet usage
+ disable_fmri
+ See "Actuators" section of |pkg5|
+
+ facet.*
+ See facets.txt
- pkg.debug
- This file is used when the package is intended to be installed in
- a debug configuration. For example, we expect to deliver a debug
- version of the kernel, in addition to the standard non-debug
- version.
+ reboot-needed
+ See "Actuators" section of |pkg5|
- XXX pkg.platform
+ refresh_fmri
+ See "Actuators" section of |pkg5|
- XXX ISA (particularly need to know i386 on i86pc vs amd64 on i86pc)
+ restart_fmri
+ See "Actuators" section of |pkg5|
+
+ suspend_fmri
+ See "Actuators" section of |pkg5|
- pkg.compatibility
- (for shipping non-bleeding edge .so.x.y.z copies, perhaps)
- XXX are we still going to use this?
+ variant.*
+ See facets.txt
-Informational tags
-^^^^^^^^^^^^^^^^^^
+Informational attributes
+^^^^^^^^^^^^^^^^^^^^^^^^
-The following tags are not necessary for correct package installation,
+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
@@ -145,10 +193,6 @@
A changeset ID for the version of the source code contained in
info.repository_url.
-info.gui.classification
- A list of labels classifying the package into the categories
- shared among |pkg5| graphical clients.
-
Attributes common to all packages for an OS platform
````````````````````````````````````````````````````
@@ -156,6 +200,33 @@
platform. For example, the |OS_Name| platform is represented by
the string "opensolaris".
+OpenSolaris attributes
+^^^^^^^^^^^^^^^^^^^^^^
+
+ opensolaris.arc_url
+ One or more URLs associated with the ARC case or cases
+ associated with the component(s) delivered by the package.
+
+ 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
````````````````````````````````
@@ -167,6 +238,42 @@
``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
--- a/doc/tags-and-attributes.txt Thu Jun 24 11:17:27 2010 -0700
+++ b/doc/tags-and-attributes.txt Thu Jun 24 07:02:54 2010 -0700
@@ -7,33 +7,46 @@
1. Definitions
Both packages and actions within a package can carry metadata, which
- we informally refer to as attributes and tags.
+ 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 are the settings that affect individual files within a package.
- Tags may eventually have values, depending on how many tags are
- required to handle the SPARC-based platform binaries.
+ 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 common. The name field is a
- The default locale, if the locale field is omitted is "C", a 7-bit
+ 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
@@ -44,15 +57,17 @@
2.3. Attributes and tags common to all packages
- The "pkg" attribute is to be used for attributes common to all
- packages, regardless of which particular OS platforms that a specific
- package may target.
+ 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.name
+ pkg.summary
A short, descriptive name for the package. In accordance with
- 2.1 above, pkg.name:fr would be the descriptive name in French.
+ 2.1.1 above, pkg.summary:fr would be the descriptive name in French.
Exact numerical version strings are discouraged in the
descriptive name.
@@ -64,68 +79,120 @@
pkg.detailed_url
One or more URLs to pages or sites with further information about
- the package.
+ 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.
+
+ variant.*
+ See facets.txt
2.3.2. Common tags
- pkg.debug
- This file is used when the package is intended to be installed in
- a debug configuration. For example, we expect to deliver a debug
- version of the kernel, in addition to the standard non-debug
- version.
+ 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
- XXX pkg.platform
+ info.keyword
+ A list of additional terms that should cause this package to be
+ returned by a search.
- XXX ISA (particularly need to know i386 on i86pc vs amd64 on i86pc)
+ 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.
- pkg.compatibility
- (for shipping non-bleeding edge .so.x.y.z copies, perhaps)
+ 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.
-2.4. Attributes common to all packages for an OS platform
+ 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".
- XXX Or "osol"?
-
2.4.1. OpenSolaris attributes
opensolaris.arc_url
One or more URLs associated with the ARC case or cases
associated with the component(s) delivered by the package.
- opensolaris.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.
+ 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.maintainer_url
- A URL associated with the entity providing the package.
-
- opensolaris.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.
+ opensolaris.zone
+ Obsolete - replaced by variant.opensolaris.zone.
- opensolaris.upstream_url
- A URL associated with the entity that creates the
- software delivered within the package.
+ variant.opensolaris.zone
+ See facets.txt
- opensolaris.source_url
- A URL to the source code bundle, if appropriate, for the package.
+2.4.1. OpenSolaris tags
- opensolaris.repository_url
- A URL to the source code repository, if appropriate, for the
- package.
+ opensolaris.zone
+ Obsolete - replaced by variant.opensolaris.zone.
- opensolaris.repository_changeset
- A changeset ID for the version of the source code contained in
- opensolaris.repository_url.
-
- opensolaris.gui.classification
- A list of labels classifying the package into the categories
- shared among pkg(5) graphical clients.
+ variant.opensolaris.zone
+ See facets.txt
2.5. Organization specific attributes
@@ -137,6 +204,54 @@
"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