doc/packaging.txt

   1
   2                 Userland Consolidation Packaging Guidelines.
   3
   4         Each component that integrates into the Userland consolidation must have at
   5 least one package manifest that describes the content to be delivered.  In some
   6 cases components *may* deliver through multiple packages.  Canonical component
   7 package manifests must be placed in the component's build directory.  They also
   8 must be named *.p5m.
   9
  10     In order to understand what must go in the content of a package manifest,
  11 it's useful to have an understanding of how a canonical manifest is transformed
  12 into a final manifest used for package publication.  Manifest transformation
  13 takes the following basic path:
  14
  15     canonical manifest
  16     (.../{component}/{component}.p5m)
  17             |
  18             v
  19     mogrified manifest
  20     (.../{component}/{build-dir}/manifest-$(MACH)-{component}.mogrified)
  21             |
  22             v
  23     mangled manifest file contents
  24     (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.mangled)
  25             |
  26             v
  27     dependencies generated
  28     (.../{component}/{build-dir}/manifest-$(MACH)-{component}.depend)
  29             |
  30             v
  31     dependencies resolved
  32     (.../{component}/{build-dir}/manifest-$(MACH)-{component}.depend.res)
  33             |
  34             v
  35     manifest validation
  36     (.../{component}/{build-dir}/.linted-$(MACH))
  37             |
  38             v
  39     publication manifest
  40     (.../{component}/{build-dir}/manifest-$(MACH)-{component}.published)
  41             |
  42             v
  43     publication
  44
  45
  46 Canonical Manifest
  47     The canonical manifest contains actions that can't otherwise be generated
  48     automatically from the data encapsulated in the component Makefile, gate
  49     transformations, build tree, and packaging tools.  This includes actions
  50     for license information, some path related attributes, legacy actions,
  51     non-discoverable dependencies, users, groups, drivers, and others.
  52
  53     Actions that are associated with objects that are specific to a single
  54     architecture should be tagged with a 'variant.arch' attribute specific to
  55     the architecture that applied to the action.  Ex:
  56         file path=/usr/lib/$(MACH64)/libx86onlybits.so variant.arch=i386
  57
  58     Actions for editable files must include an appropriate 'preserve' attribute:
  59         file path=etc/gnu/a2ps.cfg preserve=true mode=0644
  60
  61     license actions should be placed in the canonical manifest.
  62
  63 Mogrified Manifest
  64     The canonical manifest is combined with a set of the transforms
  65     in $(WS_TOP)/transforms, and a set of macros to more complete
  66     package manifest using pkgmogrify(1).  The transforms apply default
  67     attributes to the various actions in the canonical manifest(s).  More
  68     detail about the attributes can be found in the transform file themselves.
  69     The macros applied at the time of mogrification are as follows:
  70         $(MACH)
  71         $(MACH32)
  72         $(MACH64)
  73         $(PUBLISHER)
  74         $(CONSOLIDATION)
  75         $(BUILD_VERSION)
  76         $(SOLARIS_VERSION)
  77         $(OS_VERSION)
  78         $(IPS_COMPONENT_VERSION)
  79         $(COMPONENT_VERSION)
  80         $(COMPONENT_PROJECT_URL)
  81         $(COMPONENT_ARCHIVE_URL)
  82
  83 Dependencies Generated
  84     The mogrified manifest and the prototype install tree are passed through
  85     pkgdepend(1) to generate a set of dependencies for the package content.
  86     These dependencies are only those that "pkgdepend generate" can determine
  87     on its own.  Additional dependencies that cannot be automatically
  88     determined by pkgdepend(1) should be placed in the canonical manifest.
  89     Statically defined dependencies should be described in a canonical manifest
  90     in an unresolved form (ie. the form generated by "pkgdepend generate").
  91     Ex:
  92             depend fmri=__TBD pkg.debug.depend.file=etc/passwd \
  93                         pkg.debug.reason=usr/bin/vipw type=require
  94
  95         depend fmri=__TBD pkg.debug.depend.file=sh \
  96                 pkg.debug.depend.path=usr/bin \
  97                 pkg.debug.depend.reason=usr/bin/psmandup \
  98                 pkg.debug.depend.type=script type=require
  99
 100     This will allow the next step to resolve all dependencies to their proper
 101     package(s).
 102
 103 Dependencies Resolved
 104     The manifest with unresolved dependencies is passed through pkgdepend(1)
 105     again to resolve dependencies against the package repositories.  The result
 106     is a manifest that is suitable for publication.  All these manifests are
 107     processed together in a single step, which is more efficient than resolving
 108     dependencies in each manifest separately.  While each manifest ends up with
 109     a .depend.res copy in the build directory, the umbrella dependency
 110     resolution target is {build-dir}/.resolved-$(MACH).
 111
 112     The resolution step is also set up to use the -e flag to pkgdepend resolve,
 113     which limits the set of packages it looks at to resolve the dependencies it
 114     generated in the previous step.  This makes the resolution step a great deal
 115     faster, but requires that you keep a static list of these packages checked
 116     into the workspace, and update it when packages are added to it.  Having
 117     extra packages in there is safe.
 118
 119     In order to create this list, build and publish your component (or at least
 120     through the resolution stage) without a file "resolve.deps" in the component
 121     directory, and run "gmake sample-resolve.deps".  If the file is empty (that
 122     is, no computed dependencies were found), a warning will be emitted and the
 123     file will be removed, as pkgdepend currently errors out in that case.
 124
 125     To test, run "gmake clean" and re-publish.
 126
 127     Don't forget to "hg add resolve.deps"!
 128
 129     Note that there is a possibility the list of dependencies will be different
 130     on different architectures, so you should run this on both sparc and x86,
 131     and combine the two lists.  Please keep the files sorted.
 132
 133 Manifest Validation
 134     The resolved manifest(s) and prototype install tree are passed through
 135     a set of validations.  This includes running pkglint(1), comparing the
 136     manifest content to the prototype install tree, and validation of the file
 137     content of the prototype install tree.  Any anomalies are reported.
 138     Content validation is performed by extension to pkglint(1) in
 139     $(WS_TOP)/tools/python/userland-lint
 140
 141 Publication.
 142     Once manifest validation has occurred, the package(s) is/are finally
 143     published to the workspace package repository.
 144
 145
 146 # vi:set fdm=marker expandtab ts=4: