From Gentoo Wiki
Jump to: navigation, search
Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎日本語 • ‎한국어 • ‎русский

This guide introduces the reader to Java and explains how to use Java with Gentoo Linux.

What is Java?


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.

Installing a virtual machine

The choices

Gentoo provides numerous Java Runtime Environments (JREs) and Java Development Kits (JDKs). The current choices include:

Vendor JDK JRE
The IcedTea Open Java SE (formerly icedtea6-bin) dev-java/icedtea and dev-java/icedtea-bin
Oracle's Java dev-java/oracle-jdk-bin dev-java/oracle-jre-bin
The IBM Java SE dev-java/ibm-jdk-bin dev-java/ibm-jre-bin

Installing a JRE/JDK

To install the profile's default JDK run:

root #emerge --ask virtual/jdk

To install the profile's default JRE run:

root #emerge --ask 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 the ACCEPT_LICENSE variable (found in /etc/portage/make.conf), then the JDK/JRE will be unable to be installed. For more information on how to add acceptable licenses to make.conf read the Licenses chapter of the Portage Handbook.

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

Be aware each JDK will include a JRE; installing a JRE is not necessary if a JDK has been emerged.

Installing fetch-restricted virtual machines

Some of the JDKs and JREs require a few extra steps in their configurations. Emerge the packages as normal. If additional steps are required the ebuilds will provide instruction for the user on where to go and what to download.

Download the indicated file(s) into /usr/portage/distfiles Once the files are in the right directories, rerun the emerge command, at which point the JRE/JDK will be begin to install.

Setting up a headless JRE

Sometimes there is no need for a full JRE with all the capabilities of java. Using java on a server often does not require any GUI, graphical, sound or even printer related features. To install a simplified (sometimes also referred to as headless) JRE, a few USE flags need to be changed.

FILE /etc/portage/package.useRequired USE flag changes
virtual/jre headless-awt -alsa -cups

Depending on the current Gentoo profile, this might already be the case. As usual, the USE flag settings that are applicable to a particular package can be checked by running emerge in pretend mode:

user $emerge --pretend --verbose virtual/jre

Configuring the java virtual machine


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

Using the java-config tool with root privileges, a system-wide default java virtual machine (VM) can be set. Users can also use java-config to custom set their personal VM on a user-by-user basis.

eselect can also be used to change the system and user VM. See eselect java-vm help.

Setting a default virtual machine

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

root #java-config --list-available-vms
The following VMs are available for generation-2:
1)      IcedTea JDK [icedtea-7]
*)      IcedTea JDK 3.0.0_pre07 [icedtea-8]
VMs marked as 'Build Only' may contain security vulnerabilities and/or be end of life (EOL). Gentoo recommends not setting these VMs as the system's or the user's VM. Please see Build Only VM for more information.

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 java-config --set-system-vm 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):

root #java-config --set-system-vm sun-jdk-1.6
Now using sun-jdk-1.6 as your generation-2 system JVM

Alternate method: select VM by number handle number:

root #java-config --set-system-vm 3
Now using sun-jdk-1.6 as your generation-2 system JVM

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

source-ing the profile is no longer needed for updates to the user's or the system's 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 the system or user VM is strongly discouraged as these VMs will then be used when running the /usr/bin/{java,javac,..} 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 /usr/share/java-config-2/config/jdk-defaults.conf.

These defaults can be over written (even the selected system VM) in /etc/java-config-2/build/jdk.conf for complete control over which VM will get used for merging.

For example, to always use a sun-jdk:

FILE /etc/java-config-2/build/jdk.confRequiring 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:

FILE /etc/java-config-2/build/jdk.confRequiring sun-jdk-1.5 for 1.5 VMs

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

FILE /etc/java-config-2/build/jdk.confUsing multiple expressions
1.3=sun-jdk-1.4 ibm-jdk-bin

This file does not have to be edited. If these options are changed to use a unsupported VM, things could possibly break. Because of the wide variety of available VMs, the resources are not available to test and verify every package works on all of them. Bugs reported with a unsupported VM will not be prioritized as much as bugs present within supported VMs.


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 /etc/java-config-2/build/compilers.conf.

FILE /etc/java-config-2/build/compilers.confSetting compiler preferences
COMPILERS="ecj-X.Y jikes javac"

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:

Name Handle Package Description
javac javac N/A This is the default compiler that will be used, and comes with each JDK.
jikes jikes dev-java/jikes Jikes was originally developed by IBM. Anecdotally, it is generally quicker than javac. Note however, that it is more pedantic, and will fail under a few circumstances where javac has no issue. It also does not support Java 1.5 syntax yet.
Eclipse Compiler for Java ecj dev-java/eclipse-ecj ECJ is the compiler used by the Eclipse software development kit. It is very full featured, and is pretty fast. It does support Java 1.5 syntax.

