Userland Consolidation Packaging Guidelines.

	Each component that integrates into the Userland consolidation must have at

least one package manifest that describes the content to be delivered.  In some

cases components *may* deliver through multiple packages.  Canonical component

package manifests must be placed in the component's build directory.  They also

must be named *.p5m.

    In order to understand what must go in the content of a package manifest,

it's useful to have an understanding of how a canonical manifest is transformed

into a final manifest used for package publication.  Manifest transformation

takes the following basic path:

    canonical manifest

    (.../{component}/{component}.p5m)

            |

            v

    mogrified manifest

    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.mogrified)

            |

            v

    mangled manifest file contents

    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.mangled)

            |

            v

    dependencies generated

    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.depend)

            |

            v

    dependencies resolved

    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.depend.res)

            |

            v

    manifest validation

    (.../{component}/{build-dir}/.linted-$(MACH))

            |

            v

    publication manifest

    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.published)

            |

            v

    publication

Canonical Manifest

    The canonical manifest contains actions that can't otherwise be generated

    automatically from the data encapsulated in the component Makefile, gate

    transformations, build tree, and packaging tools.  This includes actions

    for license information, some path related attributes, legacy actions, 

    non-discoverable dependencies, users, groups, drivers, and others.

    Actions that are associated with objects that are specific to a single

    architecture should be tagged with a 'variant.arch' attribute specific to

    the architecture that applied to the action.  Ex:

        file path=/usr/lib/$(MACH64)/libx86onlybits.so variant.arch=i386

    Actions for editable files must include an appropriate 'preserve' attribute:

        file path=etc/gnu/a2ps.cfg preserve=true mode=0644

    license actions should be placed in the canonical manifest, as should a

    handful of other special actions noted in the "Manually generated actions"

    section just below.

Manually generated actions

    * com.oracle.info.description is a terse description of what utilities,

      libraries and/or services the package provides.  This should be short,

      specific, concise text, identifying the technology covered by the

      associated license(s).  It should fit naturally in the sentence "This

      package may contain XXX."  For example, "XXX" might be "the tar command"

      or "bzip2 compression software."  When appropriate, this may begin with

      "portions of" or another, more specific qualifying clause.

    * com.oracle.info.tpno is the Oracle 3rd party license number.

    * info.classification is "org.opensolaris.category.2008:FOO" where FOO

      varies according to the sorts of utilities, libraries and/or services

      that the package provides.  Existing packages contain most useful

      values; check them out to find the closest match.  For a complete

      list of allowed values, refer to the Solaris system file

      /usr/share/lib/pkg/opensolaris.org.sections .

    * org.opensolaris.arc-caseid is typically "PSARC/YYYY/###" and multiple

      different values are allowed.

    * pkg.summary is a short synopsis of what the package provides.

Mogrified Manifest

    The canonical manifest is combined with a set of the transforms

    in $(WS_TOP)/transforms, and a set of macros to more complete

    package manifest using pkgmogrify(1).  The transforms apply default

    attributes to the various actions in the canonical manifest(s).  More

    detail about the attributes can be found in the transform file themselves.

    The macros applied at the time of mogrification are as follows:

        $(MACH)

        $(MACH32)

        $(MACH64)

        $(PUBLISHER)

        $(CONSOLIDATION)

        $(BUILD_VERSION)

        $(SOLARIS_VERSION)

        $(OS_VERSION)

        $(IPS_COMPONENT_VERSION)

        $(COMPONENT_VERSION)

        $(COMPONENT_PROJECT_URL)

        $(COMPONENT_ARCHIVE_URL)

Dependencies Generated

    The mogrified manifest and the prototype install tree are passed through

    pkgdepend(1) to generate a set of dependencies for the package content.

    These dependencies are only those that "pkgdepend generate" can determine

    on its own.  Additional dependencies that cannot be automatically

    determined by pkgdepend(1) should be placed in the canonical manifest.

    Statically defined dependencies should be described in a canonical manifest

    in an unresolved form (ie. the form generated by "pkgdepend generate").

    Ex:

	    depend fmri=__TBD pkg.debug.depend.file=etc/passwd \

		        pkg.debug.reason=usr/bin/vipw type=require

        depend fmri=__TBD pkg.debug.depend.file=sh \

                pkg.debug.depend.path=usr/bin \

                pkg.debug.depend.reason=usr/bin/psmandup \

                pkg.debug.depend.type=script type=require

    This will allow the next step to resolve all dependencies to their proper

    package(s).

Dependencies Resolved

    The manifest with unresolved dependencies is passed through pkgdepend(1)

    again to resolve dependencies against the package repositories.  The result

    is a manifest that is suitable for publication.  All these manifests are

    processed together in a single step, which is more efficient than resolving

    dependencies in each manifest separately.  While each manifest ends up with

    a .depend.res copy in the build directory, the umbrella dependency

    resolution target is {build-dir}/.resolved-$(MACH).

    The resolution step is also set up to use the -e flag to pkgdepend resolve,

    which limits the set of packages it looks at to resolve the dependencies it

    generated in the previous step.  This makes the resolution step a great deal

    faster, but requires that you keep a static list of these packages checked

    into the workspace, and update it when packages are added to it.  Having

    extra packages in there is safe.

    In order to create this list, build and publish your component (or at least

    through the resolution stage) without a file "resolve.deps" in the component

    directory, and run "gmake sample-resolve.deps".  If the file is empty (that

    is, no computed dependencies were found), a warning will be emitted and the

    file will be removed, as pkgdepend currently errors out in that case.  If a

    component has no dependencies that pkgdepend can discover and resolve, you

    can set EXTDEPFILES = $(NULLDEPFILE) in your component Makefile to get the

    performance benefits without providing a placeholder resolve.deps yourself.

    To test, run "gmake clean" and re-publish.

    Don't forget to "hg add resolve.deps"!

    Note that there is a possibility the list of dependencies will be different

    on different architectures, so you should run this on both sparc and x86,

    and combine the two lists.  Please keep the files sorted.

Manifest Validation

    The resolved manifest(s) and prototype install tree are passed through

    a set of validations.  This includes running pkglint(1), comparing the

    manifest content to the prototype install tree, and validation of the file

    content of the prototype install tree.  Any anomalies are reported.

    Content validation is performed by extension to pkglint(1) in

    $(WS_TOP)/tools/python/userland-lint

    Note that when integrating new packages, and one or more of them depends

    on or more of the others, then this may result:

        WARNING pkglint.action005.1      obsolete dependency check skipped:

            unable to find dependency (target pkg) for (source pkg)

    This means that the target package was not found in the reference repo,

    which was the source of the pkglint cache that was created when 'gmake

    setup' was run after the workspace was created; thus the warning is

    harmless and can be ignored in this circumstance.

Publication.

    Once manifest validation has occurred, the package(s) is/are finally

    published to the workspace package repository.

# vi:set fdm=marker expandtab ts=4: