Gentoo Java GuideJoshua NicholsKarl Trygve KallebergJoshua Saddler
This guide will introduce you to Java and explain how to use Java with Gentoo
Linux.
0.92006-09-10What is Java?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, plug-ins for browsers, among other things. A JDK (Java
Development Kit) adds programming tools, such as a bytecode compiler and a
debugger.

New Java System

The way Java is handled on Gentoo has recently seen many changes and
improvements. This has only happened very recently, and as a result, all the
packages related to it are marked with testing keywords, ie ~x86. This
document assumes you are using the new system.

Keywords

If you are using the stable tree opposed to ~arch, you will need to add some
entries to your /etc/portage/package.keywords:

It is crucial that you list ALL these packages in
/etc/portage/package.keywords, otherwise you will have problems in
the later steps of this guide. Your new Java system will not function correctly
without this list.
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.

Installing a Virtual MachineThe choices

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

Vendor

JDK

JRE

The Blackdown Java Kitdev-java/blackdown-jdkdev-java/blackdown-jre

Sun's Java Kitdev-java/sun-jdkdev-java/sun-jre-bin

The IBM Java Kitdev-java/ibm-jdk-bindev-java/ibm-jre-bin

The Compaq Java Kit for Alpha/Linux/GNUdev-java/compaq-jdkdev-java/compaq-jre

BEA WebLogic's J2SE Development Kitdev-java/jrockit-jdk-bin

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.

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

As already mentioned, 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 machineOverview

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:

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.

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

While merging Java packages, the VM can and will be switched as necessary.

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. So to ensure that every
packages merges smoothly, we have defined a list of default/supported
VMs per arch. You can find them in
/usr/share/java-config/config/jdk-defaults.conf. When you are
merging a Java package, and it detects one of the VM in that file is installed,
it will automatically use that VM, instead of the system-vm.

The merge time VM switching is also needed when, for example, your system-vm is
set a 1.4 VM and the package you are merging requires a 1.5 VM. While merging
it will use the preferred 1.5 VM, leaving your system-vm choice intact.

Of course, Gentoo is all about choice, so you can override these defaults in
/etc/java-config-2/build/jdk.conf and have complete control over
which VM will get used. Some examples:

(I always want it to use a sun-jdk, ie sun-jdk-1.4 for 1.4, sun-jdk-1.5 for 1.5, etc)
*=sun-jdk

(Always use sun-jdk-1.5 wherever possible, except for when a 1.4 or 1.3 VM is explicitly required)
*=sun-jdk-1.5

# For 1.3 I prefer sun-jdk 1.4 but when it is not available, use ibm-jdk-bin,
# For 1.4, use blackdown-jdk, and for 1.5, use sun-jdk
1.3=sun-jdk-1.4 ibm-jdk-bin
1.4=blackdown-jdk
1.5=sun-jdk

You do not have to edit this file. If you change these options to use a
unsupported VM, things could possibly break. Bugs reported with a unsupported
VM won't be prioritized as much as bugs present within supported VMs.
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, you define a list your
preference for which compiler to use in
/etc/java-config-2/build/compilers.conf.

# If the ebuild supports it
# it will check the COMPILERS var front to back and
# use the first compiler that is installed
COMPILERS="ecj-3.1 jikes javac"

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

javacjavacN/A
This is the default compiler that will be used, and comes with each JDK.

jikesjikesdev-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 Javaecj-3.1=dev-java/eclipse-ecj-3.1*
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: