                 International Components for Unicode
                            ICU 4.0 ReadMe

   Version: 2008 June 28th
   Copyright © 1997-2008 International Business Machines Corporation
   and others. All Rights Reserved.
     _________________________________________________________

Table of Contents

     * [1]Introduction
     * [2]Getting Started
     * [3]What Is New In This release?
     * [4]How To Download the Source Code
     * [5]ICU Source Code Organization
     * [6]How To Build And Install ICU
          + [7]Supported Platforms
          + [8]Windows
          + [9]Cygwin
          + [10]UNIX
          + [11]z/OS (os/390)
          + [12]IBM i family (IBM i, i5/OS, OS/400)
     * [13]How To Package ICU
     * [14]Important Notes About Using ICU
          + [15]Using ICU in a Multithreaded Environment
          + [16]Windows Platform
          + [17]UNIX Type Platforms
     * [18]Platform Dependencies
          + [19]Porting To A New Platform
          + [20]Platform Dependent Implementations
     _________________________________________________________

[21]Introduction

   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:
     * The latest version of the Unicode standard
     * Character set conversions with support for over 220 codepages
     * Locale data for more than 250 locales
     * Language sensitive text collation (sorting) and searching based
       on the Unicode Collation Algorithm (=ISO 14651)
     * Regular expression matching and Unicode sets
     * Transformations for normalization, upper/lowercase, script
       transliterations (50+ pairs)
     * Resource bundles for storing and accessing localized information
     * Date/Number/Message formatting and parsing of culture specific
       input/output formats
     * Calendar specific date and time manipulation
     * Complex text layout for Arabic, Hebrew, Indic and Thai
     * Text boundary analysis for finding characters, word and sentence
       boundaries

   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.

[22]Getting started

   This document describes how to build and install ICU on your
   machine. For other information about ICU please see the following
   table of links.
   The ICU homepage also links to related information about writing
   internationalized software.

   CAPTION: Here are some useful links regarding ICU and
   internationalization in general.

   ICU, ICU4C & ICU4J Homepage [23]http://www.icu-project.org/
   FAQ - Frequently Asked Questions about ICU
   [24]http://www.icu-project.org/userguide/icufaq.html
   ICU User's Guide [25]http://www.icu-project.org/userguide/
   Download ICU Releases [26]http://www.icu-project.org/download/
   ICU4C API Documentation Online
   [27]http://www.icu-project.org/apiref/icu4c/
   Online ICU Demos [28]http://demo.icu-project.org/icu-bin/icudemos
   Contacts and Bug Reports/Feature Requests
   [29]http://www.icu-project.org/contacts.html

     [23] http://www.icu-project.org/
     [24] http://www.icu-project.org/userguide/icufaq.html
     [25] http://www.icu-project.org/userguide/
     [26] http://www.icu-project.org/download/
     [27] http://www.icu-project.org/apiref/icu4c/
     [28] http://demo.icu-project.org/icu-bin/icudemos
     [29] http://www.icu-project.org/contacts.html

   Important: Please make sure you understand the [30]Copyright and
   License Information.

     [30] http://source.icu-project.org/repos/icu/icu/trunk/license.html

[31]What is new in this release?

   To see which APIs are new or changed in this release, view the
   [32]ICU4C API Change Report.

     [32] http://source.icu-project.org/repos/icu/icu/trunk/APIChangeReport.html

   For more news about this release, see the [33]ICU 4.0 download page.

     [33] http://www.icu-project.org/download/

[34]How To Download the Source Code

   There are two ways to download ICU releases:
     * Official Release Snapshot:
       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 [35]http://www.icu-project.org/download/.
       The packaged snapshots are named icu-nnnn.zip or icu-nnnn.tgz,
       where nnnn is the version number. The .zip file is used for
       Windows platforms, while the .tgz file is preferred on most
       other platforms.
       Please unzip this file.
     * Subversion Source Repository:
       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 Subversion repository to ensure that you have the
       most recent version of all of the files. See our [36]source
       repository for details.

     [35] http://www.icu-project.org/download/
     [36] http://www.icu-project.org/repository/

