1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
6 <title>ReadMe for ICU 54.1</title>
7 <meta name="COPYRIGHT" content=
8 "Copyright (c) 1997-2014 IBM Corporation and others. All Rights Reserved." />
9 <meta name="KEYWORDS" content=
10 "ICU; International Components for Unicode; ICU4C; what's new; readme; read me; introduction; downloads; downloading; building; installation;" />
11 <meta name="DESCRIPTION" content=
12 "The introduction to the International Components for Unicode with instructions on building, installation, usage and other information about ICU." />
13 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
14 <link type="text/css" href="./icu4c.css" rel="stylesheet"/>
18 classes to use with the "body" -
19 draft - if the release note is itself a draft (May be combined with the other two)
22 rc - if the release note is a release candidate
23 milestone - if the release note is a milestone release
26 <!--<body class="rc">-->
28 <p class="only-draft"><b>Note:</b> This is a draft readme.</p>
31 <span class="only-draft">DRAFT</span>
32 International Components for Unicode<br/>
34 <span class="only-rc">Release Candidate</span>
35 <span class="only-milestone">(Milestone Release)</span>
36 <abbr title="International Components for Unicode">ICU</abbr> 54.1 ReadMe
40 <!-- Shouldn't need to comment/uncomment this paragraph, just change the body class -->
41 <p class="note only-milestone">This is a development milestone release of ICU
42 This milestone is intended for those wishing to get an early look at new features and API changes.
43 It is not recommended for production use.</p>
45 <!-- Shouldn't need to comment/uncomment this paragraph, just change the body class -->
46 <p class="note only-rc">This is a release candidate version of ICU4C.
47 It is not recommended for production use.</p>
49 <p>Last updated: 2014-September-24<br />
50 Copyright © 1997-2014 International Business Machines Corporation and
51 others. All Rights Reserved.</p>
52 <!-- Remember that there is a copyright at the end too -->
55 <h2 class="TOC">Table of Contents</h2>
58 <li><a href="#Introduction">Introduction</a></li>
60 <li><a href="#GettingStarted">Getting Started</a></li>
62 <li><a href="#News">What Is New In This release?</a></li>
64 <li><a href="#Download">How To Download the Source Code</a></li>
66 <li><a href="#SourceCode">ICU Source Code Organization</a></li>
69 <a href="#HowToBuild">How To Build And Install ICU</a>
72 <li><a href="#RecBuild">Recommended Build Options</a></li>
74 <li><a href="#UserConfig">User-Configurable Settings</a></li>
76 <li><a href="#HowToBuildWindows">Windows</a></li>
78 <li><a href="#HowToBuildCygwin">Cygwin</a></li>
80 <li><a href="#HowToBuildUNIX">UNIX</a></li>
82 <li><a href="#HowToBuildZOS">z/OS (os/390)</a></li>
84 <li><a href="#HowToBuildOS400">IBM i family (IBM i, i5/OS, OS/400)</a></li>
86 <li><a href="#HowToCrossCompileICU">How to Cross Compile ICU</a></li>
91 <li><a href="#HowToPackage">How To Package ICU</a></li>
94 <a href="#ImportantNotes">Important Notes About Using ICU</a>
97 <li><a href="#ImportantNotesMultithreaded">Using ICU in a Multithreaded
100 <li><a href="#ImportantNotesWindows">Windows Platform</a></li>
102 <li><a href="#ImportantNotesUNIX">UNIX Type Platforms</a></li>
107 <a href="#PlatformDependencies">Platform Dependencies</a>
110 <li><a href="#PlatformDependenciesNew">Porting To A New
113 <li><a href="#PlatformDependenciesImpl">Platform Dependent
114 Implementations</a></li>
120 <h2><a name="Introduction" href="#Introduction" id=
121 "Introduction">Introduction</a></h2>
123 <p>Today's software market is a global one in which it is desirable to
124 develop and maintain one application (single source/single binary) that
125 supports a wide variety of languages. The International Components for
126 Unicode (ICU) libraries provide robust and full-featured Unicode services on
127 a wide variety of platforms to help this design goal. The ICU libraries
128 provide support for:</p>
131 <li>The latest version of the Unicode standard</li>
133 <li>Character set conversions with support for over 220 codepages</li>
135 <li>Locale data for more than 300 locales</li>
137 <li>Language sensitive text collation (sorting) and searching based on the
138 Unicode Collation Algorithm (=ISO 14651)</li>
140 <li>Regular expression matching and Unicode sets</li>
142 <li>Transformations for normalization, upper/lowercase, script
143 transliterations (50+ pairs)</li>
145 <li>Resource bundles for storing and accessing localized information</li>
147 <li>Date/Number/Message formatting and parsing of culture specific
148 input/output formats</li>
150 <li>Calendar specific date and time manipulation</li>
152 <li>Complex text layout for Arabic, Hebrew, Indic and Thai</li>
154 <li>Text boundary analysis for finding characters, word and sentence
158 <p>ICU has a sister project ICU4J that extends the internationalization
159 capabilities of Java to a level similar to ICU. The ICU C/C++ project is also
160 called ICU4C when a distinction is necessary.</p>
162 <h2><a name="GettingStarted" href="#GettingStarted" id=
163 "GettingStarted">Getting started</a></h2>
165 <p>This document describes how to build and install ICU on your machine. For
166 other information about ICU please see the following table of links.<br />
167 The ICU homepage also links to related information about writing
168 internationalized software.</p>
170 <table class="docTable" summary="These are some useful links regarding ICU and internationalization in general.">
172 Here are some useful links regarding ICU and internationalization in
177 <td>ICU, ICU4C & ICU4J Homepage</td>
180 "http://icu-project.org/">http://icu-project.org/</a></td>
184 <td>FAQ - Frequently Asked Questions about ICU</td>
187 "http://userguide.icu-project.org/icufaq">http://userguide.icu-project.org/icufaq</a></td>
191 <td>ICU User's Guide</td>
194 "http://userguide.icu-project.org/">http://userguide.icu-project.org/</a></td>
198 <td>How To Use ICU</td>
200 <td><a href="http://userguide.icu-project.org/howtouseicu">http://userguide.icu-project.org/howtouseicu</a></td>
204 <td>Download ICU Releases</td>
207 "http://site.icu-project.org/download">http://site.icu-project.org/download</a></td>
211 <td>ICU4C API Documentation Online</td>
214 "http://icu-project.org/apiref/icu4c/">http://icu-project.org/apiref/icu4c/</a></td>
218 <td>Online ICU Demos</td>
221 "http://demo.icu-project.org/icu-bin/icudemos">http://demo.icu-project.org/icu-bin/icudemos</a></td>
225 <td>Contacts and Bug Reports/Feature Requests</td>
228 "http://site.icu-project.org/contacts">http://site.icu-project.org/contacts</a></td>
232 <p><strong>Important:</strong> Please make sure you understand the <a href=
233 "license.html">Copyright and License Information</a>.</p>
235 <h2><a name="News" href="#News" id="News">What is new in this
239 <p>See the <a href="APIChangeReport.html">API Change Report</a> for a complete
240 list of APIs added, removed, or changed in this release.</p>
242 <!-- ICU 54 items -->
243 <h3>Deprecation: Layout Engine</h3>
244 <p>The LayoutEngine is now deprecated. Please
245 see <a href='http://userguide.icu-project.org/layoutengine'>the
246 User's Guide</a> for more details and migration recommendations.
247 In the future, passing "<tt>--enable-layout</tt>" to configure
249 enable the layout engine.</p>
251 Note that the ParagraphLayout (layoutex) library is not deprecated.
252 There is a new option, <tt>--enable-layoutex</tt> which will build
253 the ParagraphLayout library using <a href="http://harfbuzz.org">HarfBuzz</a>
254 instead of ICU as the layout engine. See <a href="http://userguide.icu-project.org/layoutengine">
255 the users' guide</a> for more information about how to build.
257 <h3>Deprecation: Collation Short Strings</h3>
258 <p>The collation short naming scheme and its API functions are deprecated.
259 Use ucol_open() with language tag collation keywords instead (see <a href="http://userguide.icu-project.org/collation/api">Collation API Details</a>). For example, <code>ucol_open("de-u-co-phonebk-ka-shifted", &errorCode)</code>
260 for German Phonebook order with "ignore punctuation" mode.</p>
262 <h3>Deprecation: UCOL_TAILORINGS_VERSION</h3>
263 <p>This was originally intended to be the version of collation tailorings,
264 but that information is actually in the tailorings data and this
265 constant has always been (and now will continue to be) 1.</p>
267 <h3>Deprecation (in ICU 53): TimeUnitFormat</h3>
268 <p>The TimeUnitFormat and its methods were actually deprecated in ICU 53 and the
269 class as a whole was tagged as deprecated in that release, but the status tags for
270 the individual methods did not correctly indicate the deprecated status; now they do.
271 Use the MeasureFormat class and its methods instead.</p>
273 <!-- standing item -->
274 <h3>Full release notes and the latest updates</h3>
275 <p>The previous list concentrates on <em>changes that affect existing
276 applications migrating from previous ICU releases</em>.
277 For more news about this release, as well as late-breaking news, see the
278 <a href="http://site.icu-project.org/download/54">ICU download page</a>.</p>
280 <!-- end ICU 54 items -->
282 <h2><a name="Download" href="#Download" id="Download">How To Download the
285 <p>There are two ways to download ICU releases:</p>
288 <li><strong>Official Release Snapshot:</strong><br />
289 If you want to use ICU (as opposed to developing it), you should download
290 an official packaged version of the ICU source code. These versions are
291 tested more thoroughly than day-to-day development builds of the system,
292 and they are packaged in zip and tar files for convenient download. These
293 packaged files can be found at <a href=
294 "http://site.icu-project.org/download">http://site.icu-project.org/download</a>.<br />
295 The packaged snapshots are named <strong>icu-nnnn.zip</strong> or
296 <strong>icu-nnnn.tgz</strong>, where nnnn is the version number. The .zip
297 file is used for Windows platforms, while the .tgz file is preferred on
298 most other platforms.<br />
299 Please unzip this file. </li>
301 <li><strong>Subversion Source Repository:</strong><br />
302 If you are interested in developing features, patches, or bug fixes for
303 ICU, you should probably be working with the latest version of the ICU
304 source code. You will need to check the code out of our Subversion repository to
305 ensure that you have the most recent version of all of the files. See our
306 <a href="http://site.icu-project.org/repository">source
307 repository</a> for details.</li>
310 <h2><a name="SourceCode" href="#SourceCode" id="SourceCode">ICU Source Code
311 Organization</a></h2>
313 <p>In the descriptions below, <strong><i><ICU></i></strong> is the full
314 path name of the ICU directory (the top level directory from the distribution
315 archives) in your file system. You can also view the <a href=
316 "http://userguide.icu-project.org/design">ICU Architectural
317 Design</a> section of the User's Guide to see which libraries you need for
318 your software product. You need at least the data (<code>[lib]icudt</code>)
319 and the common (<code>[lib]icuuc</code>) libraries in order to use ICU.</p>
321 <table class="docTable" summary="The following files describe the code drop.">
323 The following files describe the code drop.
327 <th scope="col">File</th>
329 <th scope="col">Description</th>
335 <td>Describes the International Components for Unicode (this file)</td>
339 <td>license.html</td>
341 <td>Contains the text of the ICU license</td>
348 <table class="docTable" summary=
349 "The following directories contain source code and data files.">
351 The following directories contain source code and data files.
355 <th scope="col">Directory</th>
357 <th scope="col">Description</th>
361 <td><i><ICU></i>/source/<b>common</b>/</td>
363 <td>The core Unicode and support functionality, such as resource bundles,
364 character properties, locales, codepage conversion, normalization,
365 Unicode properties, Locale, and UnicodeString.</td>
369 <td><i><ICU></i>/source/<b>i18n</b>/</td>
371 <td>Modules in i18n are generally the more data-driven, that is to say
372 resource bundle driven, components. These deal with higher-level
373 internationalization issues such as formatting, collation, text break
374 analysis, and transliteration.</td>
378 <td><i><ICU></i>/source/<b>layout</b>/</td>
380 <td>Contains the ICU complex text layout engine. (Deprecated)</td>
383 <td><i><ICU></i>/source/<b>layoutex</b>/</td>
385 <td>Contains the ICU paragraph layout engine.</td>
389 <td><i><ICU></i>/source/<b>io</b>/</td>
391 <td>Contains the ICU I/O library.</td>
395 <td><i><ICU></i>/source/<b>data</b>/</td>
398 <p>This directory contains the source data in text format, which is
399 compiled into binary form during the ICU build process. It contains
400 several subdirectories, in which the data files are grouped by
401 function. Note that the build process must be run again after any
402 changes are made to this directory.</p>
404 <p>If some of the following directories are missing, it's probably
405 because you got an official download. If you need the data source files
406 for customization, then please download the ICU source code from <a
407 href="http://site.icu-project.org/repository">subversion</a>.</p>
410 <li><b>in/</b> A directory that contains a pre-built data library for
411 ICU. A standard source code package will contain this file without
412 several of the following directories. This is to simplify the build
413 process for the majority of users and to reduce platform porting
416 <li><b>brkitr/</b> Data files for character, word, sentence, title
417 casing and line boundary analysis.</li>
419 <li><b>locales/</b> These .txt files contain ICU language and
420 culture-specific localization data. Two special bundles are
421 <b>root</b>, which is the fallback data and parent of other bundles,
422 and <b>index</b>, which contains a list of installed bundles. The
423 makefile <b>resfiles.mk</b> contains the list of resource bundle
426 <li><b>mappings/</b> Here are the code page converter tables. These
427 .ucm files contain mappings to and from Unicode. These are compiled
428 into .cnv files. <b>convrtrs.txt</b> is the alias mapping table from
429 various converter name formats to ICU internal format and vice versa.
430 It produces cnvalias.icu. The makefiles <b>ucmfiles.mk,
431 ucmcore.mk,</b> and <b>ucmebcdic.mk</b> contain the list of
432 converters to be built.</li>
434 <li><b>translit/</b> This directory contains transliterator rules as
435 resource bundles, a makefile <b>trnsfiles.mk</b> containing the list
436 of installed system translitaration files, and as well the special
437 bundle <b>translit_index</b> which lists the system transliterator
440 <li><b>unidata/</b> This directory contains the Unicode data files.
442 "http://www.unicode.org/">http://www.unicode.org/</a> for more
445 <li><b>misc/</b> The misc directory contains other data files which
446 did not fit into the above categories. Currently it only contains
447 time zone information, and a name preperation file for <a href=
448 "http://www.ietf.org/rfc/rfc3490.txt">IDNA</a>.</li>
450 <li><b>out/</b> This directory contains the assembled memory mapped
453 <li><b>out/build/</b> This directory contains intermediate (compiled)
454 files, such as .cnv, .res, etc.</li>
457 <p>If you are creating a special ICU build, you can set the ICU_DATA
458 environment variable to the out/ or the out/build/ directories, but
459 this is generally discouraged because most people set it incorrectly.
460 You can view the <a href=
461 "http://userguide.icu-project.org/icudata">ICU Data
462 Management</a> section of the ICU User's Guide for details.</p>
467 <td><i><ICU></i>/source/test/<b>intltest</b>/</td>
469 <td>A test suite including all C++ APIs. For information about running
470 the test suite, see the build instructions specific to your platform
471 later in this document.</td>
475 <td><i><ICU></i>/source/test/<b>cintltst</b>/</td>
477 <td>A test suite written in C, including all C APIs. For information
478 about running the test suite, see the build instructions specific to your
479 platform later in this document.</td>
483 <td><i><ICU></i>/source/test/<b>iotest</b>/</td>
485 <td>A test suite written in C and C++ to test the icuio library. For
486 information about running the test suite, see the build instructions
487 specific to your platform later in this document.</td>
491 <td><i><ICU></i>/source/test/<b>testdata</b>/</td>
493 <td>Source text files for data, which are read by the tests. It contains
494 the subdirectories <b>out/build/</b> which is used for intermediate
495 files, and <b>out/</b> which contains <b>testdata.dat.</b></td>
499 <td><i><ICU></i>/source/<b>tools</b>/</td>
501 <td>Tools for generating the data files. Data files are generated by
502 invoking <i><ICU></i>/source/data/build/makedata.bat on Win32 or
503 <i><ICU></i>/source/make on UNIX.</td>
507 <td><i><ICU></i>/source/<b>samples</b>/</td>
509 <td>Various sample programs that use ICU</td>
513 <td><i><ICU></i>/source/<b>extra</b>/</td>
515 <td>Non-supported API additions. Currently, it contains the 'uconv' tool
516 to perform codepage conversion on files.</td>
520 <td><i><ICU></i>/<b>packaging</b>/</td>
522 <td>This directory contain scripts and tools for packaging the final
523 ICU build for various release platforms.</td>
527 <td><i><ICU></i>/source/<b>config</b>/</td>
529 <td>Contains helper makefiles for platform specific build commands. Used
534 <td><i><ICU></i>/source/<b>allinone</b>/</td>
536 <td>Contains top-level ICU workspace and project files, for instance to
537 build all of ICU under one MSVC project.</td>
541 <td><i><ICU></i>/<b>include</b>/</td>
543 <td>Contains the headers needed for developing software that uses ICU on
548 <td><i><ICU></i>/<b>lib</b>/</td>
550 <td>Contains the import libraries for linking ICU into your Windows
555 <td><i><ICU></i>/<b>bin</b>/</td>
557 <td>Contains the libraries and executables for using ICU on Windows.</td>
560 <!-- end of ICU structure ==================================== -->
562 <h2><a name="HowToBuild" href="#HowToBuild" id="HowToBuild">How To Build And
565 <h3><a name="RecBuild" href="#RecBuild" id=
566 "RecBuild">Recommended Build Options</a></h3>
568 <p>Depending on the platform and the type of installation,
569 we recommend a small number of modifications and build options.
570 Note that C99 compatibility is now required.</p>
572 <li><b>Namespace:</b> By default, unicode/uversion.h has
573 "using namespace icu;" which defeats much of the purpose of the namespace.
574 (This is for historical reasons: Originally, ICU4C did not use namespaces,
575 and some compilers did not support them. The default "using" statement
576 preserves source code compatibility.)<br />
577 If this compatibility is not an issue, we recommend you turn this off
578 via <code>-DU_USING_ICU_NAMESPACE=0</code>
579 or by modifying unicode/uversion.h:
580 <pre>Index: source/common/unicode/uversion.h
581 ===================================================================
582 --- source/common/unicode/uversion.h (revision 26606)
583 +++ source/common/unicode/uversion.h (working copy)
585 # define U_NAMESPACE_QUALIFIER U_ICU_NAMESPACE::
587 # ifndef U_USING_ICU_NAMESPACE
588 -# define U_USING_ICU_NAMESPACE 1
589 + // Set to 0 to force namespace declarations in ICU usage.
590 +# define U_USING_ICU_NAMESPACE 0
592 # if U_USING_ICU_NAMESPACE
595 ICU call sites then either qualify ICU types explicitly,
596 for example <code>icu::UnicodeString</code>,
597 or do <code>using icu::UnicodeString;</code> where appropriate.</li>
598 <li><b>Hardcode the default charset to UTF-8:</b> On platforms where
599 the default charset is always UTF-8,
600 like MacOS X and some Linux distributions,
601 we recommend hardcoding ICU's default charset to UTF-8.
602 This means that some implementation code becomes simpler and faster,
603 and statically linked ICU libraries become smaller.
604 (See the <a href="http://icu-project.org/apiref/icu4c/utypes_8h.html#0a33e1edf3cd23d9e9c972b63c9f7943">U_CHARSET_IS_UTF8</a>
605 API documentation for more details.)<br />
606 You can <code>-DU_CHARSET_IS_UTF8=1</code> or
607 modify unicode/utypes.h (in ICU 4.8 and below)
608 or modify unicode/platform.h (in ICU 49 and higher):
609 <pre>Index: source/common/unicode/utypes.h
610 ===================================================================
611 --- source/common/unicode/utypes.h (revision 26606)
612 +++ source/common/unicode/utypes.h (working copy)
614 * @see UCONFIG_NO_CONVERSION
616 #ifndef U_CHARSET_IS_UTF8
617 -# define U_CHARSET_IS_UTF8 0
618 +# define U_CHARSET_IS_UTF8 1
621 /*===========================================================================*/
623 <li><b>UnicodeString constructors:</b> The UnicodeString class has
624 several single-argument constructors that are not marked "explicit"
625 for historical reasons.
626 This can lead to inadvertent construction of a <code>UnicodeString</code>
627 with a single character by using an integer,
628 and it can lead to inadvertent dependency on the conversion framework
629 by using a C string literal.<br />
630 Beginning with ICU 49, you should do the following:
632 <li>Consider marking the from-<code>UChar</code>
633 and from-<code>UChar32</code> constructors explicit via
634 <code>-DUNISTR_FROM_CHAR_EXPLICIT=explicit</code> or similar.</li>
635 <li>Consider marking the from-<code>const char*</code> and
636 from-<code>const UChar*</code> constructors explicit via
637 <code>-DUNISTR_FROM_STRING_EXPLICIT=explicit</code> or similar.</li>
639 Note: The ICU test suites cannot be compiled with these settings.
641 <li><b>utf.h, utf8.h, utf16.h, utf_old.h:</b>
642 By default, utypes.h (and thus almost every public ICU header)
643 includes all of these header files.
644 Often, none of them are needed, or only one or two of them.
645 All of utf_old.h is deprecated or obsolete.<br />
646 Beginning with ICU 49,
647 you should define <code>U_NO_DEFAULT_INCLUDE_UTF_HEADERS</code> to 1
648 (via -D or uconfig.h, as above)
649 and include those header files explicitly that you actually need.<br />
650 Note: The ICU test suites cannot be compiled with this setting.</li>
651 <li><b>.dat file:</b> By default, the ICU data is built into
652 a shared library (DLL). This is convenient because it requires no
653 install-time or runtime configuration,
654 but the library is platform-specific and cannot be modified.
655 A .dat package file makes the opposite trade-off:
656 Platform-portable (except for endianness and charset family, which
657 can be changed with the icupkg tool)
658 and modifiable (also with the icupkg tool).
659 If a path is set, then single data files (e.g., .res files)
660 can be copied to that location to provide new locale data
661 or conversion tables etc.<br />
662 The only drawback with a .dat package file is that the application
663 needs to provide ICU with the file system path to the package file
664 (e.g., by calling <code>u_setDataDirectory()</code>)
665 or with a pointer to the data (<code>udata_setCommonData()</code>)
666 before other ICU API calls.
667 This is usually easy if ICU is used from an application where
668 <code>main()</code> takes care of such initialization.
669 It may be hard if ICU is shipped with
670 another shared library (such as the Xerces-C++ XML parser)
671 which does not control <code>main()</code>.<br />
672 See the <a href="http://userguide.icu-project.org/icudata">User Guide ICU Data</a>
673 chapter for more details.<br />
674 If possible, we recommend building the .dat package.
675 Specify <code>--with-data-packaging=archive</code>
676 on the configure command line, as in<br />
677 <code>runConfigureICU Linux --with-data-packaging=archive</code><br />
678 (Read the configure script's output for further instructions.
679 On Windows, the Visual Studio build generates both the .dat package
680 and the data DLL.)<br />
681 Be sure to install and use the tiny stubdata library
682 rather than the large data DLL.</li>
683 <li><b>Static libraries:</b> It may make sense to build the ICU code
684 into static libraries (.a) rather than shared libraries (.so/.dll).
685 Static linking reduces the overall size of the binary by removing
686 code that is never called.<br />
687 Example configure command line:<br />
688 <code>runConfigureICU Linux --enable-static --disable-shared</code></li>
689 <li><b>Out-of-source build:</b> It is usually desirable to keep the ICU
690 source file tree clean and have build output files written to
691 a different location. This is called an "out-of-source build".
692 Simply invoke the configure script from the target location:
693 <pre>~/icu$ svn export http://source.icu-project.org/repos/icu/icu/trunk
694 ~/icu$ mkdir trunk-dev
696 ~/icu/trunk-dev$ ../trunk/source/runConfigureICU Linux
697 ~/icu/trunk-dev$ make check</pre><br/>
698 (Note: this example shows a relative path to
699 <code>runConfigureICU</code>. If you experience difficulty,
700 try using an absolute path to <code>runConfigureICU</code>
704 <h4>ICU as a System-Level Library</h4>
705 <p>If ICU is installed as a system-level library, there are further
706 opportunities and restrictions to consider.
707 For details, see the <em>Using ICU as an Operating System Level Library</em>
708 section of the <a href="http://userguide.icu-project.org/design">User Guide ICU Architectural Design</a> chapter.</p>
710 <li><b>Data path:</b> For a system-level library, it is best to load
711 ICU data from the .dat package file because the file system path
712 to the .dat package file can be hardcoded. ICU will automatically set
713 the path to the final install location using U_ICU_DATA_DEFAULT_DIR.
714 Alternatively, you can set <code>-DICU_DATA_DIR=/path/to/icu/data</code>
715 when building the ICU code. (Used by source/common/putil.c.)<br/>
716 Consider also setting <code>-DICU_NO_USER_DATA_OVERRIDE</code>
717 if you do not want the "ICU_DATA" environment variable to be used.
718 (An application can still override the data path via
719 <code>u_setDataDirectory()</code> or
720 <code>udata_setCommonData()</code>.</li>
721 <li><b>Hide draft API:</b> API marked with <code>@draft</code>
722 is new and not yet stable. Applications must not rely on unstable
723 APIs from a system-level library.
724 Define <code>U_HIDE_DRAFT_API</code>, <code>U_HIDE_INTERNAL_API</code>
725 and <code>U_HIDE_SYSTEM_API</code>
726 by modifying unicode/utypes.h before installing it.</li>
727 <li><b>Only C APIs:</b> Applications must not rely on C++ APIs from a
728 system-level library because binary C++ compatibility
729 across library and compiler versions is very hard to achieve.
730 Most ICU C++ APIs are in header files that contain a comment with
731 <code>\brief C++ API</code>.
732 Consider not installing these header files.</li>
733 <li><b>Disable renaming:</b> By default, ICU library entry point names
734 have an ICU version suffix. Turn this off for a system-level installation,
735 to enable upgrading ICU without breaking applications. For example:<br />
736 <code>runConfigureICU Linux --disable-renaming</code><br />
737 The public header files from this configuration must be installed
738 for applications to include and get the correct entry point names.</li>
741 <h3><a name="UserConfig" href="#UserConfig" id="UserConfig">User-Configurable Settings</a></h3>
742 <p>ICU4C can be customized via a number of user-configurable settings.
743 Many of them are controlled by preprocessor macros which are
744 defined in the <code>source/common/unicode/uconfig.h</code> header file.
745 Some turn off parts of ICU, for example conversion or collation,
746 trading off a smaller library for reduced functionality.
747 Other settings are recommended (see previous section)
748 but their default values are set for better source code compatibility.</p>
750 <p>In order to change such user-configurable settings, you can
751 either modify the <code>uconfig.h</code> header file by adding
752 a specific <code>#define ...</code> for one or more of the macros
753 before they are first tested,
754 or set the compiler's preprocessor flags (<code>CPPFLAGS</code>) to include
755 an equivalent <code>-D</code> macro definition.</p>
757 <h3><a name="HowToBuildWindows" href="#HowToBuildWindows" id=
758 "HowToBuildWindows">How To Build And Install On Windows</a></h3>
760 <p>Building International Components for Unicode requires:</p>
763 <li>Microsoft Windows</li>
765 <li>Microsoft Visual C++ (see the ICU download page for the currently compatible version)</li>
767 <p class="note"><a href="#HowToBuildCygwin">Cygwin</a> is required if using a version of MSVC other than the one
768 compatible with the supplied project files or if other compilers are used to build ICU. (e.g. GCC)</p>
770 <p>The steps are:</p>
773 <li>Unzip the icu-XXXX.zip file into any convenient location. Using command
774 line zip, type "unzip -a icu-XXXX.zip -d drive:\directory", or just use
777 <li>Be sure that the ICU binary directory, <i><ICU></i>\bin\, is
778 included in the <strong>PATH</strong> environment variable. The tests will
779 not work without the location of the ICU DLL files in the path.</li>
781 <li>Open the "<i><ICU></i>\source\allinone\allinone.sln" workspace
782 file in Microsoft Visual Studio. (This solution includes all the
783 International Components for Unicode libraries, necessary ICU building
784 tools, and the test suite projects). Please see the <a href=
785 "#HowToBuildWindowsCommandLine">command line note below</a> if you want to
786 build from the command line instead.</li>
788 <li>Set the active platform to "Win32" or "x64" (See <a href="#HowToBuildWindowsPlatform">Windows platform note</a> below)
789 and configuration to "Debug" or "Release" (See <a href="#HowToBuildWindowsConfig">Windows configuration note</a> below).</li>
791 <li>Choose the "Build" menu and select "Rebuild Solution". If you want to
792 build the Debug and Release at the same time, see the <a href=
793 "#HowToBuildWindowsBatch">batch configuration note</a> below.</li>
796 <li>Run the tests. They can be run from the command line or from within Visual Studio.
798 <h4>Running the Tests from the Windows Command Line (cmd)</h4>
800 <li>For x86 (32 bit) and Debug, use: <br />
802 <tt><i><ICU></i>\source\allinone\icucheck.bat <i>Platform</i> <i>Configuration</i>
807 <samp><i><ICU></i>\source\allinone\icucheck.bat <b>x86</b> <b>Debug</b></samp>
809 <samp><i><ICU></i>\source\allinone\icucheck.bat <b>x86</b> <b>Release</b></samp>
811 <samp><i><ICU></i>\source\allinone\icucheck.bat <b>x64</b> <b>Release</b></samp></li>
814 <h4>Running the Tests from within Visual Studio</h4>
817 <li>Run the C++ test suite, "intltest". To do this: set the active startup
818 project to "intltest", and press Ctrl+F5 to run it. Make sure that it
819 passes without any errors.</li>
821 <li>Run the C test suite, "cintltst". To do this: set the active startup
822 project to "cintltst", and press Ctrl+F5 to run it. Make sure that it
823 passes without any errors.</li>
825 <li>Run the I/O test suite, "iotest". To do this: set the active startup
826 project to "iotest", and press Ctrl+F5 to run it. Make sure that it passes
827 without any errors.</li>
833 <li>You are now able to develop applications with ICU by using the
834 libraries and tools in <i><ICU></i>\bin\. The headers are in
835 <i><ICU></i>\include\ and the link libraries are in
836 <i><ICU></i>\lib\. To install the ICU runtime on a machine, or ship
837 it with your application, copy the needed components from
838 <i><ICU></i>\bin\ to a location on the system PATH or to your
839 application directory.</li>
842 <p><a name="HowToBuildWindowsCommandLine" id=
843 "HowToBuildWindowsCommandLine"><strong>Using MSDEV At The Command Line
844 Note:</strong></a> You can build ICU from the command line. Assuming that you
845 have properly installed Microsoft Visual C++ to support command line
846 execution, you can run the following command, 'devenv.com
847 <i><ICU></i>\source\allinone\allinone.sln /build "Win32|Release"'. You can also
848 use Cygwin with this compiler to build ICU, and you can refer to the <a href=
849 "#HowToBuildCygwin">How To Build And Install On Windows with Cygwin</a>
850 section for more details.</p>
852 <p><a name="HowToBuildWindowsPlatform" id=
853 "HowToBuildWindowsPlatform"><strong>Setting Active Platform
854 Note:</strong></a> Even though you are able to select "x64" as the active platform, if your operating system is
855 not a 64 bit version of Windows, the build will fail. To set the active platform, two different possibilities are:</p>
858 <li>Choose "Build" menu, select "Configuration Manager...", and select
859 "Win32" or "x64" for the Active Platform Solution.</li>
861 <li>Another way is to select the desired build configuration from "Solution
862 Platforms" dropdown menu from the standard toolbar. It will say
863 "Win32" or "x64" in the dropdown list.</li>
866 <p><a name="HowToBuildWindowsConfig" id=
867 "HowToBuildWindowsConfig"><strong>Setting Active Configuration
868 Note:</strong></a> To set the active configuration, two different
869 possibilities are:</p>
872 <li>Choose "Build" menu, select "Configuration Manager...", and select
873 "Release" or "Debug" for the Active Configuration Solution.</li>
875 <li>Another way is to select the desired build configuration from "Solution
876 Configurations" dropdown menu from the standard toolbar. It will say
877 "Release" or "Debug" in the dropdown list.</li>
880 <p><a name="HowToBuildWindowsBatch" id="HowToBuildWindowsBatch"><strong>Batch
881 Configuration Note:</strong></a> If you want to build the Win32 and x64 platforms and
882 Debug and Release configurations at the same time, choose "Build" menu, and select "Batch
883 Build...". Click the "Select All" button, and then click the "Rebuild"
886 <h3><a name="HowToBuildCygwin" href="#HowToBuildCygwin" id=
887 "HowToBuildCygwin">How To Build And Install On Windows with Cygwin</a></h3>
889 <p>Building International Components for Unicode with this configuration
893 <li>Microsoft Windows</li>
895 <li>Microsoft Visual C++ (when gcc isn't used).</li>
898 Cygwin with the following installed:
909 <li>man (if you plan to look at the man pages)</li>
914 <p>There are two ways you can build ICU with Cygwin. You can build with gcc
915 or Microsoft Visual C++. If you use gcc, the resulting libraries and tools
916 will depend on the Cygwin environment. If you use Microsoft Visual C++, the
917 resulting libraries and tools do not depend on Cygwin and can be more easily
918 distributed to other Windows computers (the generated man pages and shell
919 scripts still need Cygwin). To build with gcc, please follow the "<a href=
920 "#HowToBuildUNIX">How To Build And Install On UNIX</a>" instructions, while
921 you are inside a Cygwin bash shell. To build with Microsoft Visual C++,
922 please use the following instructions:</p>
925 <li>Start the Windows "Command Prompt" window. This is different from the
926 gcc build, which requires the Cygwin Bash command prompt. The Microsoft
927 Visual C++ compiler will not work with a bash command prompt.</li>
929 <li>If the computer isn't set up to use Visual C++ from the command line,
930 you need to run vcvars32.bat.<br />For example:<br />"<tt>C:\Program Files\Microsoft
931 Visual Studio 8\VC\bin\vcvars32.bat</tt>" can be used for 32-bit builds
932 <strong>or</strong> <br />"<tt>C:\Program Files (x86)\Microsoft Visual Studio
933 8\VC\bin\amd64\vcvarsamd64.bat</tt>" can be used for 64-bit builds on
936 <li>Unzip the icu-XXXX.zip file into any convenient location. Using command
937 line zip, type "unzip -a icu-XXXX.zip -d drive:\directory", or just use
940 <li>Change directory to "icu/source", which is where you unzipped ICU.</li>
942 <li>Run "<tt>bash <a href="source/runConfigureICU">./runConfigureICU</a>
943 Cygwin/MSVC</tt>" (See <a href="#HowToWindowsConfigureICU">Windows
944 configuration note</a> and non-functional configure options below).</li>
946 <li>Type <tt>"make"</tt> to compile the libraries and all the data files.
947 This make command should be GNU make.</li>
949 <li>Optionally, type <tt>"make check"</tt> to run the test suite, which
950 checks for ICU's functionality integrity (See <a href=
951 "#HowToTestWithoutGmake">testing note</a> below).</li>
953 <li>Type <tt>"make install"</tt> to install ICU. If you used the --prefix=
954 option on configure or runConfigureICU, ICU will be installed to the
955 directory you specified. (See <a href="#HowToInstallICU">installation
956 note</a> below).</li>
959 <p><a name="HowToWindowsConfigureICU" id=
960 "HowToWindowsConfigureICU"><strong>Configuring ICU on Windows
961 NOTE:</strong></a> </p>
963 Ensure that the order of the PATH is MSVC, Cygwin, and then other PATHs. The configure
964 script needs certain tools in Cygwin (e.g. grep).
967 Also, you may need to run <tt>"dos2unix.exe"</tt> on all of the scripts (e.g. configure)
968 in the top source directory of ICU. To avoid this issue, you can download
969 the ICU source for Unix platforms (icu-xxx.tgz).
971 <p>In addition to the Unix <a href=
972 "#HowToConfigureICU">configuration note</a> the following configure options
973 currently do not work on Windows with Microsoft's compiler. Some options can
974 work by manually editing <tt>icu/source/common/unicode/pwin32.h</tt>, but
975 manually editing the files is not recommended.</p>
978 <li><tt>--disable-renaming</tt></li>
980 <li><tt>--enable-tracing</tt></li>
982 <li><tt>--enable-rpath</tt></li>
984 <li><tt>--enable-static</tt> (Requires that U_STATIC_IMPLEMENTATION be
985 defined in user code that links against ICU's static libraries.)</li>
987 <li><tt>--with-data-packaging=files</tt> (The pkgdata tool currently does
988 not work in this mode. Manual packaging is required to use this mode.)</li>
991 <h3><a name="HowToBuildUNIX" href="#HowToBuildUNIX" id="HowToBuildUNIX">How
992 To Build And Install On UNIX</a></h3>
994 <p>Building International Components for Unicode on UNIX requires:</p>
997 <li>A C++ compiler installed on the target machine (for example: gcc, CC,
998 xlC_r, aCC, cxx, etc...).</li>
1000 <li>An ANSI C compiler installed on the target machine (for example:
1003 <li>A recent version of GNU make (3.80+).</li>
1005 <li>For a list of z/OS tools please view the <a href="#HowToBuildZOS">z/OS
1006 build section</a> of this document for further details.</li>
1009 <p>Here are the steps to build ICU:</p>
1012 <li>Decompress the icu-<i>X</i>.<i>Y</i>.tgz (or
1013 icu-<i>X</i>.<i>Y</i>.tar.gz) file. For example, <samp>gunzip -d < icu-<i>X</i>.<i>Y</i>.tgz | tar xvf -</samp></li>
1015 <li>Change directory to <code>icu/source</code>.
1016 <samp>cd icu/source</samp>
1019 <li>Some files may have the wrong permissions.<samp>chmod +x runConfigureICU configure install-sh</samp></li>
1021 <li>Run the <span style='font-family: monospace;'><a href="source/runConfigureICU">runConfigureICU</a></span>
1022 script for your platform. (See <a href="#HowToConfigureICU">configuration
1023 note</a> below).</li>
1025 <li>Now build: <samp>gmake</samp> (or just <code>make</code> if GNU make is the default make on
1026 your platform) to compile the libraries and all the data files. The proper
1027 name of the GNU make command is printed at the end of the configuration
1028 run, as in <tt>"You must use gmake to compile ICU"</tt>.
1030 Note that the compilation command output may be simplified on your platform. If this is the case, you will see just:
1031 <tt>gcc ... stubdata.c</tt>
1033 <tt>gcc -DU_NO_DEFAULT_INCLUDE_UTF_HEADERS=1 -D_REENTRANT -I../common -DU_ATTRIBUTE_DEPRECATED= -O2 -Wall -std=c99 -pedantic -Wshadow -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -c -DPIC -fPIC -o stubdata.o stubdata.c</tt>
1035 If you need to see the whole compilation line, use <span style='font-family: monospace;'>"gmake VERBOSE=1"</span>. The full compilation line will print if an error occurs.
1038 <li>Optionally,<samp>gmake check</samp> will run the test suite, which
1039 checks for ICU's functionality integrity (See <a href=
1040 "#HowToTestWithoutGmake">testing note</a> below).</li>
1042 <li>To install, <samp>gmake install</samp> to install ICU. If you used the --prefix=
1043 option on configure or runConfigureICU, ICU will be installed to the
1044 directory you specified. (See <a href="#HowToInstallICU">installation
1045 note</a> below).</li>
1048 <p><a name="HowToConfigureICU" id="HowToConfigureICU"><strong>Configuring ICU
1049 NOTE:</strong></a> Type <tt>"./runConfigureICU --help"</tt> for help on how
1050 to run it and a list of supported platforms. You may also want to type
1051 <tt>"./configure --help"</tt> to print the available configure options that
1052 you may want to give runConfigureICU. If you are not using the
1053 runConfigureICU script, or your platform is not supported by the script, you
1054 may need to set your CC, CXX, CFLAGS and CXXFLAGS environment variables, and
1055 type <tt>"./configure"</tt>.
1056 HP-UX users, please see this <a href="#ImportantNotesHPUX">note regarding
1057 HP-UX multithreaded build issues</a> with newer compilers. Solaris users,
1058 please see this <a href="#ImportantNotesSolaris">note regarding Solaris
1059 multithreaded build issues</a>.</p>
1061 <p>ICU is built with strict compiler warnings enabled by default. If this
1062 causes excessive numbers of warnings on your platform, use the --disable-strict
1063 option to configure to reduce the warning level.</p>
1065 <p><a name="HowToTestWithoutGmake" id="HowToTestWithoutGmake"><strong>Running
1066 The Tests From The Command Line NOTE:</strong></a> You may have to set
1067 certain variables if you with to run test programs individually, that is
1068 apart from "gmake check". The environment variable <strong>ICU_DATA</strong>
1069 can be set to the full pathname of the data directory to indicate where the
1070 locale data files and conversion mapping tables are when you are not using
1071 the shared library (e.g. by using the .dat archive or the individual data
1072 files). The trailing "/" is required after the directory name (e.g.
1073 "$Root/source/data/out/" will work, but the value "$Root/source/data/out" is
1074 not acceptable). You do not need to set <strong>ICU_DATA</strong> if the
1075 complete shared data library is in your library path.</p>
1077 <p><a name="HowToInstallICU" id="HowToInstallICU"><strong>Installing ICU
1078 NOTE:</strong></a> Some platforms use package management tools to control the
1079 installation and uninstallation of files on the system, as well as the
1080 integrity of the system configuration. You may want to check if ICU can be
1081 packaged for your package management tools by looking into the "packaging"
1082 directory. (Please note that if you are using a snapshot of ICU from Subversion, it
1083 is probable that the packaging scripts or related files are not up to date
1084 with the contents of ICU at this time, so use them with caution).</p>
1086 <h3><a name="HowToBuildZOS" href="#HowToBuildZOS" id="HowToBuildZOS">How To
1087 Build And Install On z/OS (OS/390)</a></h3>
1089 <p>You can install ICU on z/OS or OS/390 (the previous name of z/OS), but IBM
1090 tests only the z/OS installation. You install ICU in a z/OS UNIX system
1091 services file system such as HFS or zFS. On this platform, it is important
1092 that you understand a few details:</p>
1095 <li>The makedep and GNU make tools are required for building ICU. If it
1096 is not already installed on your system, it is available at the <a href=
1097 "http://www-03.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html">z/OS UNIX -
1098 Tools and Toys</a> site. The PATH environment variable should be updated to
1099 contain the location of this executable prior to build. Failure to add these
1100 tools to your PATH will cause ICU build failures or cause pkgdata to fail
1103 <li>Since USS does not support using the mmap() function over NFS, it is
1104 recommended that you build ICU on a local filesystem. Once ICU has been
1105 built, you should not have this problem while using ICU when the data
1106 library has been built as a shared library, which is this is the default
1109 <li>Encoding considerations: The source code assumes that it is compiled
1110 with codepage ibm-1047 (to be exact, the UNIX System Services variant of
1111 it). The pax command converts all of the source code files from ASCII to
1112 codepage ibm-1047 (USS) EBCDIC. However, some files are binary files and
1113 must not be converted, or must be converted back to their original state.
1114 You can use the <a href="as_is/os390/unpax-icu.sh">unpax-icu.sh</a> script
1115 to do this for you automatically. It will unpackage the tar file and
1116 convert all the necessary files for you automatically.</li>
1118 <li>z/OS supports both native S/390 hexadecimal floating point and (with
1119 OS/390 2.6 and later) IEEE 754 binary floating point. This is a compile
1120 time option. Applications built with IEEE should use ICU DLLs that are
1121 built with IEEE (and vice versa). The environment variable IEEE390=0 will
1122 cause the z/OS version of ICU to be built without IEEE floating point
1123 support and use the native hexadecimal floating point. By default ICU is
1124 built with IEEE 754 support. Native floating point support is sufficient
1125 for codepage conversion, resource bundle and UnicodeString operations, but
1126 the Format APIs require IEEE binary floating point.</li>
1128 <li>z/OS introduced the concept of Extra Performance Linkage (XPLINK) to
1129 bring performance improvement opportunities to call-intensive C and C++
1130 applications such as ICU. XPLINK is enabled on a DLL-by-DLL basis, so if
1131 you are considering using XPLINK in your application that uses ICU, you
1132 should consider building the XPLINK-enabled version of ICU. You need to
1133 set ICU's environment variable <code>OS390_XPLINK=1</code> prior to
1134 invoking the make process to produce binaries that are enabled for
1135 XPLINK. The XPLINK option, which is available for z/OS 1.2 and later,
1136 requires the PTF PQ69418 to build XPLINK enabled binaries.</li>
1138 <li>ICU requires XPLINK for the icuio library. If you want to use the
1139 rest of ICU without XPLINK, then you must use the --disable-icuio
1140 configure option.</li>
1142 <li>The latest versions of z/OS use <a
1143 href="http://www.ibm.com/support/docview.wss?uid=swg2120240">XPLINK
1144 version (C128) of the C++ standard library</a> by default. You may see <a
1145 href="http://www.ibm.com/support/docview.wss?uid=swg21376279">an
1146 error</a> when running with XPLINK disabled. To avoid this error,
1147 set the following environment variable or similar:
1149 <pre><samp>export _CXX_PSYSIX="CEE.SCEELIB(C128N)":"CBC.SCLBSID(IOSTREAM,COMPLEX)"</samp></pre>
1152 <li>When building ICU data, the heap size may need to be increased with the following
1153 environment variable:
1155 <pre><samp>export _CEE_RUNOPTS="HEAPPOOLS(ON),HEAP(4M,1M,ANY,FREE,0K,4080)"</samp></pre>
1159 <li>The rest of the instructions for building and testing ICU on z/OS with
1160 UNIX System Services are the same as the <a href="#HowToBuildUNIX">How To
1161 Build And Install On UNIX</a> section.</li>
1164 <h4>z/OS (Batch/PDS) support outside the UNIX system services
1167 <p>By default, ICU builds its libraries into the UNIX file system (HFS). In
1168 addition, there is a z/OS specific environment variable (OS390BATCH) to build
1169 some libraries into the z/OS native file system. This is useful, for example,
1170 when your application is externalized via Job Control Language (JCL).</p>
1172 <p>The OS390BATCH environment variable enables non-UNIX support including the
1173 batch environment. When OS390BATCH is set, the libicui18n<i>XX</i>.dll,
1174 libicuuc<i>XX</i>.dll, and libicudt<i>XX</i>e.dll binaries are built into
1175 data sets (the native file system). Turning on OS390BATCH does not turn off
1176 the normal z/OS UNIX build. This means that the z/OS UNIX (HFS) DLLs will
1177 always be created.</p>
1179 <p>Two additional environment variables indicate the names of the z/OS data
1180 sets to use. The LOADMOD environment variable identifies the name of the data
1181 set that contains the dynamic link libraries (DLLs) and the LOADEXP
1182 environment variable identifies the name of the data set that contains the
1183 side decks, which are normally the files with the .x suffix in the UNIX file
1186 <p>A data set is roughly equivalent to a UNIX or Windows file. For most kinds
1187 of data sets the operating system maintains record boundaries. UNIX and
1188 Windows files are byte streams. Two kinds of data sets are PDS and PDSE. Each
1189 data set of these two types contains a directory. It is like a UNIX
1190 directory. Each "file" is called a "member". Each member name is limited to
1191 eight bytes, normally EBCDIC.</p>
1193 <p>Here is an example of some environment variables that you can set prior to
1197 LOADMOD=<i>USER</i>.ICU.LOAD
1198 LOADEXP=<i>USER</i>.ICU.EXP</samp>
1201 <p>The PDS member names for the DLL file names are as follows:</p>
1203 <samp>IXMI<i>XX</i>IN --> libicui18n<i>XX</i>.dll
1204 IXMI<i>XX</i>UC --> libicuuc<i>XX</i>.dll
1205 IXMI<i>XX</i>DA --> libicudt<i>XX</i>e.dll</samp>
1208 <p>You should point the LOADMOD environment variable at a partitioned data
1209 set extended (PDSE) and point the LOADEXP environment variable at a
1210 partitioned data set (PDS). The PDSE can be allocated with the following
1213 <samp>Data Set Name . . . : <i>USER</i>.ICU.LOAD
1214 Management class. . : <i>**None**</i>
1215 Storage class . . . : <i>BASE</i>
1216 Volume serial . . . : <i>TSO007</i>
1217 Device type . . . . : <i>3390</i>
1218 Data class. . . . . : <i>LOAD</i>
1219 Organization . . . : PO
1220 Record format . . . : U
1221 Record length . . . : 0
1222 Block size . . . . : <i>32760</i>
1223 1st extent cylinders: 1
1224 Secondary cylinders : 5
1225 Data set name type : LIBRARY</samp>
1228 <p>The PDS can be allocated with the following attributes:</p>
1230 <samp>Data Set Name . . . : <i>USER</i>.ICU.EXP
1231 Management class. . : <i>**None**</i>
1232 Storage class . . . : <i>BASE</i>
1233 Volume serial . . . : <i>TSO007</i>
1234 Device type . . . . : <i>3390</i>
1235 Data class. . . . . : <i>**None**</i>
1236 Organization . . . : PO
1237 Record format . . . : FB
1238 Record length . . . : 80
1239 Block size . . . . : <i>3200</i>
1240 1st extent cylinders: 3
1241 Secondary cylinders : 3
1242 Data set name type : PDS</samp>
1245 <h3><a name="HowToBuildOS400" href="#HowToBuildOS400" id=
1246 "HowToBuildOS400">How To Build And Install On The IBM i Family (IBM i, i5/OS OS/400)</a></h3>
1248 <p>Before you start building ICU, ICU requires the following:</p>
1251 <li>QSHELL interpreter installed (install base option 30, operating system)
1252 <!--li>QShell Utilities, PRPQ 5799-XEH (not required for V4R5)</li--></li>
1254 <li>ILE C/C++ Compiler installed on the system</li>
1256 <li>The latest IBM tools for Developers for IBM i —
1257 <a href='http://www.ibm.com/servers/enable/site/porting/tools/'>http://www.ibm.com/servers/enable/site/porting/tools/</a>
1258 <!-- formerly: http://www.ibm.com/servers/enable/site/porting/iseries/overview/gnu_utilities.html -->
1262 <p>The following describes how to setup and build ICU. For background
1263 information, you should look at the <a href="#HowToBuildUNIX">UNIX build
1264 instructions</a>.</p>
1268 Copy the ICU source .tgz to the IBM i environment, as binary.
1269 Also, copy the <a href='as_is/os400/unpax-icu.sh'>unpax-icu.sh</a> script into the same directory, as a text file.
1273 Create target library. This library will be the target for the
1274 resulting modules, programs and service programs. You will specify this
1275 library on the OUTPUTDIR environment variable.
1277 <samp>CRTLIB LIB(<i>libraryname</i>)
1278 ADDENVVAR ENVVAR(OUTPUTDIR) VALUE('<i>libraryname</i>') REPLACE(*YES) </samp></pre>
1282 Set up the following environment variables and job characteristics in your build process
1284 <samp>ADDENVVAR ENVVAR(MAKE) VALUE('gmake') REPLACE(*YES)
1285 CHGJOB CCSID(37)</samp></pre></li>
1287 <li>Fire up the QSH <i>(all subsequent commands are run inside the qsh session.)</i>
1288 <pre><samp>qsh</samp></pre>
1291 <li>Set up the PATH: <pre><samp>export PATH=/QIBM/ProdData/DeveloperTools/qsh/bin:$PATH:/QOpenSys/usr/bin</samp></pre>
1294 <li>Unpack the ICU source code archive:
1295 <pre><samp>gzip -d icu-<i>X</i>.<i>Y</i>.tgz</samp></pre>
1298 <li>Run unpax-icu.sh on the tar file generated from the previous step.
1299 <pre><samp>unpax-icu.sh icu.tar</samp></pre></li>
1301 <li>Build the program ICULD which ICU will use for linkage.
1302 <pre><samp>cd icu/as_is/os400
1304 cd ../../..</samp></pre>
1307 <li>Change into the 'source' directory, and configure ICU. (See <a href="#HowToConfigureICU">configuration
1308 note</a> for details). Note that --with-data-packaging=archive and setting the --prefix are recommended, building in default (dll) mode is currently not supported.
1309 <pre><samp>cd icu/source
1310 ./runConfigureICU IBMi --prefix=<i>/path/to/somewhere</i> --with-data-packaging=archive</samp></pre>
1313 <li>Build ICU. <i>(Note: Do not use the -j option)</i> <pre><samp>gmake</samp></pre></li>
1315 <li>Test ICU. <pre><samp>gmake check</samp></pre>
1316 (The <tt> QIBM_MULTI_THREADED=Y</tt> flag will be automatically applied to intltest -
1317 you can look at the <a href=
1318 "http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/apis/concept4.htm">
1319 iSeries Information Center</a> for more details regarding the running of multiple threads
1324 <h3><a name="HowToCrossCompileICU" href="#HowToCrossCompileICU" id="HowToCrossCompileICU">How To Cross Compile ICU</a></h3>
1325 <p>This section will explain how to build ICU on one platform, but to produce binaries intended to run on another. This is commonly known as a cross compile.</p>
1326 <p>Normally, in the course of a build, ICU needs to run the tools that it builds in order to generate and package data and test-data.In a cross compilation setting, ICU is built on a different system from that which it eventually runs on. An example might be, if you are building for a small/headless system (such as an embedded device), or a system where you can't easily run the ICU command line tools (any non-UNIX-like system).</p>
1327 <p>To reduce confusion, we will here refer to the "A" and the "B" system.System "A" is the actual system we will be running on- the only requirements on it is are it is able to build ICU from the command line targetting itself (with configure or runConfigureICU), and secondly, that it also contain the correct toolchain for compiling and linking for the resultant platform, referred to as the "B" system.</p>
1328 <p>The autoconf docs use the term "build" for A, and "host" for B. More details at: <a href="http://www.gnu.org/software/autoconf/manual/html_node/Specifying-Names.html#Specifying-Names">http://www.gnu.org/software/autoconf/manual/html_node/Specifying-Names.html</a></p>
1329 <p>Three initially-empty directories will be used in this example:</p>
1330 <table summary="Three directories used in this example" class="docTable">
1332 <th align="left">/icu</th><td>a copy of the ICU source</td>
1335 <th align="left">/buildA</th><td>an empty directory, it will contain ICU built for A<br />(MacOSX in this case)</td>
1338 <th align="left">/buildB</th><td>an empty directory, it will contain ICU built for B<br />(HaikuOS in this case)</td>
1343 <li>Check out or unpack the ICU source code into the /icu directory.You will have the directories /icu/source, etc.</li>
1344 <li>Build ICU in /buildA normally (using runConfigureICU or configure):
1345 <pre class="samp">cd /buildA
1346 sh /icu/source/runConfigureICU <strong>MacOSX</strong>
1350 <li>Set PATH or other variables as needed, such as CPPFLAGS.</li>
1351 <li>Build ICU in /buildB<br />
1352 <p class="note">"<code>--with-cross-build</code>" takes an absolute path.</p>
1353 <pre class="samp">cd /buildB
1354 sh /icu/source/configure --host=<strong>i586-pc-haiku</strong> --with-cross-build=<strong>/buildA</strong>
1357 <li>Tests and testdata can be built with "gnumake tests".</li>
1361 <!-- end build environment -->
1363 <h2><a name="HowToPackage" href="#HowToPackage" id="HowToPackage">How To
1364 Package ICU</a></h2>
1366 <p>There are many ways that a person can package ICU with their software
1367 products. Usually only the libraries need to be considered for packaging.</p>
1369 <p>On UNIX, you should use "<tt>gmake install</tt>" to make it easier to
1370 develop and package ICU. The bin, lib and include directories are needed to
1371 develop applications that use ICU. These directories will be created relative
1372 to the "<tt>--prefix=</tt><i>dir</i>" configure option (See the <a href=
1373 "#HowToBuildUNIX">UNIX build instructions</a>). When ICU is built on Windows,
1374 a similar directory structure is built.</p>
1376 <p>When changes have been made to the standard ICU distribution, it is
1377 recommended that at least one of the following guidelines be followed for
1378 special packaging.</p>
1381 <li>Add a suffix name to the library names. This can be done with the
1382 --with-library-suffix configure option.</li>
1384 <li>The installation script should install the ICU libraries into the
1385 application's directory.</li>
1388 <p>Following these guidelines prevents other applications that use a standard
1389 ICU distribution from conflicting with any libraries that you need. On
1390 operating systems that do not have a standard C++ ABI (name mangling) for
1391 compilers, it is recommended to do this special packaging anyway. More
1392 details on customizing ICU are available in the <a href=
1393 "http://userguide.icu-project.org/">User's Guide</a>. The <a href=
1394 "#SourceCode">ICU Source Code Organization</a> section of this readme.html
1395 gives a more complete description of the libraries.</p>
1397 <table class="docTable" summary=
1398 "ICU has several libraries for you to use.">
1400 Here is an example of libraries that are frequently packaged.
1404 <th scope="col">Library Name</th>
1406 <th scope="col">Windows Filename</th>
1408 <th scope="col">Linux Filename</th>
1410 <th scope="col">Comment</th>
1414 <td>Data Library</td>
1416 <td>icudt<i>XY</i>l.dll</td>
1418 <td>libicudata.so.<i>XY</i>.<i>Z</i></td>
1420 <td>Data required by the Common and I18n libraries. There are many ways
1421 to package and <a href=
1422 "http://userguide.icu-project.org/icudata">customize this
1423 data</a>, but by default this is all you need.</td>
1427 <td>Common Library</td>
1429 <td>icuuc<i>XY</i>.dll</td>
1431 <td>libicuuc.so.<i>XY</i>.<i>Z</i></td>
1433 <td>Base library required by all other ICU libraries.</td>
1437 <td>Internationalization (i18n) Library</td>
1439 <td>icuin<i>XY</i>.dll</td>
1441 <td>libicui18n.so.<i>XY</i>.<i>Z</i></td>
1443 <td>A library that contains many locale based internationalization (i18n)
1448 <td>Layout Engine</td>
1450 <td>icule<i>XY</i>.dll</td>
1452 <td>libicule.so.<i>XY</i>.<i>Z</i></td>
1454 <td>An optional engine for doing font layout.</td>
1458 <td>Layout Extensions Engine</td>
1460 <td>iculx<i>XY</i>.dll</td>
1462 <td>libiculx.so.<i>XY</i>.<i>Z</i></td>
1464 <td>An optional engine for doing font layout that uses parts of ICU.</td>
1468 <td>ICU I/O (Unicode stdio) Library</td>
1470 <td>icuio<i>XY</i>.dll</td>
1472 <td>libicuio.so.<i>XY</i>.<i>Z</i></td>
1474 <td>An optional library that provides a stdio like API with Unicode
1479 <td>Tool Utility Library</td>
1481 <td>icutu<i>XY</i>.dll</td>
1483 <td>libicutu.so.<i>XY</i>.<i>Z</i></td>
1485 <td>An internal library that contains internal APIs that are only used by
1486 ICU's tools. If you do not use ICU's tools, you do not need this
1491 <p>Normally only the above ICU libraries need to be considered for packaging.
1492 The versionless symbolic links to these libraries are only needed for easier
1493 development. The <i>X</i>, <i>Y</i> and <i>Z</i> parts of the name are the
1494 version numbers of ICU. For example, ICU 2.0.2 would have the name
1495 libicuuc.so.20.2 for the common library. The exact format of the library
1496 names can vary between platforms due to how each platform can handles library
1499 <h2><a name="ImportantNotes" href="#ImportantNotes" id=
1500 "ImportantNotes">Important Notes About Using ICU</a></h2>
1502 <h3><a name="ImportantNotesMultithreaded" href="#ImportantNotesMultithreaded"
1503 id="ImportantNotesMultithreaded">Using ICU in a Multithreaded
1504 Environment</a></h3>
1506 <p>Some versions of ICU require calling the <code>u_init()</code> function
1507 from <code>uclean.h</code> to ensure that ICU is initialized properly. In
1508 those ICU versions, <code>u_init()</code> must be called before ICU is used
1509 from multiple threads. There is no harm in calling <code>u_init()</code> in a
1510 single-threaded application, on a single-CPU machine, or in other cases where
1511 <code>u_init()</code> is not required.</p>
1513 <p>In addition to ensuring thread safety, <code>u_init()</code> also attempts
1514 to load at least one ICU data file. Assuming that all data files are packaged
1515 together (or are in the same folder in files mode), a failure code from
1516 <code>u_init()</code> usually means that the data cannot be found. In this
1517 case, the data may not be installed properly, or the application may have
1518 failed to call <code>udata_setCommonData()</code> or
1519 <code>u_setDataDirectory()</code> which specify to ICU where it can find its
1522 <p>Since <code>u_init()</code> will load only one or two data files, it
1523 cannot guarantee that all of the data that an application needs is available.
1524 It cannot check for all data files because the set of files is customizable,
1525 and some ICU services work without loading any data at all. An application
1526 should always check for error codes when opening ICU service objects (using
1527 <code>ucnv_open()</code>, <code>ucol_open()</code>, C++ constructors,
1530 <h4>ICU 3.4 and later</h4>
1532 <p>ICU 3.4 self-initializes properly for multi-threaded use. It achieves this
1533 without performance penalty by hardcoding the core Unicode properties data,
1534 at the cost of some flexibility. (For details see Jitterbug 4497.)</p>
1536 <p><code>u_init()</code> can be used to check for data loading. It tries to
1537 load the converter alias table (<code>cnvalias.icu</code>).</p>
1539 <h4>ICU 2.6..3.2</h4>
1541 <p>These ICU versions require a call to <code>u_init()</code> before
1542 multi-threaded use. The services that are directly affected are those that
1543 don't have a service object and need to be fast: normalization and character
1546 <p><code>u_init()</code> loads and initializes the data files for
1547 normalization and character properties (<code>unorm.icu</code> and
1548 <code>uprops.icu</code>) and can therefore also be used to check for data
1551 <h4>ICU 2.4 and earlier</h4>
1553 <p>ICU 2.4 and earlier versions were not prepared for multithreaded use on
1554 multi-CPU platforms where the CPUs implement weak memory coherency. These
1555 CPUs include: Power4, Power5, Alpha, Itanium. <code>u_init()</code> was not
1558 <h4><a name="ImportantNotesHPUX" href="#ImportantNotesHPUX" id=
1559 "ImportantNotesHPUX">Using ICU in a Multithreaded Environment on
1562 <p>When ICU is built with aCC on HP-UX, the <a
1563 href="http://h21007.www2.hp.com/portal/site/dspp/menuitem.863c3e4cbcdc3f3515b49c108973a801?ciid=eb08b3f1eee02110b3f1eee02110275d6e10RCRD">-AA</a>
1564 compiler flag is used. It is required in order to use the latest
1565 <iostream> API in a thread safe manner. This compiler flag affects the
1566 version of the C++ library being used. Your applications will also need to
1567 be compiled with -AA in order to use ICU.</p>
1569 <h4><a name="ImportantNotesSolaris" href="#ImportantNotesSolaris" id=
1570 "ImportantNotesSolaris">Using ICU in a Multithreaded Environment on
1573 <h5>Linking on Solaris</h5>
1575 <p>In order to avoid synchronization and threading issues, developers are
1576 <strong>suggested</strong> to strictly follow the compiling and linking
1577 guidelines for multithreaded applications, specified in the following
1578 document from Sun Microsystems. Most notably, pay strict attention to the
1579 following statements from Sun:</p>
1582 <p>To use libthread, specify -lthread before -lc on the ld command line, or
1583 last on the cc command line.</p>
1585 <p>To use libpthread, specify -lpthread before -lc on the ld command line,
1586 or last on the cc command line.</p>
1589 <p>Failure to do this may cause spurious lock conflicts, recursive mutex
1590 failure, and deadlock.</p>
1592 <p>Source: "<i>Solaris Multithreaded Programming Guide, Compiling and
1593 Debugging</i>", Sun Microsystems, Inc., Apr 2004<br />
1595 "http://docs.sun.com/app/docs/doc/816-5137/6mba5vpke?a=view">http://docs.sun.com/app/docs/doc/816-5137/6mba5vpke?a=view</a></p>
1597 <h3><a name="ImportantNotesWindows" href="#ImportantNotesWindows" id=
1598 "ImportantNotesWindows">Windows Platform</a></h3>
1600 <p>If you are building on the Win32 platform, it is important that you
1601 understand a few of the following build details.</p>
1603 <h4>DLL directories and the PATH setting</h4>
1605 <p>As delivered, the International Components for Unicode build as several
1606 DLLs, which are placed in the "<i><ICU></i>\bin" directory. You must
1607 add this directory to the PATH environment variable in your system, or any
1608 executables you build will not be able to access International Components for
1609 Unicode libraries. Alternatively, you can copy the DLL files into a directory
1610 already in your PATH, but we do not recommend this. You can wind up with
1611 multiple copies of the DLL and wind up using the wrong one.</p>
1613 <h4><a name="ImportantNotesWindowsPath" id=
1614 "ImportantNotesWindowsPath">Changing your PATH</a></h4>
1616 <p><strong>Windows 2000/XP</strong>: Use the System Icon in the Control
1617 Panel. Pick the "Advanced" tab. Select the "Environment Variables..."
1618 button. Select the variable PATH in the lower box, and select the lower
1619 "Edit..." button. In the "Variable Value" box, append the string
1620 ";<i><ICU></i>\bin" to the end of the path string. If there is
1621 nothing there, just type in "<i><ICU></i>\bin". Click the Set button,
1622 then the OK button.</p>
1624 <p>Note: When packaging a Windows application for distribution and
1625 installation on user systems, copies of the ICU DLLs should be included with
1626 the application, and installed for exclusive use by the application. This is
1627 the only way to insure that your application is running with the same version
1628 of ICU, built with exactly the same options, that you developed and tested
1629 with. Refer to Microsoft's guidelines on the usage of DLLs, or search for the
1630 phrase "DLL hell" on <a href=
1631 "http://msdn.microsoft.com/">msdn.microsoft.com</a>.</p>
1633 <h3><a name="ImportantNotesUNIX" href="#ImportantNotesUNIX" id=
1634 "ImportantNotesUNIX">UNIX Type Platform</a></h3>
1636 <p>If you are building on a UNIX platform, and if you are installing ICU in a
1637 non-standard location, you may need to add the location of your ICU libraries
1638 to your <strong>LD_LIBRARY_PATH</strong> or <strong>LIBPATH</strong>
1639 environment variable (or the equivalent runtime library path environment
1640 variable for your system). The ICU libraries may not link or load properly
1641 without doing this.</p>
1643 <p>Note that if you do not want to have to set this variable, you may instead
1644 use the --enable-rpath option at configuration time. This option will
1645 instruct the linker to always look for the libraries where they are
1646 installed. You will need to use the appropriate linker options when linking
1647 your own applications and libraries against ICU, too. Please refer to your
1648 system's linker manual for information about runtime paths. The use of rpath
1649 also means that when building a new version of ICU you should not have an
1650 older version installed in the same place as the new version's installation
1651 directory, as the older libraries will used during the build, instead of the
1652 new ones, likely leading to an incorrectly build ICU. This is the proper
1653 behavior of rpath.</p>
1655 <h2><a name="PlatformDependencies" href="#PlatformDependencies" id=
1656 "PlatformDependencies">Platform Dependencies</a></h2>
1658 <h3><a name="PlatformDependenciesNew" href="#PlatformDependenciesNew" id=
1659 "PlatformDependenciesNew">Porting To A New Platform</a></h3>
1661 <p>If you are using ICU's Makefiles to build ICU on a new platform, there are
1662 a few places where you will need to add or modify some files. If you need
1663 more help, you can always ask the <a href=
1664 "http://site.icu-project.org/contacts">icu-support mailing list</a>. Once
1665 you have finished porting ICU to a new platform, it is recommended that you
1666 contribute your changes back to ICU via the icu-support mailing list. This
1667 will make it easier for everyone to benefit from your work.</p>
1669 <h4>Data For a New Platform</h4>
1671 <p>For some people, it may not be necessary for completely build ICU. Most of
1672 the makefiles and build targets are for tools that are used for building
1673 ICU's data, and an application's data (when an application uses ICU resource
1674 bundles for its data).</p>
1676 <p>Data files can be built on a different platform when both platforms share
1677 the same endianness and the same charset family. This assertion does not
1678 include platform dependent DLLs/shared/static libraries. For details see the
1679 User Guide <a href="http://userguide.icu-project.org/icudata">ICU
1680 Data</a> chapter.</p>
1682 <p>ICU 3.6 removes the requirement that ICU be completely built in the native
1683 operating environment. It adds the icupkg tool which can be run on any
1684 platform to turn binary ICU data files from any one of the three formats into
1685 any one of the other data formats. This allows a application to use ICU data
1686 built anywhere to be used for any other target platform.</p>
1688 <p><strong>WARNING!</strong> Building ICU without running the tests is not
1689 recommended. The tests verify that ICU is safe to use. It is recommended that
1690 you try to completely port and test ICU before using the libraries for your
1691 own application.</p>
1693 <h4>Adapting Makefiles For a New Platform</h4>
1695 <p>Try to follow the build steps from the <a href="#HowToBuildUNIX">UNIX</a>
1696 build instructions. If the configure script fails, then you will need to
1697 modify some files. Here are the usual steps for porting to a new
1702 <li>Create an mh file in icu/source/config/. You can use mh-linux or a
1703 similar mh file as your base configuration.</li>
1705 <li>Modify icu/source/aclocal.m4 to recognize your platform's mh file.</li>
1707 <li>Modify icu/source/configure.in to properly set your <b>platform</b> C
1710 <li>Run <a href="http://www.gnu.org/software/autoconf/">autoconf</a> in
1711 icu/source/ without any options. The autoconf tool is standard on most
1714 <li>If you have any optimization options that you want to normally use, you
1715 can modify icu/source/runConfigureICU to specify those options for your
1718 <li>Build and test ICU on your platform. It is very important that you run
1719 the tests. If you don't run the tests, there is no guarentee that you have
1720 properly ported ICU.</li>
1723 <h3><a name="PlatformDependenciesImpl" href="#PlatformDependenciesImpl" id=
1724 "PlatformDependenciesImpl">Platform Dependent Implementations</a></h3>
1726 <p>The platform dependencies have been mostly isolated into the following
1727 files in the common library. This information can be useful if you are
1728 porting ICU to a new platform.</p>
1732 <strong>unicode/platform.h.in</strong> (autoconf'ed platforms)<br />
1733 <strong>unicode/p<i>XXXX</i>.h</strong> (others: pwin32.h, ppalmos.h,
1734 ..): Platform-dependent typedefs and defines:<br />
1739 <li>Generic types like UBool, int8_t, int16_t, int32_t, int64_t,
1742 <li>U_EXPORT and U_IMPORT for specifying dynamic library import and
1745 <li>String handling support for the char16_t and wchar_t types.</li>
1751 <strong>unicode/putil.h, putil.c</strong>: platform-dependent
1752 implementations of various functions that are platform dependent:<br />
1757 <li>uprv_isNaN, uprv_isInfinite, uprv_getNaN and uprv_getInfinity for
1758 handling special floating point values.</li>
1760 <li>uprv_tzset, uprv_timezone, uprv_tzname and time for getting
1761 platform specific time and time zone information.</li>
1763 <li>u_getDataDirectory for getting the default data directory.</li>
1765 <li>uprv_getDefaultLocaleID for getting the default locale
1768 <li>uprv_getDefaultCodepage for getting the default codepage
1775 <strong>umutex.h, umutex.c</strong>: Code for doing synchronization in
1776 multithreaded applications. If you wish to use International Components
1777 for Unicode in a multithreaded application, you must provide a
1778 synchronization primitive that the classes can use to protect their
1779 global data against simultaneous modifications. We already supply working
1780 implementations for many platforms that ICU builds on.<br />
1784 <li><strong>umapfile.h, umapfile.c</strong>: functions for mapping or
1785 otherwise reading or loading files into memory. All access by ICU to data
1786 from files makes use of these functions.<br />
1790 <li>Using platform specific #ifdef macros are highly discouraged outside of
1791 the scope of these files. When the source code gets updated in the future,
1792 these #ifdef's can cause testing problems for your platform.</li>
1796 <p>Copyright © 1997-2014 International Business Machines Corporation and
1797 others. All Rights Reserved.<br />
1798 IBM Globalization Center of Competency - San José<br />
1799 4400 North First Street<br />
1800 San José, CA 95134<br />
projects / platform / upstream / icu.git / blob