Java Developer Guide

Java API Check

Each time you are bumping a Java library, you should check whether the API of the library did not change significantly. If the change is significant, you should decide whether new SLOT should be introduced to prevent breaking of existing applications depending on this package and the current SLOT.

There are several tools that could help you to get fast overview of the changes.

dev-util/japi-compliance-checker

This package checks for changes in Java API of two jar files. It is fast and also works with latest Java bytecode.

dev-util/pkgdiff

This is a more general tool that can also check for Java API changes. The output is more detailed and also includes information about other files included. It takes more time to generate the report though.

dev-java/java-apicheck

This package has been long used for checking for Java API changes. The output is generated on command line. It relies on on dev-java/japitools which hasn't been updated for some time.

Ebuild Generating

app-portage/java-ebuilder

This is an experimental package being developed by Gentoo Java developers. It can generate initial ebuilds from Maven pom.xml files. In its simplest form, it takes pom.xml file and several other parameters and creates an ebuild that should be checked and tested before committed. There are also add-on scripts that will generate ebuilds for any dependencies that are not packaged yet. Currently this application generates some features that are not supported by java-pkg-simple.eclass yet.

About USE flags[edit | edit source]

For more information regarding USE flags, refer to the USE flags chapter from the Gentoo Development Guide.

Java specific USE flags[edit | edit source]

There are a few specific common USE flags for Java ebuilds as follows. These use flags do not go in the normal USE variable but go in JAVA_PKG_IUSE instead. Any use flag other than the following would go in the normal USE variable. The JAVA_PKG_IUSE must precede the inherit line in an ebuild.

The USE flags that go in JAVA_PKG_IUSE

• The doc flag will build API documentation using javadoc.
• The source flag installs a zip of the source code of a package. This is traditionally used for IDEs to 'attach' source to the libraries that are being use;

Java USE flag usage

The JAVA_PKG_IUSE USE flag/variable MUST reside in the ebuild before the inherit line.

If a manual or other extensive documentation is available, it should be installed using the doc USE flag. If the build system can, you should build javadocs also using the doc USE flag. If it does not, you should consider patching it to do so, and provide the patch upstream. HTML documentation should be installed using dohtml and javadocs using java-pkg_dojavadoc.

If you want to go all the way, add the source USE flag that installs the complete source code as a .zip file. Use java-pkg_dosrc for this purpose. This allows IDEs such as Eclipse and NetBeans to do complete source-level debugging. The source USE flag will add app-arch/zip to DEPEND automatically, you do not need to add this dependency.

<syntaxhighlight lang="bash">JAVA_PKG_IUSE="doc source"

inherit ...</syntaxhighlight>

JDK/JRE

For any package that builds from source, DEPEND should be set to >=virtual/jdk-[minimum-version]. If the package does not build from source and is a Java binary, you can use a JRE instead of a JDK in DEPEND.

All java packages will require a JRE for RDEPEND, and should be set to >=virtual/jre-[minimum-version]. Unless the package requires a JDK at runtime.

<syntaxhighlight lang="bash">DEPEND=">=virtual/jdk-1.8:*"
RDEPEND=">=virtual/jre-1.8:*"</syntaxhighlight>

<syntaxhighlight lang="bash">DEPEND="java? ( >=virtual/jdk-1.8:* )"
RDEPEND="java? ( >=virtual/jre-1.8:* )"</syntaxhighlight>

Some packages do not compile with different JDK versions. If you come across such a package, you have to restrict the compilation to the specific JDK version. Running such a package with newer JDK/JRE is usually safe so you can restrict only the JDK version for compilation.

<syntaxhighlight lang="bash">DEPEND=">=virtual/jdk:1.8"
RDEPEND=">=virtual/jre-1.8:*"</syntaxhighlight>

While it is not required, you will commonly see a dependency variable that is used in both DEPEND and RDEPEND. This variable name is not mandated and is usually CDEPEND or COMMON_DEPEND for anything that will go in both DEPEND and RDEPEND. This is not really Java specific but is very common in most if not all Java ebuilds.

<syntaxhighlight lang="bash">CDEPEND="dev-java/xerces:2
        >=dev-java/log4j-1.2.8:0"
 
DEPEND=">=virtual/jdk-1.8:*
        ${CDEPEND}"

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

Slots

For Gentoo Java packages, slots are obligatory for every dependency, which also includes packages with SLOT="0". These must end in :0. Failure to adhere to this can cause issues if a package is later slotted. Portage will pull in the latest version, likely the slotted one, removing the un-slotted version, which will break usage of the dependency in the Java ebuild.

Versions

For most Gentoo Java packages you will exclude versions from dependencies, unless you need a specific version of a dependency or a newer version than what might be available. For large Java Applications that are split into multiple packages on Gentoo, it is recommended but not required, to add the version of the package to the dependency, ~category/package-${PV}:${SLOT}. This ensures other packages for the same application will all be built using the same version, in case there could be potential issues mixing pieces of an application with a different version. By having all packages depend on the version and slot, it ensures this cannot happen. Upstreams will likely not address or respond to bugs or issues that arise from using pieces with other pieces from different versions. Nor is it something Gentoo developers or users should be wasting time on.

Take the following example using dev-java/netty-buffer which depends on dev-java/netty-common. Both come from the same sources, thus they need to have dev-java/netty-buffer depend on a specific version of dev-java/netty-common as follows. This would be the depend for dev-java/netty-buffer. The version does not matter, nor does the slot. What matters is that we are passing both from the parent package to its dependency, which comes from the same sources.

<syntaxhighlight lang="bash">CDEPEND="~dev-java/netty-common-${PV}:${SLOT}"
 
DEPEND=">=virtual/jdk-1.8:*
        ${CDEPEND}"

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

Another example where the slot is different but the version is the same. This example is using www-servers/tomcat and dev-java/tomcat-servlet-api. Due to the nature of servlet-api, and its accompanying virtual java-virtuals/servlet-api, that package gets slotted per servlet-api spec, not the version of the sources. Thus www-servers/tomcat and dev-java/tomcat-servlet-api do not share the same slot, but have the same sources. Which means www-servers/tomcat should use a specific version of dev-java/tomcat-servlet-api.

<syntaxhighlight lang="bash">ECJ_SLOT="4.5"
SAPI_SLOT="4.0"

CDEPEND="dev-java/eclipse-ecj:${ECJ_SLOT}
        ~dev-java/tomcat-servlet-api-${PV}:${SAPI_SLOT}"
 
DEPEND=">=virtual/jdk-1.8:*
        ${CDEPEND}"

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

Removing bundled classes and jars

To remove bundled compiled stuff, use java-pkg_clean and JAVA_RM_FILES from java-util-2.eclass . These can also be used together.

<syntaxhighlight lang="bash">src_prepare() {
     default
     # This does not discriminate,
     # it will remove ALL .class and .jar files
     java-pkg_clean
}</syntaxhighlight>

<syntaxhighlight lang="bash">src_prepare() {
    default
    # Good for selective removal in the rare event some bundled
    # binaries/dependencies must be preserved
    JAVA_RM_FILES=(
            /path/to/file.class
            /path/to/file.jar
        )
}</syntaxhighlight>

<syntaxhighlight lang="bash">src_prepare() {
    default
    for test_file in $(find . -type f -name '*Test*'.java); do
        JAVA_RM_FILES+=("${test_file}")
    done
}</syntaxhighlight>

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.

<syntaxhighlight lang="bash">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_jarfrom jdom

    # needed at runtime not just build with specific build name, will be on the package classpath in package.env
    java-pkg_jarfrom 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_jarfrom --build-only ant-core

}</syntaxhighlight>

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.

eant

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.

<syntaxhighlight lang="bash">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"</syntaxhighlight>

java-pkg-simple

java-pkg-simple.eclass is an eclass that provides a way to build Java packages on Gentoo in a simplistic manner. This is package system independent and should be used for any package that does not come with an Ant build system, though it can even be used for packages using Ant build system. Most packages can be built using java-pkg-simple.eclass global variables in the ebuild. Using such one can omit the entire src_compile() section in most cases.

In case the package uses Maven as the build system, you can also use Gentoo tool app-portage/java-ebuilder to generate the ebuild skeleton. Though this application is still in experimental phase and some of its features are not yet supported by java-pkg-simple.eclass , it can give you fast overview of the package and also an ebuild skeleton to start with. You can also participate in improving the tool to make it more usable.

<syntaxhighlight lang="bash">inherit java-pkg-2 java-pkg-simple

...

# One or more directories with sources in them relative to ${S}.
# It is mandatory.
JAVA_SRC_DIR="src/main/java"

# List of java packages to put on the classpath.
# It is mandatory in case the package has dependencies.
JAVA_GENTOO_CLASSPATH="xalan:2,log4j:0"

# 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.
JAVA_GENTOO_CLASSPATH_EXTRA="lib/bundled.jar:/path/to/system.jar"

# In case the package does not use UTF-8 encoding, you can specify
# the used encoding.
# It is used for javac and javadoc commands.
JAVA_ENCODING="ISO-8859-1"

# Optional additional arguments to be passed to javac.
JAVAC_ARGS="-Xms:64m"

# Optional additional arguments to be passed to javadoc.
JAVADOC_ARGS="-J-Xmx180m"</syntaxhighlight>