[37]ICU Source Code Organization

   In the descriptions below, <ICU> 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 [38]ICU Architectural
   Design section of the User's Guide to see which libraries you need
   for your software product. You need at least the data ([lib]icudt)
   and the common ([lib]icuuc) libraries in order to use ICU.

     [38] http://www.icu-project.org/userguide/design.html

   CAPTION: The following files describe the code drop.

   File Description
   readme.html Describes the International Components for Unicode (this
   file)
   license.html Contains the text of the ICU license

   CAPTION: The following directories contain source code and data
   files.

   Directory Description
   <ICU>/source/common/ The core Unicode and support functionality,
   such as resource bundles, character properties, locales, codepage
   conversion, normalization, Unicode properties, Locale, and
   UnicodeString.
   <ICU>/source/i18n/ 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.
   <ICU>/source/layout/ Contains the ICU layout engine (not a
   rasterizer).
   <ICU>/source/io/ Contains the ICU I/O library.
   <ICU>/source/data/

   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.

   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 [39]subversion.
     * in/ 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.
     * brkitr/ Data files for character, word, sentence, title casing
       and line boundary analysis.
     * locales/ These .txt files contain ICU language and
       culture-specific localization data. Two special bundles are
       root, which is the fallback data and parent of other bundles,
       and index, which contains a list of installed bundles. The
       makefile resfiles.mk contains the list of resource bundle files.
     * mappings/ Here are the code page converter tables. These .ucm
       files contain mappings to and from Unicode. These are compiled
       into .cnv files. convrtrs.txt is the alias mapping table from
       various converter name formats to ICU internal format and vice
       versa. It produces cnvalias.icu. The makefiles ucmfiles.mk,
       ucmcore.mk, and ucmebcdic.mk contain the list of converters to
       be built.
     * translit/ This directory contains transliterator rules as
       resource bundles, a makefile trnsfiles.mk containing the list of
       installed system translitaration files, and as well the special
       bundle translit_index which lists the system transliterator
       aliases.
     * unidata/ This directory contains the Unicode data files. Please
       see [40]http://www.unicode.org/ for more information.
     * misc/ 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 [41]IDNA.
     * out/ This directory contains the assembled memory mapped files.
     * out/build/ This directory contains intermediate (compiled)
       files, such as .cnv, .res, etc.

     [39] http://www.icu-project.org/repository/
     [40] http://www.unicode.org/
     [41] http://www.ietf.org/rfc/rfc3490.txt

   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 [42]ICU Data Management section of the
   ICU User's Guide for details.
   <ICU>/source/test/intltest/ 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.
   <ICU>/source/test/cintltst/ 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.
   <ICU>/source/test/iotest/ 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.
   <ICU>/source/test/testdata/ Source text files for data, which are
   read by the tests. It contains the subdirectories out/build/ which
   is used for intermediate files, and out/ which contains
   testdata.dat.
   <ICU>/source/tools/ Tools for generating the data files. Data files
   are generated by invoking <ICU>/source/data/build/makedata.bat on
   Win32 or <ICU>/source/make on UNIX.
   <ICU>/source/samples/ Various sample programs that use ICU
   <ICU>/source/extra/ Non-supported API additions. Currently, it
   contains the 'uconv' tool to perform codepage conversion on files.
   <ICU>/packaging/ This directory contain scripts and tools for
   packaging the final ICU build for various release platforms.
   <ICU>/source/config/ Contains helper makefiles for platform specific
   build commands. Used by 'configure'.
   <ICU>/source/allinone/ Contains top-level ICU workspace and project
   files, for instance to build all of ICU under one MSVC project.
   <ICU>/include/ Contains the headers needed for developing software
   that uses ICU on Windows.
   <ICU>/lib/ Contains the import libraries for linking ICU into your
   Windows application.
   <ICU>/bin/ Contains the libraries and executables for using ICU on
   Windows.

     [42] http://www.icu-project.org/userguide/icudata.html

