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 .\"
   5 .\" Copyright (C) 2000-2003 IBM, Inc. and others.
   6 .\"
   7 .\" Manual page by Yves Arrouye <yves@realnames.com>.
   8 .\" Modified by Steven R. Loomis <srl@jtcsv.com>.
   9 .\"
  10 .TH PKGDATA 1 "16 April 2002" "ICU MANPAGE" "ICU @VERSION@ Manual"
  11 .SH NAME
  12 .B pkgdata
  13 \- package data for use by ICU
  14 .SH SYNOPSIS
  15 .B pkgdata
  16 [
  17 .BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
  18 ]
  19 [
  20 .BI "\-v\fP, \fB\-\-verbose"
  21 ]
  22 [
  23 .BR "\-c\fP, \fB\-\-copyright"
  24 |
  25 .BI "\-C\fP, \fB\-\-comment" " comment"
  26 ]
  27 [
  28 .BI "\-m\fP, \fB\-\-mode" " mode"
  29 ]
  30 .BI "\-p\fP, \fB\-\-name" " name"
  31 .BI "\-O\fP, \fB\-\-bldopt" " options"
  32 [
  33 .BI "\-e\fP, \fB\-\-entrypoint" " name"
  34 ]
  35 [
  36 .BI "\-r\fP, \fB\-\-revision" " version"
  37 ]
  38 [
  39 .BI "\-M" " arg"
  40 ]
  41 [
  42 .BI "\-F\fP, \fB\-\-rebuild"
  43 ]
  44 [
  45 .BI "\-k\fP, \fB\-\-clean"
  46 ]
  47 [
  48 .BI "\-I\fP, \fB\-\-install"
  49 ]
  50 [
  51 .BI "\-n\fP, \fB\-\-nooutput"
  52 ]
  53 [
  54 .BI "\-N\fP, \fB\-\-numaric"
  55 ]
  56 [
  57 .BI "\-s\fP, \fB\-\-sourcedir" " source"
  58 ]
  59 [
  60 .BI "\-d\fP, \fB\-\-destdir" " destination"
  61 ]
  62 [
  63 .BI "\-T\fP, \fB\-\-tempdir" " directory"
  64 ]
  65 [
  66 .IR file " .\|.\|."
  67 ]
  68 .SH DESCRIPTION
  69 .B pkgdata
  70 takes a set of data files and packages them for use by ICU or
  71 applications that use ICU. The typical reason to package files using
  72 .B pkgdata
  73 is to make their distribution easier and their loading by ICU faster
  74 and less consuming of limited system resources such as file
  75 descriptors.
  76 Packaged data also allow applications to be distributed with fewer
  77 resource files, or even with none at all if they link against the
  78 packaged data directly.
  79 .PP
  80 .B pkgdata
  81 supports a few different methods of packaging data that serve
  82 different purposes.
  83 .PP
  84 The default packaging
  85 .I mode
  86 is
  87 .BR common ,
  88 or
  89 .BR archive .
  90 In this mode, the different data files are bundled together as an
  91 architecture-dependent file that can later be memory mapped for use by
  92 ICU. Data packaged using this mode will be looked up under the ICU
  93 data directory. Such packaging is easy to use for applications resource
  94 bundles, for example, as long as the application can install the
  95 packaged file in the ICU data directory.
  96 .PP
  97 Another packaging mode is the
  98 .BR dll ,
  99 or
 100 .BR library ,
 101 mode, where the data files are compiled into a shared library. ICU
 102 used to be able to dynamically load these shared libraries, but as of
 103 ICU 2.0, such support has been removed. This mode is still useful for
 104 two main purposes: to build ICU itself, as the ICU data is packaged as
 105 a shared library by default; and to build resource bundles that are
 106 linked to the application that uses them. Such resource bundles can
 107 then be placed anywhere where the system's dynamic linker will be
 108 looking for shared libraries, instead of being forced to live inside
 109 the ICU data directory.
 110 .PP
 111 The
 112 .BR static
 113 packaging mode is similar to the shared library one except that it
 114 produces a static library.
 115 .\" Note that many platforms are not able to
 116 .\" dynamically load symbols from static object files, so for this reason
 117 .\" .BR udata_setAppData()
 118 .\" must be called
 119 .\" to install this data. As a convenience, pkgdata will build a C source file
 120 .\" and a header file. Given a data package named
 121 .\" .IR name, in the output
 122 .\" directory will be created
 123 .\" .IR name .c
 124 .\" and
 125 .\" .IR name .h with the single
 126 .\" function
 127 .\" .BR "udata_install_\fcIname\fB(UErrorCode *err)" ,
 128 .\" where
 129 .\" .I cname
 130 .\" is
 131 .\" .I name
 132 .\" turned into a valid C identifier.
 133 .\" The application need to call this function once. The error code returned
 134 .\" is that of
 135 .\" .BR udata_setAppData() .
 136 .\" .PP
 137 .\" Data pakackaged in a library, whether shared or static,
 138 .\" Subsequently, the application can access this data by passing
 139 .\" .I name for the
 140 .\" .I path
 141 .\" rgument to functions such as
 142 .\" .BR Bures_open() .
 143 .PP
 144 Finally,
 145 .B pkgdata
 146 supports a
 147 .B files
 148 mode which simply copies the data files instead of packaging
 149 them as a single file or library. This mode is mainly intended to
 150 provide support for building ICU before it is packaged as separate
 151 small packages for distribution with operating systems such as Debian
 152 GNU/Linux for example. Please refer to the packaging documentation in
 153 the ICU source distribution for further information on the use of this
 154 mode.
 155 .PP
 156 .B pkgdata
 157 relies on GNU
 158 .BR make (1)
 159 to do the packaging, and generates a makefile with rules to build,
 160 package, install, or clean the appropriate data.
 161 .SH OPTIONS
 162 .TP
 163 .BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
 164 Print help about usage and exit.
 165 .TP
 166 .BR "\-v\fP, \fB\-\-verbose"
 167 Display extra informative messages during execution.
 168 .TP
 169 .BR "\-c\fP, \fB\-\-copyright"
 170 Include a copyright notice in the binary data.
 171 .TP
 172 .BI "\-C\fP, \fB\-\-comment" " comment"
 173 Includes the specified
 174 .I comment
 175 in the resulting data instead of the ICU copyright notice.
 176 .TP
 177 .BI "\-m\fP, \fB\-\-mode" " mode"
 178 Set the packaging
 179 .I mode
 180 to be used by
 181 .BR pkgdata .
 182 The different modes and their meaning are explained in the
 183 .B DESCRIPTION
 184 section above. The valid mode names are
 185 .BR common
 186 (or
 187 .BR archive ),
 188 .BR dll
 189 (or
 190 .BR library ),
 191 and
 192 .BR files .
 193 .TP
 194 .BI "\-O\fP, \fB\-\-bldopt" " options"
 195 Specify options for the builder. The builder is used internally by
 196 .B pkgdata
 197 to generate the correct packaged file. Such options include, but are
 198 not limited to, setting variables used by
 199 .BR make (1)
 200 during the build of the packaged file. Note: If
 201 .BR icu-config
 202 is available, then this option is not needed.
 203 .TP
 204 .BI "\-p\fP, \fB\-\-name" " name"
 205 Set the packaged file name to
 206 .IR name .
 207 This name is also used as the default entry point name after having
 208 been turned into a valid C identifier.
 209 .TP
 210 .BI "\-e\fP, \fB\-\-entrypoint" " name"
 211 Set the data entry point (used for linking against the data in a
 212 shared library form) to
 213 .IR name .
 214 The default entry point name is the name set by the
 215 .BI "\-n\fP, \fB\-\-name"
 216 option.
 217 .TP
 218 .BI "\-r\fP, \fB\-\-revision" " version"
 219 Enable versioning of the shared library produced in
 220 .BR dll ,
 221 or
 222 .BR library ,
 223 mode. The version number has the format
 224 .I major\fP.\fIminor\fP.\fIpatchlevel
 225 and all parts except for
 226 .I major
 227 are optional. If only
 228 .I major
 229 is supplied then the version is
 230 assumed to be
 231 .IR major .0
 232 for versioning purposes.
 233 .TP
 234 .BI "\-M" " arg"
 235 Pass
 236 .I arg
 237 to
 238 .BR make (1).
 239 .TP
 240 .BI "\-F\fP, \fB\-\-rebuild"
 241 Force the rebuilding of all data and their repackaging.
 242 .TP
 243 .BI "\-k\fP, \fB\-\-clean"
 244 Clean temporary files and other build residues.
 245 .TP
 246 .BI "\-I\fP, \fB\-\-install"
 247 Install the packaged file (or all the files in the
 248 .B files
 249 mode). If the variable
 250 .B DESTDIR
 251 is set it will be used for installation.
 252 .TP
 253 .BI "\-n\fP, \fB\-\-nooutput"
 254 Do not produce any output but simply a list of affected files.
 255 .TP
 256 .BI "\-N\fP, \fB\-\-numeric"
 257 Instead of using temporary filenames similar to the input symbols, use numeric filenames such
 258 as t0002.c, etc.  May be needed for systems which don't allow many similar long filenames, or
 259 for systems that tend to run out of argument space.  Note, using this option
 260 implies "\-F\fP, \fB\-\-rebuild" - all packaging will be rebuilt every time pkgdata is run.
 261 .TP
 262 .BI "\-s\fP, \fB\-\-sourcedir" " source"
 263 Set the source directory to
 264 .IR source .
 265 The default source directory is the current directory.
 266 .TP
 267 .BI "\-d\fP, \fB\-\-destdir" " destination"
 268 Set the destination directory to
 269 .IR destination .
 270 The default destination directory is the current directory.
 271 .TP
 272 .BI "\-T\fP, \fB\-\-tempdir" " directory"
 273 Set the directory used to generate temporary files to
 274 .IR directory .
 275 The default temporary directory is the same as the destination
 276 directory
 277 as set by the
 278 .BI "\-d\fP, \fB\-\-destdir"
 279 option.
 280 .SH AUTHORS
 281 Steven Loomis
 282 .br
 283 Yves Arrouye
 284 .SH VERSION
 285 @VERSION@
 286 .SH COPYRIGHT
 287 Copyright (C) 2000-2003 IBM, Inc. and others.
 288