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