| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| |
| <html lang="en-US"> |
| <head> |
| <meta name="generator" content="HTML Tidy, see www.w3.org"> |
| <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> |
| <meta name="COPYRIGHT" content= |
| "Copyright (c) IBM Corporation and others. All Rights Reserved."> |
| <meta name="KEYWORDS" content= |
| "ICU; International Components for Unicode; what's new; readme; read me; introduction; downloads; downloading; building; installation;"> |
| <meta name="DESCRIPTION" content= |
| "The introduction to the International Components for Unicode with instructions on building, installation, usage and other information about ICU."> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| |
| <title>ReadMe for ICU</title> |
| <style type="text/css"> |
| h1 {border-width: 2px; border-style: solid; text-align: center; width: 100%; font-size: 200%; font-weight: bold} |
| h2 {margin-top: 3em; text-decoration: underline; page-break-before: always} |
| h2.TOC {page-break-before: auto} |
| h3 {margin-top: 2em; text-decoration: underline} |
| h4 {text-decoration: underline} |
| h5 {text-decoration: underline} |
| caption {font-weight: bold; text-align: left} |
| div.indent {margin-left: 2em} |
| ul.TOC {list-style-type: none} |
| samp {margin-left: 1em; border-style: groove; padding: 1em; display: block; background-color: #EEEEEE} |
| </style> |
| </head> |
| |
| <body> |
| <h1>International Components for Unicode<br> |
| <abbr title="International Components for Unicode">ICU</abbr> 2.4 |
| ReadMe</h1> |
| |
| <p>Version: 2002-Dec-20<br> |
| Copyright © 1997-2002 International Business Machines Corporation and |
| others. All Rights Reserved.</p> |
| <!-- Remember that there is a copyright at the end too --> |
| <hr> |
| |
| <h2 class="TOC">Table of Contents</h2> |
| |
| <ul class="TOC"> |
| <li><a href="#Introduction">Introduction</a></li> |
| |
| <li><a href="#GettingStarted">Getting Started</a></li> |
| |
| <li><a href="#News">What Is New In This release?</a></li> |
| |
| <li><a href="#Download">How To Download the Source Code</a></li> |
| |
| <li><a href="#SourceCode">ICU Source Code Organization</a></li> |
| |
| <li> |
| <a href="#HowToBuild">How To Build And Install ICU</a> |
| |
| <ul class="TOC"> |
| <li><a href="#HowToBuildSupported">Supported Platforms</a></li> |
| |
| <li><a href="#HowToBuildWindows">Windows</a></li> |
| |
| <li><a href="#HowToBuildWindowsXP64">Windows XP on IA64</a></li> |
| |
| <li><a href="#HowToBuildUnix">Unix</a></li> |
| |
| <li><a href="#HowToBuildZOS">z/OS (os/390)</a></li> |
| |
| <li><a href="#HowToBuildOS400">OS/400 (iSeries)</a></li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#ImportantNotes">Important Notes About Using ICU</a> |
| |
| <ul class="TOC"> |
| <li><a href="#ImportantNotesCPlusPlus">Using ICU in a Multithreaded |
| Environment</a></li> |
| |
| <li><a href="#MakeICUSmaller">How to Make ICU Smaller</a></li> |
| |
| <li><a href="#ImportantNotesBinaryCompat">Binary |
| Compatibility</a></li> |
| |
| <li><a href="#ImportantNotesWindows">Windows Platform</a></li> |
| |
| <li><a href="#ImportantNotesUnix">Unix Type Platforms</a></li> |
| |
| <li><a href="#ImportantNotesDefaultCP">Using the Default |
| Codepage</a></li> |
| </ul> |
| </li> |
| |
| <li><a href="#PlatformDependencies">Platform Dependencies</a></li> |
| </ul> |
| <hr> |
| |
| <h2><a name="Introduction" href="#Introduction">Introduction</a></h2> |
| |
| <p>Today's software market is a global one in which it is desirable to |
| develop and maintain one application (single source/single binary) that |
| supports a wide variety of languages. The International Components for |
| Unicode (ICU) libraries provide robust and full-featured Unicode services |
| on a wide variety of platforms to help this design goal. The ICU libraries |
| provide support for:</p> |
| |
| <ul> |
| <li>The latest version of the Unicode standard</li> |
| |
| <li>Character set conversions with support for over 200 codepages</li> |
| |
| <li>Locale data for more than 230 locales</li> |
| |
| <li>Language sensitive text collation (sorting) and searching based on |
| the Unicode Collation Algorithm (=ISO 14651)</li> |
| |
| <li>Regular expression matching and Unicode sets</li> |
| |
| <li>Transformations for normalization, upper/lowercase, script |
| transliterations (50+ pairs)</li> |
| |
| <li>Resource bundles for storing and accessing localized information</li> |
| |
| <li>Date/Number/Message formatting and parsing of culture specific |
| input/output formats</li> |
| |
| <li>Calendar specific date and time manipulation</li> |
| |
| <li>Complex text layout for Arabic, Hebrew, Indic and Thai</li> |
| |
| <li>Text boundary analysis for finding characters, word and sentence |
| boundaries</li> |
| </ul> |
| |
| <p>ICU has a sister project <a href= |
| "http://oss.software.ibm.com/icu4j/">ICU4J</a> that extends the |
| internationalization capabilities of Java to a level similar to ICU. The |
| ICU C/C++ project is also called ICU4C when a distinction is necessary.</p> |
| |
| <h2><a name="GettingStarted" href="#GettingStarted">Getting |
| started</a></h2> |
| |
| <p>This document describes how to build and install ICU on your machine. |
| For other information about ICU please see the following table of |
| links.<br> |
| The ICU homepage also links to related information about writing |
| internationalized software.</p> |
| |
| <table border="1" cellpadding="3" width="100%" summary=""> |
| <caption> |
| Here are some useful links regarding ICU and internationalization in |
| general. |
| </caption> |
| |
| <tr> |
| <td>ICU Homepage</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/">http://oss.software.ibm.com/icu/</a></td> |
| </tr> |
| |
| <tr> |
| <td>ICU4J Homepage</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu4j/">http://oss.software.ibm.com/icu4j/</a></td> |
| </tr> |
| |
| <tr> |
| <td>FAQ - Frequently Asked Questions about ICU</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/userguide/icufaq.html">http://oss.software.ibm.com/icu/userguide/icufaq.html</a></td> |
| </tr> |
| |
| <tr> |
| <td>ICU User's Guide</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/userguide/">http://oss.software.ibm.com/icu/userguide/</a></td> |
| </tr> |
| |
| <tr> |
| <td>Download ICU Releases</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/download/">http://oss.software.ibm.com/icu/download/</a></td> |
| </tr> |
| |
| <tr> |
| <td>API Documentation Online</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/apiref/">http://oss.software.ibm.com/icu/apiref/</a></td> |
| </tr> |
| |
| <tr> |
| <td>Online ICU Demos</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/demo/">http://oss.software.ibm.com/icu/demo/</a></td> |
| </tr> |
| |
| <tr> |
| <td>Contacts and Bug Reports/Feature Requests</td> |
| |
| <td><a href= |
| "http://oss.software.ibm.com/icu/archives/">http://oss.software.ibm.com/icu/archives/</a></td> |
| </tr> |
| </table> |
| |
| <p><strong>Important:</strong> Please make sure you understand the <a href= |
| "license.html">Copyright and License Information</a>.</p> |
| |
| <h2><a name="News" href="#News">What is new in this release?</a></h2> |
| |
| <p>The following list concentrates on <em>changes that affect existing |
| applications migrating from previous ICU releases</em>. For more news about |
| this release, see the <a href= |
| "http://oss.software.ibm.com/icu/download/2.4/">ICU 2.4 download |
| page</a>.</p> |
| |
| <h3>UnicodeString assignments</h3> |
| |
| <p>ICU 2.4 changes the behavior of the <code>UnicodeString</code> |
| assignment operator and copy constructor for where the source string is a |
| readonly alias. For such strings, the copy used to also be a readonly alias |
| to the same buffer, but that was seen as too dangerous (see <a href= |
| "http://www.jtcsv.com/cgibin/icu-bugs?findid=2296">Jitterbug 2296</a>). The |
| new <code>fastCopyFrom()</code> member function provides the old assignment |
| behavior. It can be used explicitly when it is known to be safe to maintain |
| readonly aliases instead of cloning the buffer. For more information about |
| string aliasing and other <code>UnicodeString</code> storage models see the |
| <a href="http://oss.software.ibm.com/icu/userguide/strings.html">User Guide |
| Strings chapter</a>.</p> |
| |
| <h3>Unicode-handling macros (utf*.h)</h3> |
| |
| <p>The macros in <code>source/common/unicode/utf*.h</code> have been |
| revamped, improved, simplified, and renamed. The old macros continue to be |
| available. They are in <code>utf_old.h</code>, together with an explanation |
| of the change. <code>utf.h</code>, <code>utf8.h</code> and |
| <code>utf16.h</code> contain the new macros instead. The new macros are |
| intended to be more consistent, more useful, and less confusing. Some |
| macros were simply renamed for consistency with a new naming scheme.</p> |
| |
| <p>A related change is that <code>UChar32</code> is not a |
| platform-dependent type any more, but is now always defined to be the same |
| as <code>int32_t</code>. This allows for consistent, more portable code and |
| C++ function overloading as well as negative values as sentinels on all |
| platforms. See the definition in <code>utf.h</code>.</p> |
| |
| <h3>ICU code library size</h3> |
| |
| <p>ICU code libraries can be made smaller by removing functionality. See <a |
| href="#MakeICUSmaller">How to Make ICU Smaller</a>.</p> |
| |
| <h3>Support for Unicode 3.2</h3> |
| |
| <p>Unicode properties and algorithms have been upgraded to <a href= |
| "http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode_3_2_0"> |
| Unicode 3.2</a>, which includes the addition of more than 1000 new encoded |
| characters. The UCA (<a href="http://www.unicode.org/reports/tr10/">Unicode |
| Collation Algorithm</a>) table is updated to the current version 3.1.1, |
| with Unicode 3.2-based canonical closure. All Unicode properties (except |
| for those in Unihan.txt) are now <a href= |
| "http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/ucd_icu.html"> |
| available via direct APIs, and most via UnicodeSet</a>.</p> |
| |
| <h3>Additional and modified converters</h3> |
| |
| <p>New converter implementations are added for:</p> |
| |
| <ul> |
| <li>UTF-16 and UTF-32 (detect/emit BOM according to IANA |
| registration)<br> |
| These and related names used to be aliases for UTF16_PlatformEndian and |
| UTF32_PlatformEndian but are now separate, IANA-registration-compliant |
| converters that detect and emit the respective Byte Order Mark. The |
| "platform endian" converters (without automatic BOM handling) are now |
| only available via their specific names.</li> |
| |
| <li><a href="http://www.unicode.org/reports/tr26/">CESU-8</a> (while the |
| <a href="http://www.unicode.org/reports/tr28/#3_1_conformance">UTF-8 code |
| is tightened according to Unicode 3.2</a>)</li> |
| |
| <li><a href= |
| "http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/conversion/bocu1/bocu1.html"> |
| BOCU-1</a> (MIME-compatible compression of Unicode text that preserves |
| binary order)</li> |
| </ul> |
| |
| <h3>Flexible data loading</h3> |
| |
| <p>ICU 2.2 has an extended search path functionality, more flexible data |
| override capabilities, and removes lesser-known heuristics for determining |
| the data path.</p> |
| |
| <ul> |
| <li>Performance: ICU will only load data from packages, not from single |
| files, when the search path is empty. This eliminates all file system |
| accesses after the packages (ICU data + application data) are loaded.<br> |
| If this is important, then an application should set the search path to |
| the empty path during initialization.</li> |
| |
| <li>Customizability: If the search path is not empty, then ICU searches |
| for single files before looking in packages, allowing to override/update |
| packaged data.</li> |
| |
| <li>User data: The new function ucnv_openPackage allows an application to |
| load an ICU character mapping table from its own data. This enables |
| applications to support more codepages than the ICU installation that it |
| uses.</li> |
| |
| <li>Separation between ICU data and user data: Single data files must now |
| always have a package name as prefix, which results in different file |
| names between ICU and all application packages even for the same locale |
| IDs etc.</li> |
| |
| <li>Multi-path: The search path can now contain multiple folders and can |
| list packages directly instead of just a single folder.</li> |
| |
| <li>Predictability: The search path can be set via the ICU_DATA |
| environment variable or via the u_setDataDirectory() function.<br> |
| ICU does not perform any other heuristics any more.</li> |
| </ul> |
| |
| <p><strong>Note:</strong> while some of the old binary data may be still |
| readable by ICU 2.2 (resource bundles, for example), they need to be |
| repackaged in order to be used.</p> |
| |
| <ul> |
| <li>If you have individual binary files, you have to rename them so that |
| you prepend a <code>'packagename_'</code>. Then use |
| <code>packagename</code> for opening.</li> |
| |
| <li>If you have a memory-mapped package file, you will need to unpack it |
| (use decmn tool), rename individual files as above (prepending the |
| package name), and repack the files.</li> |
| |
| <li>If you have a shared library file, you'll need to somehow get |
| individual files and repackage them.</li> |
| </ul> |
| |
| <h3>Customizable memory management</h3> |
| |
| <p>ICU 2.2 libraries do not use the global operators new and delete. |
| Instead, all C++ classes are derived from a common base class UObject which |
| implements new and delete operators for all of ICU's C++ classes. Users can |
| customize the ICU memory allocation by changing the functions in |
| source/common/cmemory.c that are used for non-class types and in UObject's |
| new and delete operators.</p> |
| |
| <p>This also means that ICU libraries may safely use a different heap than |
| the application because all memory is consistently allocated and released |
| from within the libraries. On Windows it is now possible to link the |
| application with, for example, the static C runtime library even though ICU |
| libraries use the DLL-based runtime.</p> |
| |
| <h3>Experimental locales moved to new repository</h3> |
| |
| <p>Experimental locales are ones for which we have incomplete data. Data |
| for such locales used to be included in the default ICU download, but have |
| been moved to a new <a href= |
| "http://oss.software.ibm.com/cvs/icu/locale/icu/experimental/">locale data |
| repository</a>, stored as another <a href= |
| "http://oss.software.ibm.com/icu/develop/cvs.html">ICU CVS module</a>. This |
| data can be added back into a customized ICU build, see the <a href= |
| "http://oss.software.ibm.com/icu/userguide/icudata.html">User Guide Data |
| chapter</a>. It can also still be viewed with the <a href= |
| "http://oss.software.ibm.com/icu/demo/">LocaleExplorer demo</a>.</p> |
| <hr> |
| |
| <h2><a name="Download" href="#Download">How To Download the Source |
| Code</a></h2> |
| |
| <p>There are two ways to download ICU releases:</p> |
| |
| <ul> |
| <li><strong>Official Release Snapshot:</strong><br> |
| If you want to use ICU (as opposed to developing it), you should |
| download an official packaged version of the ICU source code. These |
| versions are tested more thoroughly than day-to-day development builds of |
| the system, and they are packaged in zip and tar files for convenient |
| download. These packaged files can be found at <a href= |
| "http://oss.software.ibm.com/icu/download/">http://oss.software.ibm.com/icu/download/</a>.<br> |
| |
| The packaged snapshots are named <strong>icu-nnnn.zip</strong> or |
| <strong>icu-nnnn.tgz</strong>, where nnnn is the version number. The .zip |
| file is used for Windows platforms, while the .tgz file is preferred on |
| most other platforms.<br> |
| Please unzip this file. It will reconstruct the source directory, which |
| includes anonymous CVS control directories (see below).</li> |
| |
| <li><strong>CVS Source Repository:</strong><br> |
| If you are interested in developing features, patches, or bug fixes for |
| ICU, you should probably be working with the latest version of the ICU |
| source code. You will need to check the code out of our CVS repository to |
| ensure that you have the most recent version of all of the files. See our |
| <a href="http://oss.software.ibm.com/icu/develop/cvs.html">CVS page</a> |
| for details.</li> |
| </ul> |
| |
| <h2><a name="SourceCode" href="#SourceCode">ICU Source Code |
| Organization</a></h2> |
| |
| <p>In the descriptions below, <strong><i><ICU></i></strong> is the |
| full path name of the icu directory (the top level directory from the |
| distribution archives) in your file system. You can also view the <a href= |
| "http://oss.software.ibm.com/icu/userguide/design.html">User's Guide</a> to |
| see which libraries you need for your software product. You need at least |
| the data (<code>[lib]icudt</code>) and the common (<code>[lib]icuuc</code>) |
| libraries in order to use ICU.</p> |
| |
| <table border="1" cellpadding="0" width="100%" summary=""> |
| <caption> |
| The following files describe the code drop. |
| </caption> |
| |
| <tr> |
| <th scope="col">File</th> |
| |
| <th scope="col">Description</th> |
| </tr> |
| |
| <tr> |
| <td>readme.html</td> |
| |
| <td>Describes the International Components for Unicode (this file)</td> |
| </tr> |
| |
| <tr> |
| <td>license.html</td> |
| |
| <td>Contains the text of the ICU license</td> |
| </tr> |
| </table> |
| |
| <p><br> |
| </p> |
| |
| <table border="1" cellpadding="0" width="100%" summary=""> |
| <caption> |
| The following directories contain source code and data files. |
| </caption> |
| |
| <tr> |
| <th scope="col">Directory</th> |
| |
| <th scope="col">Description</th> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>common</b>/</td> |
| |
| <td>The core Unicode and support functionality, such as resource |
| bundles, character properties, locales, codepage conversion, |
| normalization, Unicode properties, Locale, and UnicodeString.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>i18n</b>/</td> |
| |
| <td>Modules in i18n are generally the more data-driven, that is to say |
| resource bundle driven, components. These deal with higher-level |
| internationalization issues such as formatting, collation, text break |
| analysis, and transliteration.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>data</b>/</td> |
| |
| <td> |
| This directory contains the source data in text format, which is |
| compiled into binary form during the ICU build process. It contains |
| several subdirectories, in which the data files are grouped by |
| function. Note that the build process must be run again after any |
| changes are made to this directory. |
| |
| <ul> |
| <li><b>brkitr/</b> Data files for character, word, sentence, title |
| casing and line boundary analysis.</li> |
| |
| <li><b>locales/</b> These .txt files contain ICU language and |
| culture-specific localization data. Two special bundles are |
| <b>root</b>, which is the fallback data and parent of other |
| bundles, and <b>index</b>, which contains a list of installed |
| bundles. The makefile <b>resfiles.mk</b> contains the list of |
| resource bundle files.</li> |
| |
| <li><b>mappings/</b> Here are the code page converter tables. These |
| .ucm files contain mappings to and from Unicode. These are compiled |
| into .cnv files. <b>convrtrs.txt</b> is the alias mapping table |
| from various converter name formats to ICU internal format and vice |
| versa. It produces cnvalias.icu. The makefiles <b>ucmfiles.mk, |
| ucmcore.mk,</b> and <b>ucmebcdic.mk</b> contain the list of |
| converters to be built.</li> |
| |
| <li><b>translit/</b> This directory contains transliterator rules |
| as resource bundles, a makefile <b>trnsfiles.mk</b> containing the |
| list of installed system translitaration files, and as well the |
| special bundle <b>translit_index</b> which lists the system |
| transliterator aliases.</li> |
| |
| <li><b>unidata/</b> This directory contains the Unicode data files. |
| Please see <a href= |
| "http://www.unicode.org/">http://www.unicode.org/</a> for more |
| information.</li> |
| |
| <li><b>misc/</b> The misc directory contains other data files which |
| did not fit into the above categories. Currently it only contains |
| <b>timezone.txt,</b> a generated file, which is compiled into |
| tz.dat. The <b>tz.dat</b> file contains time zone information.</li> |
| |
| <li><b>out/</b> This directory contains the assembled memory mapped |
| files.</li> |
| |
| <li><b>out/build/</b> This directory contains intermediate |
| (compiled) files, such as .cnv, .res, etc.</li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/test/<b>intltest</b>/</td> |
| |
| <td>A test suite including all C++ APIs. For information about running |
| the test suite, see the users' guide.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/test/<b>cintltst</b>/</td> |
| |
| <td>A test suite written in C, including all C APIs. For information |
| about running the test suite, see the users' guide.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/test/<b>testdata</b>/</td> |
| |
| <td>Source text files for data, which are read by the tests. It |
| contains the subdirectories <b>out/build/</b> which is used for |
| intermediate files, and <b>out/</b> which contains the files |
| <b>test1.cnv</b> through <b>test4.cnv,</b> and <b>testdata.dat.</b> |
| Note that the tests call |
| u_setDataDirectory("<ICU>/source/test/testdata/lib"), so that ICU |
| will load these files as if they were part of the ICU data package, for |
| testing purposes. This was formerly accomplished by setting the |
| ICU_DATA environment variable to point at these files. ICU_DATA should |
| not be set under normal circumstances.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>tools</b>/</td> |
| |
| <td>Tools for generating the data files. Data files are generated by |
| invoking <i><ICU></i>/source/data/build/makedata.bat on Win32 or |
| <i><ICU></i>/source/make on Unix.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>samples</b>/</td> |
| |
| <td>Various sample programs that use ICU</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>extra</b>/</td> |
| |
| <td>Non-supported API additions. Currently, it contains the 'ustdio' |
| file i/o library</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>layout</b>/</td> |
| |
| <td>Contains the ICU layout engine (not a rasterizer).</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/<b>packaging</b>/<br> |
| <i><ICU></i>/<b>debian</b>/</td> |
| |
| <td>These directories contain scripts and tools for packaging the final |
| ICU build for various release platforms.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>config</b>/</td> |
| |
| <td>Contains helper makefiles for platform specific build commands. |
| Used by 'configure'.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>allinone</b>/</td> |
| |
| <td>Contains top-level ICU workspace and project files, for instance to |
| build all of ICU under one MSVC project.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/<b>bin</b>/</td> |
| |
| <td>Contains the libraries and executables for using ICU on |
| Windows.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/<b>include</b>/</td> |
| |
| <td>Contains the headers needed for developing software that uses ICU |
| on Windows.</td> |
| </tr> |
| </table> |
| <!-- end of ICU structure ==================================== --> |
| |
| <h2><a name="HowToBuild" href="#HowToBuild">How To Build And Install |
| ICU</a></h2> |
| |
| <h3><a name="HowToBuildSupported" href="#HowToBuildSupported">Supported |
| Platforms</a></h3> |
| |
| <table border="1" cellpadding="3" summary=""> |
| <caption> |
| Here is a status of functionality of ICU on several different |
| platforms. |
| </caption> |
| |
| <tr> |
| <th scope="col">Operating system</th> |
| |
| <th scope="col">Compiler</th> |
| |
| <th scope="col">Testing frequency</th> |
| </tr> |
| |
| <tr> |
| <td>Windows NT/2000/XP</td> |
| |
| <td>Microsoft Visual C++ 6.0</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>Red Hat Linux 7.2</td> |
| |
| <td>gcc 2.96</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>AIX 5.1.0 L</td> |
| |
| <td>Visual Age C++ 5.0</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>Solaris 7 (SunOS 5.7)</td> |
| |
| <td>Workshop Pro CC 6.0</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>HP/UX 11.01</td> |
| |
| <td>aCC A.12.10</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>Windows 98</td> |
| |
| <td>Microsoft Visual C++ 6.0</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>AIX 4.3.3</td> |
| |
| <td>xlC_r 3.6.6</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Solaris 8 (SunOS 5.8)</td> |
| |
| <td>Workshop Pro CC 4.2<br> |
| (use 'runConfigureICU SOLARISCC/W4.2')</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Solaris 2.6 (SunOS 5.6)</td> |
| |
| <td>gcc 2.95.2</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>FreeBSD 4.4</td> |
| |
| <td>gcc 2.95.3</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Mac OS X (10.1)</td> |
| |
| <td>gcc-932.1, based on gcc version 2.95.2<br> |
| (Developer Tools December 2001)</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>z/OS 1.2</td> |
| |
| <td>cxx 1.2</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>HP/UX 11.01</td> |
| |
| <td>CC A.03.10</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>AS/400 (iSeries) V5R1</td> |
| |
| <td>iCC</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>NetBSD, OpenBSD</td> |
| |
| <td> </td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>SGI/IRIX</td> |
| |
| <td> </td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>Tru64 (OSF)</td> |
| |
| <td>Compaq's cxx compiler</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| </table> |
| |
| <p><br> |
| </p> |
| |
| <p><strong>Key to testing frequency</strong></p> |
| |
| <dl> |
| <dt><i>Reference platform</i></dt> |
| |
| <dd>ICU will work on these platforms with these compilers</dd> |
| |
| <dt><i>Regularly tested</i></dt> |
| |
| <dd>ICU should work on these platforms with these compilers</dd> |
| |
| <dt><i>Rarely tested</i></dt> |
| |
| <dd>ICU has been ported to these platforms but may not have been tested |
| there recently</dd> |
| </dl> |
| |
| <h3><a name="HowToBuildWindows" href="#HowToBuildWindows">How To Build And |
| Install On Windows</a></h3> |
| |
| <p>Building International Components for Unicode requires:</p> |
| |
| <ul> |
| <li>Microsoft NT 4.0 and above, or Windows 98 and above</li> |
| |
| <li>Microsoft Visual C++ 6.0 (Service Pack 2 is required to work with the |
| release build of max speed optimization).</li> |
| </ul> |
| |
| <p>(If you want to build with Microsoft Visual C++ .NET, please refer to |
| the <a href="#HowToBuildWindowsDotNet">note about building with Visual |
| Studio .NET</a> below.)</p> |
| |
| <p>The steps are:</p> |
| |
| <ol> |
| <li>Unzip the icu-XXXX.zip file into any convenient location. Using |
| command line zip, type "unzip -a icu-XXXX.zip -d drive:\directory", or |
| just use WinZip.</li> |
| |
| <li>Be sure that the ICU binary directory, <i><ICU></i>\bin\, is |
| included in the <strong>PATH</strong> environment variable. The tests |
| will not work without the location of the ICU dll files in the path.</li> |
| |
| <li>Set the <strong>TZ</strong> environment variable to |
| <strong>PST8PDT</strong>. The tests will not work in any other time |
| zone.</li> |
| |
| <li>Open the "<i><ICU></i>\source\allinone\allinone.dsw" workspace |
| file in Microsoft Visual C++ 6.0. (This workspace includes all the |
| International Components for Unicode libraries, necessary ICU building |
| tools, and the intltest and cintltest test suite projects). Please see |
| the note below if you want to build from the command line instead.</li> |
| |
| <li>Set the active Project to the "all" project. To do this: Choose |
| "Project" menu, and select "Set active project". In the submenu, select |
| the "all" workspace.</li> |
| |
| <li>Set the active configuration to "Win32 Debug" or "Win32 Release" (See |
| <a href="#HowToBuildWindowsConfig">note</a> below).</li> |
| |
| <li>Choose the "Build" menu and select "Rebuild All". If you want to |
| build the Debug and Release at the same time, see the <a href= |
| "#HowToBuildWindowsBatch">note</a> below.</li> |
| |
| <li>Run the C++ test suite, "intltest". To do this: set the active |
| project to "intltest", and press F5 to run it.</li> |
| |
| <li>Run the C test suite, "cintltst". To do this: set the active project |
| to "cintltst", and press F5 to run it.</li> |
| |
| <li>Make sure that both "cintltst" and "intltest" passed without any |
| errors. The return codes are non-zero when they do not pass. Visual C++ |
| will display the return codes in the debug tag of the output window. When |
| "intltest" and "cintltest" return 0, it means that everything is |
| installed correctly. You can press Ctrl+F5 on the test project to run the |
| test and see what error messages were displayed (if any tests |
| failed).</li> |
| |
| <li>Reset the <strong>TZ</strong> environment variable to its original |
| value, unless you plan on testing ICU any further.</li> |
| |
| <li>You are now able to develop applications with ICU by using the |
| libraries and tools in <i><ICU></i>\bin\. The headers are in |
| <i><ICU></i>\include\ and the link libraries are in |
| <i><ICU></i>\lib\. To install the ICU runtime on a machine, or ship |
| it with your application, copy the needed components from |
| <i><ICU></i>\bin\ to a location on the system PATH or to your |
| application directory.</li> |
| </ol> |
| |
| <p><a name="HowToBuildWindowsCommandLine"><strong>Using MSDEV At The |
| Command Line Note:</strong></a> You can build ICU from the command line. |
| Assuming that you have properly installed Microsoft Visual C++ to support |
| command line execution, you can run the following command, 'msdev |
| <i><ICU></i>\source\allinone\allinone.dsw /MAKE "ALL"'.</p> |
| |
| <p><a name="HowToBuildWindowsConfig"><strong>Setting Active Configuration |
| Note:</strong></a> To set the active configuration, two different |
| possibilities are:</p> |
| |
| <ul> |
| <li>Choose "Build" menu, select "Set Active Configuration", and select |
| "Win32 Release" or "Win32 Debug".</li> |
| |
| <li>Another way is to select "Customize" in the "Tools" menu, select the |
| "Toolbars" tab, enable "Build" instead of "Build Minibar", and click on |
| "Close". This will bring up a toolbar which you can move aside the other |
| permanent toolbars at the top of the MSVC window. The advantage is that |
| you now have an easy-to-reach pop-up menu that will always show the |
| currently selected active configuration. Or, you can drag the project and |
| configuration selections and drop them on the menu bar for later |
| selection.</li> |
| </ul> |
| |
| <p><a name="HowToBuildWindowsBatch"><strong>Batch Configuration |
| Note:</strong></a> If you want to build the Debug and Release |
| configurations at the same time, choose "Build" menu and select "Batch |
| Build..." instead (and mark all configurations as checked), then click the |
| button named "Rebuild All". The "all" workspace will build all the |
| libraries, test programs and various ICU tools (e.g. genrb for generating |
| binary locale data files).</p> |
| |
| <p><a name="HowToBuildWindowsDotNet"><strong>Microsoft Visual Studio .NET |
| Note:</strong></a> ICU will build with Microsoft Visual Studio .NET, though |
| this is not a supported platform at the time of this writing. Visual Studio |
| .NET will offer to convert the project files when you open the existing |
| workspace file. Choose "Yes to All" in the dialog asking whether to convert |
| the files or not (this creates new files) and then follow the rest of the |
| build instructions.</p> |
| |
| <h3><a name="HowToBuildWindowsXP64" href="#HowToBuildWindowsXP64">How To |
| Build And Install On Windows XP on IA64</a></h3> |
| |
| <p>Building International Components for Unicode requires:</p> |
| |
| <ul> |
| <li>Microsoft XP on an IA64 (Itanium®) machine</li> |
| |
| <li>Microsoft Visual C++ 6.0 (Service Pack 2 is required to work with the |
| release build of max speed optimization).</li> |
| |
| <li>Microsoft Platform SDK.</li> |
| </ul> |
| |
| <p>The steps are:</p> |
| |
| <ol> |
| <li>Follow steps 1-3 in the <a href="#HowToBuildWindows">in the previous |
| section</a>.</li> |
| |
| <li>Open the "Set Windows XP 64-bit Build Environment (Retail)" command |
| window from the Microsoft Platform SDK.</li> |
| |
| <li>Use cd to get into the <i><ICU></i> directory.</li> |
| |
| <li>Run this command: 'msdev /USEENV |
| <i><ICU></i>\source\allinone\allinone.dsw /MAKE "all - Win64 |
| Release"'</li> |
| |
| <li>Run "cd source\test\intltest\Release"</li> |
| |
| <li>Run the C++ test suite, "intltest". There should be no errors.</li> |
| |
| <li>Run "cd ..\..\cintltst\Release"</li> |
| |
| <li>Run the C test suite, "cintltst". There should be no errors.</li> |
| |
| <li>Follow the last two steps in the <a href="#HowToBuildWindows">in the |
| previous section</a>.</li> |
| </ol> |
| |
| <h3><a name="HowToBuildUnix" href="#HowToBuildUnix">How To Build And |
| Install On Unix</a></h3> |
| |
| <p>Building International Components for Unicode on Unix requires:</p> |
| |
| <ul> |
| <li>A C++ compiler installed on the target machine (for example: gcc, CC, |
| xlC_r, aCC, cxx, etc...).</li> |
| |
| <li>An ANSI C compiler installed on the target machine (for example: |
| cc).</li> |
| |
| <li>A recent version of GNU make (3.77+).</li> |
| |
| <li>For a list of z/OS tools please view the <a href= |
| "#HowToBuildZOS">z/OS build section</a> of this document for further |
| details.</li> |
| </ul> |
| |
| <p>Here are the steps to build ICU:</p> |
| |
| <ol> |
| <li>Decompress the icu-<i>X</i>.<i>Y</i>.tgz (or |
| icu-<i>X</i>.<i>Y</i>.tar.gz) file. For example, <tt>"gunzip -d < |
| icu-<i>X</i>.<i>Y</i>.tgz | tar xvf -"</tt></li> |
| |
| <li>Change directory to the "icu/source".</li> |
| |
| <li>Run <tt>"chmod +x runConfigureICU configure install-sh"</tt> because |
| these files may have the wrong permissions.</li> |
| |
| <li>Run the <tt><a href="source/runConfigureICU">runConfigureICU</a></tt> |
| script for your platform. (See <a href="#HowToConfigureICU">note</a> |
| below).</li> |
| |
| <li>Type <tt>"gmake"</tt> (or "make" if GNU make is the default make on |
| your platform) to compile the libraries and all the data files. The |
| proper name of the GNU make command is printed at the end of the |
| configuration run, as in "You must use gmake to compile ICU".</li> |
| |
| <li>Optionally, type <tt>"gmake check"</tt> to run the test suite, which |
| checks for ICU's functionality integrity (See <a href= |
| "#HowToTestWithoutGmake">note</a> below).</li> |
| |
| <li>Type <tt>"gmake install"</tt> to install ICU. If you used the |
| --prefix= option on configure or runConfigureICU, ICU will be installed |
| to the directory you specified. (See <a href="#HowToInstallICU">note</a> |
| below).</li> |
| </ol> |
| |
| <p><a name="HowToConfigureICU"><strong>Configuring ICU NOTE:</strong></a> |
| Type <tt>"./runConfigureICU --help"</tt> for help on how to run it and a |
| list of supported platforms. You may also want to type <tt>"./configure |
| --help"</tt> to print the available configure options that you may want to |
| give runConfigureICU. If you are not using the runConfigureICU script, or |
| your platform is not supported by the script, you may need to set your |
| CC,CXX, CFLAGS and CXXFLAGS environment variables, and type |
| <tt>"./configure"</tt>. Some of the more frequently used options to |
| configure are --disable-64bit-libs to create 32-bit libraries, and --srcdir |
| to do out of source builds (build the libraries in the current |
| location).</p> |
| |
| <p><a name="HowToTestWithoutGmake"><strong>Running The Tests From The |
| Command Line NOTE:</strong></a> You may have to set certain variables if |
| you with to run test programs individually, that is apart from "gmake |
| check". The <strong>TZ</strong> environment variable needs to be set to |
| <strong>PST8PDT</strong>. Also, the environment variable |
| <strong>ICU_DATA</strong> can be set to the full pathname of the data |
| directory to indicate where the locale data files and conversion mapping |
| tables are when you are not using the shared library (e.g. by using the |
| .dat archive or the individual data files). The trailing "/" is required |
| after the directory name (e.g. "$Root/source/data/out/" will work, but the |
| value "$Root/source/data/out" is not acceptable). You do not need to set |
| <strong>ICU_DATA</strong> if the complete shared data library is in your |
| library path.</p> |
| |
| <p><a name="HowToInstallICU"><strong>Installing ICU NOTE:</strong></a> Some |
| platforms use package management tools to control the installation and |
| uninstallation of files on the system, as well as the integrity of the |
| system configuration. You may want to check if ICU can be packaged for your |
| package management tools by looking into the "packaging" directory. (Please |
| note that if you are using a snapshot of ICU from CVS, it is probable that |
| the packaging scripts or related files are not up to date with the contents |
| of ICU at this time, so use them with caution).</p> |
| |
| <h3><a name="HowToBuildZOS" href="#HowToBuildZOS">How To Build And Install |
| On z/OS (OS/390)</a></h3> |
| |
| <p>You can install ICU on z/OS or OS/390 (the previous name of z/OS), but |
| IBM tests only the z/OS installation. These platforms commonly are called |
| "MVS". You install ICU in a z/OS UNIX system services file system such as |
| HFS or zFS. On this platform, it is important that you understand a few |
| details:</p> |
| |
| <ul> |
| <li>APAR PQ58392 may be needed by z/OS 1.2 or 1.3 in order to get some |
| ICU number formatting functions to work properly. The APAR affects C and |
| C++ code.</li> |
| |
| <li>The gnu utilities gmake and gzip/gunzip are needed and can be |
| obtained for z/OS from <a href= |
| "http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc"> |
| z/OS Unix - Tools and Toys</a>. Documentation on these tools can be found |
| at the <a href= |
| "http://publib-b.boulder.ibm.com/Redbooks.nsf/RedbookAbstracts/sg245944.html"> |
| Open Source Software for z/OS UNIX</a> Red Book.</li> |
| |
| <li>Encoding considerations: The source code assumes that it is compiled |
| with codepage ibm-1047 (to be exact, the UNIX System Services variant of |
| it). The pax command converts all of the source code files from ASCII to |
| codepage ibm-1047 (USS) EBCDIC. However, some files are binary files and |
| must not be converted, or must be converted back to their original state. |
| You can use the <a href="as_is/os390/unpax-icu.sh">unpax-icu.sh</a> |
| script to do this for you automatically. It will unpackage the tar file |
| and convert all the necessary files for you automatically.</li> |
| |
| <li> |
| <p>z/OS supports both native S/390 hexadecimal floating point and, |
| (with OS/390 2.6 and later) IEEE binary floating point. This is a |
| compile time option. Applications built with IEEE should use ICU dlls |
| that are built with IEEE (and vice versa). The environment variable |
| IEEE390=1 will cause the z/OS version of ICU to be built with IEEE |
| floating point. The default is native hexadecimal floating point.<br> |
| <em>Important:</em> Currently (ICU 1.4.2), native floating point |
| support is sufficient for codepage conversion, resource bundle and |
| UnicodeString operations, but the Format APIs, especially ChoiceFormat, |
| require IEEE binary floating point.</p> |
| |
| <p>Examples for configuring ICU:<br> |
| Debug build: <code>IEEE390=1 ./runConfigureICU --enable-debug |
| zOS/cxx</code><br> |
| Release build: <code>IEEE390=1 ./runConfigureICU zOS/cxx</code></p> |
| </li> |
| |
| <li>Since the default make on z/OS is not gmake, the pkgdata tool |
| requires that the "make" command is aliased to your installed version of |
| gmake. You may also need to set $MAKE equal to the fully-qualified path |
| of GNU make. GNU make is available with the "z/OS Unix - Tools and Toys" |
| that was mentioned above. The required version is the same Unix build |
| instructions.</li> |
| |
| <li>The makedep executable that is used with the z/OS ICU build process |
| is not shipped with ICU. It is available at the <a href= |
| "http://www.ibm.com/servers/eserver/zseries/zos/unix/bpxa1ty1.html#opensrc"> |
| z/OS Unix - Tools and Toys</a> site. The PATH environment variable should |
| be updated to contain the location of this executable prior to build. |
| Alternatively, makedep may be moved into an existing PATH directory.</li> |
| |
| <li>The rest of the instructions for building and testing ICU on z/OS |
| with Unix System Services are the same as the <a href= |
| "#HowToBuildUnix">How To Build And Install On Unix</a> section.</li> |
| </ul> |
| |
| <h4>z/OS (Batch/PDS) support outside the UNIX system services |
| environment</h4> |
| |
| <p>By default, ICU builds its libraries into the UNIX file system (HFS). In |
| addition, there is a z/OS specific environment variable (OS390BATCH) to |
| build some libraries into the z/OS native file system. This is useful, for |
| example, when your application is externalized via Job Control Language |
| (JCL).</p> |
| |
| <p>The OS390BATCH environment variable enables non-UNIX support including |
| the batch environment. When OS390BATCH is set, the libicuuc<i>XX</i>.dll, |
| libicudt<i>XX</i>e.dll, and libicudt<i>XX</i>e_stub.dll binaries are built |
| into data sets (the native file system). Turning on OS390BATCH does not |
| turn off the normal z/OS UNIX build. This means that the The z/OS UNIX |
| (HFS) dlls will always be created.</p> |
| |
| <p>Two additional environment variables indicate the names of the z/OS data |
| sets to use. The LOADMOD environment variable identifies the name of the |
| data set that contains the dynamic link libraries (DLLs) and the LOADEXP |
| environment variable identifies the name of the data set that contains the |
| side decks, which are normally the files with the .x suffix in the UNIX |
| file system.</p> |
| |
| <p>A data set is roughly equivalent to a UNIX or Windows file. For most |
| kinds of data sets the operating system maintains record boundaries. UNIX |
| and Windows files are byte streams. Two kinds of data sets are PDS and |
| PDSE. Each data set of these two types contains a directory. It is like a |
| UNIX directory. Each "file" is called a "member". Each member name is |
| limited to eight bytes, normally EBCDIC.</p> |
| |
| <p>Here is an example of some environment variables that you can set prior |
| to building ICU:</p> |
| <pre> |
| <samp>OS390BATCH=1 |
| LOADMOD=<i>USER</i>.ICU.LOAD |
| LOADEXP=<i>USER</i>.ICU.EXP</samp> |
| </pre> |
| |
| <p>The PDS member names for the DLL file names are as follows:</p> |
| <pre> |
| <samp>IXMI<i>XX</i>UC --> libicuuc<i>XX</i>.dll |
| IXMI<i>XX</i>DA --> libicudt<i>XX</i>e.dll |
| IXMI<i>XX</i>D1 --> libicudt<i>XX</i>e_stub.dll <i>(Only when OS390_STUBDATA=1)</i></samp> |
| </pre> |
| |
| <p>You should point the LOADMOD environment variable at a partitioned data |
| set extended (PDSE) and point the LOADEXP environment variable at a |
| partitioned data set (PDS). The PDSE can be allocated with the following |
| attributes:</p> |
| <pre> |
| <samp>Data Set Name . . . : <i>USER</i>.ICU.LOAD |
| Management class. . : <i>**None**</i> |
| Storage class . . . : <i>BASE</i> |
| Volume serial . . . : <i>TSO007</i> |
| Device type . . . . : <i>3390</i> |
| Data class. . . . . : LOAD |
| Organization . . . : PO |
| Record format . . . : U |
| Record length . . . : 0 |
| Block size . . . . : 32760 |
| 1st extent cylinders: 1 |
| Secondary cylinders : 5 |
| Data set name type : LIBRARY</samp> |
| </pre> |
| |
| <p>The PDS can be allocated with the following attributes:</p> |
| <pre> |
| <samp>Data Set Name . . . : <i>USER</i>.ICU.EXP |
| Management class. . : <i>**None**</i> |
| Storage class . . . : <i>BASE</i> |
| Volume serial . . . : <i>TSO007</i> |
| Device type . . . . : <i>3390</i> |
| Data class. . . . . : <i>**None**</i> |
| Organization . . . : PO |
| Record format . . . : FB |
| Record length . . . : 80 |
| Block size . . . . : <i>3200</i> |
| 1st extent cylinders: 3 |
| Secondary cylinders : 3 |
| Data set name type : PDS</samp> |
| </pre> |
| |
| <h3><a name="HowToBuildOS400" href="#HowToBuildOS400">How To Build And |
| Install On OS/400 (iSeries)</a></h3> |
| |
| <p>ICU Reference Release 2.4 contains partial support for the iSeries |
| platform. After building ICU and running the tests, you may notice that |
| some of the formatting tests fail. The formating failures can be ignored |
| for now. These failures are expected to be resolved in a future release of |
| OS/400.</p> |
| |
| <p>Before you start building ICU, ICU requires the following:</p> |
| |
| <ul> |
| <li>QSHELL interpreter installed (install base option 30, operating |
| system)</li> |
| <!--li>QShell Utilities, PRPQ 5799-XEH (not required for V4R5)</li--> |
| |
| <li>ILE C/C++ Compiler for iSeries, LPP 5722-WDS</li> |
| |
| <li>The latest GNU facilities (You can get the GNU facilities for OS/400 |
| from <a href= |
| "http://www.as400.ibm.com/developer/factory/porting/gnu_utilities.html">http://www.as400.ibm.com/developer/factory/porting/gnu_utilities.html</a>). |
| Older versions may not work properly.</li> |
| </ul> |
| |
| <p>The following describes how to setup and build ICU. For background |
| information, you should look at the <a href="#HowToBuildUnix">Unix</a> |
| build instructions.</p> |
| |
| <ol> |
| <li> |
| Create AS400 target library. This library will be the target for the |
| resulting modules, programs and service programs. You will specify this |
| library on the OUTPUTDIR environment variable in step 2.<br> |
| |
| <pre> |
| <samp>CRTLIB LIB(<i>libraryname</i>)</samp> |
| </pre> |
| <br> |
| </li> |
| |
| <li> |
| Set up the following environment variables in your build process (use |
| the <i>libraryname</i> from the previous step) |
| <pre> |
| <samp>ADDENVVAR ENVVAR(CC) VALUE('/usr/bin/icc') |
| ADDENVVAR ENVVAR(CXX) VALUE('/usr/bin/icc') |
| ADDENVVAR ENVVAR(MAKE) VALUE('/usr/bin/gmake') |
| ADDENVVAR ENVVAR(OUTPUTDIR) VALUE('<i>libraryname</i>')</samp> |
| </pre> |
| <i>libraryname</i> identifies target as400 library for *module, *pgm |
| and *srvpgm objects.<br> |
| <br> |
| </li> |
| <!--li>Add QCXXN, to your build process library list. This results in the resolution of CRTCPPMOD used by the icc compiler</li--> |
| |
| <li> |
| In order to get the tests to run correctly, the QUTCOFFSET needs to be |
| set to the Pacific Time Zone offset.<br> |
| <br> |
| To check your QUTCOFFSET: |
| <pre> |
| <samp>DSPSYSVAL SYSVAL(QUTCOFFSET)</samp> |
| </pre> |
| <br> |
| To change your QUTCOFFSET:<br> |
| <pre> |
| <samp>CHGSYSVAL SYSVAL(QUTCOFFSET) VALUE('-0800')</samp> |
| </pre> |
| You should change -0800 to -0700 for daylight savings.<br> |
| <br> |
| </li> |
| |
| <li>Run <tt>'CHGJOB CCSID(37)'</tt></li> |
| |
| <li>Run <tt>'QSH'</tt></li> |
| |
| <li>Run gunzip on the ICU source code compressed tar archive |
| (icu-<i>X</i>.<i>Y</i>.tgz or icu-<i>X</i>.<i>Y</i>.tar.gz).</li> |
| |
| <li>Run unpax-icu.sh on the tar file from the ICU download page.</li> |
| |
| <li>Change your current directory to icu/source.</li> |
| |
| <li>Run <tt>'cp ../as_is/os400/configure .'</tt></li> |
| |
| <li>Run <tt>'./configure --host=as400-os400'</tt></li> |
| |
| <li> |
| If you specified <tt>--with-data-packaging=archive</tt> to configure, |
| you can skip this step. In a future release of ICU, we hope to |
| eliminate this complicated step. Any suggestions to improve the ICU |
| installation are greatly appreciated, and you can send those |
| suggestions to the <a href= |
| "http://oss.software.ibm.com/developerworks/oss/mailman/listinfo/icu4c-support/"> |
| icu4c-support</a> mailing list. |
| |
| <ol type="a"> |
| <li>Run <tt>'mv data/Makefile data/Makefile.hide'</tt></li> |
| |
| <li>Run <tt>'gmake'</tt> to build some of the ICU libraries.</li> |
| |
| <li> |
| When the gmake command fails in icu/source/data, run the following |
| commands to setup and build the data library: |
| <pre> |
| <samp>cd data |
| mv Makefile.hide Makefile |
| system CRTLIB "LIB(<i>datalibraryname</i>)" |
| gmake OUTPUTDIR=<i>datalibraryname</i> |
| system CRTSRVPGM "SRVPGM(<i>libraryname</i>/LIBICUDATA)" "MODULE(<i>datalibraryname</i>/*ALL)" |
| "EXPORT(*ALL)" "TEXT('ICU 2.4 DATA')" "OPTION(*DUPPROC *DUPVAR)" |
| ln -fs /qsys.lib/<i>libraryname</i>.lib/libicudata.srvpgm out/libicudata.o |
| cd .. |
| del common/libicuuc.o |
| </samp> |
| </pre> |
| </li> |
| |
| <li>Your data library should now be usable. Go to the next step, |
| which is needed to rebind to the actual data library and finish the |
| build.</li> |
| </ol> |
| </li> |
| |
| <li>Run <tt>'gmake'</tt> to build ICU.</li> |
| |
| <li>Run <tt>'gmake check'</tt> to build the tests.</li> |
| |
| <li>The "utility/MultithreadTest" test in intltest may have failed during |
| <tt>'gmake check'</tt>. In order to make this test pass, please use |
| <tt>'gmake check QIBM_MULTI_THREADED=Y'</tt> after you built the tests |
| with <tt>'gmake check'</tt> from the previous step. You can look at the |
| <a href= |
| "http://publib.boulder.ibm.com/iseries/v5r1/ic2924/index.htm?info/apis/concept4.htm"> |
| iSeries Information Center</a> for more details.</li> |
| </ol> |
| <!-- end build environment --> |
| |
| <h2><a name="ImportantNotes" href="#ImportantNotes">Important Notes About |
| Using ICU</a></h2> |
| |
| <h3><a name="ImportantNotesCPlusPlus" href="#ImportantNotesCPlusPlus">Using |
| ICU in a Multithreaded Environment</a></h3> |
| |
| <p>If you are using ICU in a multithreaded application, there may be a |
| chance that the ICU global mutex is not initialized properly. Normally the |
| ICU global mutex is initialized during C++ static initialization, but there |
| are some compilers and linkers that do not properly perform C++ static |
| initialization in a library (this sometimes happens on HP/UX and on MacOS |
| X).</p> |
| |
| <p>Upon the first usage of most ICU APIs, the global mutex will get |
| initialized. For example, you could call uloc_countAvailable() or |
| uloc_getDefault() from your main() function before any threads are created. |
| Those functions will initialize the global mutex. Without one of these |
| function calls from a single thread, the data caches inside ICU may get |
| initialized more than once, which may cause memory leaks and other |
| problems. This problem normally does not happen when C++ static |
| initialization works properly.</p> |
| |
| <p>ICU does not use C++ static initialization for anything else, and |
| disabling threads in ICU will disable all C++ static initialization in |
| ICU.</p> |
| |
| <h3><a name="MakeICUSmaller" href="#MakeICUSmaller">How to Make ICU |
| Smaller</a></h3> |
| |
| <p>For some environments, ICU "is too large". There are two ways to remove |
| parts and make it smaller: Remove some of its library code modules from the |
| build (reducing functionality), or remove some of its data (possibly |
| reducing only codepage/locale/etc. coverage without sacrifycing overall |
| functionality). For details about reducing the data size see the <a href= |
| "http://oss.software.ibm.com/icu/userguide/">User Guide</a> "ICU Data" |
| chapter.</p> |
| |
| <p>The header file <code>source/common/unicode/uconfig.h</code> contains |
| source-code-level "switches" corresponding to <code>#if</code> directives |
| in the ICU source code. Setting one of the <code>UCONFIG_NO_...</code> |
| switches to 1 (by setting <code>CFLAGS/CPPFLAGS</code> or adding a |
| <code>#define</code> at the beginning of <code>uconfig.h</code>) turns off |
| the code associated with one of the ICU service modules. Setting one of the |
| <code>UCONFIG_ONLY_...</code> switches to 1 turns off all modules that are |
| not essential for the functioning of the associated "only" service. For the |
| current set of available switches see <code>uconfig.h</code> itself.</p> |
| |
| <p>When a source code module is turned off, then the data-building |
| makefiles should be modified to not generate the data files that are used |
| with that module. Some of the data-generating genxyz tools rely on the |
| module itself to build its data; they will generate dummy data files to |
| satisfy the dependencies of the unmodified makefiles (to make these |
| switches easily testable). Other data files for which the tools do not rely |
| on the related library modules (e.g., mapping tables [<code>.cnv</code>] |
| and transliterator files [<code>.res</code>, from |
| <code>source/data/translit/</code>]) continue to be built unless the data |
| makefiles are modified. For further details on data building see the <a |
| href="http://oss.software.ibm.com/icu/userguide/">User Guide</a> "ICU Data" |
| chapter.</p> |
| |
| <h3><a name="ImportantNotesBinaryCompat" href= |
| "#ImportantNotesBinaryCompat">Binary Compatibility</a></h3> |
| |
| <p>Even though the ICU development team tries to make a stable API, some |
| breaking changes are required from time to time. ICU does not guarentee |
| binary compatibility of its functions or its data between releases. Please |
| view the <a href= |
| "http://oss.software.ibm.com/icu/userguide/design.html">ICU Design</a> |
| chapter of the User's Guide for details.</p> |
| |
| <h3><a name="ImportantNotesWindows" href="#ImportantNotesWindows">Windows |
| Platform</a></h3> |
| |
| <p>If you are building on the Win32 platform, it is important that you |
| understand a few of the following build details.</p> |
| |
| <h4>DLL directories and the PATH setting</h4> |
| |
| <p>As delivered, the International Components for Unicode build as several |
| DLLs, which are placed in the "<i><ICU></i>\bin" directory. You must |
| add this directory to the PATH environment variable in your system, or any |
| executables you build will not be able to access International Components |
| for Unicode libraries. Alternatively, you can copy the DLL files into a |
| directory already in your PATH, but we do not recommend this. You can wind |
| up with multiple copies of the DLL and wind up using the wrong one.</p> |
| |
| <h4><a name="ImportantNotesWindowsPath">Changing your PATH</a></h4> |
| |
| <ul> |
| <li><strong>Windows 2000</strong>: Use the System Icon in the Control |
| Panel. Pick the "Advanced" tab. Select the "Environment Variables..." |
| button. Select the variable PATH in the lower box, and select the lower |
| "Edit..." button. In the "Variable Value" box, append the string |
| ";<i><ICU></i>\bin" to the end of the path string. If there is |
| nothing there, just type in "<i><ICU></i>\bin". Click the Set |
| button, then the OK button.</li> |
| |
| <li><strong>Windows NT</strong>: Use the System Icon in the Control |
| Panel. Pick the "Environment" tab, and select the variable PATH in the |
| lower box. In the "value" box, append the string |
| ";<i><ICU></i>\bin" at the end of the path string. If there is |
| nothing there, just type in "<i><ICU></i>\bin". Click the Set |
| button, then the OK button.</li> |
| |
| <li><strong>Windows 95/98/ME</strong>: Edit the autoexec.bat, and add the |
| following line to the end of file, "SET |
| PATH=%PATH%;<i><ICU></i>\bin"</li> |
| </ul> |
| |
| <p>Note: When packaging a Windows application for distribution and |
| installation on user systems, copies of the ICU DLLs should be included |
| with the application, and installed for exclusive use by the application. |
| This is the only way to insure that your application is running with the same |
| version of ICU, built with exactly the same options, that you developed and |
| tested with. Refer to Microsoft's guidelines on the usage of DLLs, or |
| search for the phrase "DLL hell" on <a href= |
| "http://msdn.microsoft.com/">msdn.microsoft.com</a>.</p> |
| |
| <h3><a name="ImportantNotesUnix" href="#ImportantNotesUnix">Unix Type |
| Platform</a></h3> |
| |
| <p>If you are building on a Unix platform, and if you are installing ICU in |
| a non-standard location, you may need to add the location of your ICU |
| libraries to your <strong>LD_LIBRARY_PATH</strong> or |
| <strong>LIBPATH</strong> environment variable (or the equivalent runtime |
| library path environment variable for your system). The ICU libraries may |
| not link or load properly without doing this.</p> |
| |
| <p>Note that if you do not want to have to set this variable, you may |
| instead use the --enable-rpath option at configuration time. This option |
| will instruct the linker to always look for the libraries where they are |
| installed. You will need to use the appropriate linker options when linking |
| your own applications and libraries against ICU, too. Please refer to your |
| system's linker manual for information about runtime paths. The use of |
| rpath also means that when building a new version of ICU you should not |
| have an older version installed in the same place as the new version's |
| installation directory, as the older libraries will used during the build, |
| instead of the new ones, likely leading to an incorrectly build ICU. (This |
| is the proper behavior of rpath.)</p> |
| |
| <h3><a name="ImportantNotesDefaultCP" href="#ImportantNotesDefaultCP">Using |
| the default codepage</a></h3> |
| |
| <p>ICU has code to determine the default codepage of the system or process. |
| This default codepage can be used to convert <code>char *</code> strings to |
| and from Unicode.</p> |
| |
| <p>Depending on system design, setup and APIs, it may not always be |
| possible to find a default codepage that fully works as expected. For |
| example,</p> |
| |
| <ul> |
| <li>On Windows there are three encodings in use at the same time. Unicode |
| (UTF-16) is always used inside of Windows, while for <code>char *</code> |
| encodings there are two classes, called "ANSI" and "OEM" codepages. ICU |
| will use the ANSI codepage. Note that the OEM codepage is used by default |
| for console window output.</li> |
| |
| <li>On some Unix-type systems, non-standard names are used for encodings, |
| or non-standard encodings are used altogether. Although ICU supports 200 |
| encodings in its standard build and many more aliases for them, it will |
| not be able to recognize such non-standard names.</li> |
| |
| <li>Some systems do not have a notion of a system or process codepage, |
| and may not have APIs for that.</li> |
| </ul> |
| |
| <p>If you have means of detecting a default codepage name that are more |
| appropriate for your application, then you should set that name with |
| <code>ucnv_setDefaultName()</code> as the first ICU function call. This |
| makes sure that the internally cached default converter will be |
| instantiated from your preferred name.</p> |
| |
| <p>Starting in ICU 2.0, when a converter for the default codepage cannot be |
| opened, a fallback default codepage name and converter will be used. On |
| most platforms, this will be US-ASCII. For z/OS (OS/390), ibm-1047-s390 is |
| the default fallback codepage. For AS/400 (iSeries), ibm-37 is the default |
| fallback codepage. This default fallback codepage is used when the |
| operating system is using a non-standard name for a default codepage, or |
| the converter was not packaged with ICU. The feature allows ICU to run in |
| unusual computing environments without completely failing.</p> |
| |
| <h2><a name="PlatformDependencies" href="#PlatformDependencies">Platform |
| Dependencies</a></h2> |
| |
| <p>The platform dependencies have been mostly isolated into the following |
| files in the common library. This information can be useful if you are |
| porting ICU to a new platform.</p> |
| |
| <ul> |
| <li> |
| <strong>unicode/platform.h.in</strong> (autoconf'ed platforms)<br> |
| <strong>unicode/p<i>XXXX</i>.h</strong> (others: pwin32.h, pmacos.h, |
| ..): Platform-dependent typedefs and defines:<br> |
| <br> |
| |
| |
| <ul> |
| <li>XP_CPLUSPLUS for C++ only.</li> |
| |
| <li>TRUE and FALSE, UBool, int8_t, int16_t etc.</li> |
| |
| <li>U_EXPORT and U_IMPORT for specifying dynamic library import and |
| export</li> |
| </ul> |
| <br> |
| </li> |
| |
| <li> |
| <strong>unicode/putil.h, putil.c</strong>: platform-dependent |
| implementations of various functions that are platform dependent:<br> |
| <br> |
| |
| |
| <ul> |
| <li>uprv_isNaN, uprv_isInfinite, uprv_getNaN and uprv_getInfinity for |
| handling special floating point values.</li> |
| |
| <li>uprv_tzset, uprv_timezone, uprv_tzname and time for getting |
| platform specific time and time zone information.</li> |
| |
| <li>u_getDataDirectory for getting the default data directory.</li> |
| |
| <li>uprv_getDefaultLocaleID for getting the default locale |
| setting.</li> |
| |
| <li>uprv_getDefaultCodepage for getting the default codepage |
| encoding.</li> |
| </ul> |
| <br> |
| </li> |
| |
| <li> |
| <strong>umutex.h, umutex.c</strong>: Code for doing synchronization in |
| multithreaded applications. If you wish to use International Components |
| for Unicode in a multithreaded application, you must provide a |
| synchronization primitive that the classes can use to protect their |
| global data against simultaneous modifications. See Users' guide for |
| more information.<br> |
| <br> |
| |
| |
| <ul> |
| <li>We supply sample implementations for WinNT, Win95, Win98, |
| Sun/Solaris, RedHat/Linux, HP-UX and for AIX on an RS/6000.</li> |
| </ul> |
| <br> |
| </li> |
| |
| <li><strong>umapfile.h, umapfile.c</strong>: functions for mapping or |
| otherwise reading or loading files into memory. All access by ICU to data |
| from files makes use of these functions.<br> |
| <br> |
| </li> |
| |
| <li>For the intltest test suite, intltest.cpp in |
| "icu/source/test/intltest/" contains the method pathnameInContext, which |
| must also be adapted to any new platform.</li> |
| |
| <li>Using platform specific #ifdef macros are highly discouraged outside |
| of the scope of these files. When the source code gets updated in the |
| future, these #ifdef's can cause testing problems for your platform.</li> |
| </ul> |
| |
| <p>It is possible to build each library individually. They must be built in |
| the following order:<br> |
| </p> |
| |
| <ol> |
| <li>stubdata</li> |
| |
| <li>common</li> |
| |
| <li>i18n</li> |
| |
| <li>toolutil</li> |
| |
| <li>makeconv</li> |
| |
| <li>gencnval</li> |
| |
| <li>genprops</li> |
| |
| <li>gennames</li> |
| |
| <li>genpname</li> |
| |
| <li>gennorm</li> |
| |
| <li>genbrk</li> |
| |
| <li>genuca</li> |
| |
| <li>genrb</li> |
| |
| <li>gentz</li> |
| |
| <li>genccode</li> |
| |
| <li>gencmn</li> |
| |
| <li>pkgdata</li> |
| |
| <li>makedata (a project on Windows, or source/data/Makefile on Unix)</li> |
| |
| <li>ctestfw, intltest and cintltst, if you want to run the test |
| suite.</li> |
| |
| <li>uconv and ustdio can also be optionally built.</li> |
| </ol> |
| <hr> |
| |
| <p>Copyright © 1997-2002 International Business Machines Corporation |
| and others. All Rights Reserved.<br> |
| IBM Globalization Center of Competency - San Jose,<br> |
| 5600 Cottle Road, San José, CA 95193<br> |
| All rights reserved.</p> |
| </body> |
| </html> |
| |