Producing and Maintaining Packages

Overview

Since both Sun personnel and customers interact with packages directly, the structure and content of package names can have a large impact on the user experience. When the product or subsystem to which a package belongs and the type of content or role of the content contained in a package is relatively obvious based on the package name, users need not inspect the content of a package or consult the documentation.

Each pkg(5) package is named by an FMRI using the "pkg:" scheme:

              pkg://authority/pkg_name@version

Generally the authority is a domain name identifying the publisher from which the package can be retrieved.

The pkg_name can be split into a category, subcategories, and a basename.

The version follows the pkg_name, separated by an '@'. It consists of four sequences of numbers, separated by punctuation. The elements in the first three sequences are separated by dots, and the sequences are arbitrarily long. Refer to the Versioning section for more details.

This section primarily focuses on choosing a reasonable basename for the pkg_name. The pkg_name categories and subcategories is an evolving area of the pkg(5) project which will only be lightly touched on here.

Best Practices

Details

1. Syntax

The package basename should use the following syntax:

• Use lower case.
• Separate words with '-'.
• Do not use spaces or the '@' symbol.

2. Structure

The package basename should conform to a standard structure:

        <product identifier><version string>-<component-identifier>

For example:

• glassfishv3-ejb
• glassfishv3-web
• glassfishv3-common
• javadb
• jruby
• glassfish2-locale

The product identifier should be used as part of the basename when the product is delivered as a set of discrete pkg components. For example glassfish-ejb and glassfish-web. This creates a product specific namespace allowing for common component identifiers to be used (e.g. -doc, -utils, -config, etc).

The version string as part of the pkg_name is optional. It is necessary to include when there is a need for more than one instance of the package to exist in a single install image. For example the Python packages could be named python2.4 and python2.5 which would allow both versions of python to be installed into the same install image. This is consistent with the Python community where minor releases of Python generally install into different directories.

The component identifier should be used to distinguish product components.

Standard component identifiers should be used when practical. The following types of subcomponents should use the following defined component identifiers:

Note:

• Need to address libraries. Should we use the OS-oriented approach of lib<component ID>, <component ID>-libs, other?

3. Readability

Package names should be concise, human readable and represent the contents of the package. An English-speaking customer or support personnel should readily be able to identify the contents of the package based on its name.

4. Name Stability

Use package names that are expected to be stable over time. Avoid marketing names unless the name is well-known and unlikely to change over the life of the product.

5. Consistent Names Across Formats

When the package is available in multiple formats (pkg(5), RPM, SVR4) consider using consistent names. When migrating from a SVR4 package it is not necessary to carry forward the SUNW prefix to the pkg(5) package name.

6. Reserved Names

The following names are reserved. These may be used as top-level IPS categories:

• site
• vendor
• cluster
• feature
• group
• metacluster
• service

Some or all of these reservations may be eliminated or reduced as the pkg(5) namespace and categorization semantics are finalized.