Gentoo Java Packing Policy

This policy is the official Gentoo Java Packing Policy and Guidelines for packaging Java applications and libraries for Gentoo Linux.

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

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 USE flags
For more information regarding USE flags, refer to the USE flags chapter from the Gentoo Development Guide.

Java specific USE flags
There are a few specific common USE flags for Java ebuilds.


 * The  flag will build API documentation using javadoc.
 * The  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;
 * The  flag will run JUnit tests against the package (tests are not installed)

Java USE flags usage
For Java ebuilds, the previously mentioned common USE flags do not go in their normal location. Instead they go in a Java specific USE flag/variable. Any other USE flags will go in their normal location. The  USE flag/variable MUST reside in the ebuild before the inherit line.

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
 * gradle - No integration with portage, build system cannot be used
 * 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.