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