--- /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: