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