reactos/lib/3rdparty/icu4ros/icu/readme.html

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