author  Norm Jacobs <Norm.Jacobs@Oracle.COM> 
Wed, 23 Feb 2011 10:37:11 0800  
changeset 99  c15c9099bb44 
parent 46  d4d60962c33f 
child 151  f9e42a3f7095 
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 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

20 
(.../{component}/{builddir}/manifest$(ARCH){component}.mogrified) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

24 
(.../{component}/{builddir}/manifest$(ARCH){component}.depend) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

28 
(.../{component}/{builddir}/manifest$(ARCH){component}.resolved) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

32 
(.../{component}/{builddir}/manifest$(ARCH){component}.linted) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

36 
(.../{component}/{builddir}/manifest$(ARCH){component}.published) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

40 

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

41 

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

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

43 
The canonical manifest contains actions that can't otherwise be generated 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

44 
automatically from the data encapsulated in the component Makefile, gate 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

45 
transformations, build tree, and packaging tools. This includes actions 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

46 
for license information, some path related attributes, legacy actions, 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

47 
nondiscoverable dependencies, user, group, driver, and others. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

48 

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

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

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

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

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

53 

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

54 
Actions that are associated with objects that are architecture dependent 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

55 
shoule be tagged with a 'variant.arch' attribute as follows: 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

56 
file path=/usr/bin/ls variant.arch=$(ARCH) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

57 

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

58 
Actions for editable files must include an appropriate 'preserve' attribute: 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

60 

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

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

62 

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

63 
Actions that can take advantage of macros supplied at pkgmogrify time 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

65 
file path=/usr/bin/$(MACH64)/ztest variant.arch=$(ARCH) 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

66 

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

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

68 
The canonical manifest is combined with a template manifest header at 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

69 
$(WS_TOP)/transforms/manifestmetadatatemplate, a set of the transforms 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

88 

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

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

90 
The mogrified manifest and the prototype install tree are passed through 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

91 
pkgdepend(1) to generate a set of dependencies for the package content. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

92 
These dependencies are only those that "pkgdepend generate" can determine 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

93 
on it's own. Additional dependencies that can not be automatically 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

94 
determined by pkgdepend(1) should be placed in the canonical manifest. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

95 
Staticly defined dependencies should be described in a canonical manifest 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

96 
in an unresolved form (ie. the form generated by "pkgdepend generate"). 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

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

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

100 

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

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

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

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

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

105 

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

106 
This will allow the next step to resolve all dependencies to their proper 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

108 

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

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

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

111 
again to resolve dependencies against the package repositories. The 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

112 
result is a manifest that is suitable for publication. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

113 

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

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

115 
The resolved manifest(s) and prototype install tree are passed through 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

116 
a set of validations. This includes running pkglint(1), comparing the 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

117 
manifest content to the prototype install tree, and validation of the file 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

118 
content of the prototype install tree. Any anomolies are reported. 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

119 
Content validation is performed by extension to pkglint(1) in 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

121 

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

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

123 
Once manifest validation has occurred, the package(s) is/are finally 
d4d60962c33f
generate detectable dependencies at build time
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff
changeset

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

125 

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

126 

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

127 
# vi:set fdm=marker expandtab ts=4: 