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
1304LOADMOD=<i>USER</i>.ICU.LOAD
1305LOADEXP=<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
1311IXMI<i>XX</i>UC --> libicuuc<i>XX</i>.dll
1312IXMI<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
1321Management class. . : <i>**None**</i>
1322Storage class . . . : <i>BASE</i>
1323Volume serial . . . : <i>TSO007</i>
1324Device type . . . . : <i>3390</i>
1325Data class. . . . . : <i>LOAD</i>
1326Organization . . . : PO
1327Record format . . . : U
1328Record length . . . : 0
1329Block size . . . . : <i>32760</i>
13301st extent cylinders: 1
1331Secondary cylinders : 5
1332Data 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
1338Management class. . : <i>**None**</i>
1339Storage class . . . : <i>BASE</i>
1340Volume serial . . . : <i>TSO007</i>
1341Device type . . . . : <i>3390</i>
1342Data class. . . . . : <i>**None**</i>
1343Organization . . . : PO
1344Record format . . . : FB
1345Record length . . . : 80
1346Block size . . . . : <i>3200</i>
13471st extent cylinders: 3
1348Secondary cylinders : 3
1349Data 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>)
1381ADDENVVAR 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)
1389CHGJOB 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
1436sh /icu/source/runConfigureICU <strong>MacOSX</strong>
1437gnumake
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
1444sh /icu/source/configure --host=<strong>i586-pc-haiku</strong> --with-cross-build=<strong>/buildA</strong>
1445gnumake</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