[43]How To Build And Install ICU

  [44]Supported Platforms

   CAPTION: Here is a status of functionality of ICU on several
   different platforms.

   Operating system Compiler Testing frequency
   Windows Vista SP1 (32 bit) Microsoft Visual C++ 2005 (8.0) Reference
   platform
   Windows Server 2003 (64 bit) Microsoft Visual C++ 2005 (8.0)
   Reference platform
   Red Hat Enterprise Linux 5 (x86, 32 bit) gcc 4.1.2 Reference
   platform
   AIX 6.1 (Power, 64-bit) IBM VisualAge 9 Reference platform
   Solaris 10 (Sparc, 32-bit, SunOS 5.10) Sun Studio 12 Reference
   platform
   HP-UX IIiv3 (Itanium, 64-bit) aCC A.6.14 Reference platform
   AIX 5.3 IBM XL C/C++ 8.0 Regularly tested
   Windows XP Microsoft Visual C++ 2005 (8.0) Regularly tested
   Red Hat Enterprise Linux 4 Update 4 gcc 3.4.4 Regularly tested
   AIX 5.2 Visual Age C++ 6.0 Regularly tested
   Solaris 9 (SunOS 5.9) Sun Studio 8 (Sun C++ 5.5) Regularly tested
   HP-UX 11.11 (PA-RISC) aCC A.03.50
   cc B.11.11.08 Regularly tested
   Windows 2000 with Cygwin Microsoft Visual C++ 2003 (7.1) Regularly
   tested
   Windows Server 2008 x64 Microsoft Visual C++ 2005 (8.0) Regularly
   tested
   Mac OS X (10.4) gcc 4.0.1 Regularly tested
   Solaris 10 gcc 4.0.3 Regularly tested
   SUSE Linux Enterprise Server 9 SP1 Intel C++ Compiler 9.0 Regularly
   tested
   z/OS 1.7 cxx 1.7 Rarely tested
   Cygwin gcc 3.4.4 Rarely tested
   IBM i family (IBM i, i5/OS, OS/400) iCC Rarely tested
   Windows Vista x64 Microsoft Visual C++ 2005 (8.0) Rarely tested
   MinGW gcc Rarely tested
   NetBSD, OpenBSD, FreeBSD gcc Rarely tested
   SUSE Linux Enterprise Server 9 (PowerPC) IBM XL C/C++ 8.0 Rarely
   tested
   QNX gcc Rarely tested
   BeOS gcc Rarely tested
   SGI/IRIX MIPSpro CC Rarely tested
   Tru64 (OSF) Compaq's cxx compiler Rarely tested
   MP-RAS NCR MP-RAS C/C++ Compiler Rarely tested

    Key to testing frequency

   Reference platform
          ICU will work on these platforms with these compilers

   Regularly tested
          ICU should work on these platforms with these compilers

   Rarely tested
          ICU has been ported to these platforms but may not have been
          tested there recently

  [45]How To Build And Install On Windows

   Building International Components for Unicode requires:
     * Microsoft Windows 2000 or above
     * Microsoft Visual C++ 2005
     * [46]Cygwin is required when other versions of Microsoft Visual
       C++ and other compilers are used to build ICU.

   The steps are:
    1. 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.
    2. Be sure that the ICU binary directory, <ICU>\bin\, is included
       in the PATH environment variable. The tests will not work
       without the location of the ICU DLL files in the path.
    3. Open the "<ICU>\source\allinone\allinone.sln" workspace file in
       Microsoft Visual Studio 2003. (This solution includes all the
       International Components for Unicode libraries, necessary ICU
       building tools, and the test suite projects). Please see the
       [47]command line note below if you want to build from the
       command line instead.
    4. Set the active platform to "Win32" or "x64" (See [48]Windows
       platform note below) and configuration to "Debug" or "Release"
       (See [49]Windows configuration note below).
    5. Choose the "Build" menu and select "Rebuild Solution". If you
       want to build the Debug and Release at the same time, see the
       [50]batch configuration note below.
    6. 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.
    7. 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.
    8. 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.
    9. You are now able to develop applications with ICU by using the
       libraries and tools in <ICU>\bin\. The headers are in
       <ICU>\include\ and the link libraries are in <ICU>\lib\. To
       install the ICU runtime on a machine, or ship it with your
       application, copy the needed components from <ICU>\bin\ to a
       location on the system PATH or to your application directory.

   Using MSDEV At The Command Line Note: 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 <ICU>\source\allinone\allinone.sln
   /build "Win32|Release"'. You can also use Cygwin with this compiler
   to build ICU, and you can refer to the [51]How To Build And Install
   On Windows with Cygwin section for more details.

   Setting Active Platform Note: Even though you are able to select
   "x64" as the active platform, if your operating system is not a 64
   bit version of Windows, the build will fail. To set the active
   platform, two different possibilities are:
     * Choose "Build" menu, select "Configuration Manager...", and
       select "Win32" or "x64" for the Active Platform Solution.
     * Another way is to select the desired build configuration from
       "Solution Platforms" dropdown menu from the standard toolbar. It
       will say "Win32" or "x64" in the dropdown list.

   Setting Active Configuration Note: To set the active configuration,
   two different possibilities are:
     * Choose "Build" menu, select "Configuration Manager...", and
       select "Release" or "Debug" for the Active Configuration
       Solution.
     * 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.

   Batch Configuration Note: If you want to build the Win32 and x64
   platforms and 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.

  [52]How To Build And Install On Windows with Cygwin

   Building International Components for Unicode with this
   configuration requires:
     * Microsoft 2000 or above
     * Microsoft Visual C++ 2003 or above (when gcc isn't used).
     * Cygwin with the following installed:
          + bash
          + GNU make
          + man (if you plan to look at the man pages)

   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 "[53]How To Build And
   Install On UNIX" instructions, while you are inside a Cygwin bash
   shell. To build with Microsoft Visual C++, please use the following
   instructions:
    1. 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.
    2. If the computer isn't set up to use Visual C++ from the command
       line, you need to run vcvars32.bat. For example "C:\Program
       Files\Microsoft Visual Studio 8\VC\bin\vcvars32.bat" can be used
       for 32-bit builds or "C:\Program Files (x86)\Microsoft Visual
       Studio 8\VC\bin\amd64\vcvarsamd64.bat" can be used for 64-bit
       builds on Windows x64.
    3. 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.
    4. Change directory to "icu/source", which is where you unzipped
       ICU.
    5. Run "bash [54]./runConfigureICU Cygwin/MSVC" (See [55]Windows
       configuration note and non-functional configure options below).
    6. Type "make" to compile the libraries and all the data files.
       This make command should be GNU make.
    7. Optionally, type "make check" to run the test suite, which
       checks for ICU's functionality integrity (See [56]testing note
       below).
    8. Type "make install" to install ICU. If you used the --prefix=
       option on configure or runConfigureICU, ICU will be installed to
       the directory you specified. (See [57]installation note below).

     [54] http://source.icu-project.org/repos/icu/icu/trunk/source/runConfigureICU

   Configuring ICU on Windows NOTE: In addition to the Unix
   [58]configuration note the following configure options currently do
   not work on Windows with Microsoft's compiler. Some options can work
   by manually editing icu/source/common/unicode/pwin32.h, but manually
   editing the files is not recommended.
     * --disable-renaming
     * --disable-threading
     * --enable-tracing
     * --enable-rpath
     * --with-iostream
     * --enable-static (Requires that U_STATIC_IMPLEMENTATION be
       defined in user code that links against ICU's static libraries.)
     * --with-data-packaging=files (The pkgdata tool currently does not
       work in this mode. Manual packaging is required to use this
       mode.)

  [59]How To Build And Install On UNIX

   Building International Components for Unicode on UNIX requires:
     * A C++ compiler installed on the target machine (for example:
       gcc, CC, xlC_r, aCC, cxx, etc...).
     * An ANSI C compiler installed on the target machine (for example:
       cc).
     * A recent version of GNU make (3.80+).
     * For a list of z/OS tools please view the [60]z/OS build section
       of this document for further details.

   Here are the steps to build ICU:
    1. Decompress the icu-X.Y.tgz (or icu-X.Y.tar.gz) file. For
       example, "gunzip -d < icu-X.Y.tgz | tar xvf -"
    2. Change directory to the "icu/source".
    3. Run "chmod +x runConfigureICU configure install-sh" because
       these files may have the wrong permissions.
    4. Run the [61]runConfigureICU script for your platform. (See
       [62]configuration note below).
    5. Type "gmake" (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".
    6. Optionally, type "gmake check" to run the test suite, which
       checks for ICU's functionality integrity (See [63]testing note
       below).
    7. Type "gmake install" to install ICU. If you used the --prefix=
       option on configure or runConfigureICU, ICU will be installed to
       the directory you specified. (See [64]installation note below).

     [61] http://source.icu-project.org/repos/icu/icu/trunk/source/runConfigureICU

   Configuring ICU NOTE: Type "./runConfigureICU --help" for help on
   how to run it and a list of supported platforms. You may also want
   to type "./configure --help" 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 "./configure". 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 [65]note regarding HP-UX multithreaded build issues with
   newer compilers. Solaris user's, please see this [66]note regarding
   Solaris multithreaded build issues.

   Running The Tests From The Command Line NOTE: You may have to set
   certain variables if you with to run test programs individually,
   that is apart from "gmake check". The environment variable ICU_DATA
   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 ICU_DATA if the complete shared data library is in your library
   path.

   Installing ICU NOTE: 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 Subversion, 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).

  [67]How To Build And Install On z/OS (OS/390)

   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:
     * 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 [68]z/OS UNIX - Tools and Toys 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.
     * 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.
     * 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 [69]unpax-icu.sh script to do this for you automatically. It
       will unpackage the tar file and convert all the necessary files
       for you automatically.
     * 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.
     * 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 OS390_XPLINK=1 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.
     * 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
       --with-iostream=old configure option when using runConfigureICU.
       This will prevent applications that use the icuio library from
       crashing.
     * The rest of the instructions for building and testing ICU on
       z/OS with UNIX System Services are the same as the [70]How To
       Build And Install On UNIX section.

     [68] http://www.ibm.com/servers/eserver/zseries/zos/unix/redbook/
     [69] http://source.icu-project.org/repos/icu/icu/trunk/as_is/os390/unpax-icu.sh

    z/OS (Batch/PDS) support outside the UNIX system services
    environment

   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).

   The OS390BATCH environment variable enables non-UNIX support
   including the batch environment. When OS390BATCH is set, the
   libicui18nXX.dll, libicuucXX.dll, and libicudtXXe.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.

   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.

   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.

   Here is an example of some environment variables that you can set
   prior to building ICU:
