Packaging ICU4J

Note: The description in this page is not applicable to ICU4J 58 or later releases. ICU4J module build targets explained in this page are no longer available in the latest ICU4J release.


This chapter describes, for the advanced user, how to package ICU4J for distribution.

Making ICU4J Smaller

The ICU project is intended to provide everything an application might need in order to process Unicode. However, in doing so, the results may become quite large on disk. A default build of ICU4J normally results in nearly 16 MB of data, and a substantial amount of binary code. To reduce the amount of data used, see the ICU Data chapter.

Modularization of ICU4J

Some clients may not wish to ship all of ICU4J with their application, since the application might only use a small part of ICU4J. ICU4J release 2.6 and later provide build options to build individual ICU4J 'modules' for a more compact distribution. The modules are based on a service and the APIs that define it, e.g., the normalizer module supports all the APIs of the Normalizer class (and some others). Tests can be run to verify that the APIs supported by the module function correctly. Because of internal code dependencies, a module contains extra classes that are not part of the module's core service API. Some or most of the APIs of these extra classes will not work. Only the module's core service API is guaranteed. Other APIs may work partially or not at all, so client code should avoid them.

Individual modules are not built directly into their own separate jar files. Since their dependencies often overlap, using separate modules to 'add on' ICU4J functionality would result in unwanted duplication of class files. Instead, building a module causes a subset of ICU4J's classes to be built and put into ICU4J's standard build directory. After one or more module targets are built, the 'moduleJar' target can then be built, which packages the class files into a 'module jar.' Other than the fact that it contains fewer class files, little distinguishes this jar file from a full ICU4J jar file, and in fact they share the same name.

Currently ICU4J can be divided into the following modules:


* should be prepended to the package name listed.

†Class in bold indicates core service API. Only APIs in this column are fully supported.

‡Sizes are of the compressed jar file containing only this module. These sizes are approximate for release3.6, they may change in future releases.


Building any of these modules is as easy as specifying a build target to the Ant build system, e.g:

To build a module that contains only the Normalizer API:

    1. Build the module.

    2. ant normalizer

    3. Build the jar containing the module.

    4. ant moduleJar

    5. Build the tests for the module.

    6. ant normalizerTests

    7. Run the tests and verify that the self tests pass.

    8. java -classpath classes -nothrow -w

If more than one module is required, the module build targets can be concatenated, e.g:

    1. Build the modules.

    2. ant normalizer collator

    3. Build the jar containing the modules.

    4. ant moduleJar

    5. Build the tests for the module.

    6. ant normalizerTests collatorTests

    7. Run the tests and verify that they pass.

    8. java -classpath classes -nothrow -w

The jar should be built before the tests, since for some targets building the tests will cause additional classes to be compiled that are not strictly necessary for the module itself.

Regardless of whether ICU4J is built as a whole or as a modules, the jar file produced is named icu4j.jar.

To ascertain if an icu4j.jar contains all of ICU4J or not, please see the manifest file in the jar

The target moduleJar does not depend on any other target. It just creates a jar of all class files under $icu4j_root/classes/com/ibm/icu/, excluding the classes files in $icu4j_root/classes/com/ibm/icu/dev folder

The list of module build targets can be obtained by running the command: ant -projecthelp