author  Mike Sullivan <Mike.Sullivan@Oracle.COM> 
Mon, 11 Mar 2013 10:38:09 0700  
branch  s11update 
changeset 2520  ceec631e74d1 
parent 255  52abf74b9323 
child 1235  413599fe2d31 
permissions  rwrr 
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/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

20 
(.../{component}/{builddir}/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}/{builddir}/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/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

28 
(.../{component}/{builddir}/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}/{builddir}/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}/{builddir}/.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/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

40 
(.../{component}/{builddir}/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 
nondiscoverable dependencies, users, groups, drivers, and others. 
46
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

52 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

53 
Actions that are associated with objects that are specific to a single 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

54 
architecture should be tagged with a 'variant.arch' attribute specific to 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

55 
the architecture that applied to the action. Ex: 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

56 
file path=/usr/lib/$(MACH64)/libx86onlybits.so variant.arch=i386 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

57 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

58 
Actions for editable files must include an appropriate 'preserve' attribute: 
151
f9e42a3f7095
7030982 hgk is delivered 444, breaks 'hg view'
Norm Jacobs <Norm.Jacobs@Oracle.COM>
parents:
46
diff
changeset

59 
file path=etc/gnu/a2ps.cfg preserve=true mode=0644 
46
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

60 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

61 
license actions should be placed in the canonical manifest. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

62 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

63 
Mogrified Manifest 
166
db8a55996482
6979538 /usr/share/gettext/po/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

64 
The canonical manifest is combined with a set of the transforms 
db8a55996482
6979538 /usr/share/gettext/po/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

65 
in $(WS_TOP)/transforms, and a set of macros to more complete 
46
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

66 
package manifest using pkgmogrify(1). The transforms apply default 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

67 
attributes to the various actions in the canonical manifest(s). More 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

68 
detail about the attributes can be found in the transform file themselves. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

69 
The macros applied at the time of mogrification are as follows: 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

70 
$(MACH) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

71 
$(MACH32) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

72 
$(MACH64) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

73 
$(PUBLISHER) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

74 
$(CONSOLIDATION) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

75 
$(BUILD_VERSION) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

76 
$(SOLARIS_VERSION) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

77 
$(OS_VERSION) 
166
db8a55996482
6979538 /usr/share/gettext/po/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

78 
$(IPS_COMPONENT_VERSION) 
db8a55996482
6979538 /usr/share/gettext/po/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

79 
$(COMPONENT_VERSION) 
46
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

80 
$(COMPONENT_PROJECT_URL) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

81 
$(COMPONENT_ARCHIVE_URL) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

82 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

83 
Dependencies Generated 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

84 
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

85 
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

86 
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

87 
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

88 
determined by pkgdepend(1) should be placed in the canonical manifest. 
166
db8a55996482
6979538 /usr/share/gettext/po/Rulesquot contains garbage
Marcel Telka <marcel.telka@oracle.com>
parents:
151
diff
changeset

89 
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

90 
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

91 
Ex: 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

92 
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

93 
pkg.debug.reason=usr/bin/vipw type=require 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

94 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

95 
depend fmri=__TBD pkg.debug.depend.file=sh \ 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

96 
pkg.debug.depend.path=usr/bin \ 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

97 
pkg.debug.depend.reason=usr/bin/psmandup \ 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

98 
pkg.debug.depend.type=script type=require 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

99 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

100 
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

101 
package(s). 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

102 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

103 
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

104 
The manifest with unresolved dependencies is passed through pkgdepend(1) 
46
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

105 
again to resolve dependencies against the package repositories. The 
185
773dda89f186
7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents:
181
diff
changeset

106 
result is a manifest that is suitable for publication. All these 
773dda89f186
7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents:
181
diff
changeset

107 
manifests are processed together in a single step, which is more 
773dda89f186
7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents:
181
diff
changeset

108 
efficient than resolving dependencies in each manifest separately. 
773dda89f186
7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents:
181
diff
changeset

109 
While each manifest ends up with a .depend.res copy in the build 
773dda89f186
7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents:
181
diff
changeset

110 
directory, the umbrella dependency resolution target is 
773dda89f186
7036473 dependency resolution should happen in one step for all component's packages
Danek Duvall <danek.duvall@oracle.com>
parents:
181
diff
changeset

111 
{builddir}/.resolved$(MACH). 
46
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

112 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

113 
Manifest Validation 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

114 
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

115 
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

116 
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

117 
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

118 
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

119 
$(WS_TOP)/tools/python/userlandlint 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

120 

d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

121 
Publication. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

122 
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

123 
published to the workspace package repository. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

124 

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 
# vi:set fdm=marker expandtab ts=4: 