| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| |
| <html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US"> |
| <head> |
| <meta name="generator" content="HTML Tidy, see www.w3.org" /> |
| |
| <title>ReadMe for ICU</title> |
| <meta name="COPYRIGHT" content= |
| "Copyright (c) 1997-2006 IBM Corporation and others. All Rights Reserved." /> |
| <meta name="KEYWORDS" content= |
| "ICU; International Components for Unicode; ICU4C; 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=us-ascii" /> |
| <style type="text/css"> |
| /*<![CDATA[*/ |
| 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> 3.7 |
| ReadMe</h1> |
| |
| <p>Version: 2006-Oct-20<br /> |
| Copyright © 1997-2006 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="#HowToBuildCygwin">Cygwin</a></li> |
| |
| <li><a href="#HowToBuildUNIX">UNIX</a></li> |
| |
| <li><a href="#HowToBuildZOS">z/OS (os/390)</a></li> |
| |
| <li><a href="#HowToBuildOS400">i5/OS (OS/400 iSeries)</a></li> |
| </ul> |
| </li> |
| |
| <li><a href="#HowToPackage">How To Package ICU</a></li> |
| |
| <li> |
| <a href="#ImportantNotes">Important Notes About Using ICU</a> |
| |
| <ul class="TOC"> |
| <li><a href="#ImportantNotesMultithreaded">Using ICU in a Multithreaded |
| Environment</a></li> |
| |
| <li><a href="#ImportantNotesWindows">Windows Platform</a></li> |
| |
| <li><a href="#ImportantNotesUNIX">UNIX Type Platforms</a></li> |
| </ul> |
| </li> |
| |
| <li> |
| <a href="#PlatformDependencies">Platform Dependencies</a> |
| |
| <ul class="TOC"> |
| <li><a href="#PlatformDependenciesNew">Porting To A New |
| Platform</a></li> |
| |
| <li><a href="#PlatformDependenciesImpl">Platform Dependent |
| Implementations</a></li> |
| </ul> |
| </li> |
| </ul> |
| <hr /> |
| |
| <h2><a name="Introduction" href="#Introduction" id= |
| "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 220 codepages</li> |
| |
| <li>Locale data for more than 250 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 ICU4J 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" id= |
| "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= |
| "These are some useful links regarding ICU and internationalization in general."> |
| <caption> |
| Here are some useful links regarding ICU and internationalization in |
| general. |
| </caption> |
| |
| <tr> |
| <td>ICU, ICU4C, ICU4J & ICU4JNI Official Homepage</td> |
| |
| <td><a href= |
| "http://www.ibm.com/software/globalization/icu/index.jsp">http://www.ibm.com/software/globalization/icu/index.jsp</a></td> |
| </tr> |
| |
| <tr> |
| <td>ICU, ICU4C, ICU4J & ICU4JNI Unofficial Homepage</td> |
| |
| <td><a href= |
| "http://icu.sourceforge.net/">http://icu.sourceforge.net/</a></td> |
| </tr> |
| |
| <tr> |
| <td>FAQ - Frequently Asked Questions about ICU</td> |
| |
| <td><a href= |
| "http://icu.sourceforge.net/userguide/icufaq.html">http://icu.sourceforge.net/userguide/icufaq.html</a></td> |
| </tr> |
| |
| <tr> |
| <td>ICU User's Guide</td> |
| |
| <td><a href= |
| "http://icu.sourceforge.net/userguide/">http://icu.sourceforge.net/userguide/</a></td> |
| </tr> |
| |
| <tr> |
| <td>Download ICU Releases</td> |
| |
| <td><a href= |
| "http://www.ibm.com/software/globalization/icu/downloads.jsp">http://www.ibm.com/software/globalization/icu/downloads.jsp</a></td> |
| </tr> |
| |
| <tr> |
| <td>API Documentation Online</td> |
| |
| <td><a href= |
| "http://icu.sourceforge.net/apiref/index.html">http://icu.sourceforge.net/apiref/index.html</a></td> |
| </tr> |
| |
| <tr> |
| <td>Online ICU Demos</td> |
| |
| <td><a href= |
| "http://www.ibm.com/software/globalization/icu/chartsdemostools.jsp">http://www.ibm.com/software/globalization/icu/chartsdemostools.jsp</a></td> |
| </tr> |
| |
| <tr> |
| <td>Contacts and Bug Reports/Feature Requests</td> |
| |
| <td><a href= |
| "http://icu.sourceforge.net/contacts.html">http://icu.sourceforge.net/contacts.html</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" id="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://www.ibm.com/software/globalization/icu/downloads.jsp">ICU 3.6 |
| download page</a>.</p> |
| |
| <h3><a name="News_app_packaging" id="News_app_packaging">Changes to packaging |
| resource bundles</a></h3> |
| |
| <p>Since ICU 3.0, the old style of packaging was deprecated, and an alternate |
| packaging mode was made available. In this release, this compatibility mode |
| of packaging has been removed from ICU. If you're using the genrb -P or -t |
| options, you are probably using the older compatible mode of data packaging. |
| This compatibility file naming mode was removed for portability and |
| performance reasons.</p> |
| |
| <p>Code changes should not be required to use the newer data file naming |
| scheme, but you will need to update your makefile scripts, if you're using |
| the older data file naming scheme. The example of using the new data file |
| naming scheme can be found in <a href="source/samples/ufortune/">the ufortune |
| sample program</a>.</p> |
| |
| <table border="1" cellpadding="0" summary= |
| "The following are examples of the file naming schemes."> |
| <caption> |
| The following are examples of the file naming schemes. |
| </caption> |
| |
| <tr> |
| <th scope="col">Old File Naming Scheme</th> |
| |
| <th scope="col">Current File Naming Scheme</th> |
| </tr> |
| |
| <tr> |
| <td>MyApp_root.res</td> |
| |
| <td>MyApp/root.res</td> |
| </tr> |
| |
| <tr> |
| <td>MyApp_en.res</td> |
| |
| <td>MyApp/en.res</td> |
| </tr> |
| </table> |
| |
| <h3><a name="News_wchar_t" id="News_wchar_t">Changes to wchar_t type for the |
| Microsoft Visual Studio builds</a></h3> |
| |
| <p>Previous versions of ICU built with Microsoft Visual Studio were not built |
| with the /Zc:wchar_t compiler option. ICU now builds with this option turned |
| on by default. This allows the built libraries to be compatible with Visual |
| Studio 2005, and this makes it easier for ICU users to use MFC in their |
| projects, which requires this option to be turned by default. If you do not |
| use the C++ API of ICU, you are not affected by this change.</p> |
| |
| <p>If you receive any errors while linking ICU into your project, please make |
| sure that you have set "Treat wchar_t as Built-in Type" to "Yes |
| (/Zc:wchar_t)" in your project files.</p> |
| |
| <h3><a name="News_scanf" id="News_scanf">Changes to scanf and storing |
| floating point types</a></h3> |
| |
| <p>In order to improve interoperability with standard scanf implementations, |
| the icuio library's implementations of scanf has changed the default scanf |
| type from <tt>double</tt> to <tt>float</tt>. This is a breaking change |
| requires you to change your code if you are using the icuio library's scanf |
| to read <tt>double</tt> or <tt>float</tt> values with %e, %f or %g. As a |
| reminder, these scanf functions in the icuio library are still marked |
| draft.</p> |
| |
| <h3><a name="News_data_package" id="News_data_package">Source download |
| contains .dat package for ICU data</a></h3> |
| |
| <p>The ICU4C 3.6 source downloads contain a pre-built .dat package with ICU's |
| data rather than the data source files. This is to simplify the build process |
| for the majority of users and to reduce platform porting issues. If you need |
| the data source files for customization, then please download the ICU source |
| code from <a href= |
| "http://www.ibm.com/software/globalization/icu/repository.jsp">CVS</a>.</p> |
| |
| <h2><a name="Download" href="#Download" id="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://www.ibm.com/software/globalization/icu/downloads.jsp">http://www.ibm.com/software/globalization/icu/downloads.jsp</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://www.ibm.com/software/globalization/icu/repository.jsp">CVS |
| page</a> for details.</li> |
| </ul> |
| |
| <h2><a name="SourceCode" href="#SourceCode" id="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://icu.sourceforge.net/userguide/design.html">ICU Architectural |
| Design</a> section of the User's Guide 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= |
| "The following files describe the code drop."> |
| <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= |
| "The following directories contain source code and data files."> |
| <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>layout</b>/</td> |
| |
| <td>Contains the ICU layout engine (not a rasterizer).</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>io</b>/</td> |
| |
| <td>Contains the ICU I/O library.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/<b>data</b>/</td> |
| |
| <td> |
| <p>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.</p> |
| |
| <p>If some of the following directories are missing, it's probably |
| because you got an official download. If you need the data source files |
| for customization, then please download the ICU source code from <a |
| href= |
| "http://www.ibm.com/software/globalization/icu/repository.jsp">CVS</a>.</p> |
| |
| <ul> |
| <li><b>in/</b> A directory that contains a pre-built data library for |
| ICU. A standard source code package will contain this file without |
| several of the following directories. This is to simplify the build |
| process for the majority of users and to reduce platform porting |
| issues.</li> |
| |
| <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 |
| time zone information, and a name preperation file for <a href= |
| "http://www.ietf.org/rfc/rfc3490.txt">IDNA</a>.</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> |
| |
| <p>If you are creating a special ICU build, you can set the ICU_DATA |
| environment variable to the out/ or the out/build/ directories, but |
| this is generally discouraged because most people set it incorrectly. |
| You can view the <a href= |
| "http://icu.sourceforge.net/userguide/icudata.html">ICU Data |
| Management</a> section of the ICU User's Guide for details.</p> |
| </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 build instructions specific to your platform |
| later in this document.</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 build instructions specific to your |
| platform later in this document.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/source/test/<b>iotest</b>/</td> |
| |
| <td>A test suite written in C and C++ to test the icuio library. For |
| information about running the test suite, see the build instructions |
| specific to your platform later in this document.</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 <b>testdata.dat.</b></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 'uconv' tool |
| to perform codepage conversion on files.</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>include</b>/</td> |
| |
| <td>Contains the headers needed for developing software that uses ICU on |
| Windows.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/<b>lib</b>/</td> |
| |
| <td>Contains the import libraries for linking ICU into your Windows |
| application.</td> |
| </tr> |
| |
| <tr> |
| <td><i><ICU></i>/<b>bin</b>/</td> |
| |
| <td>Contains the libraries and executables for using ICU on Windows.</td> |
| </tr> |
| </table> |
| <!-- end of ICU structure ==================================== --> |
| |
| <h2><a name="HowToBuild" href="#HowToBuild" id="HowToBuild">How To Build And |
| Install ICU</a></h2> |
| |
| <h3><a name="HowToBuildSupported" href="#HowToBuildSupported" id= |
| "HowToBuildSupported">Supported Platforms</a></h3> |
| |
| <table border="1" cellpadding="3" summary= |
| "ICU can be built on many platforms."> |
| <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 XP</td> |
| |
| <td>Microsoft Visual C++ .NET 2003 (7.1)</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>Red Hat Enterprise Linux 4 Update 2</td> |
| |
| <td>gcc 3.4.4</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>AIX 5.2</td> |
| |
| <td>Visual Age C++ 6.0</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>Solaris 9 (SunOS 5.9)</td> |
| |
| <td>Sun Studio 8 (Sun C++ 5.5)</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>HP-UX 11.11</td> |
| |
| <td>aCC A.03.50<br /> |
| cc B.11.11.08</td> |
| |
| <td>Reference platform</td> |
| </tr> |
| |
| <tr> |
| <td>Red Hat Enterprise Linux 3 Update 4</td> |
| |
| <td>gcc 3.2.3</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Windows 2000 with Cygwin</td> |
| |
| <td>Microsoft Visual C++ .NET 2003 (7.1)</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Mac OS X (10.4)</td> |
| |
| <td>gcc 3.3</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Solaris 7 (SunOS 5.7)</td> |
| |
| <td>Workshop Pro (Forte) CC 6.0</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Solaris 10</td> |
| |
| <td>gcc 4.0.2</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>AIX 5.1.0 L</td> |
| |
| <td>Visual Age C++ 5.0</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>SUSE Linux Enterprise Server 9 SP1</td> |
| |
| <td>Intel C++ Compiler 9.0</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>SUSE Linux Enterprise Server 9 (PowerPC)</td> |
| |
| <td>Visual Age 8.0</td> |
| |
| <td>Regularly tested</td> |
| </tr> |
| |
| <tr> |
| <td>Windows XP</td> |
| |
| <td>Microsoft Visual C++ .NET 2005</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>z/OS 1.7</td> |
| |
| <td>cxx 1.7</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>Cygwin</td> |
| |
| <td>gcc 3.4.4</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>i5/OS (OS/400 iSeries) V5R3</td> |
| |
| <td>iCC</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>Windows 98</td> |
| |
| <td>Microsoft Visual C++ 6.0</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>MinGW</td> |
| |
| <td>gcc</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>NetBSD, OpenBSD, FreeBSD</td> |
| |
| <td>gcc</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>QNX</td> |
| |
| <td>gcc</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>BeOS</td> |
| |
| <td>gcc</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>SGI/IRIX</td> |
| |
| <td>MIPSpro CC</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>Tru64 (OSF)</td> |
| |
| <td>Compaq's cxx compiler</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| |
| <tr> |
| <td>MP-RAS</td> |
| |
| <td>NCR MP-RAS C/C++ Compiler</td> |
| |
| <td>Rarely tested</td> |
| </tr> |
| </table> |
| |
| <p><br /> |
| </p> |
| |
| <h4>Key to testing frequency</h4> |
| |
| <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" id= |
| "HowToBuildWindows">How To Build And Install On Windows</a></h3> |
| |
| <p>Building International Components for Unicode requires:</p> |
| |
| <ul> |
| <li>Microsoft Windows 2000 or above</li> |
| |
| <li>Microsoft Visual C++ 2003</li> |
| |
| <li><a href="#HowToBuildCygwin">Cygwin</a> is required when other versions |
| of Microsoft Visual C++ and other compilers are used to build ICU.</li> |
| </ul> |
| |
| <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>Open the "<i><ICU></i>\source\allinone\allinone.sln" workspace |
| file in Microsoft Visual Studio .NET 2003. (This solution includes all the |
| International Components for Unicode libraries, necessary ICU building |
| tools, and the test suite projects). Please see the <a href= |
| "#HowToBuildWindowsCommandLine">command line note below</a> if you want to |
| build from the command line instead.</li> |
| |
| <li>Set the active configuration to "Debug" or "Release" (See <a href= |
| "#HowToBuildWindowsConfig">Windows configuration note</a> below).</li> |
| |
| <li>Choose the "Build" menu and select "Rebuild Solution". If you want to |
| build the Debug and Release at the same time, see the <a href= |
| "#HowToBuildWindowsBatch">batch configuration note</a> below.</li> |
| |
| <li>Run the C++ test suite, "intltest". To do this: set the active startup |
| project to "intltest", and press Ctrl+F5 to run it. Make sure that it |
| passes without any errors.</li> |
| |
| <li>Run the C test suite, "cintltst". To do this: set the active startup |
| project to "cintltst", and press Ctrl+F5 to run it. Make sure that it |
| passes without any errors.</li> |
| |
| <li>Run the I/O test suite, "iotest". To do this: set the active startup |
| project to "iotest", and press Ctrl+F5 to run it. Make sure that it passes |
| without any errors.</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" id= |
| "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, 'devenv.com |
| <i><ICU></i>\source\allinone\allinone.sln /build Release'. You can also |
| use Cygwin with this compiler to build ICU, and you can refer to the <a href= |
| "#HowToBuildCygwin">How To Build And Install On Windows with Cygwin</a> |
| section for more details.</p> |
| |
| <p><a name="HowToBuildWindowsConfig" id= |
| "HowToBuildWindowsConfig"><strong>Setting Active Configuration |
| Note:</strong></a> To set the active configuration, two different |
| possibilities are:</p> |
| |
| <ul> |
| <li>Choose "Build" menu, select "Configuration Manager...", and select |
| "Release" or "Debug" for the Active Configuration Solution.</li> |
| |
| <li>Another way is to select the desired build configuration from "Solution |
| Configurations" dropdown menu from the standard toolbar. It will say |
| "Release" or "Debug" in the dropdown list.</li> |
| </ul> |
| |
| <p><a name="HowToBuildWindowsBatch" id="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...". Click the "Select All" button, and then click the "Rebuild" |
| button.</p> |
| |
| <h3><a name="HowToBuildCygwin" href="#HowToBuildCygwin" id= |
| "HowToBuildCygwin">How To Build And Install On Windows with Cygwin</a></h3> |
| |
| <p>Building International Components for Unicode with this configuration |
| requires:</p> |
| |
| <ul> |
| <li>Microsoft NT 4.0 or above, or Windows 98 or above</li> |
| |
| <li>Microsoft Visual C++ 6.0 or above (when gcc isn't used).</li> |
| |
| <li> |
| Cygwin with the following installed: |
| |
| <ul> |
| <li>bash</li> |
| |
| <li>GNU make</li> |
| |
| <li>man (if you plan to look at the man pages)</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>There are two ways you can build ICU with Cygwin. You can build with gcc |
| or Microsoft Visual C++. If you use gcc, the resulting libraries and tools |
| will depend on the Cygwin environment. If you use Microsoft Visual C++, the |
| resulting libraries and tools do not depend on Cygwin and can be more easily |
| distributed to other Windows computers (the generated man pages and shell |
| scripts still need Cygwin). To build with gcc, please follow the "<a href= |
| "#HowToBuildUNIX">How To Build And Install On UNIX</a>" instructions, while |
| you are inside a Cygwin bash shell. To build with Microsoft Visual C++, |
| please use the following instructions:</p> |
| |
| <ol> |
| <li>Start the Windows "Command Prompt" window. This is different from the |
| gcc build, which requires the Cygwin Bash command prompt. The Microsoft |
| Visual C++ compiler will not work with a bash command prompt.</li> |
| |
| <li>If the computer isn't set up to use Visual C++ from the command line, |
| you need to run VCVARS32.BAT (for example: "<tt>C:\Program Files\Microsoft |
| Visual Studio\VC98\Bin\VCVARS32.BAT</tt>").</li> |
| |
| <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>Change directory to "icu/source", which is where you unzipped ICU.</li> |
| |
| <li>Run "<tt>bash <a href="source/runConfigureICU">./runConfigureICU</a> |
| Cygwin/MSVC</tt>" (See <a href="#HowToWindowsConfigureICU">Windows |
| configuration note</a> and non-functional configure options below).</li> |
| |
| <li>Type <tt>"make"</tt> to compile the libraries and all the data files. |
| This make command should be GNU make.</li> |
| |
| <li>Optionally, type <tt>"make check"</tt> to run the test suite, which |
| checks for ICU's functionality integrity (See <a href= |
| "#HowToTestWithoutGmake">testing note</a> below).</li> |
| |
| <li>Type <tt>"make 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">installation |
| note</a> below).</li> |
| </ol> |
| |
| <p><a name="HowToWindowsConfigureICU" id= |
| "HowToWindowsConfigureICU"><strong>Configuring ICU on Windows |
| NOTE:</strong></a> In addition to the Unix <a href= |
| "#HowToConfigureICU">configuration note</a> the following configure options |
| currently do not work on Windows with Microsoft's compiler. Some options can |
| work by manually editing <tt>icu/source/common/unicode/pwin32.h</tt>, but |
| manually editing the files is not recommended.</p> |
| |
| <ul> |
| <li><tt>--disable-renaming</tt></li> |
| |
| <li><tt>--disable-threading</tt></li> |
| |
| <li><tt>--disable-tracing</tt></li> |
| |
| <li><tt>--enable-rpath</tt></li> |
| |
| <li><tt>--with-iostream</tt></li> |
| |
| <li><tt>--enable-static</tt> (Requires that U_STATIC_IMPLEMENTATION be |
| defined in user code that links against ICU's static libraries.)</li> |
| |
| <li><tt>--with-data-packaging=files</tt> (The pkgdata tool currently does |
| not work in this mode. Manual packaging is required to use this mode.)</li> |
| </ul> |
| |
| <h3><a name="HowToBuildUNIX" href="#HowToBuildUNIX" id="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">configuration |
| 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">testing 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">installation |
| note</a> below).</li> |
| </ol> |
| |
| <p><a name="HowToConfigureICU" id="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). |
| HP-UX user's, please see this <a href="#ImportantNotesHPUX">note regarding |
| HP-UX multithreaded build issues</a> with newer compilers. Solaris user's, |
| please see this <a href="#ImportantNotesSolaris">note regarding Solaris |
| multithreaded build issues</a>.</p> |
| |
| <p><a name="HowToTestWithoutGmake" id="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 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" id="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" id="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. 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>The makedep and GNU make tools are required for building ICU. If it |
| is not already installed on your system, it is available at the <a href= |
| "http://www.ibm.com/servers/eserver/zseries/zos/unix/redbook/">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. Failure to add these |
| tools to your PATH will cause ICU build failures or cause pkgdata to fail |
| to run.</li> |
| |
| <li>Since USS does not support using the mmap() function over NFS, it is |
| recommended that you build ICU on a local filesystem. Once ICU has been |
| built, you should not have this problem while using ICU when the data |
| library has been built as a shared library, which is this is the default |
| setting.</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>z/OS supports both native S/390 hexadecimal floating point and (with |
| OS/390 2.6 and later) IEEE 754 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=0 will |
| cause the z/OS version of ICU to be built without IEEE floating point |
| support and use the native hexadecimal floating point. By default ICU is |
| built with IEEE 754 support. Native floating point support is sufficient |
| for codepage conversion, resource bundle and UnicodeString operations, but |
| the Format APIs require IEEE binary floating point.</li> |
| |
| <li>z/OS introduced the concept of Extra Performance Linkage (XPLINK) to |
| bring performance improvement opportunities to call-intensive C and C++ |
| applications such as ICU. XPLINK is enabled on a DLL-by-DLL basis, so if |
| you are considering using XPLINK in your application that uses ICU, you |
| should consider building the XPLINK-enabled version of ICU. You need to |
| set ICU's environment variable <code>OS390_XPLINK=1</code> prior to |
| invoking the make process to produce binaries that are enabled for |
| XPLINK. The XPLINK option, which is available for z/OS 1.2 and later, |
| requires the PTF PQ69418 to build XPLINK enabled binaries.</li> |
| |
| <li>Currently in ICU 3.0, there is an issue with building on z/OS without |
| XPLINK and with the C++ iostream. By default, the iostream library on z/OS |
| is XPLINK enabled. If you are not building an XPLINK enabled version of |
| ICU, you should use the <code>--with-iostream=old</code> configure option |
| when using runConfigureICU. This will prevent applications that use the |
| icuio library from crashing.</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 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>IN --> libicui18n<i>XX</i>.dll |
| 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" id= |
| "HowToBuildOS400">How To Build And Install On i5/OS (OS/400 iSeries)</a></h3> |
| |
| <p>Before you start building ICU, ICU requires the following:</p> |
| |
| <ul> |
| <li>QSHELL interpreter installed (install base option 30, operating system) |
| <!--li>QShell Utilities, PRPQ 5799-XEH (not required for V4R5)</li--></li> |
| |
| <li>ILE C/C++ Compiler for iSeries, LPP 5722-WDS</li> |
| |
| <li>The latest GNU facilities (You can get the GNU facilities for i5/OS |
| from <a href= |
| "http://www.ibm.com/servers/enable/site/porting/iseries/overview/gnu_utilities.html"> |
| http://www.ibm.com/servers/enable/site/porting/iseries/overview/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 build |
| instructions</a>.</p> |
| |
| <ol> |
| <li> |
| Create i5/OS 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. |
| <pre> |
| <samp>CRTLIB LIB(<i>libraryname</i>)</samp> |
| </pre> |
| </li> |
| |
| <li> |
| Set up the following environment variables in your build process (use the |
| <i>libraryname</i> from the previous step). The <i>libraryname</i> |
| identifies target i5/OS library for *module, *pgm and *srvpgm objects. |
| <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> |
| </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).</li> |
| |
| <li>Run unpax-icu.sh on the tar file generated from the previous step.</li> |
| |
| <li>Change your current directory to icu/source.</li> |
| |
| <li>Run <tt>'export CFLAGS=-O4 CXXFLAGS=-O4'</tt> to optimize your build of |
| ICU. If the build fails, rerun these build steps without this step before |
| asking the icu-support mailing list for help.</li> |
| |
| <li>Run <tt>'./configure'</tt></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="HowToPackage" href="#HowToPackage" id="HowToPackage">How To |
| Package ICU</a></h2> |
| |
| <p>There are many ways that a person can package ICU with their software |
| products. Usually only the libraries need to be considered for packaging.</p> |
| |
| <p>On UNIX, you should use "<tt>gmake install</tt>" to make it easier to |
| develop and package ICU. The bin, lib and include directories are needed to |
| develop applications that use ICU. These directories will be created relative |
| to the "<tt>--prefix=</tt><i>dir</i>" configure option (See the <a href= |
| "#HowToBuildUNIX">UNIX build instructions</a>). When ICU is built on Windows, |
| a similar directory structure is built.</p> |
| |
| <p>When changes have been made to the standard ICU distribution, it is |
| recommended that at least one of the following guidelines be followed for |
| special packaging.</p> |
| |
| <ol> |
| <li>Add a suffix name to the library names. This can be done with the |
| --with-library-suffix configure option.</li> |
| |
| <li>The installation script should install the ICU libraries into the |
| application's directory.</li> |
| </ol> |
| |
| <p>Following these guidelines prevents other applications that use a standard |
| ICU distribution from conflicting with any libraries that you need. On |
| operating systems that do not have a standard C++ ABI (name mangling) for |
| compilers, it is recommended to do this special packaging anyway. More |
| details on customizing ICU are available in the <a href= |
| "http://icu.sourceforge.net/userguide/">User's Guide</a>. The <a href= |
| "#SourceCode">ICU Source Code Organization</a> section of this readme.html |
| gives a more complete description of the libraries.</p> |
| |
| <table border="1" cellpadding="3" summary= |
| "ICU has several libraries for you to use."> |
| <caption> |
| Here is an example of libraries that are frequently packaged. |
| </caption> |
| |
| <tr> |
| <th scope="col">Library Name</th> |
| |
| <th scope="col">Windows Filename</th> |
| |
| <th scope="col">Linux Filename</th> |
| |
| <th scope="col">Comment</th> |
| </tr> |
| |
| <tr> |
| <td>Data Library</td> |
| |
| <td>icudt<i>XY</i>l.dll</td> |
| |
| <td>libicudata.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>Data required by the Common and I18n libraries. There are many ways |
| to package and <a href= |
| "http://icu.sourceforge.net/userguide/icudata.html">customize this |
| data</a>, but by default this is all you need.</td> |
| </tr> |
| |
| <tr> |
| <td>Common Library</td> |
| |
| <td>icuuc<i>XY</i>.dll</td> |
| |
| <td>libicuuc.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>Base library required by all other ICU libraries.</td> |
| </tr> |
| |
| <tr> |
| <td>Internationalization (i18n) Library</td> |
| |
| <td>icuin<i>XY</i>.dll</td> |
| |
| <td>libicui18n.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>A library that contains many locale based internationalization (i18n) |
| functions.</td> |
| </tr> |
| |
| <tr> |
| <td>Layout Engine</td> |
| |
| <td>icule<i>XY</i>.dll</td> |
| |
| <td>libicule.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>An optional engine for doing font layout.</td> |
| </tr> |
| |
| <tr> |
| <td>Layout Extensions Engine</td> |
| |
| <td>iculx<i>XY</i>.dll</td> |
| |
| <td>libiculx.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>An optional engine for doing font layout that uses parts of ICU.</td> |
| </tr> |
| |
| <tr> |
| <td>ICU I/O (Unicode stdio) Library</td> |
| |
| <td>icuio<i>XY</i>.dll</td> |
| |
| <td>libicuio.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>An optional library that provides a stdio like API with Unicode |
| support.</td> |
| </tr> |
| |
| <tr> |
| <td>Tool Utility Library</td> |
| |
| <td>icutu<i>XY</i>.dll</td> |
| |
| <td>libicutu.so.<i>XY</i>.<i>Z</i></td> |
| |
| <td>An internal library that contains internal APIs that are only used by |
| ICU's tools. If you do not use ICU's tools, you do not need this |
| library.</td> |
| </tr> |
| </table> |
| |
| <p>Normally only the above ICU libraries need to be considered for packaging. |
| The versionless symbolic links to these libraries are only needed for easier |
| development. The <i>X</i>, <i>Y</i> and <i>Z</i> parts of the name are the |
| version numbers of ICU. For example, ICU 2.0.2 would have the name |
| libicuuc.so.20.2 for the common library. The exact format of the library |
| names can vary between platforms due to how each platform can handles library |
| versioning.</p> |
| |
| <h2><a name="ImportantNotes" href="#ImportantNotes" id= |
| "ImportantNotes">Important Notes About Using ICU</a></h2> |
| |
| <h3><a name="ImportantNotesMultithreaded" href="#ImportantNotesMultithreaded" |
| id="ImportantNotesMultithreaded">Using ICU in a Multithreaded |
| Environment</a></h3> |
| |
| <p>Some versions of ICU require calling the <code>u_init()</code> function |
| from <code>uclean.h</code> to ensure that ICU is initialized properly. In |
| those ICU versions, <code>u_init()</code> must be called before ICU is used |
| from multiple threads. There is no harm in calling <code>u_init()</code> in a |
| single-threaded application, on a single-CPU machine, or in other cases where |
| <code>u_init()</code> is not required.</p> |
| |
| <p>In addition to ensuring thread safety, <code>u_init()</code> also attempts |
| to load at least one ICU data file. Assuming that all data files are packaged |
| together (or are in the same folder in files mode), a failure code from |
| <code>u_init()</code> usually means that the data cannot be found. In this |
| case, the data may not be installed properly, or the application may have |
| failed to call <code>udata_setCommonData()</code> or |
| <code>u_setDataDirectory()</code> which specify to ICU where it can find its |
| data.</p> |
| |
| <p>Since <code>u_init()</code> will load only one or two data files, it |
| cannot guarantee that all of the data that an application needs is available. |
| It cannot check for all data files because the set of files is customizable, |
| and some ICU services work without loading any data at all. An application |
| should always check for error codes when opening ICU service objects (using |
| <code>ucnv_open()</code>, <code>ucol_open()</code>, C++ constructors, |
| etc.).</p> |
| |
| <h4>ICU 3.4 and later</h4> |
| |
| <p>ICU 3.4 self-initializes properly for multi-threaded use. It achieves this |
| without performance penalty by hardcoding the core Unicode properties data, |
| at the cost of some flexibility. (For details see Jitterbug 4497.)</p> |
| |
| <p><code>u_init()</code> can be used to check for data loading. It tries to |
| load the converter alias table (<code>cnvalias.icu</code>).</p> |
| |
| <h4>ICU 2.6..3.2</h4> |
| |
| <p>These ICU versions require a call to <code>u_init()</code> before |
| multi-threaded use. The services that are directly affected are those that |
| don't have a service object and need to be fast: normalization and character |
| properties.</p> |
| |
| <p><code>u_init()</code> loads and initializes the data files for |
| normalization and character properties (<code>unorm.icu</code> and |
| <code>uprops.icu</code>) and can therefore also be used to check for data |
| loading.</p> |
| |
| <h4>ICU 2.4 and earlier</h4> |
| |
| <p>ICU 2.4 and earlier versions were not prepared for multithreaded use on |
| multi-CPU platforms where the CPUs implement weak memory coherency. These |
| CPUs include: Power4, Power5, Alpha, Itanium. <code>u_init()</code> was not |
| defined yet.</p> |
| |
| <h4><a name="ImportantNotesHPUX" href="#ImportantNotesHPUX" id= |
| "ImportantNotesHPUX">Using ICU in a Multithreaded Environment on |
| HP-UX</a></h4> |
| |
| <p>If you are building ICU with a newer aCC compiler and you are planning on |
| using the older <iostream.h> instead of the newer <iostream>, you |
| will need to use a special configure flag before building ICU. By default, |
| the aCC <a href="http://docs.hp.com/en/1405/options.htm#optioncap-AA">-AA</a> |
| flag is used on HP-UX when the compiler supports that option in order to make |
| ICU thread safe with RogueWave and other libraries using the 2.0 Standard C++ |
| library. Your applications that use ICU will also need to use the <a href= |
| "http://docs.hp.com/en/1405/options.htm#optioncap-AA">-AA</a> compiler flag. |
| To turn off this behavior in ICU, you will need to use the --with-iostream=old |
| configure option when you first use runConfigureICU.</p> |
| |
| <h4><a name="ImportantNotesSolaris" href="#ImportantNotesSolaris" id= |
| "ImportantNotesSolaris">Using ICU in a Multithreaded Environment on |
| Solaris</a></h4> |
| |
| <h5>Linking on Solaris</h5> |
| |
| <p>In order to avoid synchronization and threading issues, developers are |
| <strong>suggested</strong> to strictly follow the compiling and linking |
| guidelines for multithreaded applications, specified in the following |
| document from Sun Microsystems. Most notably, pay strict attention to the |
| following statements from Sun:</p> |
| |
| <blockquote> |
| <p>To use libthread, specify -lthread before -lc on the ld command line, or |
| last on the cc command line.</p> |
| |
| <p>To use libpthread, specify -lpthread before -lc on the ld command line, |
| or last on the cc command line.</p> |
| </blockquote> |
| |
| <p>Failure to do this may cause spurious lock conflicts, recursive mutex |
| failure, and deadlock.</p> |
| |
| <p>Source: "<i>Solaris Multithreaded Programming Guide, Compiling and |
| Debugging</i>", Sun Microsystems, Inc., Apr 2004<br /> |
| <a href= |
| "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> |
| |
| <h3><a name="ImportantNotesWindows" href="#ImportantNotesWindows" id= |
| "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" id= |
| "ImportantNotesWindowsPath">Changing your PATH</a></h4> |
| |
| <p><strong>Windows 2000/XP</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.</p> |
| |
| <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" id= |
| "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> |
| |
| <h2><a name="PlatformDependencies" href="#PlatformDependencies" id= |
| "PlatformDependencies">Platform Dependencies</a></h2> |
| |
| <h3><a name="PlatformDependenciesNew" href="#PlatformDependenciesNew" id= |
| "PlatformDependenciesNew">Porting To A New Platform</a></h3> |
| |
| <p>If you are using ICU's Makefiles to build ICU on a new platform, there are |
| a few places where you will need to add or modify some files. If you need |
| more help, you can always ask the <a href= |
| "http://icu.sourceforge.net/contacts.html">icu-support mailing list</a>. Once |
| you have finished porting ICU to a new platform, it is recommended that you |
| contribute your changes back to ICU via the icu-support mailing list. This |
| will make it easier for everyone to benefit from your work.</p> |
| |
| <h4>Data For a New Platform</h4> |
| |
| <p>For some people, it may not be necessary for completely build ICU. Most of |
| the makefiles and build targets are for tools that are used for building |
| ICU's data, and an application's data (when an application uses ICU resource |
| bundles for its data).</p> |
| |
| <p>Data files can be built on a different platform when both platforms share |
| the same endianness and the same charset family. This assertion does not |
| include platform dependent DLLs/shared/static libraries. For details see the |
| User Guide <a href="http://icu.sourceforge.net/userguide/icudata.html">ICU |
| Data</a> chapter.</p> |
| |
| <p>ICU 3.6 removes the requirement that ICU be completely built in the native |
| operating environment. It adds the icupkg tool which can be run on any |
| platform to turn binary ICU data files from any one of the three formats into |
| any one of the other data formats. This allows a application to use ICU data |
| built anywhere to be used for any other target platform.</p> |
| |
| <p><strong>WARNING!</strong> Building ICU without running the tests is not |
| recommended. The tests verify that ICU is safe to use. It is recommended that |
| you try to completely port and test ICU before using the libraries for your |
| own application.</p> |
| |
| <h4>Adapting Makefiles For a New Platform</h4> |
| |
| <p>Try to follow the build steps from the <a href="#HowToBuildUNIX">UNIX</a> |
| build instructions. If the configure script fails, then you will need to |
| modify some files. Here are the usual steps for porting to a new |
| platform:<br /> |
| </p> |
| |
| <ol> |
| <li>Create an mh file in icu/source/config/. You can use mh-linux or a |
| similar mh file as your base configuration.</li> |
| |
| <li>Modify icu/source/aclocal.m4 to recognize your platform's mh file.</li> |
| |
| <li>Modify icu/source/configure.in to properly set your <b>platform</b> C |
| Macro define.</li> |
| |
| <li>Run <a href="http://www.gnu.org/software/autoconf/">autoconf</a> in |
| icu/source/ without any options. The autoconf tool is standard on most |
| Linux systems.</li> |
| |
| <li>If you have any optimization options that you want to normally use, you |
| can modify icu/source/runConfigureICU to specify those options for your |
| platform.</li> |
| |
| <li>Build and test ICU on your platform. It is very important that you run |
| the tests. If you don't run the tests, there is no guarentee that you have |
| properly ported ICU.</li> |
| </ol> |
| |
| <h3><a name="PlatformDependenciesImpl" href="#PlatformDependenciesImpl" id= |
| "PlatformDependenciesImpl">Platform Dependent Implementations</a></h3> |
| |
| <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, ppalmos.h, |
| ..): Platform-dependent typedefs and defines:<br /> |
| <br /> |
| |
| |
| <ul> |
| <li>Generic types like UBool, int8_t, int16_t, int32_t, int64_t, |
| uint64_t etc.</li> |
| |
| <li>U_EXPORT and U_IMPORT for specifying dynamic library import and |
| export</li> |
| |
| <li><iostream> usability</li> |
| |
| <li>Thread safety usability</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. We already supply working |
| implementations for many platforms that ICU builds on.<br /> |
| <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>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> |
| <hr /> |
| |
| <p>Copyright © 1997-2006 International Business Machines Corporation and |
| others. All Rights Reserved.<br /> |
| IBM Globalization Center of Competency - San José<br /> |
| 4400 North First Street<br /> |
| San José, CA 95134<br /> |
| USA</p> |
| </body> |
| </html> |
| |