OS390BATCH=1
LOADMOD=USER.ICU.LOAD
LOADEXP=USER.ICU.EXP

   The PDS member names for the DLL file names are as follows:
IXMIXXIN --> libicui18nXX.dll
IXMIXXUC --> libicuucXX.dll
IXMIXXDA --> libicudtXXe.dll

   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:
Data Set Name . . . : USER.ICU.LOAD
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: 1
Secondary cylinders : 5
Data set name type  : LIBRARY

   The PDS can be allocated with the following attributes:
Data Set Name . . . : USER.ICU.EXP
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

  [71]How To Build And Install On The IBM i Family (IBM i, i5/OS
  OS/400)

   Before you start building ICU, ICU requires the following:
     * QSHELL interpreter installed (install base option 30, operating
       system)
     * ILE C/C++ Compiler installed on the system
     * The latest GNU facilities (You can get the GNU facilities from
       [72]http://www.ibm.com/servers/enable/site/porting/iseries/overv
       iew/gnu_utilities.html). Older versions may not work properly.

     [72] http://www.ibm.com/servers/enable/site/porting/iseries/overview/gnu_utilities.html

   The following describes how to setup and build ICU. For background
   information, you should look at the [73]UNIX build instructions.
    1. Create 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.
CRTLIB LIB(libraryname)
ADDENVVAR ENVVAR(OUTPUTDIR) VALUE('libraryname')
    2. Set up the following environment variables and job
       characteristics in your build process
