From Gentoo Wiki
Revision as of 14:38, 24 March 2014 by Totktonada (Talk | contribs) (brief run-java-tool mention)

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

This guide will introduce you to Java and explain 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 Runtime Environments (JREs) and Development Kits (JDKs). Among the current choices, we have:

Vendor JDK JRE
The IcedTea Open Java SE (formerly icedtea6-bin) dev-java/icedtea-bin
Oracle's Java 7 SE dev-java/oracle-jdk-bin dev-java/oracle-jre-bin
Sun's Java 6 SE (masked, inactive after Oracle aquired Sun) dev-java/sun-jdk dev-java/sun-jre-bin
The IBM Java SE dev-java/ibm-jdk-bin dev-java/ibm-jre-bin

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 /etc/portage/make.conf, then you won't be able to install the JDK/JRE. For more information on how to add acceptable licenses to make.conf, 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.

A JDK also includes a JRE, so if you install a JDK you shouldn't have to also have to install a JRE.

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 /usr/portage/distfiles . Once there, you can rerun the emerge command, at which point the JRE/JDK will be begin to install.

Configuring your virtual machine


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.

You can also use eselect to change the system and user vm. See eselect java-vm help.

Setting a default virtual machine

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

root #java-config --list-available-vms
The following VMs are available for generation-2:
1)      IcedTea-bin 1.10.4 [icedtea-bin]
2)      Sun JDK [sun-jdk-1.5] (Build Only)
*)      Sun JDK [sun-jdk-1.6]

VMs marked as Build Only may contain security vulnerabilities and/or be EOL. Gentoo recommends not setting these VMs as either your system or user VM. Please see Build Only VM for more information.

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. You use the handle or the number to java-config --set-system-vm. Here is 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

You can also select it by number:

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

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

You no longer have to source the profile for updates to the user/system VM take place.

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 /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, your system-vm is set to a 1.6 VM and the package you are merging requires a 1.5 VM. While merging it will select and use a 1.5 VM, leaving your system-vm choice intact.

To define which VM is selected when a switch is needed, we have created a list of default/supported VMs per arch. You can find them in /usr/share/java-config-2/config/jdk-defaults.conf.

You can override these defaults (and even your selected system VM) in /etc/java-config-2/build/jdk.conf and have 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


This is a deprecated template. Help us update this template!

Or, 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


This is a deprecated template. Help us update this template!

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 is a deprecated template. Help us update this template!

You do not have to edit this file. If you change these options to use a unsupported VM, things could possibly break. Because of the wide variety of available VMs, we do not have the resources to test and verify every package works on all of them. Bugs reported with a unsupported VM won't 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, you define a list your 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"

This is a deprecated template. Help us update this template!

Some compilers don't 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. We strongly recommend against using these, because your Java projects or application should ideally manage their own classpaths. If you choose to specify a default CLASSPATH, some applications may behave unexpectedly, because classes they weren't expecting would 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, 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:

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 that you have 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 in your system's login profile.

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.

CodeSourcing user specific classpath

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

This is a deprecated template. Help us update this template!

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.

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

Java Browser Plugins

Installing a plugin

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

nsplugin is not available for all architectures. Check for available plugins on your arch before trying to install a VM by runningemerge -pv <java-vm>.

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:

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 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, sun-jdk and sun-jre-bin, both include browser plugins. Just emerge one of them with the nsplugin USE flag 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, you will need to emerge emul-linux-x86-java with the nsplugin USE flag 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 your browsers:

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.

The flags

  • The java flag adds support for Java in a variety of programs
  • The nsplugin flag adds support for Mozilla-like browsers (including Firefox). You will need this for viewing Java applets in your Mozilla-like browser.
  • 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 you are using.
  • The jce flag adds support for the Java Cryptography Engine
  • For Java packages, the doc flag will build API documentation using javadoc.

Additional resources

Off-line resources

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

Online resources


We would like to thank the following authors and editors for their contributions to this guide:

  • Joshua Nichols
  • Karl Trygve Kalleberg
  • Joshua Saddler