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-$(ARCH)-{component}.mogrified)

            |

            v

    dependencies generated

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

            |

            v

    dependencies resolved

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

            |

            v

    manifest validation

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

            |

            v

    publication manifest

    (.../{component}/{build-dir}/manifest-$(ARCH)-{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, user, group, driver, 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 that are associated with objects that are architecture dependent

    shoule be tagged with a 'variant.arch' attribute as follows:

        file path=/usr/bin/ls variant.arch=$(ARCH)

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

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

    license actions should be placed in the canonical manifest.

    Actions that can take advantage of macros supplied at pkgmogrify time

    should do so.  Ex:

        file path=/usr/bin/$(MACH64)/ztest variant.arch=$(ARCH)

Mogrified Manifest

    The canonical manifest is combined with a template manifest header at

    $(WS_TOP)/transforms/manifest-metadata-template, a set of the transforms

    in $(WS_TOP)/transforms, and a set of macros are combined 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:

        $(ARCH)

        $(MACH)

        $(MACH32)

        $(MACH64)

        $(IPS_PKG_NAME)

        $(PUBLISHER)

        $(CONSOLIDATION)

        $(BUILD_VERSION)

        $(SOLARIS_VERSION)

        $(OS_VERSION)

        $(IPS_COMPONENTVERSION)

        $(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 it's own.  Additional dependencies that can not be automatically

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

    Staticly 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 unresovled dependencies is passed through pkgdepend(1)

    again to resolve dependencies against the package repositories.  The

    result is a manifest that is suitable for publication.

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 anomolies are reported.

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

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

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: