intl/icu/readme.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3
   4 <html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
   5   <head>
   6     <title>ReadMe for ICU 50.1.2</title>
   7     <meta name="COPYRIGHT" content=
   8     "Copyright (c) 1997-2013 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"/>
  15   </head>
  16
  17   <body class="draft">
  18     <h1>International Components for Unicode<br />
  19      <abbr title="International Components for Unicode">ICU</abbr> 50.1.2 ReadMe</h1>
  20
  21     <!--<p><b>Note:</b> This is a development milestone release of ICU4C 50.
  22     This milestone is intended for those wishing to get an early look at ICU 50 new features and API changes.
  23     It is not recommended for production use.</p>-->
  24     <!--<p><b>Note:</b> This is a release candidate version of ICU4C 50.
  25     It is not recommended for production use.</p>-->
  26
  27     <p>Last updated: 2013-Jan-10<br />
  28      Copyright &copy; 1997-2013 International Business Machines Corporation and
  29     others. All Rights Reserved.</p>
  30     <!-- Remember that there is a copyright at the end too -->
  31     <hr />
  32
  33     <h2 class="TOC">Table of Contents</h2>
  34
  35     <ul class="TOC">
  36       <li><a href="#Introduction">Introduction</a></li>
  37
  38       <li><a href="#GettingStarted">Getting Started</a></li>
  39
  40       <li><a href="#News">What Is New In This release?</a></li>
  41
  42       <li><a href="#Download">How To Download the Source Code</a></li>
  43
  44       <li><a href="#SourceCode">ICU Source Code Organization</a></li>
  45
  46       <li>
  47         <a href="#HowToBuild">How To Build And Install ICU</a>
  48
  49         <ul >
  50           <li><a href="#RecBuild">Recommended Build Options</a></li>
  51
  52           <li><a href="#UserConfig">User-Configurable Settings</a></li>
  53
  54           <li><a href="#HowToBuildWindows">Windows</a></li>
  55
  56           <li><a href="#HowToBuildCygwin">Cygwin</a></li>
  57
  58           <li><a href="#HowToBuildUNIX">UNIX</a></li>
  59
  60           <li><a href="#HowToBuildZOS">z/OS (os/390)</a></li>
  61
  62           <li><a href="#HowToBuildOS400">IBM i family (IBM i, i5/OS, OS/400)</a></li>
  63
  64                   <li><a href="#HowToCrossCompileICU">How to Cross Compile ICU</a></li>
  65         </ul>
  66       </li>
  67
  68
  69       <li><a href="#HowToPackage">How To Package ICU</a></li>
  70
  71       <li>
  72         <a href="#ImportantNotes">Important Notes About Using ICU</a>
  73
  74         <ul >
  75           <li><a href="#ImportantNotesMultithreaded">Using ICU in a Multithreaded
  76           Environment</a></li>
  77
  78           <li><a href="#ImportantNotesWindows">Windows Platform</a></li>
  79
  80           <li><a href="#ImportantNotesUNIX">UNIX Type Platforms</a></li>
  81         </ul>
  82       </li>
  83
  84       <li>
  85         <a href="#PlatformDependencies">Platform Dependencies</a>
  86
  87         <ul >
  88           <li><a href="#PlatformDependenciesNew">Porting To A New
  89           Platform</a></li>
  90
  91           <li><a href="#PlatformDependenciesImpl">Platform Dependent
  92           Implementations</a></li>
  93         </ul>
  94       </li>
  95     </ul>
  96     <hr />
  97
  98     <h2><a name="Introduction" href="#Introduction" id=
  99     "Introduction">Introduction</a></h2>
 100
 101     <p>Today's software market is a global one in which it is desirable to
 102     develop and maintain one application (single source/single binary) that
 103     supports a wide variety of languages. The International Components for
 104     Unicode (ICU) libraries provide robust and full-featured Unicode services on
 105     a wide variety of platforms to help this design goal. The ICU libraries
 106     provide support for:</p>
 107
 108     <ul>
 109       <li>The latest version of the Unicode standard</li>
 110
 111       <li>Character set conversions with support for over 220 codepages</li>
 112
 113       <li>Locale data for more than 290 locales</li>
 114
 115       <li>Language sensitive text collation (sorting) and searching based on the
 116       Unicode Collation Algorithm (=ISO 14651)</li>
 117
 118       <li>Regular expression matching and Unicode sets</li>
 119
 120       <li>Transformations for normalization, upper/lowercase, script
 121       transliterations (50+ pairs)</li>
 122
 123       <li>Resource bundles for storing and accessing localized information</li>
 124
 125       <li>Date/Number/Message formatting and parsing of culture specific
 126       input/output formats</li>
 127
 128       <li>Calendar specific date and time manipulation</li>
 129
 130       <li>Complex text layout for Arabic, Hebrew, Indic and Thai</li>
 131
 132       <li>Text boundary analysis for finding characters, word and sentence
 133       boundaries</li>
 134     </ul>
 135
 136     <p>ICU has a sister project ICU4J that extends the internationalization
 137     capabilities of Java to a level similar to ICU. The ICU C/C++ project is also
 138     called ICU4C when a distinction is necessary.</p>
 139
 140     <h2><a name="GettingStarted" href="#GettingStarted" id=
 141     "GettingStarted">Getting started</a></h2>
 142
 143     <p>This document describes how to build and install ICU on your machine. For
 144     other information about ICU please see the following table of links.<br />
 145      The ICU homepage also links to related information about writing
 146     internationalized software.</p>
 147
 148     <table class="docTable" summary="These are some useful links regarding ICU and internationalization in general.">
 149       <caption>
 150         Here are some useful links regarding ICU and internationalization in
 151         general.
 152       </caption>
 153
 154       <tr>
 155         <td>ICU, ICU4C &amp; ICU4J Homepage</td>
 156
 157         <td><a href=
 158         "http://icu-project.org/">http://icu-project.org/</a></td>
 159       </tr>
 160
 161       <tr>
 162         <td>FAQ - Frequently Asked Questions about ICU</td>
 163
 164         <td><a href=
 165         "http://userguide.icu-project.org/icufaq">http://userguide.icu-project.org/icufaq</a></td>
 166       </tr>
 167
 168       <tr>
 169         <td>ICU User's Guide</td>
 170
 171         <td><a href=
 172         "http://userguide.icu-project.org/">http://userguide.icu-project.org/</a></td>
 173       </tr>
 174
 175       <tr>
 176         <td>How To Use ICU</td>
 177
 178         <td><a href="http://userguide.icu-project.org/howtouseicu">http://userguide.icu-project.org/howtouseicu</a></td>
 179       </tr>
 180
 181       <tr>
 182         <td>Download ICU Releases</td>
 183
 184         <td><a href=
 185         "http://site.icu-project.org/download">http://site.icu-project.org/download</a></td>
 186       </tr>
 187
 188       <tr>
 189         <td>ICU4C API Documentation Online</td>
 190
 191         <td><a href=
 192         "http://icu-project.org/apiref/icu4c/">http://icu-project.org/apiref/icu4c/</a></td>
 193       </tr>
 194
 195       <tr>
 196         <td>Online ICU Demos</td>
 197
 198         <td><a href=
 199         "http://demo.icu-project.org/icu-bin/icudemos">http://demo.icu-project.org/icu-bin/icudemos</a></td>
 200       </tr>
 201
 202       <tr>
 203         <td>Contacts and Bug Reports/Feature Requests</td>
 204
 205         <td><a href=
 206         "http://site.icu-project.org/contacts">http://site.icu-project.org/contacts</a></td>
 207       </tr>
 208     </table>
 209
 210     <p><strong>Important:</strong> Please make sure you understand the <a href=
 211     "license.html">Copyright and License Information</a>.</p>
 212
 213     <h2><a name="News" href="#News" id="News">What is new in this
 214     release?</a></h2>
 215
 216     <p>To see which APIs are new or changed in this release, view the <a href="APIChangeReport.html">ICU4C API Change Report</a>. </p>
 217
 218     <p>The following list concentrates on <em>changes that affect existing
 219     applications migrating from previous ICU releases</em>.
 220     For more news about this release, see the
 221     <!--
 222     <a href="http://site.icu-project.org/download/">ICU download page</a>.
 223     -->
 224     <a href="http://site.icu-project.org/download/milestone">ICU milestone download page</a>.
 225     </p>
 226
 227     <h3>Thread safety support cannot be removed</h3>
 228     <p>ICU4C 50 dropped support for the --enable-threads/--disable-threads configure option
 229     and the uconfig.h <code>ICU_USE_THREADS</code> switch.
 230     ICU4C 50 and higher is always built with multi-threading safety support.
 231     ICU4C has never created threads in its libraries.</p>
 232
 233     <p>If you need to prevent ICU from using thread safe mutexes when your application does
 234     not create threads, then you can use the --enable-weak-threads configure option.
 235     The --enable-weak-threads configure option will cause ICU to weakly reference the
 236     pthread mutex functions, and the stub implementations in the C runtime will be used.
 237     If this configure option does not work on your platform, then you can call
 238     <code>u_setMutexFunctions()</code> and <code>u_setAtomicIncDecFunctions()</code>
 239     with your own empty implementations.</p>
 240
 241     <h3>The default compilers have changed</h3>
 242     <p>ICU has changed the compilers chosen by default. If the clang and clang++ compilers
 243     are available, those will be used instead of gcc and g++. If the clang compilers
 244     are not available, then gcc and g++ will be used just as before. The clang++ compiler
 245     provides C++11 support and some optimizations that are helpful to ICU. The API
 246     remains the same between these two sets of compilers, but ICU can internally leverage
 247     language features and optimizations that are available in clang++.</p>
 248
 249     <p>If you need to force ICU to compile with gcc and g++, then you can use the following
 250     from the command line in the source directory:</p>
 251
 252 <pre>
 253 <samp>./configure CC=gcc CXX=g++ CFLAGS=-O3 CXXFLAGS=-O3</samp>
 254 </pre>
 255
 256     <h3>C++ Collator subclassing-API breaking changes</h3>
 257     <p>We have made some changes to the C++ Collator API for ICU 50
 258     that will make it easier to use and implement the Collator but
 259     which are incompatible for subclasses.
 260     If there are subclasses, they will have to be modified as well.
 261     It will be easy to adapt subclass source code, if there is any.
 262     We think it is unlikely (or at least rare) that users write subclasses of the C++ Collator,
 263     given the number of virtual methods and the complexities of a collation implementation.</p>
 264
 265     <p>For details see the email "ICU4C C++ Collator subclassing-API breaking changes"
 266     sent on 2012-jul-25 to the icu-design and icu-support
 267     <a href="http://site.icu-project.org/contacts">mailing lists</a>,
 268     and <a href="http://bugs.icu-project.org/trac/ticket/9346">ICU ticket #9346</a>,
 269     including the <a href="http://bugs.icu-project.org/trac/review/9346">changes for that ticket</a>.</p>
 270
 271     <p>In particular, the <code>class TestCollator</code> in
 272     <a href="http://bugs.icu-project.org/trac/browser/icu/trunk/source/test/intltest/apicoll.cpp"><code>source/test/intltest/apicoll.cpp</code></a>
 273     <a href="http://bugs.icu-project.org/trac/changeset/32100#file5">illustrates how a subclass needs to be changed</a>.
 274     However, note that the TestCollator was also simplified slightly;
 275     not all changes made there were strictly required for the API signature changes.</p>
 276
 277     <h2><a name="Download" href="#Download" id="Download">How To Download the
 278     Source Code</a></h2>
 279
 280     <p>There are two ways to download ICU releases:</p>
 281
 282     <ul>
 283       <li><strong>Official Release Snapshot:</strong><br />
 284        If you want to use ICU (as opposed to developing it), you should download
 285       an official packaged version of the ICU source code. These versions are
 286       tested more thoroughly than day-to-day development builds of the system,
 287       and they are packaged in zip and tar files for convenient download. These
 288       packaged files can be found at <a href=
 289       "http://site.icu-project.org/download">http://site.icu-project.org/download</a>.<br />
 290        The packaged snapshots are named <strong>icu-nnnn.zip</strong> or
 291       <strong>icu-nnnn.tgz</strong>, where nnnn is the version number. The .zip
 292       file is used for Windows platforms, while the .tgz file is preferred on
 293       most other platforms.<br />
 294        Please unzip this file. </li>
 295
 296       <li><strong>Subversion Source Repository:</strong><br />
 297        If you are interested in developing features, patches, or bug fixes for
 298       ICU, you should probably be working with the latest version of the ICU
 299       source code. You will need to check the code out of our Subversion repository to
 300       ensure that you have the most recent version of all of the files. See our
 301       <a href="http://site.icu-project.org/repository">source
 302       repository</a> for details.</li>
 303     </ul>
 304
 305     <h2><a name="SourceCode" href="#SourceCode" id="SourceCode">ICU Source Code
 306     Organization</a></h2>
 307
 308     <p>In the descriptions below, <strong><i>&lt;ICU&gt;</i></strong> is the full
 309     path name of the ICU directory (the top level directory from the distribution
 310     archives) in your file system. You can also view the <a href=
 311     "http://userguide.icu-project.org/design">ICU Architectural
 312     Design</a> section of the User's Guide to see which libraries you need for
 313     your software product. You need at least the data (<code>[lib]icudt</code>)
 314     and the common (<code>[lib]icuuc</code>) libraries in order to use ICU.</p>
 315
 316     <table class="docTable" summary="The following files describe the code drop.">
 317       <caption>
 318         The following files describe the code drop.
 319       </caption>
 320
 321       <tr>
 322         <th scope="col">File</th>
 323
 324         <th scope="col">Description</th>
 325       </tr>
 326
 327       <tr>
 328         <td>readme.html</td>
 329
 330         <td>Describes the International Components for Unicode (this file)</td>
 331       </tr>
 332
 333       <tr>
 334         <td>license.html</td>
 335
 336         <td>Contains the text of the ICU license</td>
 337       </tr>
 338     </table>
 339
 340     <p><br />
 341     </p>
 342
 343     <table class="docTable" summary=
 344     "The following directories contain source code and data files.">
 345       <caption>
 346         The following directories contain source code and data files.
 347       </caption>
 348
 349       <tr>
 350         <th scope="col">Directory</th>
 351
 352         <th scope="col">Description</th>
 353       </tr>
 354
 355       <tr>
 356         <td><i>&lt;ICU&gt;</i>/source/<b>common</b>/</td>
 357
 358         <td>The core Unicode and support functionality, such as resource bundles,
 359         character properties, locales, codepage conversion, normalization,
 360         Unicode properties, Locale, and UnicodeString.</td>
 361       </tr>
 362
 363       <tr>
 364         <td><i>&lt;ICU&gt;</i>/source/<b>i18n</b>/</td>
 365
 366         <td>Modules in i18n are generally the more data-driven, that is to say
 367         resource bundle driven, components. These deal with higher-level
 368         internationalization issues such as formatting, collation, text break
 369         analysis, and transliteration.</td>
 370       </tr>
 371
 372       <tr>
 373         <td><i>&lt;ICU&gt;</i>/source/<b>layout</b>/</td>
 374
 375         <td>Contains the ICU layout engine (not a rasterizer).</td>
 376       </tr>
 377
 378       <tr>
 379         <td><i>&lt;ICU&gt;</i>/source/<b>io</b>/</td>
 380
 381         <td>Contains the ICU I/O library.</td>
 382       </tr>
 383
 384       <tr>
 385         <td><i>&lt;ICU&gt;</i>/source/<b>data</b>/</td>
 386
 387         <td>
 388           <p>This directory contains the source data in text format, which is
 389           compiled into binary form during the ICU build process. It contains
 390           several subdirectories, in which the data files are grouped by
 391           function. Note that the build process must be run again after any
 392           changes are made to this directory.</p>
 393
 394           <p>If some of the following directories are missing, it's probably
 395           because you got an official download. If you need the data source files
 396           for customization, then please download the ICU source code from <a
 397           href="http://site.icu-project.org/repository">subversion</a>.</p>
 398
 399           <ul>
 400             <li><b>in/</b> A directory that contains a pre-built data library for
 401             ICU. A standard source code package will contain this file without
 402             several of the following directories. This is to simplify the build
 403             process for the majority of users and to reduce platform porting
 404             issues.</li>
 405
 406             <li><b>brkitr/</b> Data files for character, word, sentence, title
 407             casing and line boundary analysis.</li>
 408
 409             <li><b>locales/</b> These .txt files contain ICU language and
 410             culture-specific localization data. Two special bundles are
 411             <b>root</b>, which is the fallback data and parent of other bundles,
 412             and <b>index</b>, which contains a list of installed bundles. The
 413             makefile <b>resfiles.mk</b> contains the list of resource bundle
 414             files.</li>
 415
 416             <li><b>mappings/</b> Here are the code page converter tables. These
 417             .ucm files contain mappings to and from Unicode. These are compiled
 418             into .cnv files. <b>convrtrs.txt</b> is the alias mapping table from
 419             various converter name formats to ICU internal format and vice versa.
 420             It produces cnvalias.icu. The makefiles <b>ucmfiles.mk,
 421             ucmcore.mk,</b> and <b>ucmebcdic.mk</b> contain the list of
 422             converters to be built.</li>
 423
 424             <li><b>translit/</b> This directory contains transliterator rules as
 425             resource bundles, a makefile <b>trnsfiles.mk</b> containing the list
 426             of installed system translitaration files, and as well the special
 427             bundle <b>translit_index</b> which lists the system transliterator
 428             aliases.</li>
 429
 430             <li><b>unidata/</b> This directory contains the Unicode data files.
 431             Please see <a href=
 432             "http://www.unicode.org/">http://www.unicode.org/</a> for more
 433             information.</li>
 434
 435             <li><b>misc/</b> The misc directory contains other data files which
 436             did not fit into the above categories. Currently it only contains
 437             time zone information, and a name preperation file for <a href=
 438             "http://www.ietf.org/rfc/rfc3490.txt">IDNA</a>.</li>
 439
 440             <li><b>out/</b> This directory contains the assembled memory mapped
 441             files.</li>
 442
 443             <li><b>out/build/</b> This directory contains intermediate (compiled)
 444             files, such as .cnv, .res, etc.</li>
 445           </ul>
 446
 447           <p>If you are creating a special ICU build, you can set the ICU_DATA
 448           environment variable to the out/ or the out/build/ directories, but
 449           this is generally discouraged because most people set it incorrectly.
 450           You can view the <a href=
 451           "http://userguide.icu-project.org/icudata">ICU Data
 452           Management</a> section of the ICU User's Guide for details.</p>
 453         </td>
 454       </tr>
 455
 456       <tr>
 457         <td><i>&lt;ICU&gt;</i>/source/test/<b>intltest</b>/</td>
 458
 459         <td>A test suite including all C++ APIs. For information about running
 460         the test suite, see the build instructions specific to your platform
 461         later in this document.</td>
 462       </tr>
 463
 464       <tr>
 465         <td><i>&lt;ICU&gt;</i>/source/test/<b>cintltst</b>/</td>
 466
 467         <td>A test suite written in C, including all C APIs. For information
 468         about running the test suite, see the build instructions specific to your
 469         platform later in this document.</td>
 470       </tr>
 471
 472       <tr>
 473         <td><i>&lt;ICU&gt;</i>/source/test/<b>iotest</b>/</td>
 474
 475         <td>A test suite written in C and C++ to test the icuio library. For
 476         information about running the test suite, see the build instructions
 477         specific to your platform later in this document.</td>
 478       </tr>
 479
 480       <tr>
 481         <td><i>&lt;ICU&gt;</i>/source/test/<b>testdata</b>/</td>
 482
 483         <td>Source text files for data, which are read by the tests. It contains
 484         the subdirectories <b>out/build/</b> which is used for intermediate
 485         files, and <b>out/</b> which contains <b>testdata.dat.</b></td>
 486       </tr>
 487
 488       <tr>
 489         <td><i>&lt;ICU&gt;</i>/source/<b>tools</b>/</td>
 490
 491         <td>Tools for generating the data files. Data files are generated by
 492         invoking <i>&lt;ICU&gt;</i>/source/data/build/makedata.bat on Win32 or
 493         <i>&lt;ICU&gt;</i>/source/make on UNIX.</td>
 494       </tr>
 495
 496       <tr>
 497         <td><i>&lt;ICU&gt;</i>/source/<b>samples</b>/</td>
 498
 499         <td>Various sample programs that use ICU</td>
 500       </tr>
 501
 502       <tr>
 503         <td><i>&lt;ICU&gt;</i>/source/<b>extra</b>/</td>
 504
 505         <td>Non-supported API additions. Currently, it contains the 'uconv' tool
 506         to perform codepage conversion on files.</td>
 507       </tr>
 508
 509       <tr>
 510         <td><i>&lt;ICU&gt;</i>/<b>packaging</b>/</td>
 511
 512         <td>This directory contain scripts and tools for packaging the final
 513         ICU build for various release platforms.</td>
 514       </tr>
 515
 516       <tr>
 517         <td><i>&lt;ICU&gt;</i>/source/<b>config</b>/</td>
 518
 519         <td>Contains helper makefiles for platform specific build commands. Used
 520         by 'configure'.</td>
 521       </tr>
 522
 523       <tr>
 524         <td><i>&lt;ICU&gt;</i>/source/<b>allinone</b>/</td>
 525
 526         <td>Contains top-level ICU workspace and project files, for instance to
 527         build all of ICU under one MSVC project.</td>
 528       </tr>
 529
 530       <tr>
 531         <td><i>&lt;ICU&gt;</i>/<b>include</b>/</td>
 532
 533         <td>Contains the headers needed for developing software that uses ICU on
 534         Windows.</td>
 535       </tr>
 536
 537       <tr>
 538         <td><i>&lt;ICU&gt;</i>/<b>lib</b>/</td>
 539
 540         <td>Contains the import libraries for linking ICU into your Windows
 541         application.</td>
 542       </tr>
 543
 544       <tr>
 545         <td><i>&lt;ICU&gt;</i>/<b>bin</b>/</td>
 546
 547         <td>Contains the libraries and executables for using ICU on Windows.</td>
 548       </tr>
 549     </table>
 550     <!-- end of ICU structure ==================================== -->
 551
 552     <h2><a name="HowToBuild" href="#HowToBuild" id="HowToBuild">How To Build And
 553     Install ICU</a></h2>
 554
 555     <h3><a name="RecBuild" href="#RecBuild" id=
 556     "RecBuild">Recommended Build Options</a></h3>
 557
 558     <p>Depending on the platform and the type of installation,
 559     we recommend a small number of modifications and build options.</p>
 560     <ul>
 561       <li><b>Namespace:</b> By default, unicode/uversion.h has
 562         "using namespace icu;" which defeats much of the purpose of the namespace.
 563         (This is for historical reasons: Originally, ICU4C did not use namespaces,
 564         and some compilers did not support them. The default "using" statement
 565         preserves source code compatibility.)<br />
 566         We recommend you turn this off via <code>-DU_USING_ICU_NAMESPACE=0</code>
 567         or by modifying unicode/uversion.h:
 568 <pre>Index: source/common/unicode/uversion.h
 569 ===================================================================
 570 --- source/common/unicode/uversion.h    (revision 26606)
 571 +++ source/common/unicode/uversion.h    (working copy)
 572 @@ -180,7 +180,8 @@
 573  #   define U_NAMESPACE_QUALIFIER U_ICU_NAMESPACE::
 574
 575  #   ifndef U_USING_ICU_NAMESPACE
 576 -#       define U_USING_ICU_NAMESPACE 1
 577 +        // Set to 0 to force namespace declarations in ICU usage.
 578 +#       define U_USING_ICU_NAMESPACE 0
 579  #   endif
 580  #   if U_USING_ICU_NAMESPACE
 581          U_NAMESPACE_USE
 582 </pre>
 583         ICU call sites then either qualify ICU types explicitly,
 584         for example <code>icu::UnicodeString</code>,
 585         or do <code>using icu::UnicodeString;</code> where appropriate.</li>
 586       <li><b>Hardcode the default charset to UTF-8:</b> On platforms where
 587         the default charset is always UTF-8,
 588         like MacOS X and some Linux distributions,
 589         we recommend hardcoding ICU's default charset to UTF-8.
 590         This means that some implementation code becomes simpler and faster,
 591         and statically linked ICU libraries become smaller.
 592         (See the <a href="http://icu-project.org/apiref/icu4c/utypes_8h.html#0a33e1edf3cd23d9e9c972b63c9f7943">U_CHARSET_IS_UTF8</a>
 593         API documentation for more details.)<br />
 594         You can <code>-DU_CHARSET_IS_UTF8=1</code> or
 595         modify unicode/utypes.h (in ICU 4.8 and below)
 596         or modify unicode/platform.h (in ICU 49 and higher):
 597 <pre>Index: source/common/unicode/utypes.h
 598 ===================================================================
 599 --- source/common/unicode/utypes.h      (revision 26606)
 600 +++ source/common/unicode/utypes.h      (working copy)
 601 @@ -160,7 +160,7 @@
 602   * @see UCONFIG_NO_CONVERSION
 603   */
 604  #ifndef U_CHARSET_IS_UTF8
 605 -#   define U_CHARSET_IS_UTF8 0
 606 +#   define U_CHARSET_IS_UTF8 1
 607  #endif
 608
 609  /*===========================================================================*/
 610 </pre></li>
 611       <li><b>UnicodeString constructors:</b> The UnicodeString class has
 612         several single-argument constructors that are not marked "explicit"
 613         for historical reasons.
 614         This can lead to inadvertent construction of a <code>UnicodeString</code>
 615         with a single character by using an integer,
 616         and it can lead to inadvertent dependency on the conversion framework
 617         by using a C string literal.<br />
 618         Beginning with ICU 49, you should do the following:
 619         <ul>
 620           <li>Consider marking the from-<code>UChar</code>
 621             and from-<code>UChar32</code> constructors explicit via
 622             <code>-DUNISTR_FROM_CHAR_EXPLICIT=explicit</code> or similar.</li>
 623           <li>Consider marking the from-<code>const char*</code> and
 624             from-<code>const UChar*</code> constructors explicit via
 625             <code>-DUNISTR_FROM_STRING_EXPLICIT=explicit</code> or similar.</li>
 626         </ul>
 627         Note: The ICU test suites cannot be compiled with these settings.
 628       </li>
 629       <li><b>utf.h, utf8.h, utf16.h, utf_old.h:</b>
 630         By default, utypes.h (and thus almost every public ICU header)
 631         includes all of these header files.
 632         Often, none of them are needed, or only one or two of them.
 633         All of utf_old.h is deprecated or obsolete.<br />
 634         Beginning with ICU 49,
 635         you should define <code>U_NO_DEFAULT_INCLUDE_UTF_HEADERS</code> to 1
 636         (via -D or uconfig.h, as above)
 637         and include those header files explicitly that you actually need.<br />
 638         Note: The ICU test suites cannot be compiled with this setting.</li>
 639       <li><b>.dat file:</b> By default, the ICU data is built into
 640         a shared library (DLL). This is convenient because it requires no
 641         install-time or runtime configuration,
 642         but the library is platform-specific and cannot be modified.
 643         A .dat package file makes the opposite trade-off:
 644         Platform-portable (except for endianness and charset family, which
 645         can be changed with the icupkg tool)
 646         and modifiable (also with the icupkg tool).
 647         If a path is set, then single data files (e.g., .res files)
 648         can be copied to that location to provide new locale data
 649         or conversion tables etc.<br />
 650         The only drawback with a .dat package file is that the application
 651         needs to provide ICU with the file system path to the package file
 652         (e.g., by calling <code>u_setDataDirectory()</code>)
 653         or with a pointer to the data (<code>udata_setCommonData()</code>)
 654         before other ICU API calls.
 655         This is usually easy if ICU is used from an application where
 656         <code>main()</code> takes care of such initialization.
 657         It may be hard if ICU is shipped with
 658         another shared library (such as the Xerces-C++ XML parser)
 659         which does not control <code>main()</code>.<br />
 660         See the <a href="http://userguide.icu-project.org/icudata">User Guide ICU Data</a>
 661         chapter for more details.<br />
 662         If possible, we recommend building the .dat package.
 663         Specify <code>--with-data-packaging=archive</code>
 664         on the configure command line, as in<br />
 665         <code>runConfigureICU Linux --with-data-packaging=archive</code><br />
 666         (Read the configure script's output for further instructions.
 667         On Windows, the Visual Studio build generates both the .dat package
 668         and the data DLL.)<br />
 669         Be sure to install and use the tiny stubdata library
 670         rather than the large data DLL.</li>
 671       <li><b>Static libraries:</b> It may make sense to build the ICU code
 672         into static libraries (.a) rather than shared libraries (.so/.dll).
 673         Static linking reduces the overall size of the binary by removing
 674         code that is never called.<br />
 675         Example configure command line:<br />
 676         <code>runConfigureICU Linux --enable-static --disable-shared</code></li>
 677       <li><b>Out-of-source build:</b> It is usually desirable to keep the ICU
 678         source file tree clean and have build output files written to
 679         a different location. This is called an "out-of-source build".
 680         Simply invoke the configure script from the target location:
 681 <pre>~/icu$ svn export http://source.icu-project.org/repos/icu/icu/trunk
 682 ~/icu$ mkdir trunk-dev
 683 ~/icu$ cd trunk-dev
 684 ~/icu/trunk-dev$ ../trunk/source/runConfigureICU Linux
 685 ~/icu/trunk-dev$ make check</pre></li>
 686     </ul>
 687     <h4>ICU as a System-Level Library</h4>
 688     <p>If ICU is installed as a system-level library, there are further
 689       opportunities and restrictions to consider.
 690       For details, see the <em>Using ICU as an Operating System Level Library</em>
 691       section of the <a href="http://userguide.icu-project.org/design">User Guide ICU Architectural Design</a> chapter.</p>
 692     <ul>
 693       <li><b>Data path:</b> For a system-level library, it is best to load
 694         ICU data from the .dat package file because the file system path
 695         to the .dat package file can be hardcoded. ICU will automatically set
 696         the path to the final install location using U_ICU_DATA_DEFAULT_DIR.
 697         Alternatively, you can set <code>-DICU_DATA_DIR=/path/to/icu/data</code>
 698         when building the ICU code. (Used by source/common/putil.c.)<br />
 699         Consider also setting <code>-DICU_NO_USER_DATA_OVERRIDE</code>
 700         if you do not want the "ICU_DATA" environment variable to be used.
 701         (An application can still override the data path via
 702         <code>u_setDataDirectory()</code> or
 703         <code>udata_setCommonData()</code>.</li>
 704       <li><b>Hide draft API:</b> API marked with <code>@draft</code>
 705         is new and not yet stable. Applications must not rely on unstable
 706         APIs from a system-level library.
 707         Define <code>U_HIDE_DRAFT_API</code>, <code>U_HIDE_INTERNAL_API</code>
 708         and <code>U_HIDE_SYSTEM_API</code>
 709         by modifying unicode/utypes.h before installing it.</li>
 710       <li><b>Only C APIs:</b> Applications must not rely on C++ APIs from a
 711         system-level library because binary C++ compatibility
 712         across library and compiler versions is very hard to achieve.
 713         Most ICU C++ APIs are in header files that contain a comment with
 714         <code>\brief C++ API</code>.
 715         Consider not installing these header files.</li>
 716       <li><b>Disable renaming:</b> By default, ICU library entry point names
 717         have an ICU version suffix. Turn this off for a system-level installation,
 718         to enable upgrading ICU without breaking applications. For example:<br />
 719         <code>runConfigureICU Linux --disable-renaming</code><br />
 720         The public header files from this configuration must be installed
 721         for applications to include and get the correct entry point names.</li>
 722     </ul>
 723
 724     <h3><a name="UserConfig" href="#UserConfig" id="UserConfig">User-Configurable Settings</a></h3>
 725     <p>ICU4C can be customized via a number of user-configurable settings.
 726     Many of them are controlled by preprocessor macros which are
 727     defined in the <code>source/common/unicode/uconfig.h</code> header file.
 728     Some turn off parts of ICU, for example conversion or collation,
 729     trading off a smaller library for reduced functionality.
 730     Other settings are recommended (see previous section)
 731     but their default values are set for better source code compatibility.</p>
 732
 733     <p>In order to change such user-configurable settings, you can
 734     either modify the <code>uconfig.h</code> header file by adding
 735     a specific <code>#define ...</code> for one or more of the macros
 736     before they are first tested,
 737     or set the compiler's preprocessor flags (<code>CPPFLAGS</code>) to include
 738     an equivalent <code>-D</code> macro definition.</p>
 739
 740     <h3><a name="HowToBuildWindows" href="#HowToBuildWindows" id=
 741     "HowToBuildWindows">How To Build And Install On Windows</a></h3>
 742
 743     <p>Building International Components for Unicode requires:</p>
 744
 745     <ul>
 746       <li>Microsoft Windows</li>
 747
 748       <li>Microsoft Visual C++</li>
 749
 750       <li><a href="#HowToBuildCygwin">Cygwin</a> is required when other versions
 751       of Microsoft Visual C++ and other compilers are used to build ICU.</li>
 752     </ul>
 753
 754     <p>The steps are:</p>
 755
 756     <ol>
 757       <li>Unzip the icu-XXXX.zip file into any convenient location. Using command
 758       line zip, type "unzip -a icu-XXXX.zip -d drive:\directory", or just use
 759       WinZip.</li>
 760
 761       <li>Be sure that the ICU binary directory, <i>&lt;ICU&gt;</i>\bin\, is
 762       included in the <strong>PATH</strong> environment variable. The tests will
 763       not work without the location of the ICU DLL files in the path.</li>
 764
 765       <li>Open the "<i>&lt;ICU&gt;</i>\source\allinone\allinone.sln" workspace
 766       file in Microsoft Visual Studio. (This solution includes all the
 767       International Components for Unicode libraries, necessary ICU building
 768       tools, and the test suite projects). Please see the <a href=
 769       "#HowToBuildWindowsCommandLine">command line note below</a> if you want to
 770       build from the command line instead.</li>
 771
 772       <li>Set the active platform to "Win32" or "x64" (See <a href="#HowToBuildWindowsPlatform">Windows platform note</a> below)
 773       and configuration to "Debug" or "Release" (See <a href="#HowToBuildWindowsConfig">Windows configuration note</a> below).</li>
 774
 775       <li>Choose the "Build" menu and select "Rebuild Solution". If you want to
 776       build the Debug and Release at the same time, see the <a href=
 777       "#HowToBuildWindowsBatch">batch configuration note</a> below.</li>
 778
 779
 780       <li>Run the tests. They can be run from the command line or from within Visual Studio.
 781
 782          <h4>Running the Tests from the Windows Command Line (cmd)</h4>
 783         <ul>
 784            <li>For x86 (32 bit) and Debug, use: <br />
 785
 786         <tt><i>&lt;ICU&gt;</i>\source\allinone\icucheck.bat  <i>Platform</i> <i>Configuration</i>
 787                 </tt> <br />
 788        </li>
 789         <li>So, for example:
 790                                  <br />
 791                 <tt><i>&lt;ICU&gt;</i>\source\allinone\icucheck.bat  <b>x86</b> <b>Debug</b>
 792                 </tt>
 793                                 <br/>  or <br />
 794                 <tt><i>&lt;ICU&gt;</i>\source\allinone\icucheck.bat  <b>x86</b> <b>Release</b>
 795                 </tt>
 796                                 <br/>  or <br />
 797                 <tt><i>&lt;ICU&gt;</i>\source\allinone\icucheck.bat  <b>x64</b> <b>Release</b>
 798                 </tt></li>
 799         </ul>
 800
 801          <h4>Running the Tests from within Visual Studio</h4>
 802
 803         <ol>
 804       <li>Run the C++ test suite, "intltest". To do this: set the active startup
 805       project to "intltest", and press Ctrl+F5 to run it. Make sure that it
 806       passes without any errors.</li>
 807
 808       <li>Run the C test suite, "cintltst". To do this: set the active startup
 809       project to "cintltst", and press Ctrl+F5 to run it. Make sure that it
 810       passes without any errors.</li>
 811
 812       <li>Run the I/O test suite, "iotest". To do this: set the active startup
 813       project to "iotest", and press Ctrl+F5 to run it. Make sure that it passes
 814       without any errors.</li>
 815
 816         </ol>
 817
 818         </li>
 819
 820       <li>You are now able to develop applications with ICU by using the
 821       libraries and tools in <i>&lt;ICU&gt;</i>\bin\. The headers are in
 822       <i>&lt;ICU&gt;</i>\include\ and the link libraries are in
 823       <i>&lt;ICU&gt;</i>\lib\. To install the ICU runtime on a machine, or ship
 824       it with your application, copy the needed components from
 825       <i>&lt;ICU&gt;</i>\bin\ to a location on the system PATH or to your
 826       application directory.</li>
 827     </ol>
 828
 829     <p><a name="HowToBuildWindowsCommandLine" id=
 830     "HowToBuildWindowsCommandLine"><strong>Using MSDEV At The Command Line
 831     Note:</strong></a> You can build ICU from the command line. Assuming that you
 832     have properly installed Microsoft Visual C++ to support command line
 833     execution, you can run the following command, 'devenv.com
 834     <i>&lt;ICU&gt;</i>\source\allinone\allinone.sln /build "Win32|Release"'. You can also
 835     use Cygwin with this compiler to build ICU, and you can refer to the <a href=
 836     "#HowToBuildCygwin">How To Build And Install On Windows with Cygwin</a>
 837     section for more details.</p>
 838
 839     <p><a name="HowToBuildWindowsPlatform" id=
 840     "HowToBuildWindowsPlatform"><strong>Setting Active Platform
 841     Note:</strong></a> Even though you are able to select "x64" as the active platform, if your operating system is
 842     not a 64 bit version of Windows, the build will fail. To set the active platform, two different possibilities are:</p>
 843
 844     <ul>
 845       <li>Choose "Build" menu, select "Configuration Manager...", and select
 846       "Win32" or "x64" for the Active Platform Solution.</li>
 847
 848       <li>Another way is to select the desired build configuration from "Solution
 849       Platforms" dropdown menu from the standard toolbar. It will say
 850       "Win32" or "x64" in the dropdown list.</li>
 851     </ul>
 852
 853     <p><a name="HowToBuildWindowsConfig" id=
 854     "HowToBuildWindowsConfig"><strong>Setting Active Configuration
 855     Note:</strong></a> To set the active configuration, two different
 856     possibilities are:</p>
 857
 858     <ul>
 859       <li>Choose "Build" menu, select "Configuration Manager...", and select
 860       "Release" or "Debug" for the Active Configuration Solution.</li>
 861
 862       <li>Another way is to select the desired build configuration from "Solution
 863       Configurations" dropdown menu from the standard toolbar. It will say
 864       "Release" or "Debug" in the dropdown list.</li>
 865     </ul>
 866
 867     <p><a name="HowToBuildWindowsBatch" id="HowToBuildWindowsBatch"><strong>Batch
 868     Configuration Note:</strong></a> If you want to build the Win32 and x64 platforms and
 869     Debug and Release configurations at the same time, choose "Build" menu, and select "Batch
 870     Build...". Click the "Select All" button, and then click the "Rebuild"
 871     button.</p>
 872
 873     <h3><a name="HowToBuildCygwin" href="#HowToBuildCygwin" id=
 874     "HowToBuildCygwin">How To Build And Install On Windows with Cygwin</a></h3>
 875
 876     <p>Building International Components for Unicode with this configuration
 877     requires:</p>
 878
 879     <ul>
 880       <li>Microsoft Windows</li>
 881
 882       <li>Microsoft Visual C++ (when gcc isn't used).</li>
 883
 884       <li>
 885         Cygwin with the following installed:
 886
 887         <ul>
 888           <li>bash</li>
 889
 890           <li>GNU make</li>
 891
 892           <li>ar</li>
 893
 894           <li>ranlib</li>
 895
 896           <li>man (if you plan to look at the man pages)</li>
 897         </ul>
 898       </li>
 899     </ul>
 900
 901     <p>There are two ways you can build ICU with Cygwin. You can build with gcc
 902     or Microsoft Visual C++. If you use gcc, the resulting libraries and tools
 903     will depend on the Cygwin environment. If you use Microsoft Visual C++, the
 904     resulting libraries and tools do not depend on Cygwin and can be more easily
 905     distributed to other Windows computers (the generated man pages and shell
 906     scripts still need Cygwin). To build with gcc, please follow the "<a href=
 907     "#HowToBuildUNIX">How To Build And Install On UNIX</a>" instructions, while
 908     you are inside a Cygwin bash shell. To build with Microsoft Visual C++,
 909     please use the following instructions:</p>
 910
 911     <ol>
 912       <li>Start the Windows "Command Prompt" window. This is different from the
 913       gcc build, which requires the Cygwin Bash command prompt. The Microsoft
 914       Visual C++ compiler will not work with a bash command prompt.</li>
 915
 916       <li>If the computer isn't set up to use Visual C++ from the command line,
 917       you need to run vcvars32.bat.<br />For example:<br />"<tt>C:\Program Files\Microsoft
 918       Visual Studio 8\VC\bin\vcvars32.bat</tt>" can be used for 32-bit builds
 919       <strong>or</strong> <br />"<tt>C:\Program Files (x86)\Microsoft Visual Studio
 920       8\VC\bin\amd64\vcvarsamd64.bat</tt>" can be used for 64-bit builds on
 921       Windows x64.</li>
 922
 923       <li>Unzip the icu-XXXX.zip file into any convenient location. Using command
 924       line zip, type "unzip -a icu-XXXX.zip -d drive:\directory", or just use
 925       WinZip.</li>
 926
 927       <li>Change directory to "icu/source", which is where you unzipped ICU.</li>
 928
 929       <li>Run "<tt>bash <a href="source/runConfigureICU">./runConfigureICU</a>
 930       Cygwin/MSVC</tt>" (See <a href="#HowToWindowsConfigureICU">Windows
 931       configuration note</a> and non-functional configure options below).</li>
 932
 933       <li>Type <tt>"make"</tt> to compile the libraries and all the data files.
 934       This make command should be GNU make.</li>
 935
 936       <li>Optionally, type <tt>"make check"</tt> to run the test suite, which
 937       checks for ICU's functionality integrity (See <a href=
 938       "#HowToTestWithoutGmake">testing note</a> below).</li>
 939
 940       <li>Type <tt>"make install"</tt> to install ICU. If you used the --prefix=
 941       option on configure or runConfigureICU, ICU will be installed to the
 942       directory you specified. (See <a href="#HowToInstallICU">installation
 943       note</a> below).</li>
 944     </ol>
 945
 946     <p><a name="HowToWindowsConfigureICU" id=
 947     "HowToWindowsConfigureICU"><strong>Configuring ICU on Windows
 948     NOTE:</strong></a> </p>
 949     <p>
 950     Ensure that the order of the PATH is MSVC, Cygwin, and then other PATHs. The configure
 951     script needs certain tools in Cygwin (e.g. grep).
 952     </p>
 953     <p>
 954     Also, you may need to run <tt>"dos2unix.exe"</tt> on all of the scripts (e.g. configure)
 955     in the top source directory of ICU. To avoid this issue, you can download
 956     the ICU source for Unix platforms (icu-xxx.tgz).
 957     </p>
 958     <p>In addition to the Unix <a href=
 959     "#HowToConfigureICU">configuration note</a> the following configure options
 960     currently do not work on Windows with Microsoft's compiler. Some options can
 961     work by manually editing <tt>icu/source/common/unicode/pwin32.h</tt>, but
 962     manually editing the files is not recommended.</p>
 963
 964     <ul>
 965       <li><tt>--disable-renaming</tt></li>
 966
 967       <li><tt>--enable-tracing</tt></li>
 968
 969       <li><tt>--enable-rpath</tt></li>
 970
 971       <li><tt>--enable-static</tt> (Requires that U_STATIC_IMPLEMENTATION be
 972       defined in user code that links against ICU's static libraries.)</li>
 973
 974       <li><tt>--with-data-packaging=files</tt> (The pkgdata tool currently does
 975       not work in this mode. Manual packaging is required to use this mode.)</li>
 976     </ul>
 977
 978     <h3><a name="HowToBuildUNIX" href="#HowToBuildUNIX" id="HowToBuildUNIX">How
 979     To Build And Install On UNIX</a></h3>
 980
 981     <p>Building International Components for Unicode on UNIX requires:</p>
 982
 983     <ul>
 984       <li>A C++ compiler installed on the target machine (for example: gcc, CC,
 985       xlC_r, aCC, cxx, etc...).</li>
 986
 987       <li>An ANSI C compiler installed on the target machine (for example:
 988       cc).</li>
 989
 990       <li>A recent version of GNU make (3.80+).</li>
 991
 992       <li>For a list of z/OS tools please view the <a href="#HowToBuildZOS">z/OS
 993       build section</a> of this document for further details.</li>
 994     </ul>
 995
 996     <p>Here are the steps to build ICU:</p>
 997
 998     <ol>
 999       <li>Decompress the icu-<i>X</i>.<i>Y</i>.tgz (or
1000       icu-<i>X</i>.<i>Y</i>.tar.gz) file. For example, <tt>"gunzip -d &lt;
1001       icu-<i>X</i>.<i>Y</i>.tgz | tar xvf -"</tt></li>
1002
1003       <li>Change directory to the "icu/source".</li>
1004
1005       <li>Run <span style='font-family: monospace;'>"chmod +x runConfigureICU configure install-sh"</span> because
1006       these files may have the wrong permissions.</li>
1007
1008       <li>Run the <span style='font-family: monospace;'><a href="source/runConfigureICU">runConfigureICU</a></span>
1009       script for your platform. (See <a href="#HowToConfigureICU">configuration
1010       note</a> below).</li>
1011
1012       <li>Type <span style='font-family: monospace;'>"gmake"</span> (or "make" if GNU make is the default make on
1013       your platform) to compile the libraries and all the data files. The proper
1014       name of the GNU make command is printed at the end of the configuration
1015       run, as in "You must use gmake to compile ICU".
1016       <br/>
1017       Note that the compilation command output may be simplified on your platform.  If this is the case, you will see just:
1018       <blockquote><p style='background-color: #ddd; font-family: monospace; font-size: small'>gcc ... stubdata.c</p></blockquote>
1019       rather than
1020       <blockquote><p style='background-color: #ddd; font-family: monospace; font-size: small'>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</p></blockquote>
1021       .<br/>
1022       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.
1023       </li>
1024
1025       <li>Optionally, type <span style='font-family: monospace;'>"gmake check"</span> to run the test suite, which
1026       checks for ICU's functionality integrity (See <a href=
1027       "#HowToTestWithoutGmake">testing note</a> below).</li>
1028
1029       <li>Type <span style='font-family: monospace;'>"gmake install"</span> to install ICU. If you used the --prefix=
1030       option on configure or runConfigureICU, ICU will be installed to the
1031       directory you specified. (See <a href="#HowToInstallICU">installation
1032       note</a> below).</li>
1033     </ol>
1034
1035     <p><a name="HowToConfigureICU" id="HowToConfigureICU"><strong>Configuring ICU
1036     NOTE:</strong></a> Type <tt>"./runConfigureICU --help"</tt> for help on how
1037     to run it and a list of supported platforms. You may also want to type
1038     <tt>"./configure --help"</tt> to print the available configure options that
1039     you may want to give runConfigureICU. If you are not using the
1040     runConfigureICU script, or your platform is not supported by the script, you
1041     may need to set your CC, CXX, CFLAGS and CXXFLAGS environment variables, and
1042     type <tt>"./configure"</tt>.
1043     HP-UX users, please see this <a href="#ImportantNotesHPUX">note regarding
1044     HP-UX multithreaded build issues</a> with newer compilers. Solaris users,
1045     please see this <a href="#ImportantNotesSolaris">note regarding Solaris
1046     multithreaded build issues</a>.</p>
1047
1048     <p>ICU is built with strict compiler warnings enabled by default.  If this
1049     causes excessive numbers of warnings on your platform, use the --disable-strict
1050     option to configure to reduce the warning level.</p>
1051
1052     <p><a name="HowToTestWithoutGmake" id="HowToTestWithoutGmake"><strong>Running
1053     The Tests From The Command Line NOTE:</strong></a> You may have to set
1054     certain variables if you with to run test programs individually, that is
1055     apart from "gmake check". The environment variable <strong>ICU_DATA</strong>
1056     can be set to the full pathname of the data directory to indicate where the
1057     locale data files and conversion mapping tables are when you are not using
1058     the shared library (e.g. by using the .dat archive or the individual data
1059     files). The trailing "/" is required after the directory name (e.g.
1060     "$Root/source/data/out/" will work, but the value "$Root/source/data/out" is
1061     not acceptable). You do not need to set <strong>ICU_DATA</strong> if the
1062     complete shared data library is in your library path.</p>
1063
1064     <p><a name="HowToInstallICU" id="HowToInstallICU"><strong>Installing ICU
1065     NOTE:</strong></a> Some platforms use package management tools to control the
1066     installation and uninstallation of files on the system, as well as the
1067     integrity of the system configuration. You may want to check if ICU can be
1068     packaged for your package management tools by looking into the "packaging"
1069     directory. (Please note that if you are using a snapshot of ICU from Subversion, it
1070     is probable that the packaging scripts or related files are not up to date
1071     with the contents of ICU at this time, so use them with caution).</p>
1072
1073     <h3><a name="HowToBuildZOS" href="#HowToBuildZOS" id="HowToBuildZOS">How To
1074     Build And Install On z/OS (OS/390)</a></h3>
1075
1076     <p>You can install ICU on z/OS or OS/390 (the previous name of z/OS), but IBM
1077     tests only the z/OS installation. You install ICU in a z/OS UNIX system
1078     services file system such as HFS or zFS. On this platform, it is important
1079     that you understand a few details:</p>
1080
1081     <ul>
1082       <li>The makedep and GNU make tools are required for building ICU. If it
1083       is not already installed on your system, it is available at the <a href=
1084       "http://www-03.ibm.com/servers/eserver/zseries/zos/unix/bpxa1toy.html">z/OS UNIX -
1085       Tools and Toys</a> site. The PATH environment variable should be updated to
1086       contain the location of this executable prior to build. Failure to add these
1087       tools to your PATH will cause ICU build failures or cause pkgdata to fail
1088       to run.</li>
1089
1090       <li>Since USS does not support using the mmap() function over NFS, it is
1091       recommended that you build ICU on a local filesystem. Once ICU has been
1092       built, you should not have this problem while using ICU when the data
1093       library has been built as a shared library, which is this is the default
1094       setting.</li>
1095
1096       <li>Encoding considerations: The source code assumes that it is compiled
1097       with codepage ibm-1047 (to be exact, the UNIX System Services variant of
1098       it). The pax command converts all of the source code files from ASCII to
1099       codepage ibm-1047 (USS) EBCDIC. However, some files are binary files and
1100       must not be converted, or must be converted back to their original state.
1101       You can use the <a href="as_is/os390/unpax-icu.sh">unpax-icu.sh</a> script
1102       to do this for you automatically. It will unpackage the tar file and
1103       convert all the necessary files for you automatically.</li>
1104
1105       <li>z/OS supports both native S/390 hexadecimal floating point and (with
1106       OS/390 2.6 and later) IEEE 754 binary floating point. This is a compile
1107       time option. Applications built with IEEE should use ICU DLLs that are
1108       built with IEEE (and vice versa). The environment variable IEEE390=0 will
1109       cause the z/OS version of ICU to be built without IEEE floating point
1110       support and use the native hexadecimal floating point. By default ICU is
1111       built with IEEE 754 support. Native floating point support is sufficient
1112       for codepage conversion, resource bundle and UnicodeString operations, but
1113       the Format APIs require IEEE binary floating point.</li>
1114
1115       <li>z/OS introduced the concept of Extra Performance Linkage (XPLINK) to
1116       bring performance improvement opportunities to call-intensive C and C++
1117       applications such as ICU. XPLINK is enabled on a DLL-by-DLL basis, so if
1118       you are considering using XPLINK in your application that uses ICU, you
1119       should consider building the XPLINK-enabled version of ICU. You need to
1120       set ICU's environment variable <code>OS390_XPLINK=1</code> prior to
1121       invoking the make process to produce binaries that are enabled for
1122       XPLINK. The XPLINK option, which is available for z/OS 1.2 and later,
1123       requires the PTF PQ69418 to build XPLINK enabled binaries.</li>
1124
1125       <li>ICU requires XPLINK for the icuio library. If you want to use the
1126       rest of ICU without XPLINK, then you must use the --disable-icuio
1127       configure option.</li>
1128
1129       <li>The latest versions of z/OS use <a
1130       href="http://www.ibm.com/support/docview.wss?uid=swg2120240">XPLINK
1131       version (C128) of the C++ standard library</a> by default. You may see <a
1132       href="http://www.ibm.com/support/docview.wss?uid=swg21376279">an
1133       error</a> when running with XPLINK disabled. To avoid this error,
1134       set the following environment variable or similar:
1135
1136 <pre><samp>export _CXX_PSYSIX="CEE.SCEELIB(C128N)":"CBC.SCLBSID(IOSTREAM,COMPLEX)"</samp></pre>
1137       </li>
1138
1139
1140       <li>The rest of the instructions for building and testing ICU on z/OS with
1141       UNIX System Services are the same as the <a href="#HowToBuildUNIX">How To
1142       Build And Install On UNIX</a> section.</li>
1143     </ul>
1144
1145     <h4>z/OS (Batch/PDS) support outside the UNIX system services
1146     environment</h4>
1147
1148     <p>By default, ICU builds its libraries into the UNIX file system (HFS). In
1149     addition, there is a z/OS specific environment variable (OS390BATCH) to build
1150     some libraries into the z/OS native file system. This is useful, for example,
1151     when your application is externalized via Job Control Language (JCL).</p>
1152
1153     <p>The OS390BATCH environment variable enables non-UNIX support including the
1154     batch environment. When OS390BATCH is set, the libicui18n<i>XX</i>.dll,
1155     libicuuc<i>XX</i>.dll, and libicudt<i>XX</i>e.dll binaries are built into
1156     data sets (the native file system). Turning on OS390BATCH does not turn off
1157     the normal z/OS UNIX build. This means that the z/OS UNIX (HFS) DLLs will
1158     always be created.</p>
1159
1160     <p>Two additional environment variables indicate the names of the z/OS data
1161     sets to use. The LOADMOD environment variable identifies the name of the data
1162     set that contains the dynamic link libraries (DLLs) and the LOADEXP
1163     environment variable identifies the name of the data set that contains the
1164     side decks, which are normally the files with the .x suffix in the UNIX file
1165     system.</p>
1166
1167     <p>A data set is roughly equivalent to a UNIX or Windows file. For most kinds
1168     of data sets the operating system maintains record boundaries. UNIX and
1169     Windows files are byte streams. Two kinds of data sets are PDS and PDSE. Each
1170     data set of these two types contains a directory. It is like a UNIX
1171     directory. Each "file" is called a "member". Each member name is limited to
1172     eight bytes, normally EBCDIC.</p>
1173
1174     <p>Here is an example of some environment variables that you can set prior to
1175     building ICU:</p>
1176 <pre>
1177 <samp>OS390BATCH=1
1178 LOADMOD=<i>USER</i>.ICU.LOAD
1179 LOADEXP=<i>USER</i>.ICU.EXP</samp>
1180 </pre>
1181
1182     <p>The PDS member names for the DLL file names are as follows:</p>
1183 <pre>
1184 <samp>IXMI<i>XX</i>IN --&gt; libicui18n<i>XX</i>.dll
1185 IXMI<i>XX</i>UC --&gt; libicuuc<i>XX</i>.dll
1186 IXMI<i>XX</i>DA --&gt; libicudt<i>XX</i>e.dll</samp>
1187 </pre>
1188
1189     <p>You should point the LOADMOD environment variable at a partitioned data
1190     set extended (PDSE) and point the LOADEXP environment variable at a
1191     partitioned data set (PDS). The PDSE can be allocated with the following
1192     attributes:</p>
1193 <pre>
1194 <samp>Data Set Name . . . : <i>USER</i>.ICU.LOAD
1195 Management class. . : <i>**None**</i>
1196 Storage class . . . : <i>BASE</i>
1197 Volume serial . . . : <i>TSO007</i>
1198 Device type . . . . : <i>3390</i>
1199 Data class. . . . . : <i>LOAD</i>
1200 Organization  . . . : PO
1201 Record format . . . : U
1202 Record length . . . : 0
1203 Block size  . . . . : <i>32760</i>
1204 1st extent cylinders: 1
1205 Secondary cylinders : 5
1206 Data set name type  : LIBRARY</samp>
1207 </pre>
1208
1209     <p>The PDS can be allocated with the following attributes:</p>
1210 <pre>
1211 <samp>Data Set Name . . . : <i>USER</i>.ICU.EXP
1212 Management class. . : <i>**None**</i>
1213 Storage class . . . : <i>BASE</i>
1214 Volume serial . . . : <i>TSO007</i>
1215 Device type . . . . : <i>3390</i>
1216 Data class. . . . . : <i>**None**</i>
1217 Organization  . . . : PO
1218 Record format . . . : FB
1219 Record length . . . : 80
1220 Block size  . . . . : <i>3200</i>
1221 1st extent cylinders: 3
1222 Secondary cylinders : 3
1223 Data set name type  : PDS</samp>
1224 </pre>
1225
1226     <h3><a name="HowToBuildOS400" href="#HowToBuildOS400" id=
1227     "HowToBuildOS400">How To Build And Install On The IBM i Family (IBM i, i5/OS OS/400)</a></h3>
1228
1229     <p>Before you start building ICU, ICU requires the following:</p>
1230
1231     <ul>
1232       <li>QSHELL interpreter installed (install base option 30, operating system)
1233       <!--li>QShell Utilities, PRPQ 5799-XEH (not required for V4R5)</li--></li>
1234
1235       <li>ILE C/C++ Compiler installed on the system</li>
1236
1237       <li>The latest IBM tools for Developers for IBM i &mdash;
1238         <a href='http://www.ibm.com/servers/enable/site/porting/tools/'>http://www.ibm.com/servers/enable/site/porting/tools/</a>
1239         <!-- formerly: http://www.ibm.com/servers/enable/site/porting/iseries/overview/gnu_utilities.html -->
1240       </li>
1241     </ul>
1242
1243     <p>The following describes how to setup and build ICU. For background
1244     information, you should look at the <a href="#HowToBuildUNIX">UNIX build
1245     instructions</a>.</p>
1246
1247     <ol>
1248       <li>
1249         Create target library. This library will be the target for the
1250         resulting modules, programs and service programs. You will specify this
1251         library on the OUTPUTDIR environment variable.
1252 <pre>
1253 <samp>CRTLIB LIB(<i>libraryname</i>)
1254 ADDENVVAR ENVVAR(OUTPUTDIR) VALUE('<i>libraryname</i>') REPLACE(*YES)   </samp>
1255 </pre>
1256       </li>
1257
1258       <li>
1259       Set up the following environment variables and job characteristics in your build process
1260 <pre>
1261 <samp>ADDENVVAR ENVVAR(MAKE) VALUE('gmake') REPLACE(*YES)
1262 CHGJOB CCSID(37)</samp>
1263 </pre></li>
1264
1265       <li>Run <tt>'QSH'</tt></li>
1266
1267       <li>Run: <br /><tt>export PATH=/QIBM/ProdData/DeveloperTools/qsh/bin:$PATH:/QOpenSys/usr/bin</tt>
1268       </li>
1269
1270       <li>Run <b><tt>gzip -d</tt></b> on the ICU source code compressed tar archive
1271       (icu-<i>X</i>.<i>Y</i>.tgz).</li>
1272
1273       <li>Run <a href='as_is/os400/unpax-icu.sh'>unpax-icu.sh</a> on the tar file generated from the previous step.</li>
1274
1275       <li>Change your current directory to icu/as_is/os400.</li>
1276       <li>Run <tt>qsh bldiculd.sh</tt> to build the program ICULD which ICU will use for linkage.</li>
1277
1278       <li>Change your current directory to icu/source.</li>
1279
1280       <li>Run <tt>'./runConfigureICU IBMi'</tt>  (See <a href="#HowToConfigureICU">configuration
1281       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.</li>
1282
1283       <li>Run <tt>'gmake'</tt> to build ICU. (Do not use the -j option)</li>
1284
1285       <li>Run <tt>'gmake check QIBM_MULTI_THREADED=Y'</tt> to build and run the tests.
1286       You can look at the <a href=
1287       "http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/apis/concept4.htm">
1288       iSeries Information Center</a> for more details regarding the running of multiple threads
1289       on IBM i.</li>
1290     </ol>
1291
1292       <!-- cross -->
1293     <h3><a name="HowToCrossCompileICU" href="#HowToCrossCompileICU" id="HowToCrossCompileICU">How To Cross Compile ICU</a></h3>
1294                 <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>
1295                 <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>
1296                 <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>
1297                 <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>
1298                 <p>Three initially-empty directories will be used in this example:</p>
1299                 <table summary="Three directories used in this example" class="docTable">
1300                         <tr>
1301                                 <th align="left">/icu</th><td>a copy of the ICU source</td>
1302                         </tr>
1303                         <tr>
1304                                 <th align="left">/buildA</th><td>an empty directory, it will contain ICU built for A<br />(MacOSX in this case)</td>
1305                         </tr>
1306                         <tr>
1307                                 <th align="left">/buildB</th><td>an empty directory, it will contain ICU built for B<br />(HaikuOS in this case)</td>
1308                         </tr>
1309                 </table>
1310
1311                 <ol>
1312                 <li>Check out or unpack the ICU source code into the /icu directory.You will have the directories /icu/source, etc.</li>
1313                 <li>Build ICU in /buildA normally (using runConfigureICU or configure):
1314 <pre class="samp">cd /buildA
1315 sh /icu/source/runConfigureICU <strong>MacOSX</strong>
1316 gnumake
1317 </pre>
1318                 </li>
1319                 <li>Set PATH or other variables as needed, such as CPPFLAGS.</li>
1320                 <li>Build ICU in /buildB<br />
1321                         <div class="note"><b>Note:</b> "<code>--with-cross-build</code>" takes an absolute path.</div>
1322 <pre class="samp">cd /buildB
1323 sh /icu/source/configure --host=<strong>i586-pc-haiku</strong> --with-cross-build=<strong>/buildA</strong>
1324 gnumake</pre>
1325                 </li>
1326                 <li>Tests and testdata can be built with "gnumake tests".</li>
1327         </ol>
1328       <!-- end cross -->
1329
1330     <!-- end build environment -->
1331
1332     <h2><a name="HowToPackage" href="#HowToPackage" id="HowToPackage">How To
1333     Package ICU</a></h2>
1334
1335     <p>There are many ways that a person can package ICU with their software
1336     products. Usually only the libraries need to be considered for packaging.</p>
1337
1338     <p>On UNIX, you should use "<tt>gmake install</tt>" to make it easier to
1339     develop and package ICU. The bin, lib and include directories are needed to
1340     develop applications that use ICU. These directories will be created relative
1341     to the "<tt>--prefix=</tt><i>dir</i>" configure option (See the <a href=
1342     "#HowToBuildUNIX">UNIX build instructions</a>). When ICU is built on Windows,
1343     a similar directory structure is built.</p>
1344
1345     <p>When changes have been made to the standard ICU distribution, it is
1346     recommended that at least one of the following guidelines be followed for
1347     special packaging.</p>
1348
1349     <ol>
1350       <li>Add a suffix name to the library names. This can be done with the
1351       --with-library-suffix configure option.</li>
1352
1353       <li>The installation script should install the ICU libraries into the
1354       application's directory.</li>
1355     </ol>
1356
1357     <p>Following these guidelines prevents other applications that use a standard
1358     ICU distribution from conflicting with any libraries that you need. On
1359     operating systems that do not have a standard C++ ABI (name mangling) for
1360     compilers, it is recommended to do this special packaging anyway. More
1361     details on customizing ICU are available in the <a href=
1362     "http://userguide.icu-project.org/">User's Guide</a>. The <a href=
1363     "#SourceCode">ICU Source Code Organization</a> section of this readme.html
1364     gives a more complete description of the libraries.</p>
1365
1366     <table class="docTable" summary=
1367     "ICU has several libraries for you to use.">
1368       <caption>
1369         Here is an example of libraries that are frequently packaged.
1370       </caption>
1371
1372       <tr>
1373         <th scope="col">Library Name</th>
1374
1375         <th scope="col">Windows Filename</th>
1376
1377         <th scope="col">Linux Filename</th>
1378
1379         <th scope="col">Comment</th>
1380       </tr>
1381
1382       <tr>
1383         <td>Data Library</td>
1384
1385         <td>icudt<i>XY</i>l.dll</td>
1386
1387         <td>libicudata.so.<i>XY</i>.<i>Z</i></td>
1388
1389         <td>Data required by the Common and I18n libraries. There are many ways
1390         to package and <a href=
1391         "http://userguide.icu-project.org/icudata">customize this
1392         data</a>, but by default this is all you need.</td>
1393       </tr>
1394
1395       <tr>
1396         <td>Common Library</td>
1397
1398         <td>icuuc<i>XY</i>.dll</td>
1399
1400         <td>libicuuc.so.<i>XY</i>.<i>Z</i></td>
1401
1402         <td>Base library required by all other ICU libraries.</td>
1403       </tr>
1404
1405       <tr>
1406         <td>Internationalization (i18n) Library</td>
1407
1408         <td>icuin<i>XY</i>.dll</td>
1409
1410         <td>libicui18n.so.<i>XY</i>.<i>Z</i></td>
1411
1412         <td>A library that contains many locale based internationalization (i18n)
1413         functions.</td>
1414       </tr>
1415
1416       <tr>
1417         <td>Layout Engine</td>
1418
1419         <td>icule<i>XY</i>.dll</td>
1420
1421         <td>libicule.so.<i>XY</i>.<i>Z</i></td>
1422
1423         <td>An optional engine for doing font layout.</td>
1424       </tr>
1425
1426       <tr>
1427         <td>Layout Extensions Engine</td>
1428
1429         <td>iculx<i>XY</i>.dll</td>
1430
1431         <td>libiculx.so.<i>XY</i>.<i>Z</i></td>
1432
1433         <td>An optional engine for doing font layout that uses parts of ICU.</td>
1434       </tr>
1435
1436       <tr>
1437         <td>ICU I/O (Unicode stdio) Library</td>
1438
1439         <td>icuio<i>XY</i>.dll</td>
1440
1441         <td>libicuio.so.<i>XY</i>.<i>Z</i></td>
1442
1443         <td>An optional library that provides a stdio like API with Unicode
1444         support.</td>
1445       </tr>
1446
1447       <tr>
1448         <td>Tool Utility Library</td>
1449
1450         <td>icutu<i>XY</i>.dll</td>
1451
1452         <td>libicutu.so.<i>XY</i>.<i>Z</i></td>
1453
1454         <td>An internal library that contains internal APIs that are only used by
1455         ICU's tools. If you do not use ICU's tools, you do not need this
1456         library.</td>
1457       </tr>
1458     </table>
1459
1460     <p>Normally only the above ICU libraries need to be considered for packaging.
1461     The versionless symbolic links to these libraries are only needed for easier
1462     development. The <i>X</i>, <i>Y</i> and <i>Z</i> parts of the name are the
1463     version numbers of ICU. For example, ICU 2.0.2 would have the name
1464     libicuuc.so.20.2 for the common library. The exact format of the library
1465     names can vary between platforms due to how each platform can handles library
1466     versioning.</p>
1467
1468     <h2><a name="ImportantNotes" href="#ImportantNotes" id=
1469     "ImportantNotes">Important Notes About Using ICU</a></h2>
1470
1471     <h3><a name="ImportantNotesMultithreaded" href="#ImportantNotesMultithreaded"
1472     id="ImportantNotesMultithreaded">Using ICU in a Multithreaded
1473     Environment</a></h3>
1474
1475     <p>Some versions of ICU require calling the <code>u_init()</code> function
1476     from <code>uclean.h</code> to ensure that ICU is initialized properly. In
1477     those ICU versions, <code>u_init()</code> must be called before ICU is used
1478     from multiple threads. There is no harm in calling <code>u_init()</code> in a
1479     single-threaded application, on a single-CPU machine, or in other cases where
1480     <code>u_init()</code> is not required.</p>
1481
1482     <p>In addition to ensuring thread safety, <code>u_init()</code> also attempts
1483     to load at least one ICU data file. Assuming that all data files are packaged
1484     together (or are in the same folder in files mode), a failure code from
1485     <code>u_init()</code> usually means that the data cannot be found. In this
1486     case, the data may not be installed properly, or the application may have
1487     failed to call <code>udata_setCommonData()</code> or
1488     <code>u_setDataDirectory()</code> which specify to ICU where it can find its
1489     data.</p>
1490
1491     <p>Since <code>u_init()</code> will load only one or two data files, it
1492     cannot guarantee that all of the data that an application needs is available.
1493     It cannot check for all data files because the set of files is customizable,
1494     and some ICU services work without loading any data at all. An application
1495     should always check for error codes when opening ICU service objects (using
1496     <code>ucnv_open()</code>, <code>ucol_open()</code>, C++ constructors,
1497     etc.).</p>
1498
1499     <h4>ICU 3.4 and later</h4>
1500
1501     <p>ICU 3.4 self-initializes properly for multi-threaded use. It achieves this
1502     without performance penalty by hardcoding the core Unicode properties data,
1503     at the cost of some flexibility. (For details see Jitterbug 4497.)</p>
1504
1505     <p><code>u_init()</code> can be used to check for data loading. It tries to
1506     load the converter alias table (<code>cnvalias.icu</code>).</p>
1507
1508     <h4>ICU 2.6..3.2</h4>
1509
1510     <p>These ICU versions require a call to <code>u_init()</code> before
1511     multi-threaded use. The services that are directly affected are those that
1512     don't have a service object and need to be fast: normalization and character
1513     properties.</p>
1514
1515     <p><code>u_init()</code> loads and initializes the data files for
1516     normalization and character properties (<code>unorm.icu</code> and
1517     <code>uprops.icu</code>) and can therefore also be used to check for data
1518     loading.</p>
1519
1520     <h4>ICU 2.4 and earlier</h4>
1521
1522     <p>ICU 2.4 and earlier versions were not prepared for multithreaded use on
1523     multi-CPU platforms where the CPUs implement weak memory coherency. These
1524     CPUs include: Power4, Power5, Alpha, Itanium. <code>u_init()</code> was not
1525     defined yet.</p>
1526
1527     <h4><a name="ImportantNotesHPUX" href="#ImportantNotesHPUX" id=
1528     "ImportantNotesHPUX">Using ICU in a Multithreaded Environment on
1529     HP-UX</a></h4>
1530
1531     <p>When ICU is built with aCC on HP-UX, the <a
1532     href="http://h21007.www2.hp.com/portal/site/dspp/menuitem.863c3e4cbcdc3f3515b49c108973a801?ciid=eb08b3f1eee02110b3f1eee02110275d6e10RCRD">-AA</a>
1533     compiler flag is used. It is required in order to use the latest
1534     &lt;iostream&gt; API in a thread safe manner. This compiler flag affects the
1535     version of the C++ library being used. Your applications will also need to
1536     be compiled with -AA in order to use ICU.</p>
1537
1538     <h4><a name="ImportantNotesSolaris" href="#ImportantNotesSolaris" id=
1539     "ImportantNotesSolaris">Using ICU in a Multithreaded Environment on
1540     Solaris</a></h4>
1541
1542     <h5>Linking on Solaris</h5>
1543
1544     <p>In order to avoid synchronization and threading issues, developers are
1545     <strong>suggested</strong> to strictly follow the compiling and linking
1546     guidelines for multithreaded applications, specified in the following
1547     document from Sun Microsystems. Most notably, pay strict attention to the
1548     following statements from Sun:</p>
1549
1550     <blockquote>
1551       <p>To use libthread, specify -lthread before -lc on the ld command line, or
1552       last on the cc command line.</p>
1553
1554       <p>To use libpthread, specify -lpthread before -lc on the ld command line,
1555       or last on the cc command line.</p>
1556     </blockquote>
1557
1558     <p>Failure to do this may cause spurious lock conflicts, recursive mutex
1559     failure, and deadlock.</p>
1560
1561     <p>Source: "<i>Solaris Multithreaded Programming Guide, Compiling and
1562     Debugging</i>", Sun Microsystems, Inc., Apr 2004<br />
1563      <a href=
1564     "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>
1565
1566     <h3><a name="ImportantNotesWindows" href="#ImportantNotesWindows" id=
1567     "ImportantNotesWindows">Windows Platform</a></h3>
1568
1569     <p>If you are building on the Win32 platform, it is important that you
1570     understand a few of the following build details.</p>
1571
1572     <h4>DLL directories and the PATH setting</h4>
1573
1574     <p>As delivered, the International Components for Unicode build as several
1575     DLLs, which are placed in the "<i>&lt;ICU&gt;</i>\bin" directory. You must
1576     add this directory to the PATH environment variable in your system, or any
1577     executables you build will not be able to access International Components for
1578     Unicode libraries. Alternatively, you can copy the DLL files into a directory
1579     already in your PATH, but we do not recommend this. You can wind up with
1580     multiple copies of the DLL and wind up using the wrong one.</p>
1581
1582     <h4><a name="ImportantNotesWindowsPath" id=
1583     "ImportantNotesWindowsPath">Changing your PATH</a></h4>
1584
1585     <p><strong>Windows 2000/XP</strong>: Use the System Icon in the Control
1586     Panel. Pick the "Advanced" tab. Select the "Environment Variables..."
1587     button. Select the variable PATH in the lower box, and select the lower
1588     "Edit..." button. In the "Variable Value" box, append the string
1589     ";<i>&lt;ICU&gt;</i>\bin" to the end of the path string. If there is
1590     nothing there, just type in "<i>&lt;ICU&gt;</i>\bin". Click the Set button,
1591     then the OK button.</p>
1592
1593     <p>Note: When packaging a Windows application for distribution and
1594     installation on user systems, copies of the ICU DLLs should be included with
1595     the application, and installed for exclusive use by the application. This is
1596     the only way to insure that your application is running with the same version
1597     of ICU, built with exactly the same options, that you developed and tested
1598     with. Refer to Microsoft's guidelines on the usage of DLLs, or search for the
1599     phrase "DLL hell" on <a href=
1600     "http://msdn.microsoft.com/">msdn.microsoft.com</a>.</p>
1601
1602     <h3><a name="ImportantNotesUNIX" href="#ImportantNotesUNIX" id=
1603     "ImportantNotesUNIX">UNIX Type Platform</a></h3>
1604
1605     <p>If you are building on a UNIX platform, and if you are installing ICU in a
1606     non-standard location, you may need to add the location of your ICU libraries
1607     to your <strong>LD_LIBRARY_PATH</strong> or <strong>LIBPATH</strong>
1608     environment variable (or the equivalent runtime library path environment
1609     variable for your system). The ICU libraries may not link or load properly
1610     without doing this.</p>
1611
1612     <p>Note that if you do not want to have to set this variable, you may instead
1613     use the --enable-rpath option at configuration time. This option will
1614     instruct the linker to always look for the libraries where they are
1615     installed. You will need to use the appropriate linker options when linking
1616     your own applications and libraries against ICU, too. Please refer to your
1617     system's linker manual for information about runtime paths. The use of rpath
1618     also means that when building a new version of ICU you should not have an
1619     older version installed in the same place as the new version's installation
1620     directory, as the older libraries will used during the build, instead of the
1621     new ones, likely leading to an incorrectly build ICU. This is the proper
1622     behavior of rpath.</p>
1623
1624     <h2><a name="PlatformDependencies" href="#PlatformDependencies" id=
1625     "PlatformDependencies">Platform Dependencies</a></h2>
1626
1627     <h3><a name="PlatformDependenciesNew" href="#PlatformDependenciesNew" id=
1628     "PlatformDependenciesNew">Porting To A New Platform</a></h3>
1629
1630     <p>If you are using ICU's Makefiles to build ICU on a new platform, there are
1631     a few places where you will need to add or modify some files. If you need
1632     more help, you can always ask the <a href=
1633     "http://site.icu-project.org/contacts">icu-support mailing list</a>. Once
1634     you have finished porting ICU to a new platform, it is recommended that you
1635     contribute your changes back to ICU via the icu-support mailing list. This
1636     will make it easier for everyone to benefit from your work.</p>
1637
1638     <h4>Data For a New Platform</h4>
1639
1640     <p>For some people, it may not be necessary for completely build ICU. Most of
1641     the makefiles and build targets are for tools that are used for building
1642     ICU's data, and an application's data (when an application uses ICU resource
1643     bundles for its data).</p>
1644
1645     <p>Data files can be built on a different platform when both platforms share
1646     the same endianness and the same charset family. This assertion does not
1647     include platform dependent DLLs/shared/static libraries. For details see the
1648     User Guide <a href="http://userguide.icu-project.org/icudata">ICU
1649     Data</a> chapter.</p>
1650
1651     <p>ICU 3.6 removes the requirement that ICU be completely built in the native
1652     operating environment. It adds the icupkg tool which can be run on any
1653     platform to turn binary ICU data files from any one of the three formats into
1654     any one of the other data formats. This allows a application to use ICU data
1655     built anywhere to be used for any other target platform.</p>
1656
1657     <p><strong>WARNING!</strong> Building ICU without running the tests is not
1658     recommended. The tests verify that ICU is safe to use. It is recommended that
1659     you try to completely port and test ICU before using the libraries for your
1660     own application.</p>
1661
1662     <h4>Adapting Makefiles For a New Platform</h4>
1663
1664     <p>Try to follow the build steps from the <a href="#HowToBuildUNIX">UNIX</a>
1665     build instructions. If the configure script fails, then you will need to
1666     modify some files. Here are the usual steps for porting to a new
1667     platform:<br />
1668     </p>
1669
1670     <ol>
1671       <li>Create an mh file in icu/source/config/. You can use mh-linux or a
1672       similar mh file as your base configuration.</li>
1673
1674       <li>Modify icu/source/aclocal.m4 to recognize your platform's mh file.</li>
1675
1676       <li>Modify icu/source/configure.in to properly set your <b>platform</b> C
1677       Macro define.</li>
1678
1679       <li>Run <a href="http://www.gnu.org/software/autoconf/">autoconf</a> in
1680       icu/source/ without any options. The autoconf tool is standard on most
1681       Linux systems.</li>
1682
1683       <li>If you have any optimization options that you want to normally use, you
1684       can modify icu/source/runConfigureICU to specify those options for your
1685       platform.</li>
1686
1687       <li>Build and test ICU on your platform. It is very important that you run
1688       the tests. If you don't run the tests, there is no guarentee that you have
1689       properly ported ICU.</li>
1690     </ol>
1691
1692     <h3><a name="PlatformDependenciesImpl" href="#PlatformDependenciesImpl" id=
1693     "PlatformDependenciesImpl">Platform Dependent Implementations</a></h3>
1694
1695     <p>The platform dependencies have been mostly isolated into the following
1696     files in the common library. This information can be useful if you are
1697     porting ICU to a new platform.</p>
1698
1699     <ul>
1700       <li>
1701         <strong>unicode/platform.h.in</strong> (autoconf'ed platforms)<br />
1702          <strong>unicode/p<i>XXXX</i>.h</strong> (others: pwin32.h, ppalmos.h,
1703         ..): Platform-dependent typedefs and defines:<br />
1704         <br />
1705
1706
1707         <ul>
1708           <li>Generic types like UBool, int8_t, int16_t, int32_t, int64_t,
1709           uint64_t etc.</li>
1710
1711           <li>U_EXPORT and U_IMPORT for specifying dynamic library import and
1712           export</li>
1713
1714           <li>String handling support for the char16_t and wchar_t types.</li>
1715         </ul>
1716         <br />
1717       </li>
1718
1719       <li>
1720         <strong>unicode/putil.h, putil.c</strong>: platform-dependent
1721         implementations of various functions that are platform dependent:<br />
1722         <br />
1723
1724
1725         <ul>
1726           <li>uprv_isNaN, uprv_isInfinite, uprv_getNaN and uprv_getInfinity for
1727           handling special floating point values.</li>
1728
1729           <li>uprv_tzset, uprv_timezone, uprv_tzname and time for getting
1730           platform specific time and time zone information.</li>
1731
1732           <li>u_getDataDirectory for getting the default data directory.</li>
1733
1734           <li>uprv_getDefaultLocaleID for getting the default locale
1735           setting.</li>
1736
1737           <li>uprv_getDefaultCodepage for getting the default codepage
1738           encoding.</li>
1739         </ul>
1740         <br />
1741       </li>
1742
1743       <li>
1744         <strong>umutex.h, umutex.c</strong>: Code for doing synchronization in
1745         multithreaded applications. If you wish to use International Components
1746         for Unicode in a multithreaded application, you must provide a
1747         synchronization primitive that the classes can use to protect their
1748         global data against simultaneous modifications. We already supply working
1749         implementations for many platforms that ICU builds on.<br />
1750         <br />
1751       </li>
1752
1753       <li><strong>umapfile.h, umapfile.c</strong>: functions for mapping or
1754       otherwise reading or loading files into memory. All access by ICU to data
1755       from files makes use of these functions.<br />
1756       <br />
1757       </li>
1758
1759       <li>Using platform specific #ifdef macros are highly discouraged outside of
1760       the scope of these files. When the source code gets updated in the future,
1761       these #ifdef's can cause testing problems for your platform.</li>
1762     </ul>
1763     <hr />
1764
1765     <p>Copyright &copy; 1997-2012 International Business Machines Corporation and
1766     others. All Rights Reserved.<br />
1767      IBM Globalization Center of Competency - San Jos&eacute;<br />
1768      4400 North First Street<br />
1769      San Jos&eacute;, CA 95134<br />
1770      USA</p>
1771   </body>
1772 </html>
1773