doc/packaging.txt
author Danek Duvall <danek.duvall@oracle.com>
Thu, 07 Apr 2011 15:37:10 -0700
changeset 185 773dda89f186
parent 181 87e11e685b1f
child 255 52abf74b9323
permissions -rw-r--r--
7036473 dependency resolution should happen in one step for all component's packages
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     1
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     2
                Userland Consolidation Packaging Guidelines.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     3
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     4
	Each component that integrates into the Userland consolidation must have at
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     5
least one package manifest that describes the content to be delivered.  In some
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     6
cases components *may* deliver through multiple packages.  Canonical component
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     7
package manifests must be placed in the component's build directory.  They also
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     8
must be named *.p5m.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     9
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    10
    In order to understand what must go in the content of a package manifest,
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    11
it's useful to have an understanding of how a canonical manifest is transformed
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    12
into a final manifest used for package publication.  Manifest transformation
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    13
takes the following basic path:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    14
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    15
    canonical manifest
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    16
    (.../{component}/{component}.p5m)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    17
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    18
            v
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    19
    mogrified manifest
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    20
    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.mogrified)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    21
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    22
            v
181
87e11e685b1f 7003927 userland should postprocess packaged files
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 166
diff changeset
    23
    mangled manifest file contents
87e11e685b1f 7003927 userland should postprocess packaged files
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 166
diff changeset
    24
    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.mangled)
87e11e685b1f 7003927 userland should postprocess packaged files
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 166
diff changeset
    25
            |
87e11e685b1f 7003927 userland should postprocess packaged files
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 166
diff changeset
    26
            v
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    27
    dependencies generated
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    28
    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.depend)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    29
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    30
            v
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    31
    dependencies resolved
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
    32
    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.depend.res)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    33
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    34
            v
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    35
    manifest validation
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
    36
    (.../{component}/{build-dir}/.linted-$(MACH))
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    37
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    38
            v
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    39
    publication manifest
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    40
    (.../{component}/{build-dir}/manifest-$(MACH)-{component}.published)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    41
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    42
            v
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    43
    publication
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    44
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    45
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    46
Canonical Manifest
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    47
    The canonical manifest contains actions that can't otherwise be generated
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    48
    automatically from the data encapsulated in the component Makefile, gate
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    49
    transformations, build tree, and packaging tools.  This includes actions
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    50
    for license information, some path related attributes, legacy actions, 
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
    51
    non-discoverable dependencies, users, groups, drivers, and others.
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    52
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    53
    Actions that are associated with objects that are specific to a single
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    54
    architecture should be tagged with a 'variant.arch' attribute specific to
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    55
    the architecture that applied to the action.  Ex:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    56
        file path=/usr/lib/$(MACH64)/libx86onlybits.so variant.arch=i386
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    57
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    58
    Actions for editable files must include an appropriate 'preserve' attribute:
151
f9e42a3f7095 7030982 hgk is delivered 444, breaks 'hg view'
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 46
diff changeset
    59
        file path=etc/gnu/a2ps.cfg preserve=true mode=0644
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    60
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    61
    license actions should be placed in the canonical manifest.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    62
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    63
Mogrified Manifest
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    64
    The canonical manifest is combined with a set of the transforms
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    65
    in $(WS_TOP)/transforms, and a set of macros to more complete
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    66
    package manifest using pkgmogrify(1).  The transforms apply default
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    67
    attributes to the various actions in the canonical manifest(s).  More
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    68
    detail about the attributes can be found in the transform file themselves.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    69
    The macros applied at the time of mogrification are as follows:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    70
        $(MACH)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    71
        $(MACH32)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    72
        $(MACH64)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    73
        $(IPS_PKG_NAME)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    74
        $(PUBLISHER)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    75
        $(CONSOLIDATION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    76
        $(BUILD_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    77
        $(SOLARIS_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    78
        $(OS_VERSION)
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    79
        $(IPS_COMPONENT_VERSION)
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    80
        $(COMPONENT_VERSION)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    81
        $(COMPONENT_PROJECT_URL)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    82
        $(COMPONENT_ARCHIVE_URL)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    83
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    84
Dependencies Generated
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    85
    The mogrified manifest and the prototype install tree are passed through
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    86
    pkgdepend(1) to generate a set of dependencies for the package content.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    87
    These dependencies are only those that "pkgdepend generate" can determine
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
    88
    on its own.  Additional dependencies that cannot be automatically
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    89
    determined by pkgdepend(1) should be placed in the canonical manifest.
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    90
    Statically defined dependencies should be described in a canonical manifest
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    91
    in an unresolved form (ie. the form generated by "pkgdepend generate").
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    92
    Ex:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    93
	    depend fmri=__TBD pkg.debug.depend.file=etc/passwd \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    94
		        pkg.debug.reason=usr/bin/vipw type=require
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    95
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    96
        depend fmri=__TBD pkg.debug.depend.file=sh \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    97
                pkg.debug.depend.path=usr/bin \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    98
                pkg.debug.depend.reason=usr/bin/psmandup \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    99
                pkg.debug.depend.type=script type=require
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   100
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   101
    This will allow the next step to resolve all dependencies to their proper
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   102
    package(s).
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   103
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   104
Dependencies Resolved
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   105
    The manifest with unresolved dependencies is passed through pkgdepend(1)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   106
    again to resolve dependencies against the package repositories.  The
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   107
    result is a manifest that is suitable for publication.  All these
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   108
    manifests are processed together in a single step, which is more
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   109
    efficient than resolving dependencies in each manifest separately.
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   110
    While each manifest ends up with a .depend.res copy in the build
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   111
    directory, the umbrella dependency resolution target is
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   112
    {build-dir}/.resolved-$(MACH).
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   113
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   114
Manifest Validation
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   115
    The resolved manifest(s) and prototype install tree are passed through
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   116
    a set of validations.  This includes running pkglint(1), comparing the
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   117
    manifest content to the prototype install tree, and validation of the file
185
773dda89f186 7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents: 181
diff changeset
   118
    content of the prototype install tree.  Any anomalies are reported.
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   119
    Content validation is performed by extension to pkglint(1) in
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   120
    $(WS_TOP)/tools/python/userland-lint
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   121
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   122
Publication.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   123
    Once manifest validation has occurred, the package(s) is/are finally
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   124
    published to the workspace package repository.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   125
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   126
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   127
# vi:set fdm=marker expandtab ts=4: