Ant Setup for Java Developers

Contents

  1. 1 Overview
  2. 2 Test arguments and running just one test
  3. 3 Generating Test Code Coverage Report
  4. 4 Building ICU4J API Reference Document with JCite
  5. 5 Building ICU4J Official Release Files
    1. 5.1 Prerequisites
    2. 5.2 Configuration
    3. 5.3 Ant release targets

Overview

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://source.icu-project.org/repos/icu/icu4j/trunk> (or <http://source.icu-project.org/repos/icu/icu4j/trunk>, 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
 breakIterator         Modular build of break iterator services
 breakIteratorTests    Modular build of break iterator test suite
 build-tools           Build build-tool classes
 calendar              Modular build of calendar services
 calendarTests         Modular build of calendar test suite
 charset               Build charset classes
 charset-tests         Build charset tests
 check                 Run the standard ICU4J test suite
 checktags             Check API tags before release
 cldrUtil              Build Utilities for CLDR
 clean                 Clean up build outputs
 codeCoverage          Generate code coverage report with clover
 collator              Modular build of collator services
 collatorTests         Modular build of collator test suite
 compression           Modular build of compression services
 compressionTests      Modular build of compression test suite
 core                  Build core classes
 core-tests            Build core tests
 demos                 Build demo classes
 docs                  Build API documents
 exhaustiveCheck       Run the standard ICU4J test suite in exhaustive mode
 format                Modular build of format services
 formatTests           Modular build of format test suite
 gatherapi             Run API database generator tool
 indicIMEJar           Build indic IME 'icuindicime.jar' jar file
 info                  Display the build environment information
 jar                   Build ICU4J API jar files
 jarDemos              Build ICU4J demo jar file
 jarDocs               Build ICU4J API doc jar file
 jarSrc                Build ICU4J source jar file
 jdktzCheck            Run the standard ICU4J test suite with JDK TimeZone
 localespi             Build Locale SPI classes
 localespi-tests       Build Locale SPI tests
 localespiCheck        Run the ICU4J Locale SPI test suite
 main                  Build ICU4J API classes
 moduleCheck           Run tests for a ICU4J module jar
 moduleJar             Create a ICU4J module jar file
 normalizer            Modular build of normalizer services
 normalizerTests       Modular build of normalizer test suite
 propertiesBasic       Modular build of basic character properties
 propertiesBasicTests  Modular build of basic character properties test suite
 propertiesFull        Modular build of full character properties
 propertiesFullTests   Modular build of full character properties test suite
 releaseJar            Build all jar files for distribution
 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
 stringPrep            Modular build of stringprep services
 stringPrepTests       Modular build of stringprep 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 API test classes
 tools                 Build tool classes
 translitIMEJar        Build transliterator IME 'icutransime.jar' jar file
 transliterator        Modular build of transliterator services
 transliteratorTests   Modular build of transliterator test suite
 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

You can pass arguments to the test system by using the 'testarg' variable and the 'runTest' target. For example:

 Command Line
Meaning
 ant -Dtestarg='-?' runTest The  -? argument will display a list of test options
 ant -Dtestarg='-v Charset/TestCharset/TestUTF8' runTest Run one specific test, in verbose (-v) mode
 ant -Dtestarg='-filter:funky' runTest
 Only run tests matching a specifc string
 ant -Dtestarg='-e -n' runTest
Run exhaustive tests,  print a message instead of exception on failure.


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
  • report_html.zip

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 http://arrenbrecht.ch/jcite/
    • 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: jcite-1.13.0-bin.zip
  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.

Prerequisites

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

Configuration

  • Set environment variable JCITE_DIR to specify JCite binary location (see Building ICU4J API Reference Document with JCite)
  • Create build-local.properties in the ICU4J root directory
  • Edit build-local.properties 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.

System.out.println(System.getProperty("sun.boot.class.path"));

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:

java5.bootclasspath=C:/JDK/Oracle/jdk1.5.0_22/jre/lib/rt.jar;C:/JDK/Oracle/jdk1.5.0_22/jre/lib/i18n.jar;C:/JDK/Oracle/jdk1.5.0_22/jre/lib/sunrsasign.jar;C:/JDK/Oracle/jdk1.5.0_22/jre/lib/jsse.jar;C:/JDK/Oracle/jdk1.5.0_22/jre/lib/jce.jar;C:/JDK/Oracle/jdk1.5.0_22/jre/lib/charsets.jar;C:/JDK/Oracle/jdk1.5.0_22/jre/classes

java6.bootclasspath=C:/JDK/Oracle/jdk1.6.0_45/jre/lib/resources.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/lib/rt.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/lib/sunrsasign.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/lib/jsse.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/lib/jce.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/lib/charsets.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/lib/modules/jdk.boot.jar;C:/JDK/Oracle/jdk1.6.0_45/jre/classes

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.


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

_check_config_for_release:

_verify_config_for_release:
     [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] ################################################################

BUILD SUCCESSFUL
Total time: 34 seconds





Comments