Ant Setup for Java
Contents
- Overview
- Test arguments and running just one test or the tests of just one test class
- Generating Test Code Coverage Report
- Building ICU4J API Reference Document with JCite
- Build and test ICU4J Eclipse Plugin
- Building ICU4J Release Files
Overview
ICU4J source layout was changed after 4.2. There are several ways to set up the ICU4J development environment.
Get the source code by following the Quick Start instruction. Go into the icu4j/ directory to see the build.xml file. You can run targets displayed by ant -p
.
Main targets:
all
Build all primary targetsapireport
Run API report generator toolapireportOld
Run API report generator tool (Pre Java 5 Style)build-tools
Build build-tool classescharset
Build charset classescharset-tests
Build charset testscharsetCheck
Run only the charset testscheck
Run the standard ICU4J test suitecheckDeprecated
Check consistency between javadoc @deprecated and @Deprecated annotationcheckTest
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 releasecldrUtil
Build Utilities for CLDR toolingclean
Clean up build outputscollate
Build collation classescollate-tests
Build core testscollateCheck
Run only the collation testscore
Build core classescore-tests
Build core testscoreCheck
Run only the core testscoverageJaCoCo
Run the ICU4J unit tests and generate code coverage reportcurrdata
Build currency data classesdemos
Build demo classesdocs
Build API documentsdocsStrict
Build API documents with all doclint check enableddraftAPIs
Run API collector tool and generate draft API reportexhaustiveCheck
Run the standard ICU4J test suite in exhaustive modefindbugs
Run FindBugs on all library sub projects.gatherapi
Run API database generator toolgatherapiOld
Run API database generator tool (Pre Java 5 style)icu4jJar
Build ICU4J all-in-one core jaricu4jSrcJar
Build icu4j-src.jaricu4jtestsJar
Build ICU4J all-in-one test jarindicIMEJar
Build indic IME ‘icuindicime.jar’ jar fileinfo
Display the build environment informationinit
Initialize the environment for build and test. May require internet access.jar
Build ICU4J runtime library jar filesjarDemos
Build ICU4J demo jar filejdktzCheck
Run the standard ICU4J test suite with JDK TimeZonelangdata
Build language data classeslocalespi
Build Locale SPI classeslocalespi-tests
Build Locale SPI testslocalespiCheck
Run the ICU4J Locale SPI test suitemain
Build ICU4J runtime library classespackaging-tests
Build packaging testspackagingCheck
Run packaging testsperf-tests
Build performance test classesregiondata
Build region data classesrelease
Build all ICU4J release files for distributionreleaseBinaries
Build ICU4J binary files for distributionreleaseCLDR
Build release files for CLDR toolingreleaseDocs
Build ICU4J API reference doc jar file for distributionreleaseSourceArchiveTgz
Build ICU4J source release archive (.tgz)releaseSourceArchiveZip
Build ICU4J source release archive (.zip)releaseSrcJars
Build ICU4J src jar files for distributionreleaseVer
Build all ICU4J release files for distribution with versioned file namesrunTest
Run the standard ICU4J test suite without calling any other build targetssamples
Build sample classessecure
(Deprecated)Build ICU4J API and test classes for running the ICU4J test suite with Java security manager enabledsecureCheck
Run the secure (applet-like) ICU4J test suitetest-framework
Build test framework classestests
Build ICU4J test classestimeZoneCheck
Run the complete test for TimeZoneRoundTripAlltools
Build tool classestranslit
Build translit classestranslit-tests
Build translit teststranslitCheck
Run the ICU4J Translit test suitetranslitIMEJar
Build transliterator IME ‘icutransime.jar’ jar filexliff
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 | Meaning |
---|---|
ant checkTest -Dtestclass='com.ibm.icu.dev.test.lang.TestUScript' | Runs all the tests in test class ‘TestUScript’. |
ant checkTest -Dtestclass='com.ibm.icu.dev.test.lang.TestUScript' -Dtestnames='TestNewCode,TestHasScript' | 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:
- Download JaCoCo library from EclEmma site.
- Extract library files to your local system - e.g.
C:\jacoco-0.7.6
- Set environment variable JACOCO_DIR pointing to the directory where JaCoCo files are extracted - e.g.
set JACOCO_DIR=C:\jacoco-0.7.6
- Set up ICU4J ant build environment.
- 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:
- http://arrenbrecht.ch/jcite/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: jcite-1.13.0-bin.zip
- Extract JCite file to your local system - e.g.
C:\jcite-1.13.0
- Set environment variable
JCITE_DIR
pointing to the directory where JCite files are extracted. - e.g.set JCITE_DIR=C:\jcite-1.13.0
- Set up ICU4J ant build environment.
- Run the ant target “docs” in the top-level ICU4J build.xml
- 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.
Build and test ICU4J Eclipse Plugin
Building Eclipse ICU4J plugin
- Download and install the latest Eclipse release from http://www.eclipse.org/ (The latest stable milestone is desired, but the latest official release should be OK).
- cd to
<icu4j root>
directory, and make sure$ ant releaseVer
runs clean. - cd to
<icu4j root>/eclipse-build
directory. - Copy
build-local.properties.template
tobuild-local.properties
, edit the properties files- eclipse.home pointing to the directory where the latest Eclipse version is installed (the directory contains configuration, dropins, features, p2 and others)
- java.rt - see the explanation in the properties file
- Run the default ant target - $ ant The output ICU4J plugin jar file is included in
<icu4j root>/eclipse-build/out/projects/ICU4J.com.ibm.icu/com.ibm.icu-com.ibm.icu.zip
Plugin integration test
- Backup Eclipse installation (if you want to keep it - just copy the entire Eclipse installation folder)
- Delete ICU4J plugin included in Eclipse installation -
<eclipse>/plugins/com.ibm.icu_XX.Y.Z.vYYYYMMDD-HHMM.jar
XX.YY.Z is the ICU version, and YYYYMMDD-HHMM is build date. For example, com.ibm.icu_58.2.0.v20170418-1837.jar - Copy the new ICU4J plugin jar file built by previous steps (e.g. com.ibm.icu_61.1.0.v20180502.jar) to the same folder.
- Search a text “
com.ibm.icu"
in files under<eclipse>/features
. The RCP feature has a dependency on the ICU plugin and itsfeature.xml
(e.g.<eclipse>/features/org.eclipse.e4.rcp_1.6.2.v20171129-0543/feature.xml
) contains the dependent plugin information. Replace just version attribute to match the version built by above steps. You can leave size attributes unchanged. The current ICU build script does not append hour/minute in plugin jar file, so the version format is XX.Y.Z.vYYYYMMDD. ` <plugin - Open
<eclipse>/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info
in a text editor, and update the line including com.ibm.icu plugin information.com.ibm.icu,58.2.0.v20170418-1837,plugins/com.ibm.icu_58.2.0.v20170418-1837.jar,4,false
then becomes ->
com.ibm.icu,**61.1.0.v20190502**,plugins/com.ibm.icu_**61.1.0.v20190502**.jar,4,false
- Make sure Eclipse can successfully starts with no errors. If ICU4J plug-in is not successfully loaded, Eclipse IDE won’t start.
ICU4J plugin test - Note: This is currently broken http://bugs.icu-project.org/trac/ticket/13072
- Start the Eclipse (with new ICU4J plugin), and create a new workspace.
- Import existing Eclipse project from
<icu4jroot>/eclipse-build/out/projects/com.ibm.icu.tests
- Run the project as JUnit Plug-in Test.
Building ICU4J Release Files
See Release Build