| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| |
| <html> |
| <head> |
| <meta name="GENERATOR" content="HTML Tidy, see www.w3.org"> |
| <meta name="COPYRIGHT" value= |
| "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 bits of 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: 1; border: solid; text-align: center} |
| H2 {text-decoration: underline} |
| H3 {text-decoration: underline} |
| H4 {text-decoration: underline} |
| H5 {text-decoration: underline} |
| HR {height: 2; width: "100%"; text-align: center} |
| PRE {margin-left: .5in; margin-bottom: .5in} |
| |
| </style> |
| </head> |
| |
| <body lang="en-US"> |
| <h1>International Components for Unicode<br> |
| ReadMe</h1> |
| |
| <p>Version: 2001-Mar-21<br> |
| Copyright © 1997-2001 International Business Machines Corporation |
| and others. All Rights Reserved.</p> |
| <hr> |
| |
| <p><br> |
| <br> |
| </p> |
| |
| <h2>Contents</h2> |
| |
| <ul type="disc"> |
| <li><a href="#news">Late Breaking News And What Is New?</a></li> |
| |
| <li><a href="#introduction">Introduction</a></li> |
| |
| <li><a href="#WhatContain">What the International Components for |
| Unicode Contain</a></li> |
| |
| <li><a href="#PlatformDependencies">Platform Dependencies</a></li> |
| |
| <li><a href="#ImportantNotes">Important Installation Notes</a></li> |
| |
| <li><a href="#HowToInstall">How to Build And Install ICU</a></li> |
| |
| <li><a href="#WhereToFindMore">Where To Find More Information</a></li> |
| |
| <li><a href="#SubmittingComments">Submitting Comments, Requesting |
| Features and Reporting Bugs</a></li> |
| </ul> |
| |
| <h2><a name="#news">Late Breaking News And What Is New?</a></h2> |
| |
| <ul> |
| <li><a href="#win32LibNames">Library names are changed and moved on Win32</a></li> |
| |
| <li><a href="#sharedLibNote">Using Shared Data Libraries</a></li> |
| |
| <li><a href="#ErrcodeChanges">Important Change Of Error Codes From |
| Streaming Conversion Functions</a> (change for ICU 1.6)</li> |
| |
| <li><a href="#collation">The collation implementation is being reworked</a></li> |
| |
| <li>We have improved or added support for country variants of ISO-2022, HZ, UTF-32, UTF-7, and GB 18030</li> |
| |
| <li><a href="#API_documentation">Updated API documentation</a></li> |
| |
| <li>For more news about this release, see the <a href="http://oss.software.ibm.com/icu/download/">online release notes</a>.</li> |
| </ul> |
| <hr> |
| |
| <h2><a name="introduction">Introduction</a></h2> |
| |
| <p>Today's software market is a global one in which it is desirable to |
| develop and maintain one application that supports a wide variety of |
| national languages. International Components for Unicode provides the |
| following tools to help you write language independent applications:</p> |
| |
| <ul type="disc"> |
| <li>UnicodeString supporting the Unicode 3.0 standard</li> |
| |
| <li>Resource bundles for storing and accessing localized |
| information</li> |
| |
| <li>Number formatters for converting binary numbers into text strings |
| for meaningful display</li> |
| |
| <li>Date and time formatters for converting internal time data into |
| text strings for meaningful display</li> |
| |
| <li>Message formatters for putting together sequences of strings, |
| numbers dates and other format to create messages</li> |
| |
| <li>Text collation supporting language sensitive comparison of |
| strings</li> |
| |
| <li>Text boundary analysis for finding characters, word and sentence |
| boundaries</li> |
| |
| <li>Changing simple data files rather than modifying program code |
| easily localizes applications written using these tools</li> |
| |
| <li>Over 160 locales supported. Visit the <a href= |
| "http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer"> |
| LocaleExplorer |
| (http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer)</a> |
| site for a demonstration and a full list of supported locales or see |
| the <a href= |
| "http://oss.software.ibm.com/cvs/icu/~checkout~/icu/data/index.txt">index |
| file with the supported locales</a>. Also see the <a href= |
| "http://oss.software.ibm.com/icu/userguide/">User Guide</a>.</li> |
| </ul> |
| |
| <p>It is possible to support additional locales by adding more locale |
| data files, with no code changes.</p> |
| |
| <p>Please refer to POSIX programmer's Guide for details on what the ISO |
| locale ID means.</p> |
| |
| <p>Your comments are important to making this release successful. We are |
| committed to fixing any bugs, and will also use your feedback to help |
| plan future releases.</p> |
| |
| <p><strong><u>IMPORTANT</u>: Please make sure you understand the <a href= |
| "license.html">Copyright and License information</a>.</strong></p> |
| |
| <p><br> |
| </p> |
| |
| <h2><a name="WhatContain">What the International Components for Unicode |
| Contain</a></h2> |
| |
| <p>There are two ways to download the ICU releases,</p> |
| |
| <ul type="disc"> |
| <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> |
| |
| If packaged snapshot is named <strong>ICUXXXXXX.zip</strong> or |
| <strong>ICUXXXXXX.tgz</strong> , XXXXXX is the release version |
| number.<br> |
| Please unzip this file. It will reconstruct the source directory, |
| including 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. There are several ways to do this:</li> |
| |
| <li style="list-style: none"> |
| <ul type="circle"> |
| <li>WebCVS:<br> |
| If you want to browse the code and only make occasional downloads, |
| you may want to use WebCVS. It provides a convenient, web-based |
| interface for browsing and downloading the latest version of the |
| ICU source code and documentation. You can also view each file's |
| revision history, display the differences between individual |
| revisions, determine which revisions were part of which official |
| release, and so on.</li> |
| |
| <li> |
| WinCVS:<br> |
| If you will be doing serious work on ICU, you should probably |
| install a CVS client on your own machine so that you can do batch |
| operations without going through the WebCVS interface. On |
| Windows, we suggest the WinCVS client. The following is the |
| example instruction on how to download ICU via WinCVS: |
| |
| <ol> |
| <li>Install the WinCVS client, which you can download from the |
| WinCVS home page.</li> |
| |
| <li>In the WinCVS preferences, specify your CVSRoot to be |
| ":pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu"<br> |
| with the password "anoncvs". To enter the CVSRoot value, |
| select "Preferences" from the "Cvs Admin" pull-down menu. |
| Authentication should be set to "'passwd' file on the cvs |
| server".</li> |
| |
| <li>To "extract" the most recent version of ICU, select |
| "Checkout module" from the "Cvs Admin" menu. Specify "icu" for |
| the module name.</li> |
| </ol> |
| </li> |
| |
| <li>CVS command line:<br> |
| You can also check out the repository anonymously on UNIX using |
| the following commands, after first setting your CVSROOT to point |
| to the ICU repository:<br> |
| <br> |
| <i>export |
| CVSROOT=:pserver:anoncvs@oss.software.ibm.com:/usr/cvs/icu<br> |
| cvs login CVS password: anoncvs<br> |
| cvs checkout icu<br> |
| cvs logout</i></li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>For more details on how to download ICU directly from the web site, |
| please also see <a href= |
| "http://oss.software.ibm.com/icu/download/">http:/oss.software.ibm.com/icu/download/</a></p> |
| |
| <p>Below, <strong>$Root</strong> is the placement of the icu directory in |
| your file system, like "drive:\...\icu" in your environment. "drive:\..." |
| stands for any drive and any directory on that drive that you chose to |
| install icu into.</p> |
| |
| <table border="1" cellpadding="0" width="100%" summary=""> |
| <caption align="left"> |
| <strong>The following files describe the code drop</strong> |
| </caption> |
| |
| <tr> |
| <td width="20%">readme.html</td> |
| |
| <td width="80%">Describes the International Components for Unicode |
| (this file)</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">license.html</td> |
| |
| <td width="80%">Contains IBM's public license</td> |
| </tr> |
| </table> |
| |
| <p><br> |
| </p> |
| |
| <table border="1" cellpadding="0" width="100%" summary=""> |
| <caption align="left"> |
| <strong>The following directories contain source code and data |
| files</strong> |
| </caption> |
| |
| <tr> |
| <td width="20%">$Root/source/common/</td> |
| |
| <td width="80%">The core Unicode and support functionality, such as |
| resource bundles, character properties, locales, codepage conversion, |
| and normalization.Unicode, Locale, UnicodeString.</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/i18n/</td> |
| |
| <td width="80%">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 width="20%">$Root/source/test/intltest/</td> |
| |
| <td width="80%">A test suite including all C++ APIs. For information |
| about running the test suite, see the users' guide.</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/test/cintltst/</td> |
| |
| <td width="80%">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 width="20%">$Root/data/</td> |
| |
| <td width="80%"> |
| This directory contains the source data in text format, which is |
| compiled into binary form during the ICU build process. The output |
| from these files is stored in $Root/source/data/build while |
| awaiting further packaging. |
| |
| <ul> |
| <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> |
| <p><b>Resource Bundle sources</b> .txt files containing 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. <b>resfiles.txt</b> contains the list of |
| resource bundle files.</p> |
| |
| <p>Also here are transliteration bundles, and the list of |
| installed transliteration files in |
| <b>translit_index.txt</b>.</p> |
| |
| <p>All resource bundles are compiled into .res files. The |
| <b>ucmfiles.txt</b> file contains the list of converter |
| files.</p> |
| </li> |
| |
| <li><b>Code page converter tables</b> .ucm files containing |
| mappings to and from Unicode. These are compiled into .cnv |
| files.</li> |
| |
| <li><b>convrtrs.txt</b> is the alias mapping table from various |
| converter name formats to ICU internal format and vice versa. It |
| produces cnvalias.dat.</li> |
| |
| <li><b>timezone.txt</b> is a generated file which is compiled |
| into tz.dat, containing time zone information.</li> |
| </ul> |
| </td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/data</td> |
| |
| <td width="80%">This directory is where the final, packaged version |
| of the ICU binary data ends up. If the ICU_DATA environment variable |
| is used, then it should be set to this directory. The intermediate |
| individual data files (.res, .cnv) are kept in the subdirectory |
| "$Root/source/data/build" prior to packaging.</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/tools</td> |
| |
| <td width="80%">Tools for generating the data files. Data files are |
| generated by invoking $Root/source/data/build/makedata.bat on Win32 |
| or $Root/source/make on unix.</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/samples</td> |
| |
| <td width="80%">Various sample programs that use ICU</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/extra</td> |
| |
| <td width="80%">Non-supported API additions. Currently, it contains |
| the 'ustdio' file i/o library</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/layout</td> |
| |
| <td width="80%">Contains the ICU layout engine (not a |
| rasterizer).</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/packaging<br> |
| $Root/debian</td> |
| |
| <td width="80%">These directories contain scripts and tools for |
| packaging the final ICU build for various release platforms.</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/config</td> |
| |
| <td width="80%">Contains helper makefiles for platform specific build |
| commands. Used by 'configure'.</td> |
| </tr> |
| |
| <tr> |
| <td width="20%">$Root/source/allinone</td> |
| |
| <td width="80%">Contains top-level ICU project files, for instance to |
| build all of ICU under one MSVC project.</td> |
| </tr> |
| </table> |
| |
| <p><br> |
| </p> |
| <!-- end of ICU structure ==================================== --> |
| |
| |
| <h2><a name="PlatformDependencies">Platform Dependencies</a></h2> |
| |
| <p>The platform dependencies have been mostly isolated into the following |
| files:</p> |
| |
| <ul type="disc"> |
| <li> |
| <u>platform.h.in</u>: (autoconf'ed platforms)<br> |
| <u>p<i>XXXX</i>.h</u> (others: pwin32.h, pos2.h, pmacos.h, ..): |
| Platform-dependent typedefs and defines:<br> |
| <br> |
| |
| <ul type="circle"> |
| <li>XP_CPLUSPLUS for C++ only.</li> |
| |
| <li>TRUE and FALSE, bool_t, int8_t, int16_t etc.</li> |
| |
| <li>U_EXPORT and U_IMPORT for specifying dynamic library import and |
| export</li> |
| </ul> |
| <br> |
| </li> |
| <li> |
| <u>putil.c:</u> platform-dependent implementations of various |
| functions that are platform dependent: (declared in putil.h)<br> |
| <br> |
| |
| |
| <ul type="circle"> |
| <li>icu_isNaN, icu_isInfinite(double), icu_getNaN(); |
| icu_getInfinity for handling special floating point values.</li> |
| |
| <li>icu_tzset, icu_timezone, icu_tzname and time for reading |
| platform specific time and timezone information.</li> |
| |
| <li>icu_getDefaultDataDirectory, icu_getDefaultLocaleID for reading |
| the locale setting and data directory.</li> |
| |
| <li>icu_isBigEndian for finding the endianess of the platform.</li> |
| |
| <li>icu_nextDouble is used specifically by the ChoiceFormat |
| API.</li> |
| </ul> |
| <br> |
| </li> |
| <li> |
| <u>umutex.h and umutex.c</u>: 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 type="circle"> |
| <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> |
| <u>udata.h</u> and <u>udata.c</u>: The data-accessing interface in |
| ICU is implemented such that there is a lot of flexibility for |
| reading a data file. Each platform can tune the performance of file |
| accessing for its environment by choosing to implement one of the |
| following options:<br> |
| <br> |
| |
| |
| <ul type="circle"> |
| <li>DLL</li> |
| |
| <li>Memory map</li> |
| |
| <li>Plain text</li> |
| </ul> |
| <br> |
| </li> |
| |
| <li>If you are changing the platform-dependent files, utypes.h and |
| putil.h may also be interesting, but they shouldn't have to be changed. |
| If you think any other files than the ones mentioned above have |
| platform dependencies, please contact us.</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> |
| |
| </ul> |
| |
| <h2><a name="ImportantNotes">Important Installation Notes</a></h2> |
| |
| <h3><a name="ImportantNotesWin32">Win32 Platform</a></h3> |
| |
| <hr> |
| <h3><a name="win32LibNames">BREAKING NEWS: Library names are changed and libraries are moved on Win32</a></h3> |
| |
| <p>As it was previously mentioned and proposed on <a href="http://oss.software.ibm.com/icu/archives/icu/icu.0009/msg00138.html">ICU list</a>, |
| ICU libraries on Win32 are now renamed and relocated. The following changes took place in ICU 1.7:</p> |
| |
| <ol> |
| <li>in icu\lib: |
| <ul> |
| <li>Debug\icuuc.lib -> icuucd.lib</li> |
| <li>Release\icuuc.lib -> icuuc.lib</li> |
| <li>Debug\icui18n.lib -> icuind.lib</li> |
| <li>Release\icui18n.lib -> icuin.lib</li> |
| <li>Debug\ustdio.lib -> icuiod.lib</li> |
| <li>Release\ustdio.lib -> icuio.lib</li> |
| </ul> |
| </li> |
| <li>in icu\bin: |
| <ul> |
| <li>Debug\icuuc.dll -> icuuc17d.dll</li> |
| <li>Release\icuuc.dll -> icuuc17.dll</li> |
| <li>Debug\icui18n.dll -> icuin17d.dll</li> |
| <li>Release\icui18n.dll -> icuin17.dll</li> |
| <li>Debug\ustdio.dll -> icuio17d.dll</li> |
| <li>Release\ustdio.dll -> icuio17.dll</li> |
| </ul> |
| </li> |
| </ol> |
| |
| <p>Also, ctestfw and ex toolutil (now icutu17) libraries appeared in |
| icu\bin and icu\lib dirs, but this shouldn't concern regular users of |
| ICU.</p> |
| |
| <h4>What to do, and how to cope?</h4> |
| |
| <p>When you first try to compile your programs with new version of icu, |
| compilation will fail. The following steps are required:</p> |
| |
| <ol> |
| <li>Change your path from ...\icu\bin\debug or ...\icu\bin\release to |
| just ...\icu\bin</li> |
| |
| <li>Make the same change for MSVC executable directory setting |
| (tools->options->directories)</li> |
| |
| <li>In all your .dsp files (project settings), on linker tab change |
| input libraries according to the above scheme. You want to do it for |
| both debug and release versions.</li> |
| </ol> |
| |
| <p>When a new, binary incompatible version appears after 1.7, the |
| libraries will change the version number. Make sure that you reference |
| the correct version independent *.lib file when you have more than one |
| version of ICU built on your machine. Each *.lib file references its |
| correct version dependent shared library. The libraries with debug |
| information contain a "d" on the end of the base DLL name (e.g. icuuc.lib |
| vs. icuucd.lib).</p> |
| |
| <hr> |
| |
| <p>If you are building on the Win32 platform, it is important that you |
| understand a few build details:</p> |
| |
| <p><u>DLL directories and the PATH setting:</u> As delivered, the |
| International Components for Unicode build as several DLLs. These DLLs |
| are placed in the "icu\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> |
| |
| <p><u>To change your PATH:</u></p> |
| |
| <ul type="disk"> |
| <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 |
| ";$Root\bin" to the end of the path string. If there is nothing there, |
| just type in "$Root\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 ";$Root\bin" at the |
| end of the path string. If there is nothing there, just type in |
| "$Root\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%;$Root\bin"</li> |
| </ul> |
| |
| <p><u>Link with Runtime libraries:</u> All the DLLs link with the C |
| runtime library "Debug Multithreaded DLL" or "Multithreaded DLL." (This |
| is changed through the Project Settings dialog, on the C/C++ tab, under |
| Code Generation.) It is important that any executable or other DLL you |
| build which uses the International Components for Unicode DLLs links with |
| these runtime libraries as well. If you do not do this, you will |
| seemingly get memory errors when you run the executable.<br> |
| </p> |
| |
| <h3><a name="collation">Collation Improvements</a></h3> |
| <p>We are reimplementing the collation implementation to make it faster |
| (much of this is done with ICU 1.7), to comply with the Unicode Collation Algorithm |
| (ICU 1.8), and also to make the locale-specific collation data smaller |
| (by separating it from the shared UCA data, also for ICU 1.8).<br> |
| <em>This means that sort keys and even some collation results are changing from ICU 1.6 |
| and will change again for ICU 1.8.</em><br> |
| For details, see our <a href="http://oss.software.ibm.com/icu/develop/collation/">collation design document</a>.</p> |
| |
| <h3><a name="API_documentation">API documentation</a></h3> |
| |
| <p>We are updating our API documentation, generated JavaDoc-style from |
| the public header files. It is available for <a href= |
| "http://oss.software.ibm.com/icu/apiref/">online browsing</a> as well as |
| <a href="http://oss.software.ibm.com/icu/download/">for download from the |
| release folder</a>.</p> |
| |
| <p>Also, as a more general and comprehensive documentation, we are |
| working on improving the <a href= |
| "http://oss.software.ibm.com/icu/userguide/">ICU User Guide</a>.</p> |
| |
| <h3><a name="ImportantNotesOS390">OS/390 Platform</a></h3> |
| |
| <p>If you are building on the OS/390 UNIX System Services platform, it is |
| important that you understand a few details:</p> |
| |
| <ul> |
| <li>The gnu utilities gmake and gzip/gunzip are needed and can be |
| obtained for OS/390 from <a href= |
| "http://www.mks.com/">http://www.mks.com/</a>. Search for OS/390, |
| register, and follow download directions.</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. Those files are: |
| |
| <ul> |
| <li>All the .brk files located in the icu/data directory |
| (icu/data/*.brk)</li> |
| |
| <li>icu/source/test/testdata/uni-text.txt</li> |
| |
| <li>icu/source/test/testdata/th18057.txt</li> |
| </ul> |
| Such a conversion can be done using iconv:<br> |
| <code>iconv -f IBM-1047 -t ISO8859-1 uni-text.txt > |
| uni-text.txt</code> |
| </li> |
| |
| <li> |
| DLL directories and the LIBPATH setting: Building and testing ICU |
| needs the ICU libraries on the LIBPATH. In other words, the LIBPATH |
| should contain (each path prepended with the root directory that |
| contains the icu directory): |
| |
| <ul> |
| <li>icu/source/common</li> |
| <li>icu/source/i18n</li> |
| <li>icu/source/tools/ctestfw</li> |
| <li>icu/source/tools/toolutil</li> |
| <li>icu/source/extra/ustdio</li> |
| </ul> |
| </li> |
| |
| <li> |
| <p>OS/390 supports both native S/390 hexadecimal floating point and, |
| (with Version 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 OS/390 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 ./configure</code><br> |
| Release build: <code>CFLAGS=-2 IEEE390=1 ./configure</code></p> |
| </li> |
| |
| <li>Since the default make on OS/390 is not gmake, pkgdata tool |
| requires that the environment variable MAKE be set to fully |
| qualified path to gmake.</li> |
| |
| <li>The makedep executable that is used with the OS/390 ICU build |
| process is not shipped with ICU. It is available at the <a href= |
| "http://www.s390.ibm.com/products/oe/bpxa1ty2.html">OS/390 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>To run all of the tests for ICU, use "gmake check". When running |
| individual tests of the test suite, the TZ environment |
| variable should be set to export TZ="PST8PDT" so that time zone |
| comparisons are correct.</li> |
| </ul> |
| |
| <h4><a name="ImportantNotesOS390Batch">OS/390 Batch (PDS) |
| support</a></h4> |
| |
| <p>By default, ICU builds its libraries into the HFS. However, there is a |
| 390-specific switch to build some libraries into PDS files. The switch is |
| the environmental variable OS390BATCH, and if set, the following |
| libraries are built into PDS files: libicuuc<i>XX</i>.dll, |
| libicudt<i>XX</i>e.dll, libicudt<i>XX</i>e_390.dll, and libtestdata.dll. |
| Turning on OS390BATCH does not turn off the normal HFS build, thus the |
| HFS dlls will always be created.</p> |
| |
| <p>The names of the PDS files are determined by the value of the |
| environmental variables LOADMOD and LOADEXP. These variables must contain |
| the target PDS names whenever the OS390BATCH variable is set. LOADMOD is |
| the library (.dll) target dataset and LOADEXP is the side deck (.x) |
| target dataset.</p> |
| |
| <p>The PDS member names are as follows:</p> |
| <pre> |
| IXMICUUC --> libicuuc<i>XX</i>.dll |
| IXMICUDA --> libicudt<i>XX</i>e.dll |
| IXMICUD1 --> libicudt<i>XX</i>e_390.dll |
| IXMICUTE --> libtestdata.dll |
| </pre> |
| <p>Example PDS attributes are as follows:</p> |
| <pre> |
| Data Set Name . . . : <i>USER</i>.ICU.LOAD |
| General Data |
| Management class. . : **None** |
| Storage class . . . : BASE |
| Volume serial . . . : TSO007 |
| Device type . . . . : 3390 |
| Data class. . . . . : LOAD |
| Organization . . . : PO |
| Record format . . . : U |
| Record length . . . : 0 |
| Block size . . . . : 32760 |
| 1st extent cylinders: 40 |
| Secondary cylinders : 59 |
| Data set name type : PDS |
| |
| Data Set Name . . . : <i>USER</i>.ICU.EXP |
| General Data |
| Management class. . : **None** |
| Storage class . . . : BASE |
| Volume serial . . . : TSO007 |
| Device type . . . . : 3390 |
| Data class. . . . . : **None** |
| Organization . . . : PO |
| Record format . . . : FB |
| Record length . . . : 80 |
| Block size . . . . : 3200 |
| 1st extent cylinders: 3 |
| Secondary cylinders : 3 |
| Data set name type : PDS |
| </pre> |
| |
| <h3><a name="ImportantNotesOS400">OS/400 Platform</a></h3> |
| |
| <p>ICU Reference Release 1.4.0 contains partial support for the 400 |
| platform, but additional work by the user is currently needed to get it |
| to build completely. A future release of ICU should work |
| out-of-the-box under OS/400.</p> |
| |
| <ul> |
| <li> |
| Requirements: |
| |
| <ul> |
| <li>QSHELL interpreter installed (install base option 30, operating |
| system)</li> |
| |
| <li>QShell Utilities, PRPQ 5799-XEH</li> |
| |
| <li>ILE C++ for AS/400, PRPQ 5799-GDW</li> |
| |
| <li>GNU facilities (You can get the GNU facilities for OS/400 from <a href= |
| "http://www.as400.ibm.com/developer/porting/gnu_utilities.html">http://www.as400.ibm.com/developer/porting/gnu_utilities.html</a>).</li> |
| </ul> |
| <!-- end requirements --> |
| </li> |
| |
| <li> |
| Build environment setup: |
| |
| <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> |
| <div style="margin-left: 2em">CRTLIB LIB(<i>libraryname</i>)</div><br> |
| </li> |
| |
| <li> |
| Set up the following environment variables in your build process |
| (use the <i>libraryname</i> from the previous step) |
| |
| <div style="margin-left: 2em"> |
| ADDENVVAR ENVVAR(ICU_DATA) VALUE('/icu/source/data')<br> |
| ADDENVVAR ENVVAR(CC) VALUE('/usr/bin/icc')<br> |
| ADDENVVAR ENVVAR(CXX) VALUE('/usr/bin/icc')<br> |
| ADDENVVAR ENVVAR(MAKE) VALUE('/usr/bin/gmake')<br> |
| ADDENVVAR ENVVAR(OUTPUTDIR) VALUE('<i>libraryname</i>') |
| <i>identifies target as400 library for *module, *pgm and |
| *srvpgm objects</i> |
| </div> |
| <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>For timezones to work correctly, the QUTCOFFSET |
| needs to be set to the proper UTC(Coordinated univeral time) offset.<br> |
| <br> |
| To check your QUTCOFFSET: |
| <div style="margin-left: 2em"> |
| DSPSYSVAL SYSVAL(QUTCOFFSET) |
| </div> |
| <br> |
| To change your QUTCOFFSET:<br> |
| <div style="margin-left: 2em"> |
| CHGSYSVAL SYSVAL(QUTCOFFSET) VALUE('<i>+/-hh:mm</i>') |
| </div> |
| <br> |
| <i>The +/- represents either + or - from UTC. The "hh" represents |
| the number of hours from UTC, and "mm" represents the minutes |
| from UTC.</i><br> |
| <br> |
| </li> |
| |
| <li>Run 'QSH'</li> |
| |
| <li> |
| Configure the Makefiles (see configure below) |
| <strong>Note:</strong> Verify that the mh-os400 configure file is |
| used. |
| |
| <ul> |
| <li>Run 'configure --host=as400-os400'</li> |
| |
| <li>The 'clean' and 'install' targets will not work without |
| changes because of symbolic links. To delete the target module, |
| program, or service programs replace <tt>rm -rf</tt> with |
| <strong>$(RMV)</strong>, and in the library installation |
| targets (install-library) change <tt>$(INSTALL)</tt> to |
| <strong><tt>$(INSTALL-S)</tt></strong>.</li> |
| </ul> |
| </li> |
| |
| <li>Run 'gmake -e'. The '-e' option is needed to pickup the |
| compilers.</li> |
| |
| <li>Run 'gmake -e check' to run the tests.</li> |
| </ol> |
| <!-- end build environment --> |
| </li> |
| </ul> |
| |
| <h2><a name="HowToInstall">How To Build And Install ICU</a></h2> |
| |
| <h3><a name="HowToInstallWindows">How To Build And Install On |
| Windows</a></h3> |
| |
| <p>Building International Components for Unicode requires:</p> |
| |
| <ul type="disc"> |
| <li>Microsoft NT 3.51 or 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>The steps are:</p> |
| |
| <ol start="1" type="1"> |
| <li>Unzip the icu-XXXX.zip file, type "unzip -a icu-XXXX.zip -d |
| drive:\directory" under command prompt or use WinZip. |
| drive:\directory\icu is the root ($Root) directory (you may but don't |
| need to place "icu" into another directory). If you change the root, |
| you will change the project settings accordingly in EACH makefile in |
| the project, updating the "include" and "library" paths.</li> |
| |
| <li>Set the environment variable <strong>ICU_DATA</strong> to the full |
| pathname of the data directory. The trailing "\" is required after the |
| directory name (e.g. "$Root\source\data\" will work, but the value |
| "$Root\source\data" is not acceptable). This environment variable |
| indicates where the locale data files and conversion mapping tables are |
| located.</li> |
| |
| <li>Be sure that the ICU binary directory, $Root\bin\, |
| is included in the <strong>PATH</strong> environment variable. The |
| tests may not work without the 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 |
| timezone.</li> |
| |
| <li>Use Microsoft Visual C++ 6.0 to open the |
| "$Root\source\allinone\allinone.dsw" workspace (This workspace includes |
| all the International Components for Unicode libraries, necessary ICU |
| building tools, and the intltest and cintltest test suite |
| projects).</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 note below).</li> |
| |
| <li>Choose the "Build" menu and select "Rebuild All". 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 test programs as well as the |
| tools for generating binary locale data files. The "makedata" project |
| will be run automatically to convert the locale data files from text |
| format into icudata.dll.</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.</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.</li> |
| </ol> |
| |
| <p><strong>Note:</strong> To set the active configuration, two different |
| possibilities are:</p> |
| |
| <ul type="disc"> |
| <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>It is also possible to build each library individually, using the |
| workspaces in each respective directory. They have to be built in the |
| following order:<br> |
| </p> |
| |
| <ol start="1" type="1"> |
| <li>common</li> |
| |
| <li>i18n</li> |
| |
| <li>makedata (which invokes makeconv, genrb, genccode, etc.)</li> |
| |
| <li>ctestfw</li> |
| |
| <li>intltest and cintltst, if you want to run the test suite.</li> |
| </ol> |
| |
| <h3><a name="HowToInstallUnix">How To Build And Install On Unix</a></h3> |
| |
| <p>There is a set of Makefiles for Unix that supports Linux w/gcc, |
| Solaris w/gcc and Workshop CC, AIX w/xlc and OS/390 with C++.</p> |
| |
| <p>Building International Components for Unicode on Unix requires:</p> |
| |
| <p>A UNIX C++ compiler, (gcc, cc, xlc_r, etc...) installed on the target |
| machine. A recent version of GNU make (3.7+). OS/390 gnu utilities for |
| both make (gmake) and zip (gzip/gunzip) can be found at the MKS web site |
| at <a href="http://www.mks.com">http://www.mks.com</a>. Please do a |
| search on "os/390".</p> |
| |
| <p>The steps are:</p> |
| |
| <ol start="1" type="1"> |
| <li>Decompress the icuXXXX.tar (or icuXXXX.tgz) file and use pax.</li> |
| |
| <li>Before running the test programs or samples, please set the |
| environment variable <strong>ICU_DATA</strong>, the full pathname of |
| the data directory, to indicate where the locale data files and |
| conversion mapping tables are. If this variable is not set, the default |
| user data directory will be used. The trailing "/" is required after |
| the directory name (e.g. "$Root/source/data/" will work, but the value |
| "$Root/source/data" is not acceptable). When you are running individual |
| tests, the <strong>TZ</strong> environment variable needs to be set to |
| <strong>PST8PDT</strong>. Normally "make check" does this for you |
| automatically.</li> |
| |
| <li>Change directory to the "icu/source".</li> |
| |
| <li>If it is not already set, please set the executable flag for the |
| following files (by executing 'chmod +x' command): runConfigureICU, |
| configure, install-sh and config.*,</li> |
| |
| <li>You also need to set other environment variables for different |
| build systems. See the <a href= |
| "http://oss.software.ibm.com/icu/userguide/">User Guide</a> or the |
| provided <a href="source/runConfigureICU">script</a>.</li> |
| |
| <li>Type "./configure" or type "./configure --help" to print the |
| available options.</li> |
| |
| <li>Type "make" to compile the libraries and all the data files. On |
| OS/390, both IEEE binary floating point and native S/390 hexadecimal |
| floating point calculations are supported. The default is to build with |
| native floating-point support. Please set the environment variable |
| IEEE390=1 if you would like to make the ICU DLLs with IEEE floating |
| point support.</li> |
| |
| <li>Optionally, type "make check" to verify the test suite.</li> |
| |
| <li>Type "make install" to install.</li> |
| </ol> |
| |
| <p>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> |
| |
| <p>It is also possible to build each library individually, using the |
| Makefiles in each respective directory. They have to be built in the |
| following order:</p> |
| |
| <ol start="1" type="1"> |
| <li>common</li> |
| |
| <li>i18n</li> |
| |
| <li>makeconv</li> |
| |
| <li>genrb</li> |
| |
| <li>gentz</li> |
| |
| <li>genccode</li> |
| |
| <li>ctestfw</li> |
| |
| <li>intltest and cintltst, if you want to run the test suite.</li> |
| </ol> |
| |
| <h3><a name="sharedLibNote">Using Shared Data Libraries</a></h3> |
| |
| <p>HP/UX has a documented characteristic where the shl_unload() function |
| always unloads a library, regardless of how many times the library has |
| been loaded. Most operating systems reference count libraries as they are |
| opened. In the future (Jitterbug 414) this may be corrected in ICU, but |
| at present, we work around this problem by simply NOT ever unloading |
| shared libraries. This means that once a data library is loaded (ex: |
| libicudata.sl) by a process, it cannot be unloaded and replaced without |
| stopping and restarting the process.</p> |
| |
| |
| <h3><a name="ErrcodeChanges">Important Change Of Error Codes From |
| Streaming Conversion Functions (change for ICU 1.6)</a></h3> |
| |
| <p>We have decided to make a semantic change to the conversion API which |
| affects applications using ICU that are migrated to use ICU versions 1.6 |
| or later compared to earlier ICU versions before 1.6:<br> |
| The error code that is set from streaming conversion like</p> |
| <pre> |
| ucnv_fromUnicode() - ucnv_toUnicode() |
| ucnv_fromUChars() - ucnv_toUChars() |
| scsu_compress() - scsu_decompress() |
| </pre> |
| when the target buffer is full but the source not empty is changed from |
| <code>U_INDEX_OUTOFBOUNDS_ERROR</code> to |
| <code>U_BUFFER_OVERFLOW_ERROR</code>. This change makes the error codes |
| more consistent with their names and with their use in other icu |
| APIs.<br> |
| <br> |
| |
| |
| <p>You need to test for this new error code if your code uses ICU for |
| conversion and used the old error code. ucnv.h and scsu.h are updated |
| with this information. Please search in your source code for |
| <code>U_INDEX_OUTOFBOUNDS_ERROR</code>. If it is used with the above |
| functions (<em>not</em> with <code>ucnv_getNextUChar()</code>), then you |
| need to change it to <code>U_BUFFER_OVERFLOW_ERROR</code> in order to get |
| your code to work with icu 1.6 or later.</p> |
| |
| <p>See the updated sample code in <code>icu/source/samples</code>. All |
| samples are updated. See <a href= |
| "http://oss.software.ibm.com/developerworks/opensource/icu/bugs?findid=516"> |
| jitterbug 516</a> for details. This was discussed in July 2000 on the icu |
| mailing list. Please see the list archive for the <a href= |
| "http://oss.software.ibm.com/icu/archives/icu/icu.0007/msg00142.html">discussion</a>.</p> |
| |
| <h2><a name="WhereToFindMore">Where To Find More Information</a></h2> |
| |
| <p><a href= |
| "http://oss.software.ibm.com/icu/">http://oss.software.ibm.com/icu/</a> |
| is the homepage of the International Components for Unicode.</p> |
| |
| <p>The API Documentation is available <a href= |
| "http://oss.software.ibm.com/icu/apiref/">online</a> or <a href= |
| "http://oss.software.ibm.com/icu/download/">for download</a>. The (draft |
| of) the User Guide is available for <a href= |
| "http://oss.software.ibm.com/icu/userguide/">browsing and as a PDF |
| file</a>.</p> |
| |
| <p><a href= |
| "http://www.ibm.com/developer/unicode/">http://www.ibm.com/developer/unicode/</a> |
| is a pointer to information on how to make applications global.</p> |
| |
| |
| <h2><a name="SubmittingComments">Submitting Comments, Requesting Features |
| and Reporting Bugs</a></h2> |
| |
| <p>To submit comments, request features and report bugs, please contact |
| us. The best forum is the ICU mailing list. See the <a href= |
| "http://oss.software.ibm.com/icu/archives/">information on how to browse |
| and join the list</a>. If you find a bug in the code that has not been |
| submitted and/or fixed yet, then please <a href= |
| "http://oss.software.ibm.com/developerworks/opensource/icu/bugs">submit a |
| jitterbug</a>.</p> |
| |
| <hr> |
| |
| <p>Copyright © 1997-2001 International Business Machines Corporation |
| and others. All Rights Reserved.<br> |
| IBM Center for Emerging Technologies Silicon Valley,<br> |
| 10275 N De Anza Blvd., Cupertino, CA 95014<br> |
| All rights reserved.</p> |
| </body> |
| </html> |
