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