ADDENVVAR ENVVAR(MAKE) VALUE('/usr/bin/gmake')
CHGJOB CCSID(37)
    3. Run 'QSH'
    4. Run gunzip on the ICU source code compressed tar archive
       (icu-X.Y.tgz).
    5. Run unpax-icu.sh on the tar file generated from the previous
       step.
    6. Change your current directory to icu/source.
    7. Run './runConfigureICU IBMi' (See [74]configuration note for
       details).
    8. Run 'gmake' to build ICU.
    9. Run 'gmake check QIBM_MULTI_THREADED=Y' to build and run the
       tests. You can look at the [75]iSeries Information Center for
       more details regarding the running of multiple threads on IBM i.

     [75] http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/apis/concept4.htm

[76]How To Package ICU

   There are many ways that a person can package ICU with their
   software products. Usually only the libraries need to be considered
   for packaging.

   On UNIX, you should use "gmake install" 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 "--prefix=dir" configure option (See the [77]UNIX
   build instructions). When ICU is built on Windows, a similar
   directory structure is built.

   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.
    1. Add a suffix name to the library names. This can be done with
       the --with-library-suffix configure option.
    2. The installation script should install the ICU libraries into
       the application's directory.

   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 [78]User's Guide. The [79]ICU Source Code Organization section
   of this readme.html gives a more complete description of the
   libraries.

     [78] http://www.icu-project.org/userguide/

   CAPTION: Here is an example of libraries that are frequently
   packaged.

   Library Name Windows Filename Linux Filename Comment
   Data Library icudtXYl.dll libicudata.so.XY.Z Data required by the
   Common and I18n libraries. There are many ways to package and
   [80]customize this data, but by default this is all you need.
   Common Library icuucXY.dll libicuuc.so.XY.Z Base library required by
   all other ICU libraries.
   Internationalization (i18n) Library icuinXY.dll libicui18n.so.XY.Z A
   library that contains many locale based internationalization (i18n)
   functions.
   Layout Engine iculeXY.dll libicule.so.XY.Z An optional engine for
   doing font layout.
   Layout Extensions Engine iculxXY.dll libiculx.so.XY.Z An optional
   engine for doing font layout that uses parts of ICU.
   ICU I/O (Unicode stdio) Library icuioXY.dll libicuio.so.XY.Z An
   optional library that provides a stdio like API with Unicode
   support.
   Tool Utility Library icutuXY.dll libicutu.so.XY.Z 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.

     [80] http://www.icu-project.org/userguide/icudata.html

   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 X, Y and Z 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.

