Ant Setup for Java Developers


ICU4J source layout was changed after 4.2.  There are several ways to set up the ICU4J development environment.

Note: For read-only (guest) repository access, use  "http://" instead of "svn+ssh://".

Check out files from <svn+ssh://> (or <>, and so on) .  You still see build.xml at the workspace root directory.  You can run targets displayed by "ant -p".

Main targets:

  all                      Build all primary targets
  apireport                Run API report generator tool
  apireportOld             Run API report generator tool (Pre Java 5 Style)
  build-tools              Build build-tool classes
  charset                  Build charset classes
  charset-tests            Build charset tests
  charsetCheck             Run only the charset tests
  check                    Run the standard ICU4J test suite
  checkDeprecated          Check consistency between javadoc @deprecated and @Deprecated annotation
  checkTest                Run only the specified tests of the specified test class or, if no arguments are given, the standard ICU4J test suite.
  checktags                Check API tags before release
  cldrUtil                 Build Utilities for CLDR tooling
  clean                    Clean up build outputs
  collate                  Build collation classes
  collate-tests            Build core tests
  collateCheck             Run only the collation tests
  core                     Build core classes
  core-tests               Build core tests
  coreCheck                Run only the core tests
  coverageJaCoCo           Run the ICU4J unit tests and generate code coverage report
  currdata                 Build currency data classes
  demos                    Build demo classes
  docs                     Build API documents
  docsStrict               Build API documents with all doclint check enabled
  draftAPIs                Run API collector tool and generate draft API report
  exhaustiveCheck          Run the standard ICU4J test suite in exhaustive mode
  findbugs                 Run FindBugs on all library sub projects.
  gatherapi                Run API database generator tool
  gatherapiOld             Run API database generator tool (Pre Java 5 style)
  icu4jJar                 Build ICU4J all-in-one core jar
  icu4jSrcJar              Build icu4j-src.jar
  icu4jtestsJar            Build ICU4J all-in-one test jar
  indicIMEJar              Build indic IME 'icuindicime.jar' jar file
  info                     Display the build environment information
  init                     Initialize the environment for build and test. May require internet access.
  jar                      Build ICU4J runtime library jar files
  jarDemos                 Build ICU4J demo jar file
  jdktzCheck               Run the standard ICU4J test suite with JDK TimeZone
  langdata                 Build language data classes
  localespi                Build Locale SPI classes
  localespi-tests          Build Locale SPI tests
  localespiCheck           Run the ICU4J Locale SPI test suite
  main                     Build ICU4J runtime library classes
  packaging-tests          Build packaging tests
  packagingCheck           Run packaging tests
  perf-tests               Build performance test classes
  regiondata               Build region data classes
  release                  Build all ICU4J release files for distribution
  releaseBinaries          Build ICU4J binary files for distribution
  releaseCLDR              Build release files for CLDR tooling
  releaseDocs              Build ICU4J API reference doc jar file for distribution
  releaseSourceArchiveTgz  Build ICU4J source release archive (.tgz)
  releaseSourceArchiveZip  Build ICU4J source release archive (.zip)
  releaseSrcJars           Build ICU4J src jar files for distribution
  releaseVer               Build all ICU4J release files for distribution with versioned file names
  runTest                  Run the standard ICU4J test suite without calling any other build targets
  samples                  Build sample classes
  secure                   (Deprecated)Build ICU4J API and test classes for running the ICU4J test suite with Java security manager enabled
  secureCheck              Run the secure (applet-like) ICU4J test suite
  swatDeprecated           Convert @deprecated @draft tags to @provisional
  swatProvisional          Convert @provisional tags to @deprecated @draft
  test-framework           Build test framework classes
  tests                    Build ICU4J test classes
  timeZoneCheck            Run the complete test for TimeZoneRoundTripAll
  tools                    Build tool classes
  translit                 Build translit classes
  translit-tests           Build translit tests
  translitCheck            Run the ICU4J Translit test suite
  translitIMEJar           Build transliterator IME 'icutransime.jar' jar file
  xliff                    Build xliff converter tool

Default target: main

The typical usage is - "ant check", which will build main ICU4J libraries and run the standard unit test suite.

For running ant you may need to set up some environment variables first. For example, on Windows:
set ANT_HOME=C:\ant\apache-ant-1.7.1
set JAVA_HOME=C:\Program Files\Java\jdk1.5.0_07
set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%

Test arguments and running just one test or the tests of just one test class

You can pass arguments to the test system by using the 'testclass' and 'testnames' variables and the 'checkTest' target. For example:

 Command Line
 ant checkTest -Dtestclass='' Runs all the tests in test class 'TestUScript'.
 ant checkTest -Dtestclass=''
 Runs the tests 'TestNewCode' and 'TestHasScript' in test class 'TestUScript'.
 ant checkTest -Dtestnames='TestNewCode,TestHasScript' Error: test class not specified.
 ant checkTest
 Runs the standard ICU4J test suite (same as 'ant check').

The JUnit-generated test result reports are in out/junit-results/checkTest. Go into the 'html/' subdirectory and load 'index.html' into a browser.

Generating Test Code Coverage Report

#10513 added code coverage target "coverageJaCoCo" in the ICU4J ant build.xml. To run the target:

  1. Download JaCoCo library from EclEmma site.
  2. Extract library files to your local system - e.g. C:\jacoco-0.7.6
  3. Set environment variable JACOCO_DIR pointing to the directory where JaCoCo files are extracted - e.g. set JACOCO_DIR=C:\jacoco-0.7.6
  4. Set up ICU4J ant build environment.
  5. Run the ant target "coverageJaCoCo" in the top-level ICU4J build.xml
Following output report files will be generated in /out/jacoco directory.
  • report.csv
  • report.xml

Building ICU4J API Reference Document with JCite

Since ICU4J 49M2, JCite (Java Source Code Citation System) is integrated into ICU4J documentation build. To build the API documentation for public release, you must use JCite for embedding some coding examples in the API documentation. To set up the environment:

  1. Download JCite binary (you need 1.13.0+ for JDK 7 support) from
    • Note that JCite no longer is available for download from the official web site, which links to Google Code, which was closed down in 2016.
    • The Internet Archive has a copy of the last version of JCite found on Google Code before it was closed down:
  2. Extract JCite file to your local system - e.g. C:\jcite-1.13.0
  3. Set environment variable JCITE_DIR pointing to the directory where JCite files are extracted. - e.g. set JCITE_DIR=C:\jcite-1.13.0
  4. Set up ICU4J ant build environment.
  5. Run the ant target "docs" in the top-level ICU4J build.xml
  6. If the build (on Linux) fails because package com.sun.javadoc is not found then set the JAVA_HOME environment variable to point to <path>/java/jdk. The Javadoc package is in <path>/java/jdk/lib/tools.jar.
Note: The ant target "docs" checks if JCITE_DIR is defined or not. If not defined, it will build ICU4J API docs without JCite. In this case, JCite taglet "{@.jcite ....}" won't be resolved and the embedded tag is left unchanged in the output files.

Building ICU4J Official Release Files

This instruction is applicable to ICU4J 54.1.1 or later official releases up to ICU4J 56.1, including public milestone/release candidate versions. Since ICU4J 57m1, the minimum JRE version was updated to JRE 6, so JRE5 is no longer required.

ICU4J library (as of ICU 54) supports JRE 5 or later Java runtime environment. ICU4J localespi module supports JRE 6 or later versions, because the locale service provider interface was introduced in Java 6. ICU4J 53.1 official binaries were built with JDK 7 with target class file format version 1.5 and 1.6 (localespi), without Java system libraries from JRE 5 and JRE 6. ICU4J 53.1 official binaries worked well on JRE 5 and JRE 6. ICU4J 54.1 official binaries were also built with JDK 7, but the binaries had a problem on JRE 5 and JRE 6, because a new code introduced after ICU4J 53.1 depends on a JDK class that has a backward compatibility problem (See ticket #11326). To avoid the Java's system library class''s backward compatibility problem, ICU4J binary files must be compiled with Java system libraries from JRE 5 and JRE 6. The instruction below explains how to set up the build environment for official release binaries.


  • JRE 5 (Not required for ICU4J 57m1 or later)
  • JRE 6
  • JDK 8 (to run ant build)
  • JDK 7 (to run ant build - up to ICU4J 57.x)
  • Apache ant (the latest available version is preferred - at least 1.9 as of ICU4J 54 release)
  • JCite 1.13.0 (or later version)


  • Set environment variable JCITE_DIR to specify JCite binary location (see Building ICU4J API Reference Document with JCite)
  • Create in the ICU4J root directory
  • Edit to add two properties
    • java5.bootclasspath (Not required for ICU4J 57m1 or later)
    • java6.bootclasspath
The value of javaX.bootclasspath should include JRE's system library path. A set of jar files included in the system library path may vary depending on JRE vendor (Oracle, OpenJDK and IBM use different set of jars) and version. The easiest way to get the system library path is to run a simple Java program on the target JRE.


For example, the values on my Linux system (Ubuntu) look like below:

java5.bootclasspath = /home/yoshito/java/Oracle/jdk1.5.0_22/jre/lib/rt.jar:/home/yoshito/java/Oracle/jdk1.5.0_22/jre/lib/i18n.jar:/home/yoshito/java/Oracle/jdk1.5.0_22/jre/lib/sunrsasign.jar:/home/yoshito/java/Oracle/jdk1.5.0_22/jre/lib/jsse.jar:/home/yoshito/java/Oracle/jdk1.5.0_22/jre/lib/jce.jar:/home/yoshito/java/Oracle/jdk1.5.0_22/jre/lib/charsets.jar:/home/yoshito/java/Oracle/jdk1.5.0_22/jre/classes

java6.bootclasspath = /home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/resources.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/rt.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/sunrsasign.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/jsse.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/jce.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/charsets.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/lib/modules/jdk.boot.jar:/home/yoshito/java/Oracle/jdk1.6.0_45/jre/classes

Note: On my system, Oracle JDK 5 is installed at /home/yoshito/java/Oracle/jdk1.5.0_22, Oracle JDK 6 is installed at /home/yoshito/java/Oracle/jdk1.6.0_45.

One Windows system, path separator back slash '\' should be replaced with forward slash '/'. For example:



Ant release targets

There are some ant build target defined in the top level build.xml.
  • release : Building ICU4J release binaries, but version string is not included in the output file names (icu4j.jar, icu4j-charset.jar...)
  • releaseVer: Building ICU4J release binaries, with version string included in the output file names (icu4j-54_1.jar, icu4j-charset-54_1.jar...)
  • publishToMavenRepo: releaseVer + collecting/renaming/generating ICU4J release files for the maven central repository, and posting these files to the staging repository
For official releases (not including milestones/release candidates), the target publishToMavenRepo is used for generating files for both ICU side download page and maven repository. To run publishToMavenRepo requires some extra configuration (maven ant task), Sonatype account and pgp key for signatures. See build.xml for more details.

These target are generating ICU4J release files even JCite location or javaX.bootclasspath is not defined. However, such output files are not appropriate for an official release. To warn the insufficient build environment, these target print out warning message below at the end.

    [mkdir] Created dir: /home/yoshito/devj/trunk2/out/checksum


     [echo] ################################################################
     [echo] [WARNING] Insufficient Build Configuration for ICU4J Release
     [echo] JRE 5 System Library Path:      Not Defined!
     [echo] JRE 6 System Library Path:      Not Defined!
     [echo] JCite Library Path:             Not Defined!
     [echo] ################################################################

Total time: 34 seconds