Java

This guide will introduce you to Java and explain how to use Java with Gentoo Linux.

Overview
Java is a programming language developed by engineers of Sun Microsystems. The language is object-oriented and designed to run on multiple platforms without the need of recompiling code for each platform. Although Java can be compiled as a native program, much of Java's popularity can be attributed to its portability, along with other features such as garbage collection. To make platform independence possible the Java compiler compiles the Java code to an intermediate representation called "Java bytecode" that runs on a JRE (Java Runtime Environment) and not directly on the operating system.

In order to run Java bytecode, one needs to have a JRE (Java Runtime Environment) installed. A JRE provides core libraries, a platform dependent Java Virtual Machine, plugins for browsers, among other things. A JDK (Java Development Kit) adds programming tools, such as a bytecode compiler and a debugger.

The choices
Gentoo provides numerous Runtime Environments (JREs) and Development Kits (JDKs). Among the current choices, we have:

Installing a JRE/JDKs
To install your profile's default JDK, you can run emerge virtual/jdk. Or to install your profile's default JRE, you can emerge virtual/jre.

Some JDKs and JREs, including the Sun packages, require accepting an End User License Agreement, or EULA. If its license (such as dlj-1.1) is not listed in ACCEPT_LICENSE in, then you won't be able to install the JDK/JRE. For more information on how to add acceptable licenses to, please read the Portage Handbook.

To avoid any restrictive license hassle, consider installing icedtea-bin, which is an open Java implementation from the OpenJDK project.

Installing fetch-restricted virtual machines
Some of the JDKs and JREs require you to jump through a few hoops before installing. Simply emerge the packages as you normally would. The ebuilds will then instruct you where to go and what to download.

You should download the indicated file(s) into. Once there, you can rerun the emerge command, at which point the JRE/JDK will be begin to install.

Overview
Gentoo has the ability to have multiple JDKs and JREs installed without causing conflicts.

Using the java-config tool, you can set the system-wide default (provided you have root access). Users can also use java-config to set up their own personal default.

Setting a default virtual machine
Running the command java-config --list-available-vms will output a list of all JREs and JDKs installed on the system. Here is an example of output:

The * indicates this is the current active vm (system-vm or user-vm when set). The name in the brackets ([]) is the handle or ID for that particular VM. The handle or the number to java-config --set-system-vm can be used to set the vm. Here is an example of how to set the system VM.

Setting the system VM by handle (preferred):

Alternate method: select vm by number handle number:

As a regular user, use java-config --set-user-vm.

Build Only VM
Some virtual machines are flagged as build-only due to being EOL and/or containing security vulnerabilities. These virtual machines will not automatically be used by Gentoo for the running of applications using Gentoo launchers (run-java-tool script designed for switching VMs), but will still be available for use by Gentoo's build environment as some packages may require them for building. The setting of these virtual machines as either your system or user VM is strongly discouraged as these VMs will then be used when running the executables, as well as used by any packages not using Gentoo's launcher scripts.

Preferred Build VM
While merging Java packages, the VM used for building can sometimes be different from the one currently set as the system VM.

This merge time VM switching is needed when, for example, the system-vm is set to a 1.6 VM and the package being merge requires a 1.5 VM. While merging it will select and use a 1.5 VM, leaving the system-vm choice intact.

To define which VM is selected when a switch is needed, a list of default/supported VMs per arch has been created. It can be found in.

These defaults can be over written (even the selected system VM) in for complete control over which VM will get used for merging.

For example, to always use a sun-jdk:

Or, to always use sun-jdk-1.5 wherever possible, except for when a 1.4 or 1.3 VM is explicitly required:

Or to use different providers for different versions, such as requiring  if a 1.3 (yes, 1.3) VM is asked, and fall back to ibm-jdk-bin otherwise:

Compilers
The standard Java compiler used for building is javac, which comes with each JDK. In addition to configuring the VM used at build time, it is also possible configure which compiler is used. Essentially, define a list with preference for which compiler to use in.

Some compilers do not support all possible -target and -source arguments. Therefore, each compiler in the list is checked to see if it can support the desired -source/-target. javac will work in all cases, so if no other suitable compiler is found, it will be used instead.

More details about each compiler are provided below:

Setting a default CLASSPATH
java-config can also be used to set a system-wide default CLASSPATH, as well a user-specific default CLASSPATH.

First, list available Java libraries installed on the system to possibly put in the  variable. Here is an example of output:

Again, the names in brackets ([]) are the IDs to pass to java-config --set-system-classpath. Here is an example:

Update the environment by logging out, then in again or by typing source.

For users, java-config --set-user-classpath will create, which should then source from the shell's profile.

If you really want a system wide or user default classpath you can add something like the following to your shell's profile. But we would advise against it.

Installing a plugin
You can install a Java plugin for your web browser by emerging a Java VM with the  USE flag set.

Portage will allow you to install multiple versions of Java plugins, though only one will be used by your browser. You can check the list of available plugins by running:

In this example, sun-jre-bin is selected for the browser plugin.

Verify that the correct plugin was selected:

Java.com also provides a link to verify your installed plugin. Additionally, if you are using a Mozilla-based browser, you can verify your Java plugin by typing about:plugins into the address bar.

Plugins on multilib systems
If you are running a mixed 64-bit and 32-bit multilib system (for example, on AMD64), you can use 64-bit and 32-bit Java plugins. Unless you have a pressing need to run 32-bit Java applications, we recommend using native 64-bit plugins on 64-bit web browsers.

There are several native 64-bit browser plugins available. The default JDK/JRE pair,  and , both include browser plugins. Just emerge one of them with the  USE flag enabled.

To use a 32-bit plugin on a 32-bit browser, you will need to emerge with the   USE flag enabled.

Next, check which plugins are available:

Now select the right plugin for your browsers:

Verify the correct plugin was selected:

Setting USE flags
For more information regarding USE flags, refer to the USE flags chapter from the Gentoo Handbook.

The flags

 * The  flag adds support for Java in a variety of programs
 * The  flag adds support for Mozilla-like browsers (including Firefox). You will need this for viewing Java applets in your Mozilla-like browser.
 * The  flag installs a zip of the source code of a package. This is traditionally used for IDEs to 'attach' source to the libraries you are using.
 * The  flag adds support for the Java Cryptography Engine
 * For Java packages, the  flag will build API documentation using javadoc.

Off-line resources

 * java-config man page
 * java-config --help

Online resources

 * The Java Project Page
 * The gentoo-java, gentoo-user, and gentoo-dev mailing list archives
 * #gentoo and #gentoo-java on IRC
 * Wikipedia's entry for Java
 * If you have suggestions or questions regarding this document, please email the Gentoo Java team: