doc/packaging.txt
author Mike Sullivan <Mike.Sullivan@Oracle.COM>
Fri, 13 May 2016 17:33:30 -0700
changeset 5983 f10ab5ae99d7
parent 5571 bd6c9b9b753f
child 7829 2de4f4ace09c
permissions -rw-r--r--
Close of build 99.3.
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
1393
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    61
    license actions should be placed in the canonical manifest, as should a
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    62
    handful of other special actions noted in the "Manually generated actions"
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    63
    section just below.
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    64
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    65
Manually generated actions
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    66
    * com.oracle.info.description is a terse description of what utilities,
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    67
      libraries and/or services the package provides.  This should be short,
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    68
      specific, concise text, identifying the technology covered by the
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    69
      associated license(s).  It should fit naturally in the sentence "This
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    70
      package may contain XXX."  For example, "XXX" might be "the tar command"
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    71
      or "bzip2 compression software."  When appropriate, this may begin with
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    72
      "portions of" or another, more specific qualifying clause.
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    73
    * com.oracle.info.tpno is the Oracle 3rd party license number.
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    74
    * info.classification is "org.opensolaris.category.2008:FOO" where FOO
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    75
      varies according to the sorts of utilities, libraries and/or services
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    76
      that the package provides.  Existing packages contain most useful
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    77
      values; check them out to find the closest match.  For a complete
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    78
      list of allowed values, refer to the Solaris system file
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    79
      /usr/share/lib/pkg/opensolaris.org.sections .
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    80
    * org.opensolaris.arc-caseid is typically "PSARC/YYYY/###" and multiple
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    81
      different values are allowed.
300d3de848bb 16726438 manifest-metadata-template needs work
John Beck <John.Beck@Oracle.COM>
parents: 1235
diff changeset
    82
    * pkg.summary is a short synopsis of what the package provides.
2142
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    83
    * org.opensolaris.consolidation is the name of the consolidation delivering
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    84
      the package.  In Userland, this is $(CONSOLIDATION) (which expands to
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    85
      "Userland" during the build).  Manifests in the Userland gate can also
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    86
      decorate this package attribute with an 'incorporate={incorporation-name}'
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    87
      decoration to specify where the package should be incorporated at the end
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    88
      of the userland build.  A special value of 'none' will cause the package
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    89
      to be unincorporated and float freely from the rest of the rest of the
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    90
      packages.  Note that unincorporated packages don't automatically get
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    91
      updated with the rest of the system when 'pkg update' is run unless the
