git.saurik.com Git - apple/icu.git/blob - icuSources/tools/pkgdata/pkgdata.1.in

1 .\" Hey, Emacs! This is -*-nroff-*- you know...

2 .\"

3 .\" pkgdata.1: manual page for the pkgdata utility

4 .\"

6 .\" License & terms of use: http://www.unicode.org/copyright.html

8 .\"

9 .\" Manual page by Yves Arrouye <yves@realnames.com>.

10 .\" Modified by Michael Ow <mow@us.ibm.com>.

11 .\"

12 .TH PKGDATA 1 "6 February 2009" "ICU MANPAGE" "ICU @VERSION@ Manual"

13 .SH NAME

14 .B pkgdata

15 \- package data for use by ICU

16 .SH SYNOPSIS

17 .B pkgdata

18 [

19 .BR "\-h\fP, \fB\-?\fP, \fB\-\-help"

20 ]

21 [

22 .BI "\-v\fP, \fB\-\-verbose"

23 ]

24 [

25 .BR "\-c\fP, \fB\-\-copyright"

26 |

27 .BI "\-C\fP, \fB\-\-comment" " comment"

28 ]

29 [

30 .BI "\-m\fP, \fB\-\-mode" " mode"

31 ]

32 .BI "\-p\fP, \fB\-\-name" " name"

33 .BI "\-O\fP, \fB\-\-bldopt" " options"

34 [

35 .BI "\-e\fP, \fB\-\-entrypoint" " name"

36 ]

37 [

38 .BI "\-r\fP, \fB\-\-revision" " version"

39 ]

40 [

41 .BI "\-F\fP, \fB\-\-rebuild"

42 ]

43 [

44 .BI "\-I\fP, \fB\-\-install"

45 ]

46 [

47 .BI "\-s\fP, \fB\-\-sourcedir" " source"

48 ]

49 [

50 .BI "\-d\fP, \fB\-\-destdir" " destination"

51 ]

52 [

53 .BI "\-T\fP, \fB\-\-tempdir" " directory"

54 ]

55 [

56 .IR file " .\|.\|."

57 ]

58 .SH DESCRIPTION

59 .B pkgdata

60 takes a set of data files and packages them for use by ICU or

61 applications that use ICU. The typical reason to package files using

62 .B pkgdata

63 is to make their distribution easier and their loading by ICU faster

64 and less consuming of limited system resources such as file

65 descriptors.

66 Packaged data also allow applications to be distributed with fewer

67 resource files, or even with none at all if they link against the

68 packaged data directly.

69 .PP

70 .B pkgdata

71 supports a few different methods of packaging data that serve

72 different purposes.

73 .PP

74 The default packaging

75 .I mode

76 is

77 .BR common ,

78 or

79 .BR archive .

80 In this mode, the different data files are bundled together as an

81 architecture-dependent file that can later be memory mapped for use by

82 ICU. Data packaged using this mode will be looked up under the ICU

83 data directory. Such packaging is easy to use for applications resource

84 bundles, for example, as long as the application can install the

85 packaged file in the ICU data directory.

86 .PP

87 Another packaging mode is the

88 .BR dll ,

89 or

90 .BR library ,

91 mode, where the data files are compiled into a shared library. ICU

92 used to be able to dynamically load these shared libraries, but as of

93 ICU 2.0, such support has been removed. This mode is still useful for

94 two main purposes: to build ICU itself, as the ICU data is packaged as

95 a shared library by default; and to build resource bundles that are

96 linked to the application that uses them. Such resource bundles can

97 then be placed anywhere where the system's dynamic linker will be

98 looking for shared libraries, instead of being forced to live inside

99 the ICU data directory.

100 .PP

101 The

102 .BR static

103 packaging mode is similar to the shared library one except that it

104 produces a static library.

105 .\" Note that many platforms are not able to

106 .\" dynamically load symbols from static object files, so for this reason

107 .\" .BR udata_setAppData()

108 .\" must be called

109 .\" to install this data. As a convenience, pkgdata will build a C source file

110 .\" and a header file. Given a data package named

111 .\" .IR name, in the output

112 .\" directory will be created

113 .\" .IR name .c

114 .\" and

115 .\" .IR name .h with the single

116 .\" function

117 .\" .BR "udata_install_\fcIname\fB(UErrorCode *err)" ,

118 .\" where

119 .\" .I cname

120 .\" is

121 .\" .I name

122 .\" turned into a valid C identifier.

123 .\" The application need to call this function once. The error code returned

