1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/tools/pkgdata/pkgdata.1.in Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,258 @@
1.4 +.\" Hey, Emacs! This is -*-nroff-*- you know...
1.5 +.\"
1.6 +.\" pkgdata.1: manual page for the pkgdata utility
1.7 +.\"
1.8 +.\" Copyright (C) 2000-2009 IBM, Inc. and others.
1.9 +.\"
1.10 +.\" Manual page by Yves Arrouye <yves@realnames.com>.
1.11 +.\" Modified by Michael Ow <mow@us.ibm.com>.
1.12 +.\"
1.13 +.TH PKGDATA 1 "6 February 2009" "ICU MANPAGE" "ICU @VERSION@ Manual"
1.14 +.SH NAME
1.15 +.B pkgdata
1.16 +\- package data for use by ICU
1.17 +.SH SYNOPSIS
1.18 +.B pkgdata
1.19 +[
1.20 +.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
1.21 +]
1.22 +[
1.23 +.BI "\-v\fP, \fB\-\-verbose"
1.24 +]
1.25 +[
1.26 +.BR "\-c\fP, \fB\-\-copyright"
1.27 +|
1.28 +.BI "\-C\fP, \fB\-\-comment" " comment"
1.29 +]
1.30 +[
1.31 +.BI "\-m\fP, \fB\-\-mode" " mode"
1.32 +]
1.33 +.BI "\-p\fP, \fB\-\-name" " name"
1.34 +.BI "\-O\fP, \fB\-\-bldopt" " options"
1.35 +[
1.36 +.BI "\-e\fP, \fB\-\-entrypoint" " name"
1.37 +]
1.38 +[
1.39 +.BI "\-r\fP, \fB\-\-revision" " version"
1.40 +]
1.41 +[
1.42 +.BI "\-F\fP, \fB\-\-rebuild"
1.43 +]
1.44 +[
1.45 +.BI "\-I\fP, \fB\-\-install"
1.46 +]
1.47 +[
1.48 +.BI "\-s\fP, \fB\-\-sourcedir" " source"
1.49 +]
1.50 +[
1.51 +.BI "\-d\fP, \fB\-\-destdir" " destination"
1.52 +]
1.53 +[
1.54 +.BI "\-T\fP, \fB\-\-tempdir" " directory"
1.55 +]
1.56 +[
1.57 +.IR file " .\|.\|."
1.58 +]
1.59 +.SH DESCRIPTION
1.60 +.B pkgdata
1.61 +takes a set of data files and packages them for use by ICU or
1.62 +applications that use ICU. The typical reason to package files using
1.63 +.B pkgdata
1.64 +is to make their distribution easier and their loading by ICU faster
1.65 +and less consuming of limited system resources such as file
1.66 +descriptors.
1.67 +Packaged data also allow applications to be distributed with fewer
1.68 +resource files, or even with none at all if they link against the
1.69 +packaged data directly.
1.70 +.PP
1.71 +.B pkgdata
1.72 +supports a few different methods of packaging data that serve
1.73 +different purposes.
1.74 +.PP
1.75 +The default packaging
1.76 +.I mode
1.77 +is
1.78 +.BR common ,
1.79 +or
1.80 +.BR archive .
1.81 +In this mode, the different data files are bundled together as an
1.82 +architecture-dependent file that can later be memory mapped for use by
1.83 +ICU. Data packaged using this mode will be looked up under the ICU
1.84 +data directory. Such packaging is easy to use for applications resource
1.85 +bundles, for example, as long as the application can install the
1.86 +packaged file in the ICU data directory.
1.87 +.PP
1.88 +Another packaging mode is the
1.89 +.BR dll ,
1.90 +or
1.91 +.BR library ,
1.92 +mode, where the data files are compiled into a shared library. ICU
1.93 +used to be able to dynamically load these shared libraries, but as of
1.94 +ICU 2.0, such support has been removed. This mode is still useful for
1.95 +two main purposes: to build ICU itself, as the ICU data is packaged as
1.96 +a shared library by default; and to build resource bundles that are
1.97 +linked to the application that uses them. Such resource bundles can
1.98 +then be placed anywhere where the system's dynamic linker will be
1.99 +looking for shared libraries, instead of being forced to live inside
1.100 +the ICU data directory.
1.101 +.PP
1.102 +The
1.103 +.BR static
1.104 +packaging mode is similar to the shared library one except that it
1.105 +produces a static library.
1.106 +.\" Note that many platforms are not able to
1.107 +.\" dynamically load symbols from static object files, so for this reason
1.108 +.\" .BR udata_setAppData()
1.109 +.\" must be called
1.110 +.\" to install this data. As a convenience, pkgdata will build a C source file
1.111 +.\" and a header file. Given a data package named
1.112 +.\" .IR name, in the output
1.113 +.\" directory will be created
1.114 +.\" .IR name .c
1.115 +.\" and
1.116 +.\" .IR name .h with the single
1.117 +.\" function
1.118 +.\" .BR "udata_install_\fcIname\fB(UErrorCode *err)" ,
1.119 +.\" where
1.120 +.\" .I cname
1.121 +.\" is
1.122 +.\" .I name
1.123 +.\" turned into a valid C identifier.
1.124 +.\" The application need to call this function once. The error code returned
1.125 +.\" is that of
1.126 +.\" .BR udata_setAppData() .
1.127 +.\" .PP
1.128 +.\" Data pakackaged in a library, whether shared or static,
1.129 +.\" Subsequently, the application can access this data by passing
1.130 +.\" .I name for the
1.131 +.\" .I path
1.132 +.\" rgument to functions such as
1.133 +.\" .BR Bures_open() .
1.134 +.PP
1.135 +Finally,
1.136 +.B pkgdata
1.137 +supports a
1.138 +.B files
1.139 +mode which simply copies the data files instead of packaging
1.140 +them as a single file or library. This mode is mainly intended to
1.141 +provide support for building ICU before it is packaged as separate
1.142 +small packages for distribution with operating systems such as Debian
1.143 +GNU/Linux for example. Please refer to the packaging documentation in
1.144 +the ICU source distribution for further information on the use of this
1.145 +mode.
1.146 +.PP
1.147 +.B pkgdata
1.148 +builds, packages, installs, or cleans the appropriate data based on the options given
1.149 +without the need to call GNU
1.150 +.BR make
1.151 +anymore.
1.152 +.SH OPTIONS
1.153 +.TP
1.154 +.BR "\-h\fP, \fB\-?\fP, \fB\-\-help"
1.155 +Print help about usage and exit.
1.156 +.TP
1.157 +.BR "\-v\fP, \fB\-\-verbose"
1.158 +Display extra informative messages during execution.
1.159 +.TP
1.160 +.BR "\-c\fP, \fB\-\-copyright"
1.161 +Include a copyright notice in the binary data.
1.162 +.TP
1.163 +.BI "\-C\fP, \fB\-\-comment" " comment"
1.164 +Includes the specified
1.165 +.I comment
1.166 +in the resulting data instead of the ICU copyright notice.
1.167 +.TP
1.168 +.BI "\-m\fP, \fB\-\-mode" " mode"
1.169 +Set the packaging
1.170 +.I mode
1.171 +to be used by
1.172 +.BR pkgdata .
1.173 +The different modes and their meaning are explained in the
1.174 +.B DESCRIPTION
1.175 +section above. The valid mode names are
1.176 +.BR common
1.177 +(or
1.178 +.BR archive ),
1.179 +.BR dll
1.180 +(or
1.181 +.BR library ),
1.182 +and
1.183 +.BR files .
1.184 +.TP
1.185 +.BI "\-O\fP, \fB\-\-bldopt" " options"
1.186 +Specify options for the builder. The builder is used internally by
1.187 +.B pkgdata
1.188 +to generate the correct packaged file. Such options include, but are
1.189 +not limited to, setting variables used by
1.190 +.BR make (1)
1.191 +during the build of the packaged file. Note: If
1.192 +.BR icu-config
1.193 +is available, then this option is not needed.
1.194 +.TP
1.195 +.BI "\-p\fP, \fB\-\-name" " name"
1.196 +Set the packaged file name to
1.197 +.IR name .
1.198 +This name is also used as the default entry point name after having
1.199 +been turned into a valid C identifier.
1.200 +.TP
1.201 +.BI "\-e\fP, \fB\-\-entrypoint" " name"
1.202 +Set the data entry point (used for linking against the data in a
1.203 +shared library form) to
1.204 +.IR name .
1.205 +The default entry point name is the name set by the
1.206 +.BI "\-n\fP, \fB\-\-name"
1.207 +option.
1.208 +.TP
1.209 +.BI "\-r\fP, \fB\-\-revision" " version"
1.210 +Enable versioning of the shared library produced in
1.211 +.BR dll ,
1.212 +or
1.213 +.BR library ,
1.214 +mode. The version number has the format
1.215 +.I major\fP.\fIminor\fP.\fIpatchlevel
1.216 +and all parts except for
1.217 +.I major
1.218 +are optional. If only
1.219 +.I major
1.220 +is supplied then the version is
1.221 +assumed to be
1.222 +.IR major .0
1.223 +for versioning purposes.
1.224 +.TP
1.225 +.BI "\-F\fP, \fB\-\-rebuild"
1.226 +Force the rebuilding of all data and their repackaging.
1.227 +.TP
1.228 +.BI "\-I\fP, \fB\-\-install"
1.229 +Install the packaged file (or all the files in the
1.230 +.B files
1.231 +mode). If the variable
1.232 +.B DESTDIR
1.233 +is set it will be used for installation.
1.234 +.TP
1.235 +.BI "\-s\fP, \fB\-\-sourcedir" " source"
1.236 +Set the source directory to
1.237 +.IR source .
1.238 +The default source directory is the current directory.
1.239 +.TP
1.240 +.BI "\-d\fP, \fB\-\-destdir" " destination"
1.241 +Set the destination directory to
1.242 +.IR destination .
1.243 +The default destination directory is the current directory.
1.244 +.TP
1.245 +.BI "\-T\fP, \fB\-\-tempdir" " directory"
1.246 +Set the directory used to generate temporary files to
1.247 +.IR directory .
1.248 +The default temporary directory is the same as the destination
1.249 +directory
1.250 +as set by the
1.251 +.BI "\-d\fP, \fB\-\-destdir"
1.252 +option.
1.253 +.SH AUTHORS
1.254 +Steven Loomis
1.255 +.br
1.256 +Yves Arrouye
1.257 +.SH VERSION
1.258 +@VERSION@
1.259 +.SH COPYRIGHT
1.260 +Copyright (C) 2000-2009 IBM, Inc. and others.
1.261 +
