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