124 .\" is that of

125 .\" .BR udata_setAppData() .

126 .\" .PP

127 .\" Data pakackaged in a library, whether shared or static,

128 .\" Subsequently, the application can access this data by passing

129 .\" .I name for the

130 .\" .I path

131 .\" rgument to functions such as

132 .\" .BR Bures_open() .

133 .PP

134 Finally,

135 .B pkgdata

136 supports a

137 .B files

138 mode which simply copies the data files instead of packaging

139 them as a single file or library. This mode is mainly intended to

140 provide support for building ICU before it is packaged as separate

141 small packages for distribution with operating systems such as Debian

142 GNU/Linux for example. Please refer to the packaging documentation in

143 the ICU source distribution for further information on the use of this

144 mode.

145 .PP

146 .B pkgdata

147 builds, packages, installs, or cleans the appropriate data based on the options given

148 without the need to call GNU

149 .BR make

150 anymore.

151 .SH OPTIONS

152 .TP

153 .BR "\-h\fP, \fB\-?\fP, \fB\-\-help"

154 Print help about usage and exit.

155 .TP

156 .BR "\-v\fP, \fB\-\-verbose"

157 Display extra informative messages during execution.

158 .TP

159 .BR "\-c\fP, \fB\-\-copyright"

160 Include a copyright notice in the binary data.

161 .TP

162 .BI "\-C\fP, \fB\-\-comment" " comment"

163 Includes the specified

164 .I comment

165 in the resulting data instead of the ICU copyright notice.

166 .TP

167 .BI "\-m\fP, \fB\-\-mode" " mode"

168 Set the packaging

169 .I mode

170 to be used by

171 .BR pkgdata .

172 The different modes and their meaning are explained in the

173 .B DESCRIPTION

174 section above. The valid mode names are

175 .BR common

176 (or

177 .BR archive ),

178 .BR dll

179 (or

180 .BR library ),

181 and

182 .BR files .

183 .TP

184 .BI "\-O\fP, \fB\-\-bldopt" " options"

185 Specify options for the builder. The builder is used internally by

186 .B pkgdata

187 to generate the correct packaged file. Such options include, but are

188 not limited to, setting variables used by

189 .BR make (1)

190 during the build of the packaged file. Note: If

191 .BR icu-config

192 is available, then this option is not needed.

193 .TP

194 .BI "\-p\fP, \fB\-\-name" " name"

195 Set the packaged file name to

196 .IR name .

197 This name is also used as the default entry point name after having

198 been turned into a valid C identifier.

199 .TP

200 .BI "\-e\fP, \fB\-\-entrypoint" " name"

201 Set the data entry point (used for linking against the data in a

202 shared library form) to

203 .IR name .

204 The default entry point name is the name set by the

205 .BI "\-n\fP, \fB\-\-name"

206 option.

207 .TP

208 .BI "\-r\fP, \fB\-\-revision" " version"

209 Enable versioning of the shared library produced in

210 .BR dll ,

211 or

212 .BR library ,

213 mode. The version number has the format

214 .I major\fP.\fIminor\fP.\fIpatchlevel

215 and all parts except for

216 .I major

217 are optional. If only

218 .I major

219 is supplied then the version is

220 assumed to be

221 .IR major .0

222 for versioning purposes.

223 .TP

224 .BI "\-F\fP, \fB\-\-rebuild"

225 Force the rebuilding of all data and their repackaging.

226 .TP

227 .BI "\-I\fP, \fB\-\-install"

228 Install the packaged file (or all the files in the

229 .B files

230 mode). If the variable

231 .B DESTDIR

232 is set it will be used for installation.

233 .TP

234 .BI "\-s\fP, \fB\-\-sourcedir" " source"

235 Set the source directory to

236 .IR source .

237 The default source directory is the current directory.

238 .TP

239 .BI "\-d\fP, \fB\-\-destdir" " destination"

240 Set the destination directory to

241 .IR destination .

242 The default destination directory is the current directory.

243 .TP

244 .BI "\-T\fP, \fB\-\-tempdir" " directory"

245 Set the directory used to generate temporary files to

246 .IR directory .

247 The default temporary directory is the same as the destination

248 directory

249 as set by the

250 .BI "\-d\fP, \fB\-\-destdir"

251 option.

252 .SH AUTHORS

253 Steven Loomis

254 .br

255 Yves Arrouye

256 .SH VERSION

257 @VERSION@

258 .SH COPYRIGHT

260