|
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.
|
|
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 include a static list of these packages in
|
your component Makefile REQUIRED_PACKAGES macro. You can automatically
|
add REQURIED_PACKAGES settings for the packages used in dependency
|
resolution by running "gmake REQUIRED_PACKAGES". Once you have done so,
|
you should manually verify the Makefile additions. Having extra
|
packages in there is safe.
|
|
This list is kept as the REQUIRED_PACKAGES list in your component
|
Makefile, which you must append to (as shared-rules introduce some
|
packages there themselves for your benefit).
|
|
To test, run "gmake clean" and re-publish.
|
|
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 lists 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
|
|
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:
|
