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