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