Java User Guide

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.

Existing installs
For existing installs, regardless of if you have installed anything Java before, make sure you have followed the Java Upgrade Guide.

New installs
New installs should require no further preparation.

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

The default for Java 1.4 is the Blackdown JRE/JDK pair, as it is freely ("free as in beer") available without any registration fuss.

JREs and JDKs from Sun, IBM, and BEA are generally faster, but getting them is a bit more work, as you are required to read and accept their license before downloading (IBM additionally requires you to register).

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.

In recent events, Sun has relicensed their JDK and JRE under a more Linux distro friendly license. As a result, Sun releases Java 1.5 and onwards are freely downloadable, without any further hassle.

Setting a default virtual machine
Running the command with the   option will output a list of all JREs and JDKs installed on the system. Here is an example of the output:

The * indicates this is the current active JVM (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 can be used to set the VM. The following text provides an example of how to set the system VM.

Setting the System VM by handle (preferred):

lternate method: select VM by number handle number:

As a regular user, use java-config.

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, you will want to list available Java libraries installed on your system that might want to be put in your CLASSPATH. Here is an example of output:

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

You will have to update your environment by logging out, then in again or sourcing /etc/profile.

For users, java-config --set-user-classpath will create ~/.gentoo/java-env-classpath, which you should then source from your 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.

Setting classpath:

Java browser plugins
The Java browser plugin used to be managed via. This has now been removed in favor of a simpler out-of-the-box experience. For basic usage, simply emerge the chosen JVM with the  USE flag enabled. Note that Oracle's plugin is only available for and.

Also note that Chromium-based browsers no longer support NPAPI-based plugins since the code was removed in September 2015. The list of supporting browsers is shrinking but still includes Firefox as of version 46.

For more information, including JVM selection, Web Start, and multilib, see the README installed with icedtea-web.

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). This is needed for viewing Java applets in a Mozilla-like browser;
 * The flag adds support for the Java Cryptography Engine;

Following USE flags go in JAVA_PKG_IUSE.
 * 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;
 * For Java packages, the flag will build API documentation using javadoc.

External resources

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