<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
<title>ReadMe for ICU 69.1</title>
<meta name="COPYRIGHT" content=
"Copyright (C) 2016 and later: Unicode, Inc. and others. License & terms of use: http://www.unicode.org/copyright.html"/>
<!-- meta name="COPYRIGHT" content=
"Copyright (c) 1997-2016 IBM Corporation and others. All Rights Reserved." / -->
<meta name="KEYWORDS" content=
"ICU; International Components for Unicode; ICU4C; 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=utf-8" />
<link type="text/css" href="./icu4c.css" rel="stylesheet"/>
classes to use with the "body" -
draft - if the release note is itself a draft (May be combined with the other two)
rc - if the release note is a release candidate
milestone - if the release note is a milestone release
<p class="only-draft"><b>Note:</b> This is a draft readme.</p>
<span class="only-draft">DRAFT</span>
International Components for Unicode<br/>
<span class="only-rc">Release Candidate</span>
<!-- <span class="only-milestone">(Milestone Release)</span> -->
<span class="only-milestone">(Preview Release)</span>
<abbr title="International Components for Unicode">ICU</abbr> 69.1 ReadMe
<!-- Most of the time we shouldn't need to comment/uncomment this paragraph, just change the body class -->
<!-- <p class="note only-milestone">This is a development milestone release of ICU
This milestone is intended for those wishing to get an early look at new features and API changes.
It is not recommended for production use.</p> -->
<p class="note only-milestone">This is a preview release of ICU.
It is not recommended for production use.</p>
<!-- Shouldn't need to comment/uncomment this paragraph, just change the body class -->
<p class="note only-rc">This is a release candidate version of ICU4C.
It is not recommended for production use.</p>
<p>Last updated: 2021-Mar-16<br/>
Copyright © 2016 and later: Unicode, Inc. and others. License & terms of use:
<a href="http://www.unicode.org/copyright.html">http://www.unicode.org/copyright.html</a><br/>
Copyright © 1997-2016 International Business Machines Corporation and others.
<!-- Remember that there is a copyright at the end too -->
<h2 class="TOC">Table of Contents</h2>
<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>
<a href="#HowToBuild">How To Build And Install ICU</a>
<li><a href="#RecBuild">Recommended Build Options</a></li>
<li><a href="#UserConfig">User-Configurable Settings</a></li>
<li><a href="#HowToBuildWindows">Windows</a></li>
<li><a href="#HowToBuildCygwin">Cygwin</a></li>
<li><a href="#HowToBuildUNIX">UNIX</a></li>
<li><a href="#HowToBuildZOS">z/OS (os/390)</a></li>
<li><a href="#HowToBuildOS400">IBM i family (IBM i, i5/OS, OS/400)</a></li>
<li><a href="#HowToCrossCompileICU">How to Cross Compile ICU</a></li>
<li><a href="#HowToPackage">How To Package ICU</a></li>
<a href="#ImportantNotes">Important Notes About Using ICU</a>
<li><a href="#ImportantNotesMultithreaded">Using ICU in a Multithreaded
<li><a href="#ImportantNotesWindows">Windows Platform</a></li>
<li><a href="#ImportantNotesUNIX">UNIX Type Platforms</a></li>
<a href="#PlatformDependencies">Platform Dependencies</a>
<li><a href="#PlatformDependenciesNew">Porting To A New
<li><a href="#PlatformDependenciesImpl">Platform Dependent
<h2><a name="Introduction" href="#Introduction" id=
"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 (ICU) libraries provide robust and full-featured Unicode services on
a wide variety of platforms to help this design goal. The ICU libraries
<li>The latest version of the Unicode standard</li>
<li>Character set conversions with support for over 220 codepages</li>
<li>Locale data for more than 300 locales</li>
<li>Language sensitive text collation (sorting) and searching based on the
Unicode Collation Algorithm (=ISO 14651)</li>
<li>Regular expression matching and Unicode sets</li>
<li>Transformations for normalization, upper/lowercase, script
transliterations (50+ pairs)</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>Calendar specific date and time manipulation</li>
<li>Text boundary analysis for finding characters, word and sentence
<p>ICU has a sister project ICU4J 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" id=
"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 class="docTable" summary="These are some useful links regarding ICU and internationalization in general.">
Here are some useful links regarding ICU and internationalization in
<td>ICU, ICU4C & ICU4J Homepage</td>
"http://icu-project.org/">http://icu-project.org/</a></td>
<td>FAQ - Frequently Asked Questions about ICU</td>
"https://unicode-org.github.io/icu/userguide/icufaq">https://unicode-org.github.io/icu/userguide/icufaq</a></td>
<td>ICU User's Guide</td>
"https://unicode-org.github.io/icu/userguide/">https://unicode-org.github.io/icu/userguide/</a></td>
"https://unicode-org.github.io/icu/userguide/howtouseicu">https://unicode-org.github.io/icu/userguide/howtouseicu</a></td>
<td>Download ICU Releases</td>
"http://site.icu-project.org/download">http://site.icu-project.org/download</a></td>
<td>ICU4C API Documentation Online</td>
"http://icu-project.org/apiref/icu4c/">http://icu-project.org/apiref/icu4c/</a></td>
<td>Online ICU Demos</td>
"http://demo.icu-project.org/icu-bin/icudemos">http://demo.icu-project.org/icu-bin/icudemos</a></td>
<td>Contacts and Bug Reports/Feature Requests</td>
"http://site.icu-project.org/contacts">http://site.icu-project.org/contacts</a></td>
<p><strong>Important:</strong> Please make sure you understand the <a href=
"http://source.icu-project.org/repos/icu/trunk/icu4c/LICENSE">Copyright and License Information</a>.</p>
<h2><a name="News" href="#News" id="News">What Is New In This Release?</a></h2>
<p>See the <a href="http://site.icu-project.org/download/69">ICU 69 download page</a>
for more information on this release, including any other changes, bug fixes, known issues,
changes to supported platforms and build environments,
and migration issues for existing applications migrating from previous ICU releases.</p>
<p>See the <a href="APIChangeReport.html">API Change Report</a> for a complete list of
APIs added, removed, or changed in this release.</p>
<p><a name="RecentPreviousChanges" id="RecentPreviousChanges"></a>For
changes in previous releases, see the
main <a href="http://site.icu-project.org/download">ICU download page</a>
with its version-specific subpages.</p>
<h2><a name="Download" href="#Download" id="Download">How To Download the
<p>There are two ways to download ICU releases:</p>
<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://site.icu-project.org/download">http://site.icu-project.org/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. </li>
<li><strong>GitHub 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 clone and checkout the code from our GitHub repository to
ensure that you have the most recent version of all of the files. See our
<a href="http://site.icu-project.org/repository">source
repository</a> for details.</li>
<h2><a name="SourceCode" href="#SourceCode" id="SourceCode">ICU Source Code
<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=
"https://unicode-org.github.io/icu/userguide/design">ICU Architectural
Design</a> section of the User's Guide 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 class="docTable" summary="The following files describe the code drop.">
The following files describe the code drop.
<th scope="col">File</th>
<th scope="col">Description</th>
<td>Describes the International Components for Unicode (this file)</td>
<td>Contains the text of the ICU license</td>
<table class="docTable" summary=
"The following directories contain source code and data files.">
The following directories contain source code and data files.
<th scope="col">Directory</th>
<th scope="col">Description</th>
<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>
<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>
<td><i><ICU></i>/source/<b>layoutex</b>/</td>
<td>Contains the ICU paragraph layout engine.</td>
<td><i><ICU></i>/source/<b>io</b>/</td>
<td>Contains the ICU I/O library.</td>
<td><i><ICU></i>/source/<b>data</b>/</td>
<p>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.</p>
<p>If some of the following directories are missing, it's probably
because you got an official download. If you need the data source files
for customization, then please download the complete ICU source code from <a
href="http://site.icu-project.org/repository">the ICU repository</a>.</p>
<li><b>in/</b> A directory that contains a pre-built data library for
ICU. A standard source code package will contain this file without
several of the following directories. This is to simplify the build
process for the majority of users and to reduce platform porting
<li><b>brkitr/</b> Data files for character, word, sentence, title
casing and line boundary analysis.</li>
<li><b>coll/</b> Data for collation tailorings. The makefile
<b>colfiles.mk</b> contains the list of resource bundle files.</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. Some of the locale data is split out into the type-specific
directories curr, lang, region, unit, and zone, described below.</li>
<li><b>curr/</b> Locale data for currency symbols and names (including
plural forms), with its own makefile <b>resfiles.mk</b>.</li>
<li><b>lang/</b> Locale data for names of languages, scripts, and locale
key names and values, with its own makefile <b>resfiles.mk</b>.</li>
<li><b>region/</b> Locale data for names of regions, with its own
makefile <b>resfiles.mk</b>.</li>
<li><b>unit/</b> Locale data for measurement unit patterns and names,
with its own makefile <b>resfiles.mk</b>.</li>
<li><b>zone/</b> Locale data for time zone names, with its own
makefile <b>resfiles.mk</b>.</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
<li><b>unidata/</b> This directory contains the Unicode data files.
"http://www.unicode.org/">http://www.unicode.org/</a> for more
<li><b>misc/</b> The misc directory contains other data files which
did not fit into the above categories, including time zone
information, region-specific data, and other data derived from CLDR
<li><b>out/</b> This directory contains the assembled memory mapped
<li><b>out/build/</b> This directory contains intermediate (compiled)
files, such as .cnv, .res, etc.</li>
<p>If you are creating a special ICU build, you can set the ICU_DATA
environment variable to the out/ or the out/build/ directories, but
this is generally discouraged because most people set it incorrectly.
You can view the <a href=
"https://unicode-org.github.io/icu/userguide/icudata">ICU Data
Management</a> section of the ICU User's Guide for details.</p>
<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 build instructions specific to your platform
later in this document.</td>
<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 build instructions specific to your
platform later in this document.</td>
<td><i><ICU></i>/source/test/<b>iotest</b>/</td>
<td>A test suite written in C and C++ to test the icuio library. For
information about running the test suite, see the build instructions
specific to your platform later in this document.</td>
<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 <b>testdata.dat.</b></td>
<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>
<td><i><ICU></i>/source/<b>samples</b>/</td>
<td>Various sample programs that use ICU</td>
<td><i><ICU></i>/source/<b>extra</b>/</td>