Home | History | Annotate | only in /external/icu4c
Up to higher level directory
NameDateSize
aclocal.m413-Nov-201218.2K
allinone/13-Nov-2012
Android.mk13-Nov-2012781
APIChangeReport.html13-Nov-2012134.3K
CleanSpec.mk13-Nov-20123.1K
common/13-Nov-2012
config/13-Nov-2012
config.guess13-Nov-201243.9K
config.log13-Nov-201230.7K
config.status13-Nov-201234.7K
config.sub13-Nov-201232.6K
configure13-Nov-2012258.3K
configure.in13-Nov-201240.9K
configure.in.orig13-Nov-201240.5K
configure.mk13-Nov-2012670
configure.orig13-Nov-2012257K
data/13-Nov-2012
Doxyfile.in13-Nov-20129.7K
extra/13-Nov-2012
i18n/13-Nov-2012
icu4c.css13-Nov-20126.5K
icudefs.mk.in13-Nov-20129.4K
install-sh13-Nov-20125.5K
io/13-Nov-2012
layout/13-Nov-2012
layoutex/13-Nov-2012
license.html13-Nov-20121.9K
Makefile.in13-Nov-201212.2K
Makefile.org13-Nov-20126.7K
mkinstalldirs13-Nov-2012935
NOTICE13-Nov-20125.4K
readme.html13-Nov-201273.1K
runConfigureICU13-Nov-201210.8K
samples/13-Nov-2012
stubdata/13-Nov-2012
test/13-Nov-2012
tools/13-Nov-2012
unicode-license.txt13-Nov-20122.9K

readme.html

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