[81]Important Notes About Using ICU

  [82]Using ICU in a Multithreaded Environment

   Some versions of ICU require calling the u_init() function from
   uclean.h to ensure that ICU is initialized properly. In those ICU
   versions, u_init() must be called before ICU is used from multiple
   threads. There is no harm in calling u_init() in a single-threaded
   application, on a single-CPU machine, or in other cases where
   u_init() is not required.

   In addition to ensuring thread safety, u_init() 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 u_init() 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 udata_setCommonData() or
   u_setDataDirectory() which specify to ICU where it can find its
   data.

   Since u_init() 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 ucnv_open(), ucol_open(),
   C++ constructors, etc.).

    ICU 3.4 and later

   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.)

   u_init() can be used to check for data loading. It tries to load the
   converter alias table (cnvalias.icu).

    ICU 2.6..3.2

   These ICU versions require a call to u_init() 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.

   u_init() loads and initializes the data files for normalization and
   character properties (unorm.icu and uprops.icu) and can therefore
   also be used to check for data loading.

    ICU 2.4 and earlier

   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.
   u_init() was not defined yet.

    [83]Using ICU in a Multithreaded Environment on HP-UX

   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 [84]-AA 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
   [85]-AA 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.

     [84] http://docs.hp.com/en/1405/options.htm#optioncap-AA
     [85] http://docs.hp.com/en/1405/options.htm#optioncap-AA

    [86]Using ICU in a Multithreaded Environment on Solaris

      Linking on Solaris

   In order to avoid synchronization and threading issues, developers
   are suggested 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:

     To use libthread, specify -lthread before -lc on the ld command
     line, or last on the cc command line.

     To use libpthread, specify -lpthread before -lc on the ld command
     line, or last on the cc command line.

   Failure to do this may cause spurious lock conflicts, recursive
   mutex failure, and deadlock.

   Source: "Solaris Multithreaded Programming Guide, Compiling and
   Debugging", Sun Microsystems, Inc., Apr 2004
   [87]http://docs.sun.com/app/docs/doc/816-5137/6mba5vpke?a=view

     [87] http://docs.sun.com/app/docs/doc/816-5137/6mba5vpke?a=view

  [88]Windows Platform

   If you are building on the Win32 platform, it is important that you
   understand a few of the following build details.

    DLL directories and the PATH setting

   As delivered, the International Components for Unicode build as
   several DLLs, which 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.

    Changing your PATH

   Windows 2000/XP: 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 ";<ICU>\bin"
   to the end of the path string. If there is nothing there, just type
   in "<ICU>\bin". Click the Set button, then the OK button.

   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 [89]msdn.microsoft.com.

     [89] http://msdn.microsoft.com/

  [90]UNIX Type Platform

   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 LD_LIBRARY_PATH or LIBPATH 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.

   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.

