Java Developer Guide

Before going into details of how Java is handled on Gentoo, please make sure you have read and are aware of the Gentoo Java Packaging Policies and also the Java article. This guide will not cover such, but will cover more specific details on Gentoo Java ebuilds.

Java on Gentoo
This section will give you more insight into how Gentoo handles Java. You should be familiar with the Java User Guide before proceeding.

Virtual machines (VMs)
As discussed in the User Guide, there are several VMs available from portage.

Testing all packages to ensure they build and run with every VM is a huge undertaking, and there simply are not enough resources to guarantee every package will build and run with every VM.

We now maintain a list of "supported virtual machines" for each architecture. These are the VMs we will test the packages against before committing changes to portage. When you emerge a package, it will by default try to use the best "supported virtual machine."

Of course, Gentoo and Linux in general are about choice, so if you prefer a different VM over the "supported virtual machines", you can easily use that VM instead. However, you should also know that bugs reported with one of the non-"supported virtual machine" will get a low priority if it isn't present using a "supported virtual machine".

Configuring which VM to use
You can choose which VM to use on a per-user basis, and which VM to use for the system (ie when running things as root). Both of these are configured using java-config.

A user's current VM is represented by a symlink located at. This symlink points to the JAVA_HOME of the chosen VM. Similarly, the system VM is represented by a symlink at.

The current VM can also be changed on the fly. This can be accomplished setting the environment GENTOO_VM to contain the name of a VM that java-config knows about.

Java tools
The traditional Java tools, ie,, , , etc, are all located in. They are actually all symlinks to the script. This script will call the appropriate tool, depending on how the script is invoked, from the current VM. The contents of the GENTOO_VM variable is checked first, then the user VM, and lastly the system VM.

Build-time VM switching
As outlined in the User Guide, and mentioned briefly earlier, the VM will switch at build time to accommodate the needs of the package. The VM to use is first determined by JAVA_PKG_FORCE_VM, then , and lastly the system VM.

Bytecode compatibility
The default behavior of is to compile bytecode that will be compatible with the current VM version and higher (ie forward compatible). It is possible to specify which VM to compile for to provide the best compatibility.

At build time, the DEPEND and RDEPEND variables will determine what VM to compile for based on and. Additionally, this can be controlled by the environment variables JAVA_PKG_WANT_SOURCE and JAVA_PKG_WANT_TARGET.

There is a wrapper for called, which will use the appropriate VM's , and then specify the appropriate   and. For projects that use ant, the can be translated to specify the appropriate   and.

Filesystem layout
In general, the directory policies are handled for you by the helper functions in the java-utils-2 eclass.

These functions adhere to the following path name conventions:


 * contains information about the package.
 * files created from source code are installed to
 * pre-built files not compiled by the ebuild are installed to
 * Javadoc documentation is installed to
 * Source archives are installed to
 * User-executable scripts are installed to
 * System-wide environment files are installed to
 * User-specific environment files can be put into

Prepare Enviroment
Before getting started there are a few things to prepare in your development environment, such as environment variables to set, and/or packages to merge.

Variables
There are a couple Java specific portage environment variables to be set. They are optional, but the first is recommend to be set by anyone doing Java ebuild development.


 * Set this variable in make.conf to enable use of . Which will look for and report any unneeded dependencies and/or any bundled dependencies found not part of the package dependencies.
 * Set this variable in make.conf to enable use of . Which will look for and report any unneeded dependencies and/or any bundled dependencies found not part of the package dependencies.


 * Set this variable to enable debugging in Java eclasses
 * Set this variable to enable debugging in Java eclasses

Packages
There are some packages that can help you with Java ebuild development and bumping to new versions.

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.


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


 * 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.
 * 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.


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

Ebuild Generating

 * This is an experimental package being developed by Gentoo Java developers. It can generate initial ebuilds from Maven  files. In its simplest form, it takes   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  yet.
 * This is an experimental package being developed by Gentoo Java developers. It can generate initial ebuilds from Maven  files. In its simplest form, it takes   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  yet.