Setting a default CLASSPATH

The options explained in this section should be considered deprecated and will most likely be removed in the future. It is strongly recommended against using these, because Java projects or applications should ideally manage their own classpaths. When choosing to specify a default CLASSPATH, some applications may behave unexpectedly, because classes they were not expecting to be on the 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 CLASSPATH variable. Here is an example of output:

root #java-config --list-available-packages
[xerces-2] The next generation of high performance, fully compliant XML parsers in the Apache Xerces family (/usr/share/xerces-2/package.env)
[junit] Simple framework to write repeatable tests (/usr/share/junit/package.env)
[bsh] BeanShell: A small embeddable Java source interpreter (/usr/share/bsh/package.env)
[bcel] The Byte Code Engineering Library: analyze, create, manipulate Java class files (/usr/share/bcel/package.env)
[log4j] A low-overhead robust logging package for Java (/usr/share/log4j/package.env)

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

root #java-config --set-system-classpath log4j,xerces-2
The current directory (.) will not be part of the system classpath, as that should be added to the system's login profile.

Update the environment by logging out, then in again or by typing source /etc/profile

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

CODE Sourcing user specific classpath
if [[ -f "${HOME}/.gentoo/java-env-classpath" ]]; then
       source ${HOME}/.gentoo/java-env-classpath

If desiring a system wide or user default classpath add something like the following to the shell's profile. This is advised against:

root #export CLASSPATH="${CLASSPATH}:$(java-config --classpath log4j,xerces-2)"

Java browser plugins

Installing a plugin

It is possible to install a Java plugins for a web browsers by emerging a Java VM with the nsplugin USE flag set.

nsplugin is not available for all architectures. Check for available plugins for the specific arch before trying to install a VM by running emerge -pv <java-vm>

Portage will allow installations of multiple Java plugins versions, though only one will be used by the web browser. Check the list of available plugins by running:

root #eselect java-nsplugin list
   [1]   sun-jre-bin-1.6
   [2]   icedtea-bin

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

root #eselect java-nsplugin set sun-jre-bin-1.6

Verify that the correct plugin was selected:

root #eselect java-nsplugin list
   [1]   sun-jre-bin-1.6  current
   [2]   icedtea-bin also provides a link to verify the installed plugin. Additionally, if a Mozilla-based browser is being used, verification of the Java plugin can be performed by typing about:plugins into the address bar.

Plugins on multilib systems

If running a mixed 64-bit and 32-bit multilib system (for example, on amd64), use both 64-bit and 32-bit Java plugins. Unless there is a pressing need to run 32-bit Java applications, users have been recommended to use native 64-bit plugins on 64-bit web browsers.

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

root #echo "dev-java/sun-jre-bin nsplugin" >> /etc/portage/package.use
root #emerge sun-jre-bin

To use a 32-bit plugin on a 32-bit browser, the app-emulation/emul-linux-x86-java package will need to be emerged with nsplugin USE enabled.

root #echo "app-emulation/emul-linux-x86-java nsplugin" >> /etc/portage/package.use
root #emerge emul-linux-x86-java

Next, check which plugins are available:

root #eselect java-nsplugin list
Available 32-bit Java browser plugins
  [1]   emul-linux-x86-java-1.5
  [2]   emul-linux-x86-java-1.6
Available 64-bit Java browser plugins
  [1]   icedtea-bin
  [2]   sun-jre-bin-1.6

Now select the right plugin for the browser:

root #eselect java-nsplugin set 32bit emul-linux-x86-java-1.6
root #eselect java-nsplugin set 64bit sun-jre-bin-1.6

Verify the correct plugin was selected:

root #eselect java-nsplugin list
Available 32-bit Java browser plugins
  [1]   emul-linux-x86-java-1.5
  [2]   emul-linux-x86-java-1.6  current
Available 64-bit Java browser plugins
  [1]   icedtea-bin
  [2]   sun-jre-bin-1.6  current

USE flags for use with Java

Setting USE flags

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

USE flags

  • The java flag adds support for Java in a variety of programs;
  • The nsplugin flag adds support for Mozilla-like browsers (including Firefox). This is needed for viewing Java applets in a Mozilla-like browser;
  • The jce flag adds support for the Java Cryptography Engine;

Following USE flags go in JAVA_PKG_IUSE.

  • The source 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 doc flag will build API documentation using javadoc.

See also

External resources

More information can be found offline:

  • man java-config
  • java-config --help

For suggestions or questions regarding this document, please email the Gentoo Java team:

This article is based on a document formerly found on our main website
The following people contributed to the original document: Joshua Nichols, Karl Trygve Kalleberg, Joshua Saddler
They are listed here as the Wiki history does not allow for any external attribution. If you edit the Wiki article, please do not add yourself here; your contributions are recorded on the history page.