Java Developer Guide/Using java-ant-2.eclass

Preparing sources for building with ant

Replacing removed bundled jars

There are some build systems that require jars to be in certain locations. Per Gentoo Java Packaging Policy and the previous section those jars have now been removed. They need to be replaced using symlinks to system jars to let the build system proceed without further modification. This is mostly a legacy way of doing things, as most build systems will look for jars on the classpath.

CODE Replacing removed bundled jar files with system

src_prepare() {
    default
    # change directory to where the jars you removed were located
    cd lib

    # needed at runtime not just build, will be on the package classpath in package.env
    java-pkg_jar-from jdom

    # needed at runtime not just build with specific build name, will be on the package classpath in package.env
    java-pkg_jar-from ant-core ant.jar ant-1.5.4.jar

    # not needed at runtime just build, will NOT be on the package classpath in package.env
    java-pkg_jar-from --build-only ant-core

}

Modify build system

There are times when you might need to modify the build system. If a project uses ant as a build system, there can be unwanted targets that are always called. Or targets that will download dependencies outside of portage. Other times there might be unwanted classes or resources on the classpath, or it is missing a classpath that will be set/added to the ebuild.

To avoid unwanted targets you can either remove them entirely from the build.xml file, or you can comment out the targets via XML comments, . This can be done via one or more patches and/or sed if minimal. Pay close attention to target dependencies, and dependent targets. At times bypassing one unwanted target can bypass other wanted targets. There are times you might need to change a target's dependencies rather than bypassing a target entirely.

Note
When you comment out targets or anything in xml via XML comments, , those comments will disappear when the xml file is passed through the xml-rewriter. It will remove any comments entirely. This can cause patches to fail if the patch is made after the xml-rewriter has modified the xml file. Make sure to always make patches and sed for raw untouched sources.

Compiling with ant

eant is a Gentoo wrapper around ant. One should never invoke ant directly in an ebuild but instead call eant, though even calling eant is unnecessary in most packages with ant build systems, and should not be done. Instead eant function can be controlled via global variables in the ebuild. Using such one can omit the entire src_compile() section in many cases.

CODE Using eant Global Variables

inherit java-pkg-2 java-ant-2

...

# Re-write the classpath in any and all build.xmls in the sources
# This should be done in most cases
JAVA_ANT_REWRITE_CLASSPATH="true"

# This is passed to the ANT_TASKS variable, which can be set directly.
# This contains names of Gentoo Java Package(s) including slot if > 0.
# There can be more than one task, comma separated, or multi-line no commas.
EANT_ANT_TASKS="bnd-3,cpptasks"

# Controls the location of build.xml, with the default being ./build.xml.
# Normally do not need to set this, but if its in a different location
# or in a subdirectory, set this to that location.
EANT_BUILD_XML="sub/directory/build.xml"

# This tells eant/ant which target to call, default is jar.
# If the build target of the package is jar you can omit this variable.
EANT_BUILD_TARGET="jars"

# This tells eant/ant which target to call to build javadocs, default javadoc.
# If the doc target of the package is javadoc you can omit this variable.
EANT_DOC_TARGET="javadocs"

# If the package has a test target, set this to the name of that target.
EANT_TEST_TARGET="junit"

# This is used to build the classpath for the package.
# This contains names of Gentoo Java Package(s) including slot if > 0.
# This is only required if you need jars on the classpath.
# In some cases where only the jdk is needed, this can be omitted.
# Single line comma separated list of package names with slot,
# or if lengthy, multi-line with no commas is preferred.
# Slot format can be either ${PN}:${SLOT} or ${PN}-${SLOT}, 
# with the exception that slot -0 is not valid but slot :0 is valid.
EANT_GENTOO_CLASSPATH="
        commons-logging:0
        jdom-2
        jgoodies-common:0
        xalan
"

# This is used to add raw jars to the classpath.
# Jars either bundled or installed outside portage.
# It contains paths to jars, not package names.
# Paths can be absolute or relative to the package build system.
# Paths are colon separated.
EANT_GENTOO_CLASSPATH_EXTRA="lib/bundled.jar:/path/to/system.jar"

# This is used to pass extra arguments to ant,
# or in some cases to negate defaults which follow;
# -Dnoget=true -Dmaven.mode.offline=true -Dbuild.sysclasspath=ignore -Dmaven.test.skip=true
# If you are packaging something that imports ant classes,
# you may need to negate the -Dbuild.sysclasspath=ignore
EANT_EXTRA_ARGS="-Dbuild.sysclasspath=last"

# Set this if you need tools.jar from the JDK itself.
# The value does not matter, just has to be set to something.
EANT_NEEDS_TOOLS="true"

Typical examples using java-ant-2.eclass

FILE foo-1.0.ebuildExample of a Java ant ebuild

EAPI=8
JAVA_PKG_IUSE="doc source"

inherit java-pkg-2 java-ant-2

DESCRIPTION="Fictional example ebuild."
HOMEPAGE="http://www.gentoo.org/"
SRC_URI="mirror://gentoo/${P}-src.tar.gz"

LICENSE="Apache-2.0"
SLOT="0"
KEYWORDS="~x86 ~sparc ~ppc ~amd64 ppc64"
IUSE="examples"

CDEPEND="dev-java/xerces:2
        >=dev-java/log4j-1.2.8:0"

RDEPEND=">=virtual/jre-1.8:*
        ${CDEPEND}"

DEPEND=">=virtual/jdk-1.8:*
        ${CDEPEND}"

S=${WORKDIR}/${P}-src

src_prepare() {
        default
        # Remove bundled jars
        java-pkg_clean

        # Replace removed bundled jars with system
        cd "${S}/lib"
        java-pkg_jar-from xerces-2
        # Replace with a version specific jar
        java-pkg_jar-from log4j log4j.jar log4j-1.2.8.jar
}

src_install() {
        java-pkg_newjar target/${P}-dev.jar ${PN}.jar

        use doc && java-pkg_dojavadoc dist/api
        use source && java-pkg_dosrc src/java/org
        use examples && java-pkg_doexamples src/java/examples
}