General guidelines
In addition to standard Gentoo ebuild guidelines, there are some specific guidelines for Java packages:


 * Avoid using bundled files at all costs for source-based packages. Instead, they should use system installed versions with the help of our eclass functions.
 * If you only need the path to installed libraries, you can use . Don't call   directly - it will not record the dependency in the package env.
 * Always provide an easily understandable reason after, so that end-users will provide the maintainers with sensible feedback if the build should fail.
 * Avoid cluttering up the environment by adding environment files to . Instead, store your env file in, and then have user scripts source their environment file when it launches. Otherwise, developers, who regularly override CLASSPATH , CATALINA_HOME and other environment variables, will have problems running regular apps. If you use the launcher it will also automatically source the appropriate env file.
 * Make sure you always compile with a correct source/target version. This is important to ensure future and backwards compatibility. If the packages use ant, this can be done for you automatically. See java-ant-2.eclass. If not you will have to patch it to pass  to . Also, as the lowest supported version of JDK in Gentoo is 1.8, use at least that version if possible to avoid future problems when lower source/target versions will become unsupported by JDKs, which would cause an unnecessary extra maintenance of the packages.
 * Do no install jars which contain versions in their filename, ie . Use  which renames and installs jars without version in the file name.
 * For packages that use Ant to build, try to DEPEND on just when possible instead of .  is automatically added to DEPEND if you inherit . If the package makes use of 'optional' ant tasks, you'll need to DEPEND on  or add   before inherit. The latter is of course preferred. see the Ant Guide for details.

USE flags
Gentoo Java ebuilds unlike most others start with a USE flag variable, a Java specific one JAVA_PKG_IUSE. The only thing that can come before this variable in an ebuild is the EAPI variable. You still set the other USE flag for various general USE flags, but there are Java specific USE flags that go in this variable and DO NOT go in the other normal USE flag.

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  USE flag. If the build system can, you should build javadocs also using the  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  and javadocs using.

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

Dependencies
Gentoo Java ebuild dependencies for the most part are just like in any other ebuild. There are two common dependencies that will always exist for any Java ebuild, no matter if Java is optional or not. Though if Java is optional, the dependencies would be conditional based on a USE flag, likely  USE flag. There are some packages which may require a JDK at runtime, otherwise most should have a JRE for runtime. When depending on a package, take care that you depend on a sufficiently recent version, and explicitly ensure at building time that the providing package gives you the correct interface, i.e. the correct.

JDK/JRE
For any package that builds from source, DEPEND should be set to. 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. Unless the package requires a JDK at runtime.

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.

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.

Slots
For Gentoo Java packages, slots are obligatory for every dependency, which also includes packages with. These must end in. 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,. 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 which depends on. Both come from the same sources, thus they need to have depend on a specific version of  as follows. This would be the depend for. 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.

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

Preparing sources
Gentoo Java ebuilds use the normal  and. Previously  was used instead but that is now deprecated. Within, along with doing the normal patching and other things you might need to do in order to prepare the sources, it is policy and practice to always remove any bundled class and/or jar files that came with the package sources, which is one of the first things you should do for any Java package, regardless of optional Java support or not.

Removing bundled classes and jars
To remove bundled compiled stuff, use  and   from. These can also be used together.

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.

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.

Compiling
There are two common ways to compile full Java packages on Gentoo using either  or  functions and variables.

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

java-pkg-simple
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 global variables in the ebuild. Using such one can omit the entire  section in most cases.

In case the package uses Maven as the build system, you can also use Gentoo tool to generate the ebuild skeleton. Though this application is still in experimental phase and some of its features are not yet supported by, 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.

Typical examples
Without further ado, here are a few examples:

Warnings
There are some common warnings that are produced by the java compiler. A few are Gentoo specific and others are general. Some are of concern, and others are not.

Bootstrap class path
Anytime the source version is lower than the current java version you will see the following warning.

While this is a generic warning, it comes from a Gentoo specific issue. Anytime the source version is lower than the current java version, a rt.jar from that older version needs to be set as the bootstrap classpath. This is presently not done on Gentoo, thus the warning.

It is safe to ignore, providing you do not try to run the resulting java binaries on a version of java older than that which it was compiled on. That does somewhat defeat the purpose of using a lower source but sometimes that is necessary for a variety of other reasons.