[91]Platform Dependencies

  [92]Porting To A New Platform

   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 [93]icu-support
   mailing list. 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.

     [93] http://www.icu-project.org/contacts.html

    Data For a New Platform

   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).

   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 [94]ICU Data chapter.

     [94] http://www.icu-project.org/userguide/icudata.html

   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.

   WARNING! 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.

    Adapting Makefiles For a New Platform

   Try to follow the build steps from the [95]UNIX 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:
    1. Create an mh file in icu/source/config/. You can use mh-linux or
       a similar mh file as your base configuration.
    2. Modify icu/source/aclocal.m4 to recognize your platform's mh
       file.
    3. Modify icu/source/configure.in to properly set your platform C
       Macro define.
    4. Run [96]autoconf in icu/source/ without any options. The
       autoconf tool is standard on most Linux systems.
    5. 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.
    6. 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.

     [96] http://www.gnu.org/software/autoconf/

  [97]Platform Dependent Implementations

   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.
     * unicode/platform.h.in (autoconf'ed platforms)
       unicode/pXXXX.h (others: pwin32.h, ppalmos.h, ..):
       Platform-dependent typedefs and defines:
          + Generic types like UBool, int8_t, int16_t, int32_t,
            int64_t, uint64_t etc.
          + U_EXPORT and U_IMPORT for specifying dynamic library import
            and export
          + <iostream> usability
          + Thread safety usability
     * unicode/putil.h, putil.c: platform-dependent implementations of
       various functions that are platform dependent:
          + uprv_isNaN, uprv_isInfinite, uprv_getNaN and
            uprv_getInfinity for handling special floating point
            values.
          + uprv_tzset, uprv_timezone, uprv_tzname and time for getting
            platform specific time and time zone information.
          + u_getDataDirectory for getting the default data directory.
          + uprv_getDefaultLocaleID for getting the default locale
            setting.
          + uprv_getDefaultCodepage for getting the default codepage
            encoding.
     * umutex.h, umutex.c: 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.
     * umapfile.h, umapfile.c: functions for mapping or otherwise
       reading or loading files into memory. All access by ICU to data
       from files makes use of these functions.
     * 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.
     _________________________________________________________

   Copyright © 1997-2008 International Business Machines Corporation
   and others. All Rights Reserved.
   IBM Globalization Center of Competency - San José
   4400 North First Street
   San José, CA 95134
   USA

