--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/packaging.txt Tue Nov 09 10:33:32 2010 -0600
@@ -0,0 +1,127 @@
+
+ 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: