Gentoo Java Packing Policy

This policy is the official Gentoo Java Packing Policy and Guidelines for packaging Java applications and libraries for Gentoo Linux. For details on Java ebuilds syntax, semantics, and examples please refer to the Developer Guide

Overview
Packaging Java applications and libraries on Gentoo Linux is not trivial, and is a rather complex process with a bit of a steep learning curve. This policy and guide seeks to standardize Java ebuilds, when to use what eclass, build system, etc. This should help anyone seeking to contribute as well as existing Gentoo developers learn about Gentoo Java packaging nuances. For details on Java ebuilds syntax, semantics, and examples please refer to the Developer Guide

Why have a Java policy?
This policy is necessary to keep Java ebuilds consistent, to form an official standard, and to reduce the burden of correcting contributed Java ebuilds. Please adhere to this policy when packaging Java applications and libraries for Gentoo Linux.

Build from Source
As is standard practice on Gentoo, all Java applications and libraries are to be built from source. This includes any dependencies which might be bundled and/or downloaded during compile. Limited exceptions are made for some applications and almost never for a library, all on a case by case basis. Some complex applications have to many dependencies which are not packaged, sources are not available, and/or the package is not easily built. Those might qualify for exceptions, but by default all Java packages should be built from source. For reasons why, please refer to Why Build from Source.

Dependencies
Dependent packages, anything another package depends on be it a application or library, needs to also be packaged and built from source. Packages are NOT allowed to resolve and/or download their own dependencies outside of portage ever, without exception! Portage should handle any dependencies for the package. Which require dependencies to be packaged. Bundled dependencies should be removed from sources to ensure when the package is built, it is using system dependencies not any provided in the package. There are limited exceptions on a case by case basis. Gentoo Java eclasses will emit warning messages if any bundled binary class or jar files are found.

Slotting
Applications and libraries should be slotted according to the API they provide. If two version have the same API, or if a new version is fully compatible with the previous version, then they should be in the same SLOT.

Java libraries have a tendency to sometimes break API and ABI between minor revisions, ie from 2.1.1 to 2.1.2. As a result, it is necessary to slot early, and slot often. Gentoo developers have made a tool dev-java/java-apicheck that can be used to determine if there are API changes in a package to justify a slot. Anytime there are API changes, there should be a new slot.

For Java applications, it is mostly sufficient to keep only the latest version. If the application comes in series, such as Tomcat, we want to keep the latest revision in each series. Very old series may eventually be dropped completely, even if they are still maintained by upstream.

Package Conventions
Java applications can be quite large. Many have sub-pieces that can be built standalone. It is common for other sub-pieces to depend on another sub-piece as part of the application. On Gentoo such sub-pieces are to be packaged on their own. If need be eclasses can be created to help with common aspects for all sub-pieces. When packaging any Java application on Gentoo, the application should be broken down to the smallest build-able pieces. Creating individual packages for any and all sub-pieces. The package name will start with the application name, followed by the sub-piece name of the application.

For any application that has sub-pieces it is recommended, but not required, to slot the package and all sub-pieces. Slotting will prevent updating a single sub-piece, without updating the reset. That does create extra work, but it will keep an application's sources complete without mixing versions of sub-pieces. Which upstream will likely not like mixed versions of sub-pieces, nor address any issues that might arise from such. Slotting prevents such issues, but does come with the drawback of requiring all sub-pieces of an application to be updated to update the application itself.

JDBC Drivers
JDBC Drivers should always be named with the  preffix added to the package name of the jdbc driver.

Minimum JRE/JDK Version
All Java ebuilds should set the JRE/JDK to the minimum version unless you need a newer version. One should NEVER set the jre/jdk version less than the current minimum, unless a package will not compile with the current minimum version. This is very rare, and likely any packages are outdated. Most any current Java application and/or library should compile and work just fine with the minimum, or require a newer. It is acceptable to set to a newer/greater version, however please only do so when you actually need a newer/greater version. Otherwise all Java ebuilds should be set to the current minimum JRE/JDK Version.

About Eclasses
For more information regarding Eclasses, refer to the Eclass writing chapter from the Gentoo Development Guide.

Java specific Eclasses
There are several Java Eclasses available as follows:


 * - Eclass for ant based Java packages, reference
 * - Eclass for Java Packages, reference
 * - Eclass for package with optional Java support, reference
 * - Eclass for Java sources without build instructions or usable/working build system, reference
 * - Base Eclass for Java packages (never used directly in ebuild), reference
 * - Java virtuals Eclass (only used for java virtual packages), reference
 * - Java Virtual Machine Eclass (only used for java vm packages), reference

Which Eclass to use
All Java packages will always inherit. Packages that have optional java support should use. For either of those, if the package has a Ant build system, you will want to also inherit. If the package lacks a build system, or is using an unsupported build system such as Gradle or Maven, then you will want to inherit and use.

The only time you will use  is for a virtual Java package. It is not used for normal Java packages. Do not inherit this class unless this is a virtual package.

The only time you will use  is for Java Virtual Machine packages. It is not used for normal Java packages. Do not inherit this class unless the package is for a Java Virtual Machine.

The  should not be inherited directly from an ebuild EVER! The other eclasses already inherit this eclass, thus no need to ever inherit it directly.

Java Build Systems
Java has a few common build systems, the most common are as follows:


 * ant - Full integration with portage, build system can and should be used
 * gant - No integration with portage, build system cannot be used
 * gradle - No integration with portage, build system cannot be used
 * ivy - No integration with portage, can be bypassed and use ant build system ONLY
 * maven - No integration with portage, build system cannot be used

Which Build System to use
By default try to always use the build system provided by upstream, which may require modifications and/or patching. In the event that does not work, or it is using an unsupported build system such as Gradle or Maven, move on to the next section No Build System.

No Build System
For packages without a build system, or using an unsupported build system. You either need to see about using, or you might even have to write your own Ant build.xml file so you can build the package with Ant. Please do not use the  feature of Maven to generate build.xml files for Ant. These generated files are generic.

Ant
Ant is fully integrated with portage. Java packages that come with an ant build system should use the. Functions provided by the  should simplify the ebuild creation process. Packages that come with an Ant based build system, should NOT use  instead of. There have been cases where ebuild revisions have flipped flopped between eclasses, this policy is seeking to prevent just that. If it ships with an Ant based build system, then use it, DO NOT bypass it for alternative means!

Gant
Gant is not integrated with portage. It is not feasible to use Gant to build Java packages on Gentoo at this time. You may attempt such, but will likely run into other issues. At this time there are no plans for Gant integration into portage. Please refer to the No Build System section.

Gradle
Gradle is not integrated with portage. It is not feasible to use Gradle to build Java packages on Gentoo at this time. You may attempt such, but will likely run into other issues. At this time there are no plans for Gradle integration into portage. Please refer to the No Build System section.

Ivy
Ivy is not integrated with portage. it is not feasible to use Ivy to build Java packages on Gentoo at this time. However Ivy being a dependency resolver usually around an Ant build system. Which means you can bypass, comment out or otherwise, the Ivy portions and proceed with using the rest of the Ant build system. However if Ivy is being used for a build tool other than Ant, then you cannot proceed at all. Please refer to the No Build System section.

Maven
Maven is not integrated with portage. It is not feasible to use Maven to build Java packages on Gentoo at this time. You may attempt such, but will likely run into other issues. At this time there are plans for Maven integration into portage but no ETA. Several efforts have been made to both building Maven from source (bootstrap) and for building packages with Maven. Unfortunately those efforts and work never made it beyond the Java overlay. It has been quite some time since anyone has worked on Maven integration. Though there have been discussions, and some theoretical plans, but no ETA and no one presently working on it. Thus at this time for Maven based packages, please refer to the No Build System section.

Non-Standard
There are many other non-standard build systems such as autoconf, automake, or scripts to build the package. Usually these are for packages where Java parts are optional, and mostly building non-Java based software. However there might be times where software is using Java Native Interface, and might have some non-Java parts to compile. There are others where the package is mostly non-Java but has a part that is Java, and is not using a standard Java build system for the Java portion. Care must be taken in such situations to ensure the Java parts are built correctly. Likely the best thing in such case is to build that Java part with either  or by making a build.xml file for Ant and using. If you attempt to build Java code without using Gentoo Java Eclasses, the result will likely be incorrect, if usable. Please do not bypass Gentoo Java Eclasses for alternative means of building Java packages, code, or pieces.

= Java Filesystem Layout =

In general, the directory policies are handled for you by the helper functions in the java-utils-2 eclass. You may not deviate from this filesystem layout. Do not put jars anywhere else, unless the package requires such!

These functions adhere to the following path name conventions:


 * /usr/share/${PN}-${SLOT}/package.env contains information about the package.
 * .jar files created from source code are installed to /usr/share/${PN}-${SLOT}/lib/
 * .jar pre-built files not compiled by the ebuild are installed to /opt/${PN}-${SLOT}/lib
 * Javadoc documentation is installed to /usr/share/doc/${PF}/html/api/
 * Source archives are installed to /usr/share/${PN}-${SLOT}/source/
 * User-executable scripts are installed to /usr/bin
 * System-wide environment files are in installed to /usr/env.d/java
 * User-specific environment files can be put into ${HOME}/.gentoo/env.d/

Java Jar Repository
At this time Gentoo does not have a central jar repository for use with tools such as Maven. There are plans to create a Gentoo jar repository, likely specific to Maven, but could be used by other tools.