pkgdata.1: manual page for the pkgdata utility
Copyright (C) 2016 and later: Unicode, Inc. and others.
License & terms of use: http://www.unicode.org/copyright.html
Copyright (C) 2000-2009 IBM, Inc. and others.
Manual page by Yves Arrouye <yves@realnames.com>.
Modified by Michael Ow <mow@us.ibm.com>.
pkgdata supports a few different methods of packaging data that serve different purposes.
The default packaging mode is common , or archive . In this mode, the different data files are bundled together as an architecture-dependent file that can later be memory mapped for use by ICU. Data packaged using this mode will be looked up under the ICU data directory. Such packaging is easy to use for applications resource bundles, for example, as long as the application can install the packaged file in the ICU data directory.
Another packaging mode is the dll , or library , mode, where the data files are compiled into a shared library. ICU used to be able to dynamically load these shared libraries, but as of ICU 2.0, such support has been removed. This mode is still useful for two main purposes: to build ICU itself, as the ICU data is packaged as a shared library by default; and to build resource bundles that are linked to the application that uses them. Such resource bundles can then be placed anywhere where the system's dynamic linker will be looking for shared libraries, instead of being forced to live inside the ICU data directory.
The
static packaging mode is similar to the shared library one except that it
produces a static library.
Note that many platforms are not able to
dynamically load symbols from static object files, so for this reason
.BR udata_setAppData()
must be called
to install this data. As a convenience, pkgdata will build a C source file
and a header file. Given a data package named
.IR name, in the output
directory will be created
.IR name .c
and
.IR name .h with the single
function
.BR "udata_install_\fcIname(UErrorCode *err)" ,
where
.I cname
is
.I name
turned into a valid C identifier.
The application need to call this function once. The error code returned
is that of
.BR udata_setAppData() .
.PP
Data pakackaged in a library, whether shared or static,
Subsequently, the application can access this data by passing
.I name for the
.I path
rgument to functions such as
.BR Bures_open() .
Finally, pkgdata supports a files mode which simply copies the data files instead of packaging them as a single file or library. This mode is mainly intended to provide support for building ICU before it is packaged as separate small packages for distribution with operating systems such as Debian GNU/Linux for example. Please refer to the packaging documentation in the ICU source distribution for further information on the use of this mode.
pkgdata builds, packages, installs, or cleans the appropriate data based on the options given without the need to call GNU make anymore.
"-h, -?, --help" Print help about usage and exit.
"-v, --verbose" Display extra informative messages during execution.
"-c, --copyright" Include a copyright notice in the binary data.
"-C, --comment" " comment" Includes the specified comment in the resulting data instead of the ICU copyright notice.
"-m, --mode" " mode" Set the packaging mode to be used by pkgdata . The different modes and their meaning are explained in the DESCRIPTION section above. The valid mode names are common (or archive ), dll (or library ), and files .
"-O, --bldopt" " options" Specify options for the builder. The builder is used internally by pkgdata to generate the correct packaged file. Such options include, but are not limited to, setting variables used by make (1) during the build of the packaged file. Note: If icu-config is available, then this option is not needed.
"-p, --name" " name" Set the packaged file name to name . This name is also used as the default entry point name after having been turned into a valid C identifier.
"-e, --entrypoint" " name" Set the data entry point (used for linking against the data in a shared library form) to name . The default entry point name is the name set by the "-n, --name" option.
"-r, --revision" " version" Enable versioning of the shared library produced in dll , or library , mode. The version number has the format major.minor.patchlevel and all parts except for major are optional. If only major is supplied then the version is assumed to be major .0 for versioning purposes.
"-F, --rebuild" Force the rebuilding of all data and their repackaging.
"-I, --install" Install the packaged file (or all the files in the files mode). If the variable DESTDIR is set it will be used for installation.
"-s, --sourcedir" " source" Set the source directory to source . The default source directory is the current directory.
"-d, --destdir" " destination" Set the destination directory to destination . The default destination directory is the current directory.
"-T, --tempdir" " directory" Set the directory used to generate temporary files to directory . The default temporary directory is the same as the destination directory as set by the "-d, --destdir" option.
Yves Arrouye