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