ICU Build Recommendations

Markus Scherer, 2005jul22

To go into the ICU4C readme or into the User Guide.

Recommended Build Configuration

Most users of ICU should share a common, upgradable set of libraries, which is possible, and recommended if all of the following apply:

• You are using only ICU C APIs, not C++ APIs.
• You are using only APIs that are marked with @stable or @deprecated.
• You want the latest versions of locale data, Unicode versions, etc.
• You are shipping the complete, unmodified set of ICU binaries.

Build ICU with the following command:

CFLAGS='-DICU_DATA_DIR=\"/usr/share/icu/\" -DICU_NO_USER_DATA_OVERRIDE=1' CXXFLAGS='-DICU_DATA_DIR=\"/usr/share/icu/\" -DICU_NO_USER_DATA_OVERRIDE=1' ./runConfigureICU Your_OS_Configuration --disable-renaming --disable-draft --with-data-packaging=archive --prefix=/usr

Comments:

• The ICU_DATA_DIR hardcodes a u_getDataDirectory() path so that the .dat package can be used without the caller having to know where ICU's data lives.
• The ICU_NO_USER_DATA_OVERRIDE switch turns off getenv("ICU_DATA") so that a system-wide environment variable can't screw things up. (Maybe we should get rid of the environment variable at this point...)
• --disable-renaming removes the ICU version numbers from the library entry points, so that an application can link against ICU and run with later versions without relinking, as long as they use stable (or deprecated) APIs. Automatic updates.
• --disable-draft hides draft (unstable) APIs from applications so that the previous point can be enforced.
• --with-data-packaging=archive builds the ICU data into a .dat package, which is much more flexible than building it into a DLL/shared library.

Additional Recommendations

• If your platform supports multiple configurations (e.g., both 32-bit and 64-bit code) in a single set of libraries, you should build such a single set.

Platform-Specific Considerations

• MacOS X (Darwin): Build "fat binaries" with x86 and PowerPC code. Instructions TBD. Are both code versions 32-bit, or do fat binaries contain 3 or 4 code versions to include 64-bit code?
• AIX PowerPC: Build "dual object" libraries with both 32-bit and 64-bit code. Instructions TBD. Is a dual object build possible only for libraries, or also for executables like the ICU tools and test suites?
• Windows: Instructions TBD. Support the recommended build configuration only for cygwin builds?
• Solaris Sparc: Set the compile flag for use of CPU registers (more extensive save&restore) as required for system-level libraries. Instructions TBD. See support mailing list archive.

TODO: Change defaults to build the recommended configuration? Provide binaries for more platforms, built with the recommended configuration?

Recommended Install Location

ICU libraries, built with the recommended configuration, should be installed into a shared location.

TODO: We may need to recommend two locations per platform, for example using subfolders. A platform may require that its own set of ICU libraries not be updated, while sharing them and also providing a second location for the latest shared ICU version. For example: /usr/share/icu/system/ vs. /usr/share/icu/latest/ Additional version-specific locations (/usr/share/icu/3.2/) may or may not also make sense; version-specific installations may be best in an applications' own location.

Installation Binaries

The following binaries should be part of a complete installation:

Libraries: icuuc, icuin, icuio, iculx, icule

Tools executables: genrb, makeconv, genbrk, gencmn, genccode, pkgdata, icuswap

TODO: What about Java tools like the XLIFF2ICUConverter?!

Application-Specific Build Configuration

You cannot use the recommended build configuration if any of the following applies:

• You are using ICU C++ APIs. (C++ does not support binary compatibility.)
• You are using APIs that are marked with @draft.
• You require particular data versions and functional results, for example from collation.
• You are building partial ICU libraries, for example using the configuration switches in uconfig.h, or modifying the library code in any other way.

In this case, you should build ICU with renaming enabled and install it into your application install location. You can add a library prefix or suffix for further distinction.