ips/doc/pkg5_docs/pkgs-and-groups.txt

PSARC/2008/190
pkg(5): image packaging system

PACKAGES AND GROUPS

1.  Definitions

    To be consistent with the system, following the introduction of the
    fault management architecture, each package is named by an FMRI in
    the "pkg:" scheme.  That is, we have

    pkg://publisher/pkg_name@version

    The publisher is generally expected to be a forward or reverse
    domain name identifying the publisher from which a package can be
    retrieved.  Publishers which cannot be determined to be a domain
    name are legitimate, but optional functionality, like automatic
    server discovery for a particular publisher, may fail to work.
    In the examples that follow, we use "opensolaris.org" as a generic
    publisher.

    The pkg_name, like service names, can be split into a category,
    subcategories, and a basename.  This namespace might be populated
    with "manifest" and other metadata endpoints, as well as the SHA-1
    names of the package's included files.  (Although the direct access
    to properties of the svc FMRI scheme has been rarely used.)

    A "group package" is a package that depends upon (minimum versions
    of) other packages, as well as optionally delivering files or other
    actions.  An "incorporation" is a group package that places forward
    constraints upon the versions of the packages it depends upon, which
    restricts the interval of valid package versions to one the author
    of the incorporation believes functional.

2.  Namespace

2.1.  Single namespace, separate publishers

    The primary design point of the package namespace is to allow
    multiple package producers to co-exist in a single namespace, so
    that images can switch between equivalent components from different
    producers.

2.2.  Domain-name-based escape

    At any point in the category hierarchy, a safe namespace can be
    created by using the forward or reverse domain name, either as a
    subcategory or as a comma-led prefix to a subcategory or package
    base name.  (This scheme is similar to FMRI namespace escapes in
    smf(5), although we are eliminating use of stock symbol prefixes.)

    For instance, when example.com wishes to publish the "whiskers"
    package without reference to a larger namespace convention it can
    use any of the following examples

    pkg://opensolaris.org/.../example.com/whiskers
    pkg://opensolaris.org/.../com.example/whiskers

    pkg://opensolaris.org/.../example.com,whiskers
    pkg://opensolaris.org/.../com.example,whiskers

    pkg://opensolaris.org/.../example.com,software/whiskers
    pkg://opensolaris.org/.../com.example,software/whiskers

    and so forth.

2.2.  Locally reserved namespace

    The top-level "site" category is reserved for use by the entity that
    administrates the server.  Neither the organizations producing the
    operating system nor those providing additional software components
    may use the site category.

    The top-level "vendor" category is reserved for use by organizations
    providing additional.  The leading subcategory must be a domain.
    That is, if example.com wishes to publish the "whiskers" package in
    the vendor category, it would use a package name like

    pkg://opensolaris.org/vendor/example.com/whiskers

2.3.  Additional reserved namespace

    The top-level "cluster", "feature", "group", "metacluster", and
    "service" categories are all reserved for future use.

    Inception note: some or all of these reservations may be eliminated
    or reduced when the single namespace convention reaches its final
    form.

2.4.  Single namespace conventions

2.4.1.  Discussion

    Packaging systems and distributions appear to have explicit
    categories, subcategories, and potentially larger groups; some
    distributions have explicit fields for these values, others use
    tagging or multi-valued fields, which allows them to classify
    certain packages multiply.  For the FMRI namespace case, the system
    is similar to a packaging system with multiple, single-valued,
    category fields.

    There appear to be two standard approaches to categorizing packages:

    1.  By what primary class of thing a package delivers.

    2.  By what area of functionality a package's contents address.

    In the first approach, we get strict top-level categories like
    "application", "driver", "library", and "system" or "kernel", as
    well as potentially overlapping categories like "utility" and
    "tool".  Use of the leading subcategory is limited, and generally
    given to the subsystem involved.  A relatively detailed worked
    example of the X11 subsystem under this scheme is given in

    http://mail.opensolaris.org/pipermail/pkg-discuss/2008-February/001838.html

    In the second, we would also see categories like these, but leading
    subcategory is much more likely to classify according to
    functionality, so that we would see "application/mail",
    "application/web", "application/compiler", and so forth.  Most
    network packaging systems appear to classify in this fashion.

    An appealing variation of the second form is to rotate all of the
    non-"application" packages under a "system" mega-category, such that
    all of the leaf packages (with the possible exception of device
    drivers) are exposed at the category level.  Table 1 shows some
    example transformations under this scheme.

    FROM			TO
    application/web/firefox	web/firefox
    application/compiler/gcc4	compiler/gcc4
    library/c			system/library/c 
    kernel/generic		system/kernel/generic

    Table 1:  Rotating non-application categories under system.