813e4817e573 18139749 userland-incorporator should allow generation of multiple incorporations
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents: 1907
diff changeset
    92
      unincorporated package(s) are specified on the command line.
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    93
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    94
Mogrified Manifest
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
    95
    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
    96
    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
    97
    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
    98
    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
    99
    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
   100
    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
   101
        $(MACH)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   102
        $(MACH32)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   103
        $(MACH64)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   104
        $(PUBLISHER)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   105
        $(CONSOLIDATION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   106
        $(BUILD_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   107
        $(SOLARIS_VERSION)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   108
        $(OS_VERSION)
166
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
   109
        $(IPS_COMPONENT_VERSION)
db8a55996482 6979538 /usr/share/gettext/po/Rules-quot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents: 151
diff changeset
   110
        $(COMPONENT_VERSION)
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   111
        $(COMPONENT_PROJECT_URL)
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   112
        $(COMPONENT_ARCHIVE_URL)
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
Dependencies Generated
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   115
    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
   116
    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
   117
    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
   118
    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
   119
    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
   120
    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
   121
    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
   122
    Ex:
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   123
	    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
   124
		        pkg.debug.reason=usr/bin/vipw type=require
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
        depend fmri=__TBD pkg.debug.depend.file=sh \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   127
                pkg.debug.depend.path=usr/bin \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   128
                pkg.debug.depend.reason=usr/bin/psmandup \
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   129
                pkg.debug.depend.type=script type=require
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   130
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   131
    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
   132
    package(s).
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   133
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   134
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
   135
    The manifest with unresolved dependencies is passed through pkgdepend(1)
1235
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   136
    again to resolve dependencies against the package repositories.  The result
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   137
    is a manifest that is suitable for publication.  All these manifests are
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   138
    processed together in a single step, which is more efficient than resolving
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   139
    dependencies in each manifest separately.  While each manifest ends up with
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   140
    a .depend.res copy in the build directory, the umbrella dependency
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   141
    resolution target is {build-dir}/.resolved-$(MACH).
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   142
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   143
    The resolution step is also set up to use the -e flag to pkgdepend resolve,
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   144
    which limits the set of packages it looks at to resolve the dependencies it
413599fe2d31 15960689 pkgdepend resolve takes longer than it might
Danek Duvall <danek.duvall@oracle.com>
parents: 255
diff changeset
   145
    generated in the previous step.  This makes the resolution step a great deal
3817
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2143
diff changeset
   146
    faster, but requires that you include a static list of these packages in
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2143
diff changeset
   147
    your component Makefile REQUIRED_PACKAGES macro.  You can automatically
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2143
diff changeset
   148
    add REQURIED_PACKAGES settings for the packages used in dependency
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2143
diff changeset
   149
    resolution by running "gmake REQUIRED_PACKAGES".  Once you have done so,
30b42c38bbc4 15786608 SUNBT7162754 create new meta package developer/opensolaris/userland
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2143
diff changeset
   150
    you should manually verify the Makefile additions.
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   151
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   152
Manifest Validation
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   153
    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
   154
    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
   155
    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
   156
    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
   157
    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
   158
    $(WS_TOP)/tools/python/userland-lint
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   159
1907
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   160
    Note that when integrating new packages, and one or more of them depends
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   161
    on or more of the others, then this may result:
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   162
        WARNING pkglint.action005.1      obsolete dependency check skipped:
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   163
            unable to find dependency (target pkg) for (source pkg)
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   164
    This means that the target package was not found in the reference repo,
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   165
    which was the source of the pkglint cache that was created when 'gmake
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   166
    setup' was run after the workspace was created; thus the warning is
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   167
    harmless and can be ignored in this circumstance.
446472de62e9 PSARC 2014/151 Python 3.4
John Beck <John.Beck@Oracle.COM>
parents: 1428
diff changeset
   168
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   169
Publication.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   170
    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
   171
    published to the workspace package repository.
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   172
5107
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   173
Facets
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   174
    Many facets are automatically set by default via transforms 
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   175
    in $(WS_TOPS)/transforms, such as facet.doc.*, facet.devel, etc.
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   176
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   177
    optional.test
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   178
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   179
    In most cases, we do not include files in the package manifest
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   180
    if they are used exclusively for testing that component.
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   181
    If we do include component test files, they should be tagged
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   182
    with the facet optional.test=true.  There is no default transform
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   183
    for such files, since they do not follow a naming pattern.
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   184
    See the components python/python-3{4,5}, mailman, or 
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   185
    python/astroid for examples.
b5545e1bba48 22220352 enable system-test target for pylint
April Chin <april.chin@oracle.com>
parents: 5072
diff changeset
   186
2143
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   187
Renames
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   188
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   189
    Renames in IPS are tricky.  We will use a case study to illustrate how
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   190
    this needs to work.
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   191
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   192
    All of the library/python-2/FOO modules that we had in Userland at the
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   193
    time were renamed to library/python/FOO in s12_41.  This involved:
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   194
2143
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   195
    * changing the FMRI to drop the "-2"
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   196
2143
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   197
    * adding an optional dependency on the old name at the version and build
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   198
      in which the rename occurred; this forces the rename.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   199
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   200
    * depend type=optional fmri=library/python-2/FOO-$(PYV)@VERSION,BUILD
2143
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   201
      where FOO is the component name (e.g., "alembic", "amqp", etc.),
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   202
      "$(PYV)" is that literal string, VERSION was the expanded value of
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   203
      COMPONENT_VERSION from each component's Makefile (e.g., "0.6.0" for
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   204
      alembic, "1.0.12" for amqp, etc.), and BUILD was set to
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   205
      "5.12-5.12.0.0.0.41.0".  Note that BUILD needs to be set to the value of
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   206
      the build you are integrating into.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   207
4813
5e86eaf216ff 21699326 Userland package history simplification
John Beck <John.Beck@Oracle.COM>
parents: 3817
diff changeset
   208
    * creation of the file "history" (or adding to it if it already exists)
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   209
      in each affected component directory (see NOTE 2 below); one or more
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   210
      new lines should be added (in the case of python or other language
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   211
      component, one for the versionless package plus one for each versioned
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   212
      instance of the package; for an example of a less complicated
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   213
      component that does not have a 'versionless' package like python, see
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   214
      components/subversion)
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   215
      
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   216
      with syntax:
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   217
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   218
	  renames:      OLD-NAME@VERSION,BUILD NEW-NAME
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   219
	  obsoletions:  OLD-NAME@VERSION,BUILD
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   220
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   221
      where e.g. OLD-NAME was library/python-2/FOO, NEW-NAME was
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   222
      library/python/FOO, VERSION and BUILD are all as above.  Most Python
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   223
      modules, including the two mentioned above, have such files which can
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   224
      serve as examples.
2143
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   225
5571
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   226
      By default, packages created from the history files will be part of
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   227
      the userland-incorporation.  If a package needs to be included in a
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   228
      different incorporation, then incorporate=INCORPORATION may be
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   229
      placed on the end of either the rename or obsoletion line.
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   230
      Examples with incorporate=consolidation/desktop/gnome-incorporation
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   231
      may be found in components/meta-packages/history/history.
bd6c9b9b753f 22839226 Migrate Desktop meta-packages to Userland gate
Alan Coopersmith <Alan.Coopersmith@Oracle.COM>
parents: 5454
diff changeset
   232
2143
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   233
    So far, not too bad.  This gets slightly more complicated when back-
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   234
    porting in that BUILD needs to be set to the back-port build (e.g.,
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   235
    "5.11-0.175.3.0.0.8.0", as was the case for tkinter-27) rather than
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   236
    the S12 build.
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   237
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   238
    If the component is at the same version as when the rename was done, then
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   239
    that's it.  But if the component has since been upgraded, then care must
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   240
    be taken to set VERSION in both places above to the value that it was in
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   241
    s12_41 when the rename was originally done.  In particular, the latest
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   242
    version of a package name in an earlier release branch must not be greater
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   243
    than the latest version of that same package name in the newer release
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   244
    branch.  Otherwise the audits from Release Engineering will complain and
82f79e5e7f43 19782852 document how to do IPS renames in Userland
John Beck <John.Beck@Oracle.COM>
parents: 2142
diff changeset
   245
    our gatekeeper will make you do a follow-up push to fix this.
46
d4d60962c33f generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
   246
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   247
    In addition, during the transition period before all CBE machines have
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   248
    the new package, the REQUIRED_PACKAGES in the Makefiles of any components
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   249
    that depend on your package must include both your old and new package
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   250
    names.  This is because those names are actually the limit set, to speed
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   251
    up processing, rather than a true required list.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   252
    
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   253
    If you tell pkgdepend it can look for the the component dependencies in
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   254
    either the old package name or the new name, then it will find them and
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   255
    be happy.  If only one of your package names is listed and it doesn't
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   256
    happen to be the one installed on the build system, the dependencies will
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   257
    be unsatisifed and the build will break.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   258
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   259
    Until the new package name is available for installation, "gmake
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   260
    system-check" will fail because it attempts to install all the packages
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   261
    listed in REQUIRED_PACKAGES.  This can be ignored, but should be noted
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   262
    in a flag-day so that people are aware they can ignore it.  Once the new
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   263
    package name can be installed (even simply after running "gmake publish"
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   264
    for the missing component and having your workspace publisher enabled on
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   265
    the test system), this is no longer an issue, so there is no urgency in
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   266
    removing the old name from the list.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   267
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   268
    NOTE:  The package version for the old name must be in the format shown
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   269
    on in pkg contents -m output (before the colon) and not in the format
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   270
    seen in the output of pkg list or pkg info, e.g.:
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   271
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   272
    So, if contents -m library/python-2/subversion showed this:
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   273
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   274
    set name=pkg.fmri value=pkg://solaris/library/python-2/[email protected],5.12-5.12.0.0.0.41.0:20140130T085214Z
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   275
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   276
    they used this:
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   277
        library/python-2/[email protected],5.12-5.12.0.0.0.41.0
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   278
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   279
    not this:
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   280
        library/python-2/[email protected]
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   281
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   282
    NOTE 2: The generic package renaming directions in Solaris documentation,
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   283
    which call for preserving a 'rename' package (containing only metadata and
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   284
    dependencies on the new package names) is not applicable when using the
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   285
    Userland history file method.  The 'rename' package is created by
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   286
    the Userland consolidation build, using the data in the history file.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   287
    So simply rename and edit the manifest (p5m file) to the new name instead
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   288
    of creating an additional file.
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   289
5072
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   290
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   291
=============================
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   292
Component EOF (End Of Feature) 
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   293
=============================
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   294
This is a brief description on how to remove a component from Userland for
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   295
an EOF.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   296
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   297
Deleting the Component
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   298
----------------------
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   299
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   300
At some point, you will need to do a "hg remove" of the component's directory.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   301
This can be done before or after you make the necessary entry in the
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   302
components/meta-packages/history/history file.  In this file you will see plenty
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   303
of examples like this:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   304
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   305
backup/[email protected]
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   306
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   307
You will need to make sure you have the correct package name, version, and
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   308
build you are targeting for the EOF for your new entry.  Also check for an old
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   309
SUNW entry at the top of the file.  If there is one you will need to change
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   310
this to match the targeted build.  So something like this:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   311
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   312
[email protected],5.11-0.133 backup/[email protected]
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   313
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   314
Should be changed to:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   315
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   316
[email protected]
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   317
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   318
Remember that the package may have had numerous names in its history.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   319
Generally the way to find this is by using:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   320
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   321
    pkg search -o search.match_type,pkg.name depend::<package name>
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   322
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   323
First with the package to be EOF'ed, and then examining each of the dependent
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   324
packages. If there are require dependencies on any of the dependents, then the
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   325
latter should be examined to see if it need to be either EOF'ed at the same
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   326
time, or at least updated to remove the dependency you're trying to EOF.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   327
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   328
Check to see if the package you are removing is referenced by a group package
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   329
(pkg list -n 'group/*').  See the 'EOFs and Removals' and 'Group Packages'
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   330
sections in /usr/src/pkg/README.pkg from the on-gate for further details. 
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   331
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   332
Testing
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   333
-------
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   334
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   335
To test your changes the first thing you will need to do is to invoke
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   336
'gmake publish' from the components/meta-packages/history directory or at the
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   337
top level (a full Userland build) if you are removing multiple components.  Once
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   338
this is complete you will need to setup a client with the EOF package(s)
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   339
installed.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   340
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   341
Then perform the following steps:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   342
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   343
1. # pkg set-publisher \
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   344
     -P -p file:///net/strax/builds/your_name/your_dir/i386/repo
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   345
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   346
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   347
If you are removing just a single component:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   348
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   349
2. pkg change-facet 'facet.version-lock.<eof_package_name_goes_here>=false'
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   350
3. pkg update pkg://nightly/<eof_package_name_goes_here>
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   351
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   352
After the update the component package should be removed from the test system.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   353
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   354
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   355
If you are removing multiple components:
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   356
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   357
2. pkg change-facet \
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   358
     version-lock.consolidation/userland/userland-incorporation=false
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   359
3. pkg update pkg://nightly/consolidation/userland/userland-incorporation
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   360
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   361
After the update the EOF component packages should be removed from the test
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   362
system.
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   363
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   364
For languages and anything else that has modules or is otherwise part of the
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   365
Userland build environment you will need to do a full build, of both ISAs, on
3f6521b6cb16 22007373 Need documentation on how to EOF Userland components
Bill Rushmore <bill.rushmore@oracle.com>
parents: 4813
diff changeset
   366
the test machines you just updated.
5454
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   367
1efad1afb469 PSARC/2015/194 libsasl ON to Userland migration and update
Jan Parcel <jan.parcel@oracle.com>
parents: 5107
diff changeset
   368
# vi:set fdm=marker expandtab ts=4: