1655 lines
64 KiB
HTML
1655 lines
64 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
|
<meta name="COPYRIGHT" content=
|
|
"Copyright (c) IBM Corporation and others. All Rights Reserved.">
|
|
<meta name="KEYWORDS" content=
|
|
"ICU; International Components for Unicode; what's new; readme; read me; introduction; downloads; downloading; building; installation;">
|
|
<meta name="DESCRIPTION" content=
|
|
"The introduction to the International Components for Unicode with instructions on building, installation, usage and other information about ICU.">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
|
|
<title>ReadMe for ICU</title>
|
|
<style type="text/css">
|
|
h1 {border-width: 2px; border-style: solid; text-align: center; width: 100%; font-size: 200%; font-weight: bold}
|
|
h2 {margin-top: 3em; text-decoration: underline; page-break-before: always}
|
|
h2.TOC {page-break-before: auto}
|
|
h3 {margin-top: 2em; text-decoration: underline}
|
|
h4 {text-decoration: underline}
|
|
h5 {text-decoration: underline}
|
|
caption {font-weight: bold; text-align: left}
|
|
div.indent {margin-left: 2em}
|
|
ul.TOC {list-style-type: none}
|
|
samp {margin-left: 2em; border-style: groove; padding: 1em; display: block; background-color: #EEEEEE}
|
|
</style>
|
|
</head>
|
|
|
|
<body lang="en-US">
|
|
<h1>International Components for Unicode<br>
|
|
ICU 2.2 ReadMe</h1>
|
|
|
|
<p>Version: 2002-Oct-01<br>
|
|
Copyright © 1997-2002 International Business Machines Corporation and
|
|
others. All Rights Reserved.</p>
|
|
<!-- Remember that there is a copyright at the end too -->
|
|
<hr>
|
|
|
|
<h2 class="TOC">Table of Contents</h2>
|
|
|
|
<ul class="TOC">
|
|
<li><a href="#Introduction">Introduction</a></li>
|
|
|
|
<li><a href="#GettingStarted">Getting Started</a></li>
|
|
|
|
<li><a href="#News">What Is New In This release?</a></li>
|
|
|
|
<li><a href="#Download">How To Download the Source Code</a></li>
|
|
|
|
<li><a href="#SourceCode">ICU Source Code Organization</a></li>
|
|
|
|
<li>
|
|
<a href="#HowToBuild">How To Build And Install ICU</a>
|
|
|
|
<ul class="TOC">
|
|
<li><a href="#HowToBuildSupported">Supported Platforms</a></li>
|
|
|
|
<li><a href="#HowToBuildWindows">Windows</a></li>
|
|
|
|
<li><a href="#HowToBuildWindowsXP64">Windows XP on IA64</a></li>
|
|
|
|
<li><a href="#HowToBuildUnix">Unix</a></li>
|
|
|
|
<li><a href="#HowToBuildZOS">z/OS (os/390)</a></li>
|
|
|
|
<li><a href="#HowToBuildOS400">OS/400 (iSeries)</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#MakeICUSmaller">
|
|
How to Make ICU Smaller</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ImportantNotes">Important Notes About Using ICU</a>
|
|
|
|
<ul class="TOC">
|
|
<li><a href="#ImportantNotesCPlusPlus">Using ICU in a Multithreaded
|
|
Environment</a></li>
|
|
|
|
<li><a href="#ImportantNotesBinaryCompat">Binary
|
|
Compatibility</a></li>
|
|
|
|
<li><a href="#ImportantNotesWindows">Windows Platform</a></li>
|
|
|
|
<li><a href="#ImportantNotesUnix">Unix Type Platforms</a></li>
|
|
|
|
<li><a href="#ImportantNotesDefaultCP">Using the Default
|
|
Codepage</a></li>
|
|
|
|
<li><a href="#ImportantNotesDeprecatedAPI">Methods For Enabling
|
|
Deprecated APIs</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#PlatformDependencies">Platform Dependencies</a></li>
|
|
</ul>
|
|
<hr>
|
|
|
|
<h2><a name="Introduction" href="#Introduction">Introduction</a></h2>
|
|
|
|
<p>Today's software market is a global one in which it is desirable to
|
|
develop and maintain one application (single source/single binary) that
|
|
supports a wide variety of languages. The International Components for
|
|
Unicode (C/C++) provides tools to help write platform-independent
|
|
applications that are internationalized and localized, with support
|
|
for:</p>
|
|
|
|
<ul>
|
|
<li>Support for the latest version of the Unicode standard</li>
|
|
|
|
<li>Character set conversions, with support for over 200 codepages</li>
|
|
|
|
<li>Locale data for more than 220 locales</li>
|
|
|
|
<li>Text collation (sorting) based on the Unicode Collation Algorithm
|
|
(=ISO 14651), customizable and tailored for national standards</li>
|
|
|
|
<li>Transliteration services for script<->script transliterations
|
|
and general text operations</li>
|
|
|
|
<li>Resource bundles for storing and accessing localized information</li>
|
|
|
|
<li>Date/Number/Message formatting and parsing of culture-specific
|
|
input/output formats</li>
|
|
|
|
<li>Text boundary analysis for finding characters, word and sentence
|
|
boundaries</li>
|
|
</ul>
|
|
|
|
<p>ICU has a sister project <a href=
|
|
"http://oss.software.ibm.com/icu4j/">ICU4J</a> that extends the
|
|
internationalization capabilities of Java to a level similar to ICU. The
|
|
ICU C/C++ project is also called ICU4C when a distinction is necessary.</p>
|
|
|
|
<h2><a name="GettingStarted" href="#GettingStarted">Getting
|
|
started</a></h2>
|
|
|
|
<p>This document describes how to build and install ICU on your machine.
|
|
For other information about ICU please see the following table of
|
|
links.<br>
|
|
The ICU homepage also links to related information about writing
|
|
internationalized software.</p>
|
|
|
|
<table border="1" cellpadding="3" width="100%" summary="">
|
|
<caption>
|
|
Here are some useful links regarding ICU and internationalization in
|
|
general.
|
|
</caption>
|
|
|
|
<tr>
|
|
<td>ICU Homepage</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/">http://oss.software.ibm.com/icu/</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>ICU4J Homepage</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu4j/">http://oss.software.ibm.com/icu4j/</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>FAQ - Frequently Asked Questions about ICU</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/userguide/icufaq.html">http://oss.software.ibm.com/icu/userguide/icufaq.html</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>ICU User's Guide</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/userguide/">http://oss.software.ibm.com/icu/userguide/</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Download ICU Releases</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/download/">http://oss.software.ibm.com/icu/download/</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>API Documentation Online</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/apiref/">http://oss.software.ibm.com/icu/apiref/</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Online ICU Demos</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/demo/">http://oss.software.ibm.com/icu/demo/</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Contacts and Bug Reports/Feature Requests</td>
|
|
|
|
<td><a href=
|
|
"http://oss.software.ibm.com/icu/archives/">http://oss.software.ibm.com/icu/archives/</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Important:</strong> Please make sure you understand the <a href=
|
|
"license.html">Copyright and License Information</a>.</p>
|
|
|
|
<h2><a name="News" href="#News">What is new in this release?</a></h2>
|
|
|
|
<p>The following list concentrates on <em>changes that affect existing
|
|
applications migrating from previous ICU releases</em>. For more news about
|
|
this release, see the <a href=
|
|
"http://oss.software.ibm.com/icu/download/2.2/">ICU 2.2 download
|
|
page</a>.</p>
|
|
|
|
<h3>UnicodeString assignments</h3>
|
|
|
|
<p>ICU 2.4 changes the behavior of the <code>UnicodeString</code> assignment operator
|
|
and copy constructor for where the source string is a readonly alias.
|
|
For such strings, the copy used to also be a readonly alias to the same buffer,
|
|
but that was seen as too dangerous (see <a href="http://www.jtcsv.com/cgibin/icu-bugs?findid=2296">Jitterbug 2296</a>).
|
|
The new <code>fastCopyFrom()</code> member function provides the old
|
|
assignment behavior.
|
|
It can be used explicitly when it is known to be safe to maintain readonly aliases
|
|
instead of cloning the buffer.
|
|
For more information about string aliasing and other <code>UnicodeString</code> storage models
|
|
see the <a href="http://oss.software.ibm.com/icu/userguide/strings.html">User Guide Strings chapter</a>.</p>
|
|
|
|
<h3>Unicode-handling macros (utf*.h)</h3>
|
|
|
|
<p>The macros in <code>source/common/unicode/utf*.h</code> have been
|
|
revamped, improved, simplified, and renamed. The old macros continue to be
|
|
available. They are in <code>utf_old.h</code>, together with an explanation
|
|
of the change. <code>utf.h</code>, <code>utf8.h</code> and <code>utf16.h</code>
|
|
contain the new macros instead. The new macros are intended to be more
|
|
consistent, more useful, and less confusing. Some macros were simply renamed
|
|
for consistency with a new naming scheme.</p>
|
|
|
|
<p>A related change is that <code>UChar32</code> is not a platform-dependent
|
|
type any more, but is now always defined to be the same as <code>int32_t</code>.
|
|
This allows for consistent, more portable code and C++ function overloading
|
|
as well as negative values as sentinels on all platforms. See the definition
|
|
in <code>utf.h</code>.</p>
|
|
|
|
<h3>ICU code library size</h3>
|
|
|
|
<p>ICU code libraries can be made smaller by removing functionality. See <a href="#MakeICUSmaller">How
|
|
to Make ICU Smaller</a>.</p>
|
|
|
|
<h3>Support for Unicode 3.2</h3>
|
|
|
|
<p>Unicode properties and algorithms have been upgraded to <a href=
|
|
"http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode_3_2_0">
|
|
Unicode 3.2</a>, which includes the addition of more than 1000 new encoded
|
|
characters. The UCA (<a href="http://www.unicode.org/reports/tr10/">Unicode
|
|
Collation Algorithm</a>) table is updated to the current version 3.1.1,
|
|
with Unicode 3.2-based canonical closure. All Unicode properties (except
|
|
for those in Unihan.txt) are now <a href=
|
|
"http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/ucd_icu.html">
|
|
available via direct APIs, and most via UnicodeSet</a>.</p>
|
|
|
|
<h3>Additional and modified converters</h3>
|
|
|
|
<p>New converter implementations are added for:</p>
|
|
|
|
<ul>
|
|
<li>UTF-16 and UTF-32 (detect/emit BOM according to IANA
|
|
registration)<br>
|
|
These and related names used to be aliases for UTF16_PlatformEndian and
|
|
UTF32_PlatformEndian but are now separate, IANA-registration-compliant
|
|
converters that detect and emit the respective Byte Order Mark. The
|
|
"platform endian" converters (without automatic BOM handling) are now
|
|
only available via their specific names.</li>
|
|
|
|
<li><a href="http://www.unicode.org/reports/tr26/">CESU-8</a> (while the
|
|
<a href="http://www.unicode.org/reports/tr28/#3_1_conformance">UTF-8 code
|
|
is tightened according to Unicode 3.2</a>)</li>
|
|
|
|
<li><a href=
|
|
"http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/conversion/bocu1/bocu1.html">
|
|
BOCU-1</a> (MIME-compatible compression of Unicode text that preserves
|
|
binary order)</li>
|
|
</ul>
|
|
|
|
<h3>Flexible data loading</h3>
|
|
|
|
<p>ICU 2.2 has an extended search path functionality, more flexible data
|
|
override capabilities, and removes lesser-known heuristics for determining
|
|
the data path.</p>
|
|
|
|
<ul>
|
|
<li>Performance: ICU will only load data from packages, not from single
|
|
files, when the search path is empty. This eliminates all file system
|
|
accesses after the packages (ICU data + application data) are loaded.<br>
|
|
If this is important, then an application should set the search path to
|
|
the empty path during initialization.</li>
|
|
|
|
<li>Customizability: If the search path is not empty, then ICU searches
|
|
for single files before looking in packages, allowing to override/update
|
|
packaged data.</li>
|
|
|
|
<li>User data: The new function ucnv_openPackage allows an application to
|
|
load an ICU character mapping table from its own data. This enables
|
|
applications to support more codepages than the ICU installation that it
|
|
uses.</li>
|
|
|
|
<li>Separation between ICU data and user data: Single data files must now
|
|
always have a package name as prefix, which results in different file
|
|
names between ICU and all application packages even for the same locale
|
|
IDs etc.</li>
|
|
|
|
<li>Multi-path: The search path can now contain multiple folders and can
|
|
list packages directly instead of just a single folder.</li>
|
|
|
|
<li>Predictability: The search path can be set via the ICU_DATA
|
|
environment variable or via the u_setDataDirectory() function.<br>
|
|
ICU does not perform any other heuristics any more.</li>
|
|
</ul>
|
|
|
|
<p><strong>Note:</strong> while some of the old binary data may be still
|
|
readable by ICU 2.2 (resource bundles, for example), they need to be
|
|
repackaged in order to be used.</p>
|
|
|
|
<ul>
|
|
<li>If you have individual binary files, you have to rename them so that
|
|
you prepend a <code>'packagename_'</code>. Then use
|
|
<code>packagename</code> for opening.</li>
|
|
|
|
<li>If you have a memory-mapped package file, you will need to unpack it
|
|
(use decmn tool), rename individual files as above (prepending the
|
|
package name), and repack the files.</li>
|
|
|
|
<li>If you have a shared library file, you'll need to somehow get
|
|
individual files and repackage them.</li>
|
|
</ul>
|
|
|
|
<h3>Customizable memory management</h3>
|
|
|
|
<p>ICU 2.2 libraries do not use the global operators new and delete.
|
|
Instead, all C++ classes are derived from a common base class UObject which
|
|
implements new and delete operators for all of ICU's C++ classes. Users can
|
|
customize the ICU memory allocation by changing the functions in
|
|
source/common/cmemory.c that are used for non-class types and in UObject's
|
|
new and delete operators.</p>
|
|
|
|
<p>This also means that ICU libraries may safely use a different heap than
|
|
the application because all memory is consistently allocated and released
|
|
from within the libraries. On Windows it is now possible to link the
|
|
application with, for example, the static C runtime library even though ICU
|
|
libraries use the DLL-based runtime.</p>
|
|
|
|
<h3>Experimental locales moved to new repository</h3>
|
|
|
|
<p>Experimental locales are ones for which we have incomplete data. Data
|
|
for such locales used to be included in the default ICU download, but have
|
|
been moved to a new <a href=
|
|
"http://oss.software.ibm.com/cvs/icu/locale/icu/experimental/">locale data
|
|
repository</a>, stored as another <a href=
|
|
"http://oss.software.ibm.com/icu/develop/cvs.html">ICU CVS module</a>. This
|
|
data can be added back into a customized ICU build, see the <a href=
|
|
"http://oss.software.ibm.com/icu/userguide/icudata.html">User Guide Data
|
|
chapter</a>. It can also still be viewed with the <a href=
|
|
"http://oss.software.ibm.com/icu/demo/">LocaleExplorer demo</a>.</p>
|
|
<hr>
|
|
|
|
<h2><a name="Download" href="#Download">How To Download the Source
|
|
Code</a></h2>
|
|
|
|
<p>There are two ways to download ICU releases:</p>
|
|
|
|
<ul>
|
|
<li><strong>Official Release Snapshot:</strong><br>
|
|
If you want to use ICU (as opposed to developing it), you should
|
|
download an official packaged version of the ICU source code. These
|
|
versions are tested more thoroughly than day-to-day development builds of
|
|
the system, and they are packaged in zip and tar files for convenient
|
|
download. These packaged files can be found at <a href=
|
|
"http://oss.software.ibm.com/icu/download/">http://oss.software.ibm.com/icu/download/</a>.<br>
|
|
|
|
The packaged snapshots are named <strong>icu-nnnn.zip</strong> or
|
|
<strong>icu-nnnn.tgz</strong>, where nnnn is the version number. The .zip
|
|
file is used for Windows platforms, while the .tgz file is preferred on
|
|
most other platforms.<br>
|
|
Please unzip this file. It will reconstruct the source directory, which
|
|
includes anonymous CVS control directories (see below).</li>
|
|
|
|
<li><strong>CVS Source Repository:</strong><br>
|
|
If you are interested in developing features, patches, or bug fixes for
|
|
ICU, you should probably be working with the latest version of the ICU
|
|
source code. You will need to check the code out of our CVS repository to
|
|
ensure that you have the most recent version of all of the files. See our
|
|
<a href="http://oss.software.ibm.com/icu/develop/cvs.html">CVS page</a>
|
|
for details.</li>
|
|
</ul>
|
|
|
|
<h2><a name="SourceCode" href="#SourceCode">ICU Source Code
|
|
Organization</a></h2>
|
|
|
|
<p>In the descriptions below, <strong><i><ICU></i></strong> is the
|
|
full path name of the icu directory (the top level directory from the
|
|
distribution archives) in your file system. You can also view the <a href=
|
|
"http://oss.software.ibm.com/icu/userguide/design.html">User's Guide</a> to
|
|
see which libraries you need for your software product. You need at least
|
|
the data (<code>[lib]icudt</code>) and the common (<code>[lib]icuuc</code>)
|
|
libraries in order to use ICU.</p>
|
|
|
|
<table border="1" cellpadding="0" width="100%" summary="">
|
|
<caption>
|
|
The following files describe the code drop.
|
|
</caption>
|
|
|
|
<tr>
|
|
<td>readme.html</td>
|
|
|
|
<td>Describes the International Components for Unicode (this file)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>license.html</td>
|
|
|
|
<td>Contains the text of the ICU license</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><br>
|
|
</p>
|
|
|
|
<table border="1" cellpadding="0" width="100%" summary="">
|
|
<caption>
|
|
The following directories contain source code and data files.
|
|
</caption>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>common</b>/</td>
|
|
|
|
<td>The core Unicode and support functionality, such as resource
|
|
bundles, character properties, locales, codepage conversion,
|
|
normalization, Unicode properties, Locale, and UnicodeString.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>i18n</b>/</td>
|
|
|
|
<td>Modules in i18n are generally the more data-driven, that is to say
|
|
resource bundle driven, components. These deal with higher-level
|
|
internationalization issues such as formatting, collation, text break
|
|
analysis, and transliteration.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>data</b>/</td>
|
|
|
|
<td>
|
|
This directory contains the source data in text format, which is
|
|
compiled into binary form during the ICU build process. It contains
|
|
several subdirectories, in which the data files are grouped by
|
|
function. Note that the build process must be run again after any
|
|
changes are made to this directory.
|
|
|
|
<ul>
|
|
<li><b>brkitr/</b> Data files for character, word, sentence, title
|
|
casing and line boundary analysis.</li>
|
|
|
|
<li><b>locales/</b> These .txt files contain ICU language and
|
|
culture-specific localization data. Two special bundles are
|
|
<b>root</b>, which is the fallback data and parent of other
|
|
bundles, and <b>index</b>, which contains a list of installed
|
|
bundles. The makefile <b>resfiles.mk</b> contains the list of
|
|
resource bundle files.</li>
|
|
|
|
<li><b>mappings/</b> Here are the code page converter tables. These
|
|
.ucm files contain mappings to and from Unicode. These are compiled
|
|
into .cnv files. <b>convrtrs.txt</b> is the alias mapping table
|
|
from various converter name formats to ICU internal format and vice
|
|
versa. It produces cnvalias.icu. The makefiles <b>ucmfiles.mk,
|
|
ucmcore.mk,</b> and <b>ucmebcdic.mk</b> contain the list of
|
|
converters to be built.</li>
|
|
|
|
<li><b>translit/</b> This directory contains transliterator rules
|
|
as resource bundles, a makefile <b>trnsfiles.mk</b> containing the
|
|
list of installed system translitaration files, and as well the
|
|
special bundle <b>translit_index</b> which lists the system
|
|
transliterator aliases.</li>
|
|
|
|
<li><b>unidata/</b> This directory contains the Unicode data files.
|
|
Please see <a href=
|
|
"http://www.unicode.org/">http://www.unicode.org/</a> for more
|
|
information.</li>
|
|
|
|
<li><b>misc/</b> The misc directory contains other data files which
|
|
did not fit into the above categories. Currently it only contains
|
|
<b>timezone.txt,</b> a generated file, which is compiled into
|
|
tz.dat. The <b>tz.dat</b> file contains time zone information.</li>
|
|
|
|
<li><b>out/</b> This directory contains the assembled memory mapped
|
|
files.</li>
|
|
|
|
<li><b>out/build/</b> This directory contains intermediate
|
|
(compiled) files, such as .cnv, .res, etc.</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/test/<b>intltest</b>/</td>
|
|
|
|
<td>A test suite including all C++ APIs. For information about running
|
|
the test suite, see the users' guide.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/test/<b>cintltst</b>/</td>
|
|
|
|
<td>A test suite written in C, including all C APIs. For information
|
|
about running the test suite, see the users' guide.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/test/<b>testdata</b>/</td>
|
|
|
|
<td>Source text files for data, which are read by the tests. It
|
|
contains the subdirectories <b>out/build/</b> which is used for
|
|
intermediate files, and <b>out/</b> which contains the files
|
|
<b>test1.cnv</b> through <b>test4.cnv,</b> and <b>testdata.dat.</b>
|
|
Note that the tests call
|
|
u_setDataDirectory("<ICU>/source/test/testdata/lib"), so that ICU
|
|
will load these files as if they were part of the ICU data package, for
|
|
testing purposes. This was formerly accomplished by setting the
|
|
ICU_DATA environment variable to point at these files. ICU_DATA should
|
|
not be set under normal circumstances.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>tools</b>/</td>
|
|
|
|
<td>Tools for generating the data files. Data files are generated by
|
|
invoking <i><ICU></i>/source/data/build/makedata.bat on Win32 or
|
|
<i><ICU></i>/source/make on Unix.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>samples</b>/</td>
|
|
|
|
<td>Various sample programs that use ICU</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>extra</b>/</td>
|
|
|
|
<td>Non-supported API additions. Currently, it contains the 'ustdio'
|
|
file i/o library</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>layout</b>/</td>
|
|
|
|
<td>Contains the ICU layout engine (not a rasterizer).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/<b>packaging</b>/<br>
|
|
<i><ICU></i>/<b>debian</b>/</td>
|
|
|
|
<td>These directories contain scripts and tools for packaging the final
|
|
ICU build for various release platforms.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>config</b>/</td>
|
|
|
|
<td>Contains helper makefiles for platform specific build commands.
|
|
Used by 'configure'.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/source/<b>allinone</b>/</td>
|
|
|
|
<td>Contains top-level ICU workspace and project files, for instance to
|
|
build all of ICU under one MSVC project.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/<b>bin</b>/</td>
|
|
|
|
<td>Contains the libraries and executables for using ICU on
|
|
Windows.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><i><ICU></i>/<b>include</b>/</td>
|
|
|
|
<td>Contains the headers needed for developing software that uses ICU
|
|
on Windows.</td>
|
|
</tr>
|
|
</table>
|
|
<!-- end of ICU structure ==================================== -->
|
|
|
|
<h2><a name="HowToBuild" href="#HowToBuild">How To Build And Install
|
|
ICU</a></h2>
|
|
|
|
<h3><a name="HowToBuildSupported" href="#HowToBuildSupported">Supported
|
|
Platforms</a></h3>
|
|
|
|
<table border="1" cellpadding="3" summary="">
|
|
<caption>
|
|
Here is a status of functionality of ICU on several different
|
|
platforms.
|
|
</caption>
|
|
|
|
<tr>
|
|
<th>Operating system</th>
|
|
|
|
<th>Compiler</th>
|
|
|
|
<th>Testing frequency</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Windows NT/2000/XP</td>
|
|
|
|
<td>Microsoft Visual C++ 6.0</td>
|
|
|
|
<td>Reference platform</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Red Hat Linux 7.2</td>
|
|
|
|
<td>gcc 2.96</td>
|
|
|
|
<td>Reference platform</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>AIX 5.1.0 L</td>
|
|
|
|
<td>Visual Age C++ 5.0</td>
|
|
|
|
<td>Reference platform</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Solaris 7 (SunOS 5.7)</td>
|
|
|
|
<td>Workshop Pro CC 6.0</td>
|
|
|
|
<td>Reference platform</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>HP/UX 11.01</td>
|
|
|
|
<td>aCC A.12.10</td>
|
|
|
|
<td>Reference platform</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Windows 98</td>
|
|
|
|
<td>Microsoft Visual C++ 6.0</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>AIX 4.3.3</td>
|
|
|
|
<td>xlC_r 3.6.6</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Solaris 8 (SunOS 5.8)</td>
|
|
|
|
<td>Workshop Pro CC 4.2</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Solaris 7 (SunOS 5.7)</td>
|
|
|
|
<td>Workshop Pro CC 4.2</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Solaris 2.6 (SunOS 5.6)</td>
|
|
|
|
<td>gcc 2.95.2</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>FreeBSD 4.4</td>
|
|
|
|
<td>gcc 2.95.3</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Mac OS X (10.1)</td>
|
|
|
|
<td>gcc-932.1, based on gcc version 2.95.2<br>
|
|
(Developer Tools December 2001)</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>z/OS 1.2</td>
|
|
|
|
<td>cxx 1.2</td>
|
|
|
|
<td>Regularly tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>HP/UX 11.01</td>
|
|
|
|
<td>CC A.03.10</td>
|
|
|
|
<td>Rarely tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>AS/400 (iSeries) V5R1</td>
|
|
|
|
<td>iCC</td>
|
|
|
|
<td>Rarely tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>NetBSD, OpenBSD</td>
|
|
|
|
<td> </td>
|
|
|
|
<td>Rarely tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>SGI/IRIX</td>
|
|
|
|
<td> </td>
|
|
|
|
<td>Rarely tested</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Tru64 (OSF)</td>
|
|
|
|
<td>Compaq's cxx compiler</td>
|
|
|
|
<td>Rarely tested</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><br>
|
|
</p>
|
|
|
|
<p><strong>Key to testing frequency</strong></p>
|
|
|
|
<dl>
|
|
<dt><i>Reference platform</i></dt>
|
|
|
|
<dd>ICU will work on these platforms with these compilers</dd>
|
|
|
|
<dt><i>Regularly tested</i></dt>
|
|
|
|
<dd>ICU should work on these platforms with these compilers</dd>
|
|
|
|
<dt><i>Rarely tested</i></dt>
|
|
|
|
<dd>ICU has been ported to these platforms but may not have been tested
|
|
there recently</dd>
|
|
</dl>
|
|
|
|
<h3><a name="HowToBuildWindows" href="#HowToBuildWindows">How To Build And
|
|
Install On Windows</a></h3>
|
|
|
|
<p>Building International Components for Unicode requires:</p>
|
|
|
|
<ul>
|
|
<li>Microsoft NT 4.0 and above, or Windows 98 and above</li>
|
|
|
|
<li>Microsoft Visual C++ 6.0 (Service Pack 2 is required to work with the
|
|
release build of max speed optimization).</li>
|
|
</ul>
|
|
|
|
<p>(If you want to build with Microsoft Visual C++ .NET, please refer to
|
|
the <a href="#HowToBuildWindowsDotNet">note about building with Visual
|
|
Studio .NET</a> below.)</p>
|
|
|
|
<p>The steps are:</p>
|
|
|
|
<ol>
|
|
<li>Unzip the icu-XXXX.zip file into any convenient location. Using
|
|
command line zip, type "unzip -a icu-XXXX.zip -d drive:\directory", or
|
|
just use WinZip.</li>
|
|
|
|
<li>Be sure that the ICU binary directory, <i><ICU></i>\bin\, is
|
|
included in the <strong>PATH</strong> environment variable. The tests
|
|
will not work without the location of the ICU dll files in the path.</li>
|
|
|
|
<li>Set the <strong>TZ</strong> environment variable to
|
|
<strong>PST8PDT</strong>. The tests will not work in any other time
|
|
zone.</li>
|
|
|
|
<li>Open the "<i><ICU></i>\source\allinone\allinone.dsw" workspace
|
|
file in Microsoft Visual C++ 6.0. (This workspace includes all the
|
|
International Components for Unicode libraries, necessary ICU building
|
|
tools, and the intltest and cintltest test suite projects). Please see
|
|
the note below if you want to build from the command line instead.</li>
|
|
|
|
<li>Set the active Project to the "all" project. To do this: Choose
|
|
"Project" menu, and select "Set active project". In the submenu, select
|
|
the "all" workspace.</li>
|
|
|
|
<li>Set the active configuration to "Win32 Debug" or "Win32 Release" (See
|
|
<a href="#HowToBuildWindowsConfig">note</a> below).</li>
|
|
|
|
<li>Choose the "Build" menu and select "Rebuild All". If you want to
|
|
build the Debug and Release at the same time, see the <a href=
|
|
"#HowToBuildWindowsBatch">note</a> below.</li>
|
|
|
|
<li>Run the C++ test suite, "intltest". To do this: set the active
|
|
project to "intltest", and press F5 to run it.</li>
|
|
|
|
<li>Run the C test suite, "cintltst". To do this: set the active project
|
|
to "cintltst", and press F5 to run it.</li>
|
|
|
|
<li>Make sure that both "cintltst" and "intltest" passed without any
|
|
errors. The return codes are non-zero when they do not pass. Visual C++
|
|
will display the return codes in the debug tag of the output window. When
|
|
"intltest" and "cintltest" return 0, it means that everything is
|
|
installed correctly. You can press Ctrl+F5 on the test project to run the
|
|
test and see what error messages were displayed (if any tests
|
|
failed).</li>
|
|
|
|
<li>Reset the <strong>TZ</strong> environment variable to its original
|
|
value, unless you plan on testing ICU any further.</li>
|
|
|
|
<li>You are now able to develop applications with ICU by using the
|
|
libraries and tools in <i><ICU></i>\bin\. The headers are in
|
|
<i><ICU></i>\include\ and the link libraries are in
|
|
<i><ICU></i>\lib\. To install the ICU runtime on a machine, or ship
|
|
it with your application, copy the needed components from
|
|
<i><ICU></i>\bin\ to a location on the system PATH or to your
|
|
application directory.</li>
|
|
</ol>
|
|
|
|
<p><a name="HowToBuildWindowsCommandLine"><strong>Using MSDEV At The
|
|
Command Line Note:</strong></a> You can build ICU from the command line.
|
|
Assuming that you have properly installed Microsoft Visual C++ to support
|
|
command line execution, you can run the following command, 'msdev
|
|
<i><ICU></i>\source\allinone\allinone.dsw /MAKE "ALL"'.</p>
|
|
|
|
<p><a name="HowToBuildWindowsConfig"><strong>Setting Active Configuration
|
|
Note:</strong></a> To set the active configuration, two different
|
|
possibilities are:</p>
|
|
|
|
<ul>
|
|
<li>Choose "Build" menu, select "Set Active Configuration", and select
|
|
"Win32 Release" or "Win32 Debug".</li>
|
|
|
|
<li>Another way is to select "Customize" in the "Tools" menu, select the
|
|
"Toolbars" tab, enable "Build" instead of "Build Minibar", and click on
|
|
"Close". This will bring up a toolbar which you can move aside the other
|
|
permanent toolbars at the top of the MSVC window. The advantage is that
|
|
you now have an easy-to-reach pop-up menu that will always show the
|
|
currently selected active configuration. Or, you can drag the project and
|
|
configuration selections and drop them on the menu bar for later
|
|
selection.</li>
|
|
</ul>
|
|
|
|
<p><a name="HowToBuildWindowsBatch"><strong>Batch Configuration
|
|
Note:</strong></a> If you want to build the Debug and Release
|
|
configurations at the same time, choose "Build" menu and select "Batch
|
|
Build..." instead (and mark all configurations as checked), then click the
|
|
button named "Rebuild All". The "all" workspace will build all the
|
|
libraries, test programs and various ICU tools (e.g. genrb for generating
|
|
binary locale data files).</p>
|
|
|
|
<p><a name="HowToBuildWindowsDotNet"><strong>Microsoft Visual Studio .NET
|
|
Note:</strong></a> ICU will build with Microsoft Visual Studio .NET, though
|
|
this is not a supported platform at the time of this writing. Visual Studio
|
|
.NET will offer to convert the project files when you open the existing
|
|
workspace file. Choose "Yes to All" in the dialog asking whether to convert
|
|
the files or not (this creates new files) and then follow the rest of the
|
|
build instructions.</p>
|
|
|
|
<h3><a name="HowToBuildWindowsXP64" href="#HowToBuildWindowsXP64">How To
|
|
Build And Install On Windows XP on IA64</a></h3>
|
|
|
|
<p>Building International Components for Unicode requires:</p>
|
|
|
|
<ul>
|
|
<li>Microsoft XP on an IA64 (Itanium®) machine</li>
|
|
|
|
<li>Microsoft Visual C++ 6.0 (Service Pack 2 is required to work with the
|
|
release build of max speed optimization).</li>
|
|
|
|
<li>Microsoft Platform SDK.</li>
|
|
</ul>
|
|
|
|
<p>The steps are:</p>
|
|
|
|
<ol>
|
|
<li>Follow steps 1-3 in the <a href="#HowToBuildWindows">in the previous
|
|
section</a>.</li>
|
|
|
|
<li>Open the "Set Windows XP 64-bit Build Environment (Retail)" command
|
|
window from the Microsoft Platform SDK.</li>
|
|
|
|
<li>Use cd to get into the <i><ICU></i> directory.</li>
|
|
|
|
<li>Run this command: 'msdev /USEENV
|
|
<i><ICU></i>\source\allinone\allinone.dsw /MAKE "all - Win64
|
|
Release"'</li>
|
|
|
|
<li>Run "cd source\test\intltest\Release"</li>
|
|
|
|
<li>Run the C++ test suite, "intltest". There should be no errors.</li>
|
|
|
|
<li>Run "cd ..\..\cintltst\Release"</li>
|
|
|
|
<li>Run the C test suite, "cintltst". There should be no errors.</li>
|
|
|
|
<li>Follow the last two steps in the <a href="#HowToBuildWindows">in the
|
|
previous section</a>.</li>
|
|
</ol>
|
|
|
|
<h3><a name="HowToBuildUnix" href="#HowToBuildUnix">How To Build And
|
|
Install On Unix</a></h3>
|
|
|
|
<p>Building International Components for Unicode on Unix requires:</p>
|
|
|
|
<ul>
|
|
<li>A C++ compiler installed on the target machine (for example: gcc, CC,
|
|
xlC_r, aCC, cxx, etc...).</li>
|
|
|
|
<li>An ANSI C compiler installed on the target machine (for example:
|
|
cc).</li>
|
|
|
|
<li>A recent version of GNU make (3.77+).</li>
|
|
|
|
<li>For a list of z/OS tools please view the <a href=
|
|
"#HowToBuildZOS">z/OS build section</a> of this document for further
|
|
details.</li>
|
|
</ul>
|
|
|
|
<p>Here are the steps to build ICU:</p>
|
|
|
|
<ol>
|
|
<li>Decompress the icuXXXX.tar (or icuXXXX.tgz) file. For example,
|
|
<tt>gunzip -d < icuXXXX.tgz | tar xvf -</tt></li>
|
|
|
|
<li>Change directory to the "icu/source".</li>
|
|
|
|
<li>Run "chmod +x runConfigureICU configure install-sh" because these
|
|
files may have the wrong permissions.</li>
|
|
|
|
<li>Run the <a href="source/runConfigureICU">runConfigureICU</a> script
|
|
for your platform. (See <a href="#HowToConfigureICU">note</a>
|
|
below).</li>
|
|
|
|
<li>Type "gmake" (or "make" if GNU make is the default make on your
|
|
platform) to compile the libraries and all the data files. The proper
|
|
name of the GNU make command is printed at the end of the configuration
|
|
run, as in "You must use gmake to compile ICU".</li>
|
|
|
|
<li>Optionally, type "gmake check" (or "make check") to run the test
|
|
suite, which checks for ICU's functionality integrity (See <a href=
|
|
"#HowToTestWithoutGmake">note</a> below).</li>
|
|
|
|
<li>Type "gmake install" (or "make install") to install. The install
|
|
targets support the use of the DESTDIR variable to create the
|
|
installation tree under a specific destination directory. (See <a href=
|
|
"#HowToInstallICU">note</a> below).</li>
|
|
</ol>
|
|
|
|
<p><a name="HowToConfigureICU"><strong>Configuring ICU NOTE:</strong></a>
|
|
Type "./runConfigureICU --help" for help on how to run it and a list of
|
|
supported platforms. You may also want to type "./configure --help" to
|
|
print the available configure options that you may want to give
|
|
runConfigureICU. If you are not using the runConfigureICU script, or your
|
|
platform is not supported by the script, you may need to set your CC,CXX,
|
|
CFLAGS and CXXFLAGS environment variables, and type "./configure". Some of
|
|
the more frequently used options to configure are --disable-64bit-libs to
|
|
create 32-bit libraries, and --srcdir to do out of source builds (build the
|
|
libraries in the current location).</p>
|
|
|
|
<p><a name="HowToTestWithoutGmake"><strong>Running The Tests From The
|
|
Command Line NOTE:</strong></a> You may have to set certain variables if
|
|
you with to run test programs individually, that is apart from "make
|
|
check". The <strong>TZ</strong> environment variable needs to be set to
|
|
<strong>PST8PDT</strong>. Also, the environment variable
|
|
<strong>ICU_DATA</strong> can be set to the full pathname of the data
|
|
directory to indicate where the locale data files and conversion mapping
|
|
tables are when you are not using the shared library (e.g. by using the
|
|
.dat archive or the individual data files). The trailing "/" is required
|
|
after the directory name (e.g. "$Root/source/data/" will work, but the
|
|
value "$Root/source/data" is not acceptable). You do not need to set
|
|
<strong>ICU_DATA</strong> if the complete data library is in your library
|
|
path.</p>
|
|
|
|
<p><a name="HowToInstallICU"><strong>Installing ICU NOTE:</strong></a> If
|
|
you are using the "gmake install" command, using the "--prefix" option on
|
|
configure or runConfigureICU will install ICU to the specified
|
|
location.</p>
|
|
|
|
<p>Some platforms use package management tools to control the installation
|
|
and uninstallation of files on the system, as well as the integrity of the
|
|
system configuration. You may want to check if ICU can be packaged for your
|
|
package management tools by looking into the "packaging" directory. (Please
|
|
note that if you are using a snapshot of ICU from CVS, it is probable that
|
|
the packaging scripts or related files are not up to date with the contents
|
|
of ICU at this time, so use them with caution).</p>
|
|
|
|
<h3><a name="HowToBuildZOS" href="#HowToBuildZOS">How To Build And Install
|
|
On z/OS (OS/390)</a></h3>
|
|
|
|
<p>You can install ICU on z/OS or OS/390 (the previous name of z/OS), but
|
|
IBM tests only the z/OS installation. These platforms commonly are called
|
|
"MVS". You install ICU in a z/OS UNIX system services file system such as
|
|
HFS or zFS. On this platform, it is important that you understand a few
|
|
details:</p>
|
|
|
|
<ul>
|
|
<li>APAR PQ58392 may be needed by z/OS 1.2 or 1.3 in order to get some
|
|
ICU number formatting functions to work properly. The APAR affects C and
|
|
C++ code.</li>
|
|
|
|
<li>The gnu utilities gmake and gzip/gunzip are needed and can be
|
|
obtained for z/OS from <a href=
|
|
"http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc">
|
|
z/OS Unix - Tools and Toys</a>. Documentation on these tools can be found
|
|
at the <a href=
|
|
"http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg245944.html">
|
|
Open Source Software for z/OS UNIX</a> Red Book.</li>
|
|
|
|
<li>Encoding considerations: The source code assumes that it is compiled
|
|
with codepage ibm-1047 (to be exact, the UNIX System Services variant of
|
|
it). The pax command converts all of the source code files from ASCII to
|
|
codepage ibm-1047 (USS) EBCDIC. However, some files are binary files and
|
|
must not be converted, or must be converted back to their original state.
|
|
You can use the <a href="as_is/os390/unpax-icu.sh">unpax-icu.sh</a>
|
|
script to do this for you automatically. It will unpackage the tar file
|
|
and convert all the necessary files for you automatically.</li>
|
|
|
|
<li>
|
|
<p>z/OS supports both native S/390 hexadecimal floating point and,
|
|
(with OS/390 2.6 and later) IEEE binary floating point. This is a
|
|
compile time option. Applications built with IEEE should use ICU dlls
|
|
that are built with IEEE (and vice versa). The environment variable
|
|
IEEE390=1 will cause the z/OS version of ICU to be built with IEEE
|
|
floating point. The default is native hexadecimal floating point.<br>
|
|
<em>Important:</em> Currently (ICU 1.4.2), native floating point
|
|
support is sufficient for codepage conversion, resource bundle and
|
|
UnicodeString operations, but the Format APIs, especially ChoiceFormat,
|
|
require IEEE binary floating point.</p>
|
|
|
|
<p>Examples for configuring ICU:<br>
|
|
Debug build: <code>IEEE390=1 ./runConfigureICU --enable-debug
|
|
zOS/cxx</code><br>
|
|
Release build: <code>IEEE390=1 ./runConfigureICU zOS/cxx</code></p>
|
|
</li>
|
|
|
|
<li>Since the default make on z/OS is not gmake, the pkgdata tool
|
|
requires that the "make" command is aliased to your installed version of
|
|
gmake. You may also need to set $MAKE equal to the fully-qualified path
|
|
of GNU make. GNU make is available with the "z/OS Unix - Tools and Toys"
|
|
that was mentioned above. The required version is the same Unix build
|
|
instructions.</li>
|
|
|
|
<li>The makedep executable that is used with the z/OS ICU build process
|
|
is not shipped with ICU. It is available at the <a href=
|
|
"http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc">
|
|
z/OS Unix - Tools and Toys</a> site. The PATH environment variable should
|
|
be updated to contain the location of this executable prior to build.
|
|
Alternatively, makedep may be moved into an existing PATH directory.</li>
|
|
|
|
<li>The rest of the instructions for building and testing ICU on z/OS
|
|
with Unix System Services are the same as the <a href=
|
|
"#HowToBuildUnix">How To Build And Install On Unix</a> section.</li>
|
|
</ul>
|
|
|
|
<h4>z/OS (Batch/PDS) support outside the UNIX system services
|
|
environment</h4>
|
|
|
|
<p>By default, ICU builds its libraries into the UNIX file system (HFS). In
|
|
addition, there is a z/OS specific environment variable (OS390BATCH) to
|
|
build some libraries into the z/OS native file system. This is useful, for
|
|
example, when your application is externalized via Job Control Language
|
|
(JCL).</p>
|
|
|
|
<p>The OS390BATCH environment variable enables non-UNIX support including
|
|
the batch environment. When OS390BATCH is set, the libicuuc<i>XX</i>.dll,
|
|
libicudt<i>XX</i>e.dll, and libicudt<i>XX</i>e_stub.dll binaries are built
|
|
into data sets (the native file system). Turning on OS390BATCH does not
|
|
turn off the normal z/OS UNIX build. This means that the The z/OS UNIX
|
|
(HFS) dlls will always be created.</p>
|
|
|
|
<p>Two additional environment variables indicate the names of the z/OS data
|
|
sets to use. The LOADMOD environment variable identifies the name of the
|
|
data set that contains the dynamic link libraries (DLLs) and the LOADEXP
|
|
environment variable identifies the name of the data set that contains the
|
|
side decks, which are normally the files with the .x suffix in the UNIX
|
|
file system.</p>
|
|
|
|
<p>A data set is roughly equivalent to a UNIX or Windows file. For most
|
|
kinds of data sets the operating system maintains record boundaries. UNIX
|
|
and Windows files are byte streams. Two kinds of data sets are PDS and
|
|
PDSE. Each data set of these two types contains a directory. It is like a
|
|
UNIX directory. Each "file" is called a "member". Each member name is
|
|
limited to eight bytes, normally EBCDIC.</p>
|
|
|
|
<p>Here is an example of some environment variables that you can set prior
|
|
to building ICU:</p>
|
|
<pre>
|
|
<samp>OS390BATCH=1
|
|
LOADMOD=<i>USER</i>.ICU.LOAD
|
|
LOADEXP=<i>USER</i>.ICU.EXP</samp>
|
|
</pre>
|
|
|
|
<p>The PDS member names for the DLL file names are as follows:</p>
|
|
<pre>
|
|
<samp>IXMI<i>XX</i>UC --> libicuuc<i>XX</i>.dll
|
|
IXMI<i>XX</i>DA --> libicudt<i>XX</i>e.dll
|
|
IXMI<i>XX</i>D1 --> libicudt<i>XX</i>e_stub.dll <i>(Only when OS390_STUBDATA=1)</i></samp>
|
|
</pre>
|
|
|
|
<p>You should point the LOADMOD environment variable at a partitioned data
|
|
set extended (PDSE) and point the LOADEXP environment variable at a
|
|
partitioned data set (PDS). The PDSE can be allocated with the following
|
|
attributes:</p>
|
|
<pre>
|
|
<samp>Data Set Name . . . : <i>USER</i>.ICU.LOAD
|
|
Management class. . : <i>**None**</i>
|
|
Storage class . . . : <i>BASE</i>
|
|
Volume serial . . . : <i>TSO007</i>
|
|
Device type . . . . : <i>3390</i>
|
|
Data class. . . . . : LOAD
|
|
Organization . . . : PO
|
|
Record format . . . : U
|
|
Record length . . . : 0
|
|
Block size . . . . : 32760
|
|
1st extent cylinders: 1
|
|
Secondary cylinders : 5
|
|
Data set name type : LIBRARY</samp>
|
|
</pre>
|
|
|
|
<p>The PDS can be allocated with the following attributes:</p>
|
|
<pre>
|
|
<samp>Data Set Name . . . : <i>USER</i>.ICU.EXP
|
|
Management class. . : <i>**None**</i>
|
|
Storage class . . . : <i>BASE</i>
|
|
Volume serial . . . : <i>TSO007</i>
|
|
Device type . . . . : <i>3390</i>
|
|
Data class. . . . . : <i>**None**</i>
|
|
Organization . . . : PO
|
|
Record format . . . : FB
|
|
Record length . . . : 80
|
|
Block size . . . . : <i>3200</i>
|
|
1st extent cylinders: 3
|
|
Secondary cylinders : 3
|
|
Data set name type : PDS</samp>
|
|
</pre>
|
|
|
|
<h3><a name="HowToBuildOS400" href="#HowToBuildOS400">How To Build And
|
|
Install On OS/400 (iSeries)</a></h3>
|
|
|
|
<p>ICU Reference Release 2.2 contains partial support for the iSeries
|
|
platform. After building ICU and running the tests, you will notice that
|
|
some of the multthread and formatting tests fail. The SPAWN CL command will
|
|
allow the multithread tests in the intltest test suite to run successfully.
|
|
The formating failures can be ignored for now. These failures are expected
|
|
to be resolved in a future release of ICU.</p>
|
|
|
|
<p>The following describes how to setup and build ICU.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Requirements:
|
|
|
|
<ul>
|
|
<li>QSHELL interpreter installed (install base option 30, operating
|
|
system)</li>
|
|
<!--li>QShell Utilities, PRPQ 5799-XEH (not required for V4R5)</li-->
|
|
|
|
<li>ILE C/C++ Compiler for iSeries, LPP 5722-WDS</li>
|
|
|
|
<li>The latest GNU facilities (You can get the GNU facilities for
|
|
OS/400 from <a href=
|
|
"http://www.as400.ibm.com/developer/factory/porting/gnu_utilities.html">http://www.as400.ibm.com/developer/factory/porting/gnu_utilities.html</a>).
|
|
Older versions may not work properly.</li>
|
|
</ul>
|
|
<!-- end requirements -->
|
|
</li>
|
|
|
|
<li>
|
|
Build environment setup:
|
|
|
|
<ol>
|
|
<li>
|
|
Create AS400 target library. This library will be the target for
|
|
the resulting modules, programs and service programs. You will
|
|
specify this library on the OUTPUTDIR environment variable in step
|
|
2.<br>
|
|
|
|
<pre>
|
|
<samp>CRTLIB LIB(<i>libraryname</i>)</samp>
|
|
</pre>
|
|
<br>
|
|
</li>
|
|
|
|
<li>
|
|
Set up the following environment variables in your build process
|
|
(use the <i>libraryname</i> from the previous step)
|
|
<pre>
|
|
<samp>ADDENVVAR ENVVAR(CC) VALUE('/usr/bin/icc')
|
|
ADDENVVAR ENVVAR(CXX) VALUE('/usr/bin/icc')
|
|
ADDENVVAR ENVVAR(MAKE) VALUE('/usr/bin/gmake')
|
|
ADDENVVAR ENVVAR(OUTPUTDIR) VALUE('<i>libraryname</i>')</samp>
|
|
</pre>
|
|
<i>libraryname</i> identifies target as400 library for *module,
|
|
*pgm and *srvpgm objects.<br>
|
|
<br>
|
|
</li>
|
|
<!--li>Add QCXXN, to your build process library list. This results in the resolution of CRTCPPMOD used by the icc compiler</li-->
|
|
|
|
<li>
|
|
In order to get the tests to run correctly, the QUTCOFFSET needs to
|
|
be set to the Pacific Time Zone offset.<br>
|
|
<br>
|
|
To check your QUTCOFFSET:
|
|
<pre>
|
|
<samp>DSPSYSVAL SYSVAL(QUTCOFFSET)</samp>
|
|
</pre>
|
|
<br>
|
|
To change your QUTCOFFSET:<br>
|
|
<pre>
|
|
<samp>CHGSYSVAL SYSVAL(QUTCOFFSET) VALUE('-0800')</samp>
|
|
</pre>
|
|
You should change -0800 to -0700 for daylight savings.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Run 'CHGJOB CCSID(37)'</li>
|
|
|
|
<li>Run 'QSH'</li>
|
|
|
|
<li>Run gunzip on the ICU source code compressed tar archive
|
|
(icu-<i>X</i>-<i>Y</i>.tar.gz or icu-<i>X</i>-<i>Y</i>.tgz).</li>
|
|
|
|
<li>Run unpax-icu.sh on the tar file from the ICU download page.</li>
|
|
|
|
<li>Change your current directory to icu/source.</li>
|
|
|
|
<li>Run 'cp ../as_is/os400/configure .'</li>
|
|
|
|
<li>Run './configure --host=as400-os400
|
|
--with-data-packaging=archive'</li>
|
|
|
|
<li>Run 'gmake -e'. The '-e' option is needed to pickup the
|
|
compilers.</li>
|
|
|
|
<li>Run 'gmake -e check' to run the tests.</li>
|
|
</ol>
|
|
<!-- end build environment -->
|
|
</li>
|
|
</ul>
|
|
|
|
<h2><a name="MakeICUSmaller">How to Make ICU Smaller</a></h2>
|
|
|
|
<p>For some environments, ICU "is too large". There are two ways
|
|
to remove parts and make it smaller: Remove some of its library code modules
|
|
from the build (reducing functionality), or remove some of its data
|
|
(possibly reducing only codepage/locale/etc. coverage without sacrifycing
|
|
overall functionality). For details about reducing the data size see the <a href="http://oss.software.ibm.com/icu/userguide/">User
|
|
Guide</a> "ICU Data" chapter.</p>
|
|
|
|
<p>The header file <code>source/common/unicode/uconfig.h</code> contains
|
|
source-code-level "switches" corresponding to <code>#if</code>
|
|
directives in the ICU source code. Setting one of the <code>UCONFIG_NO_...</code>
|
|
switches to 1 (by setting <code>CFLAGS/CPPFLAGS</code> or adding a <code>#define</code>
|
|
at the beginning of <code>uconfig.h</code>) turns off the code associated
|
|
with one of the ICU service modules. Setting one of the <code>UCONFIG_ONLY_...</code>
|
|
switches to 1 turns off all modules that are not essential for the
|
|
functioning of the associated "only" service. For the current set
|
|
of available switches see <code>uconfig.h</code> itself.</p>
|
|
|
|
<p>When a source code module is turned off, then the data-building makefiles
|
|
should be modified to not generate the data files that are used with that
|
|
module. Some of the data-generating genxyz tools rely on the module itself
|
|
to build its data; they will generate dummy data files to satisfy the
|
|
dependencies of the unmodified makefiles (to make these switches easily
|
|
testable). Other data files for which the tools do not rely on the related
|
|
library modules (e.g., mapping tables [<code>.cnv</code>] and transliterator
|
|
files [<code>.res</code>, from <code>source/data/translit/</code>]) continue
|
|
to be built unless the data makefiles are modified. For further details on
|
|
data building see the <a href="http://oss.software.ibm.com/icu/userguide/">User
|
|
Guide</a> "ICU Data" chapter.</p>
|
|
|
|
<h2><a name="ImportantNotes" href="#ImportantNotes">Important Notes About
|
|
Using ICU</a></h2>
|
|
|
|
<h3><a name="ImportantNotesCPlusPlus" href="#ImportantNotesCPlusPlus">Using
|
|
ICU in a Multithreaded Environment</a></h3>
|
|
|
|
<p>If you are using ICU in a multithreaded application, there may be a
|
|
chance that the ICU global mutex is not initialized properly. Normally the
|
|
ICU global mutex is initialized during C++ static initialization, but there
|
|
are some compilers and linkers that do not properly perform C++ static
|
|
initialization in a library (this sometimes happens on HP/UX and on MacOS
|
|
X).</p>
|
|
|
|
<p>Upon the first usage of most ICU APIs, the global mutex will get
|
|
initialized. For example, you could call uloc_countAvailable() or
|
|
uloc_getDefault() from your main() function before any threads are created.
|
|
Those functions will initialize the global mutex. Without one of these
|
|
function calls from a single thread, the data caches inside ICU may get
|
|
initialized more than once, which may cause memory leaks and other
|
|
problems. This problem normally does not happen when C++ static
|
|
initialization works properly.</p>
|
|
|
|
<p>ICU does not use C++ static initialization for anything else, and
|
|
disabling threads in ICU will disable all C++ static initialization in
|
|
ICU.</p>
|
|
|
|
<h3><a name="ImportantNotesBinaryCompat" href=
|
|
"#ImportantNotesBinaryCompat">Binary Compatibility</a></h3>
|
|
|
|
<p>Even though the ICU development team tries to make a stable API, some
|
|
breaking changes are required from time to time. ICU does not guarentee
|
|
binary compatibility of its functions or its data between releases. Please
|
|
view the <a href=
|
|
"http://oss.software.ibm.com/icu/userguide/design.html">ICU Design</a>
|
|
chapter of the User's Guide for details.</p>
|
|
|
|
<h3><a name="ImportantNotesWindows" href="#ImportantNotesWindows">Windows
|
|
Platform</a></h3>
|
|
|
|
<p>If you are building on the Win32 platform, it is important that you
|
|
understand a few of the following build details.</p>
|
|
|
|
<h4>DLL directories and the PATH setting</h4>
|
|
|
|
<p>As delivered, the International Components for Unicode build as several
|
|
DLLs, which are placed in the "<i><ICU></i>\bin" directory. You must
|
|
add this directory to the PATH environment variable in your system, or any
|
|
executables you build will not be able to access International Components
|
|
for Unicode libraries. Alternatively, you can copy the DLL files into a
|
|
directory already in your PATH, but we do not recommend this. You can wind
|
|
up with multiple copies of the DLL and wind up using the wrong one.</p>
|
|
|
|
<h4><a name="ImportantNotesWindowsPath">Changing your PATH</a></h4>
|
|
|
|
<ul>
|
|
<li><strong>Windows 2000</strong>: Use the System Icon in the Control
|
|
Panel. Pick the "Advanced" tab. Select the "Environment Variables..."
|
|
button. Select the variable PATH in the lower box, and select the lower
|
|
"Edit..." button. In the "Variable Value" box, append the string
|
|
";<i><ICU></i>\bin" to the end of the path string. If there is
|
|
nothing there, just type in "<i><ICU></i>\bin". Click the Set
|
|
button, then the OK button.</li>
|
|
|
|
<li><strong>Windows NT</strong>: Use the System Icon in the Control
|
|
Panel. Pick the "Environment" tab, and select the variable PATH in the
|
|
lower box. In the "value" box, append the string
|
|
";<i><ICU></i>\bin" at the end of the path string. If there is
|
|
nothing there, just type in "<i><ICU></i>\bin". Click the Set
|
|
button, then the OK button.</li>
|
|
|
|
<li><strong>Windows 95/98/ME</strong>: Edit the autoexec.bat, and add the
|
|
following line to the end of file, "SET
|
|
PATH=%PATH%;<i><ICU></i>\bin"</li>
|
|
</ul>
|
|
|
|
<p>Note: When packaging a Windows application for distribution and
|
|
installation on user systems, copies of the ICU DLLs should be included
|
|
with the application, and installed for exclusive use by the application.
|
|
This is the only way to insure that your app is running with the same
|
|
version of ICU, built with exactly the same options, that you developed and
|
|
tested with. Refer to Microsoft's guidelines on the usage of DLLs, or
|
|
search for the phrase "DLL hell" on <a href=
|
|
"http://msdn.microsoft.com/">msdn.microsoft.com</a>.</p>
|
|
|
|
<h4>Linking with Runtime libraries</h4>
|
|
|
|
<p>All the DLLs link with the C runtime library "Debug Multithreaded DLL"
|
|
or "Multithreaded DLL." (This is changed through the Project Settings
|
|
dialog, on the C/C++ tab, under Code Generation.) It is important that any
|
|
executable or other DLL you build which uses the International Components
|
|
for Unicode DLLs links with these runtime libraries as well. If you do not
|
|
do this, you will get random memory errors when you run the executable.<br>
|
|
</p>
|
|
|
|
<h3><a name="ImportantNotesUnix" href="#ImportantNotesUnix">Unix Type
|
|
Platform</a></h3>
|
|
|
|
<p>If you are building on a Unix platform, and if you are installing ICU in
|
|
a non-standard location, you may need to add the location of your ICU
|
|
libraries to your <strong>LD_LIBRARY_PATH</strong> or
|
|
<strong>LIBPATH</strong> environment variable (or the equivalent runtime
|
|
library path environment variable for your system). The ICU libraries may
|
|
not link or load properly without doing this.</p>
|
|
|
|
<p>Note that if you do not want to have to set this variable, you may
|
|
instead use the --enable-rpath option at configuration time. This option
|
|
will instruct the linker to always look for the libraries where they are
|
|
installed. You will need to use the appropriate linker options when linking
|
|
your own applications and libraries against ICU, too. Please refer to your
|
|
system's linker manual for information about runtime paths. The use of
|
|
rpath also means that when building a new version of ICU you should not
|
|
have an older version installed in the same place as the new version's
|
|
installation directory, as the older libraries will used during the build,
|
|
instead of the new ones, likely leading to an incorrectly build ICU. (This
|
|
is the proper behavior of rpath.)</p>
|
|
|
|
<h3><a name="ImportantNotesDefaultCP" href="#ImportantNotesDefaultCP">Using
|
|
the default codepage</a></h3>
|
|
|
|
<p>ICU has code to determine the default codepage of the system or process.
|
|
This default codepage can be used to convert <code>char *</code> strings to
|
|
and from Unicode.</p>
|
|
|
|
<p>Depending on system design, setup and APIs, it may not always be
|
|
possible to find a default codepage that fully works as expected. For
|
|
example,</p>
|
|
|
|
<ul>
|
|
<li>On Windows there are three encodings in use at the same time. Unicode
|
|
(UTF-16) is always used inside of Windows, while for <code>char *</code>
|
|
encodings there are two classes, called "ANSI" and "OEM" codepages. ICU
|
|
will use the ANSI codepage. Note that the OEM codepage is used by default
|
|
for console window output.</li>
|
|
|
|
<li>On some Unix-type systems, non-standard names are used for encodings,
|
|
or non-standard encodings are used altogether. Although ICU supports 200
|
|
encodings in its standard build and many more aliases for them, it will
|
|
not be able to recognize such non-standard names.</li>
|
|
|
|
<li>Some systems do not have a notion of a system or process codepage,
|
|
and may not have APIs for that.</li>
|
|
</ul>
|
|
|
|
<p>If you have means of detecting a default codepage name that are more
|
|
appropriate for your application, then you should set that name with
|
|
<code>ucnv_setDefaultName()</code> as the first ICU function call. This
|
|
makes sure that the internally cached default converter will be
|
|
instantiated from your preferred name.</p>
|
|
|
|
<p>Starting in ICU 2.0, when a converter for the default codepage cannot be
|
|
opened, a fallback default codepage name and converter will be used. On
|
|
most platforms, this will be US-ASCII. For z/OS (OS/390), ibm-1047-s390 is
|
|
the default fallback codepage. For AS/400 (iSeries), ibm-37 is the default
|
|
fallback codepage. This default fallback codepage is used when the
|
|
operating system is using a non-standard name for a default codepage, or
|
|
the converter was not packaged with ICU. The feature allows ICU to run in
|
|
unusual computing environments without completely failing.</p>
|
|
|
|
<h3><a name="ImportantNotesDeprecatedAPI" href=
|
|
"#ImportantNotesDeprecatedAPI">Methods for enabling deprecated
|
|
APIs</a></h3>
|
|
|
|
<h4>C</h4>
|
|
|
|
<p>Some deprecated C APIs can be enabled without recompiling the ICU
|
|
libraries. This can be achieved by defining certain symbols before
|
|
including the ICU header files. For example, to enable deprecated C APIs
|
|
for formatting.</p>
|
|
<pre>
|
|
<samp>#ifndef U_USE_DEPRECATED_FORMAT_API
|
|
# define U_USE_DEPRECATED_FORMAT_API 1
|
|
#endif
|
|
|
|
#include "unicode/udat.h"
|
|
|
|
int main(){
|
|
UDateFormat *def, *fr, *fr_pat ;
|
|
UErrorCode status = U_ZERO_ERROR;
|
|
UChar temp[30];
|
|
|
|
fr = udat_open(UDAT_FULL, UDAT_DEFAULT, "fr_FR", NULL,0, &status);
|
|
if(U_FAILURE(status)){
|
|
printf("Error creating the french dateformat using full time style\n %s\n",
|
|
myErrorName(status) );
|
|
}
|
|
/* This is supposed to open default date format,
|
|
but later on it treats it like it is "en_US".
|
|
This is very bad when you try to run the tests
|
|
on a machine where the default locale is NOT "en_US"
|
|
*/
|
|
def = udat_open(UDAT_SHORT, UDAT_SHORT, "en_US", NULL, 0, &status);
|
|
if(U_FAILURE(status)){
|
|
.... /* handle the error */
|
|
}
|
|
}</samp>
|
|
</pre>
|
|
|
|
<h4>C++</h4>
|
|
|
|
<p>Deprecated C++ APIs cannot be enabled without recompiling ICU libraries.
|
|
Every service has a specific symbol that should be defined to enable the
|
|
deprecated API of that service. For example: To enable deprecated APIs in
|
|
transliteration service, the U_USE_DEPRECATED_TRANSLITERATOR_API symbol
|
|
should be defined before compiling ICU.</p>
|
|
|
|
<h2><a name="PlatformDependencies" href="#PlatformDependencies">Platform
|
|
Dependencies</a></h2>
|
|
|
|
<p>The platform dependencies have been mostly isolated into the following
|
|
files in the common library. This information can be useful if you are
|
|
porting ICU to a new platform.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<strong>unicode/platform.h.in</strong> (autoconf'ed platforms)<br>
|
|
<strong>unicode/p<i>XXXX</i>.h</strong> (others: pwin32.h, pmacos.h,
|
|
..): Platform-dependent typedefs and defines:<br>
|
|
<br>
|
|
|
|
|
|
<ul>
|
|
<li>XP_CPLUSPLUS for C++ only.</li>
|
|
|
|
<li>TRUE and FALSE, UBool, int8_t, int16_t etc.</li>
|
|
|
|
<li>U_EXPORT and U_IMPORT for specifying dynamic library import and
|
|
export</li>
|
|
</ul>
|
|
<br>
|
|
</li>
|
|
|
|
<li>
|
|
<strong>unicode/putil.h, putil.c</strong>: platform-dependent
|
|
implementations of various functions that are platform dependent:<br>
|
|
<br>
|
|
|
|
|
|
<ul>
|
|
<li>uprv_isNaN, uprv_isInfinite, uprv_getNaN and uprv_getInfinity for
|
|
handling special floating point values.</li>
|
|
|
|
<li>uprv_tzset, uprv_timezone, uprv_tzname and time for getting
|
|
platform specific time and time zone information.</li>
|
|
|
|
<li>u_getDataDirectory for getting the default data directory.</li>
|
|
|
|
<li>uprv_getDefaultLocaleID for getting the default locale
|
|
setting.</li>
|
|
|
|
<li>uprv_getDefaultCodepage for getting the default codepage
|
|
encoding.</li>
|
|
</ul>
|
|
<br>
|
|
</li>
|
|
|
|
<li>
|
|
<strong>umutex.h, umutex.c</strong>: Code for doing synchronization in
|
|
multithreaded applications. If you wish to use International Components
|
|
for Unicode in a multithreaded application, you must provide a
|
|
synchronization primitive that the classes can use to protect their
|
|
global data against simultaneous modifications. See Users' guide for
|
|
more information.<br>
|
|
<br>
|
|
|
|
|
|
<ul>
|
|
<li>We supply sample implementations for WinNT, Win95, Win98,
|
|
Sun/Solaris, RedHat/Linux, HP-UX and for AIX on an RS/6000.</li>
|
|
</ul>
|
|
<br>
|
|
</li>
|
|
|
|
<li><strong>umapfile.h, umapfile.c</strong>: functions for mapping or
|
|
otherwise reading or loading files into memory. All access by ICU to data
|
|
from files makes use of these functions.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>For the intltest test suite, intltest.cpp in
|
|
"icu/source/test/intltest/" contains the method pathnameInContext, which
|
|
must also be adapted to any new platform.</li>
|
|
|
|
<li>Using platform specific #ifdef macros are highly discouraged outside
|
|
of the scope of these files. When the source code gets updated in the
|
|
future, these #ifdef's can cause testing problems for your platform.</li>
|
|
</ul>
|
|
|
|
<p>It is possible to build each library individually. They must be built in
|
|
the following order:<br>
|
|
</p>
|
|
|
|
<ol>
|
|
<li>stubdata</li>
|
|
|
|
<li>common</li>
|
|
|
|
<li>i18n</li>
|
|
|
|
<li>toolutil</li>
|
|
|
|
<li>makeconv</li>
|
|
|
|
<li>gencnval</li>
|
|
|
|
<li>gennames</li>
|
|
|
|
<li>gennorm</li>
|
|
|
|
<li>genrb</li>
|
|
|
|
<li>genbrk</li>
|
|
|
|
<li>gentz</li>
|
|
|
|
<li>genuca</li>
|
|
|
|
<li>genccode</li>
|
|
|
|
<li>gencmn</li>
|
|
|
|
<li>pkgdata</li>
|
|
|
|
<li>makedata (a project on Windows, or source/data/Makefile on Unix)</li>
|
|
|
|
<li>ctestfw, intltest and cintltst, if you want to run the test
|
|
suite.</li>
|
|
|
|
<li>uconv and ustdio can also be optionally built.</li>
|
|
</ol>
|
|
<hr>
|
|
|
|
<p>Copyright © 1997-2002 International Business Machines Corporation
|
|
and others. All Rights Reserved.<br>
|
|
IBM Globalization Center of Competency - San Jose,<br>
|
|
5600 Cottle Road, San José, CA 95193<br>
|
|
All rights reserved.</p>
|
|
</body>
|
|
</html>
|
|
|