doc/packaging.txt
author Norm Jacobs <Norm.Jacobs@Oracle.COM>
Tue, 08 Feb 2011 10:54:06 -0800
changeset 76 a084497ff237
parent 46 d4d60962c33f
child 151 f9e42a3f7095
permissions -rw-r--r--
7016379 migrate elinks to userland (fix pkglint) 7017379 package metadata not required for building should be kept in the package manifest (fix dependency generation)
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
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    20
    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.mogrified)
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
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    23
    dependencies generated
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    24
    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.depend)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    25
            |
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    26
            v
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    27
    dependencies resolved
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    28
    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.resolved)
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
    manifest validation
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    32
    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.linted)
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
    publication manifest
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    36
    (.../{component}/{build-dir}/manifest-$(ARCH)-{component}.published)
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
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    40
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
Canonical Manifest
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    43
    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
    44
    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
    45
    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
    46
    for license information, some path related attributes, legacy actions, 
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    47
    non-discoverable dependencies, user, group, driver, and others.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    48
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    49
    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
    50
    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
    51
    the architecture that applied to the action.  Ex:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    52
        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
    53
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    54
    Actions that are associated with objects that are architecture dependent
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    55
    shoule be tagged with a 'variant.arch' attribute as follows:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    56
        file path=/usr/bin/ls variant.arch=$(ARCH)
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:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    59
        file path=etc/gnu/a2ps.cfg preserve=true
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
    Actions that can take advantage of macros supplied at pkgmogrify time
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    64
    should do so.  Ex:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    65
        file path=/usr/bin/$(MACH64)/ztest variant.arch=$(ARCH)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    66
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    67
Mogrified Manifest
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    68
    The canonical manifest is combined with a template manifest header at
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    69
    $(WS_TOP)/transforms/manifest-metadata-template, a set of the transforms
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    70
    in $(WS_TOP)/transforms, and a set of macros are combined to more complete
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    71
    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
    72
    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
    73
    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
    74
    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
    75
        $(ARCH)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    76
        $(MACH)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    77
        $(MACH32)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    78
        $(MACH64)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    79
        $(IPS_PKG_NAME)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    80
        $(PUBLISHER)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    81
        $(CONSOLIDATION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    82
        $(BUILD_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    83
        $(SOLARIS_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    84
        $(OS_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    85
        $(IPS_COMPONENTVERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    86
        $(COMPONENT_PROJECT_URL)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    87
        $(COMPONENT_ARCHIVE_URL)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    88
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    89
Dependencies Generated
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    90
    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
    91
    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
    92
    These dependencies are only those that "pkgdepend generate" can determine
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    93
    on it's own.  Additional dependencies that can not be automatically
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    94
    determined by pkgdepend(1) should be placed in the canonical manifest.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    95
    Staticly defined dependencies should be described in a canonical manifest
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    96
    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
    97
    Ex:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    98
	    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
    99
		        pkg.debug.reason=usr/bin/vipw 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
        depend fmri=__TBD pkg.debug.depend.file=sh \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   102
                pkg.debug.depend.path=usr/bin \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   103
                pkg.debug.depend.reason=usr/bin/psmandup \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   104
                pkg.debug.depend.type=script type=require
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   105
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   106
    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
   107
    package(s).
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   108
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   109
Dependencies Resolved
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   110
    The manifest with unresovled dependencies is passed through pkgdepend(1)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   111
    again to resolve dependencies against the package repositories.  The
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   112
    result is a manifest that is suitable for publication.
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
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   118
    content of the prototype install tree.  Any anomolies are reported.
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: