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