Home | History | Annotate | Download | only in doc
      1 
      2 PSARC/2008/190
      3 pkg(5): image packaging system
      4 
      5 TAGS AND ATTRIBUTES
      6 
      7 1.  Definitions
      8 
      9     Both packages and actions within a package can carry metadata, which
     10     we informally refer to as attributes and tags.
     11 
     12     Attributes:  settings that apply to an entire package.  Introduction
     13     of an attribute that causes different deliveries by the client could
     14     cause a conflict with the versioning algebra, so we attempt to avoid
     15     them.
     16 
     17     Tags are the settings that affect individual files within a package.
     18     Tags may eventually have values, depending on how many tags are
     19     required to handle the SPARC-based platform binaries.
     20 
     21 2.  Attribute and tag syntax and namespace
     22 
     23 2.1.  Syntax
     24 
     25     The syntax for attributes and tags is similar to that used for
     26     pkg(5) and smf(5) FMRIs.
     27 
     28     [org_prefix,][name][:locale]
     29 
     30     The organizational prefix is a forward-ordered or reverse-ordered
     31     domain name, followed by a common.  The name field is a  
     32     The default locale, if the locale field is omitted is "C", a 7-bit
     33     ASCII locale.
     34 
     35     Each of these fields is [A-Za-z][A-Za-z0-9_-.]*.
     36 
     37 2.2.  Unprefixed attributes and tags.
     38 
     39     All unprefixed attributes and tags are reserved for use by the
     40     framework.
     41 
     42     Generally, unprefixed tags are introduced in the definition of an
     43     action.
     44 
     45 2.3.  Attributes and tags common to all packages
     46 
     47     The "pkg" attribute is to be used for attributes common to all
     48     packages, regardless of which particular OS platforms that a specific
     49     package may target.
     50 
     51 2.3.1.  Common attributes
     52 
     53     pkg.name
     54        A short, descriptive name for the package.  In accordance with
     55        2.1 above, pkg.name:fr would be the descriptive name in French.
     56        Exact numerical version strings are discouraged in the
     57        descriptive name.
     58 
     59        Example:  "Apache HTTPD Web Server 2.x"
     60 
     61     pkg.description
     62        A descriptive paragraph for the package.  Exact numerical version
     63        strings can be embedded in the paragraph.
     64 
     65     pkg.detailed_url
     66        One or more URLs to pages or sites with further information about
     67        the package.
     68 
     69 2.3.2.  Common tags
     70 
     71     pkg.debug
     72        This file is used when the package is intended to be installed in
     73        a debug configuration.  For example, we expect to deliver a debug
     74        version of the kernel, in addition to the standard non-debug
     75        version.
     76 
     77     XXX pkg.platform
     78 
     79     XXX ISA (particularly need to know i386 on i86pc vs amd64 on i86pc)
     80 
     81     pkg.compatibility
     82 	(for shipping non-bleeding edge .so.x.y.z copies, perhaps)
     83 
     84 2.4.  Attributes common to all packages for an OS platform
     85 
     86     Each OS platform is expected to define a string representing that
     87     platform.  For example, the OpenSolaris platform is represented by
     88     the string "opensolaris".
     89 
     90     XXX Or "osol"?
     91 
     92 2.4.1.  OpenSolaris attributes
     93 
     94     opensolaris.arc_url
     95         One or more URLs associated with the ARC case or cases
     96 	associated with the component(s) delivered by the package.
     97 
     98     opensolaris.maintainer
     99         A human readable string describing the entity providing the
    100 	package.  For an individual, this string is expected to be their
    101 	name, or name and email.
    102 
    103     opensolaris.maintainer_url
    104         A URL associated with the entity providing the package.
    105 
    106     opensolaris.upstream
    107 	A human readable string describing the entity that creates the
    108 	software.  For an individual, this string is expected to be
    109 	their name, or name and email.
    110 
    111     opensolaris.upstream_url
    112         A URL associated with the entity that creates the 
    113 	software delivered within the package.
    114 
    115     opensolaris.source_url
    116         A URL to the source code bundle, if appropriate, for the package.
    117 
    118     opensolaris.repository_url
    119         A URL to the source code repository, if appropriate, for the
    120 	package.
    121 
    122     opensolaris.repository_changeset
    123         A changeset ID for the version of the source code contained in
    124 	opensolaris.repository_url.
    125 
    126     opensolaris.gui.classification
    127         A list of labels classifying the package into the categories
    128 	shared among pkg(5) graphical clients.
    129 
    130 2.5.  Organization specific attributes
    131 
    132     Organizations wishing to provide a package with additional metadata
    133     or to amend an existing package's metadata (in a repository that
    134     they have control over) must use an organization-specific prefix.
    135     For example, a service organization might introduce
    136     "service.example.com,support_level" or
    137     "com.example.service,support_level" to describe a level of support
    138     for a package and its contents.
    139 
    140 3.3.  Attributes best avoided
    141 
    142 built-on release
    143 
    144     One problem we may run into is packages that have been built on a
    145     release newer than that on the image.  These packages should be
    146     evaluated as unsuitable for the image, and not offered in the graph.
    147     There are a few ways to handle this case:
    148 
    149     1.  Separate repository.  All packages offered by a repository were
    150 	built on a known system configuration.  This change requires
    151 	negotiation between client and server for a built-on match
    152 	condition.  It also means that multiple repositories are needed
    153 	for a long lifecycle distribution.
    154 
    155     2.  Attributes.  Each package comes with a built-on attribute.  This
    156 	means that clients move from one built-on release to another
    157 	triggered by conditions set by the base package on the client.
    158 	Another drawback is that it becomes impossible to request a
    159 	specific package by an FMRI, without additional knowledge.
    160 
    161     3.  Additional version specifier.  We could extend
    162 	release,branch:timestamp to release,built,branch:timestamp--or
    163 	fold the built and branch version together.  Since the built
    164 	portion must reserve major.minor.micro, that means we move to a
    165 	package FMRI that looks like
    166 
    167 	coreutils (a] 6.7,5.11.0.1:timestamp
    168 
    169 	This choice looks awkward.  We could instead treat the built
    170 	portion as having a default value on a particular client.  Then
    171 	the common specifier would be
    172 
    173 	name@release[,build]-branch:timestamp
    174 
    175         build would be the highest available valid release for the
    176 	image.
    177 
    178     The meaning of the built-on version could be controversial.  A
    179     simple approach would be to base it on base/minimal's release,
    180     rather than uname(1) output.
    181 
    182 
    183 
    184