Gentoo Java Guide

1. Installing a JDK/JRE

Overview 

Gentoo provides numerous JDKs and JREs. The default is the Blackdown JDK/JRE pair, as it is freely (beer) available without any registration fuss.

Both the Sun JDK/JRE and the IBM JDK/JRE 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).

Our ebuilds for the Sun and IBM JDK/JREs will notify you of where to go to download them.

Installing the Sun/IBM JDK/JREs 

If you run emerge sun-jdk-1.3.1 or emerge ibm-jdk-1.3.1, you will be notified that you are required to download the actual tarballs yourself. This has to do with license restrictions for the Sun JDK/JRE (online click-wrap license) and registration issues with the IBM JDK/JRE.

You should download the indicated file(s) into /usr/portage/distfiles. Once that is done, you can rerun the emerge command, then the JDK/JRE will be installed properly into /opt.

2. Configuring your JDK/JRE

Overview 

Gentoo has the ability to have multiple JDKs and JREs installed without them conflicting.

Using the java-config tool, you can set the system-wide default if you have root access. Users can also use java-config to set up their own personal default, that is different from the system-wide default.

Setting a default JDK/JRE 

Running the command java-config --list-available-vms will give you a list of all available JREs and JDKs on your system, thus:

# java-config --list-available-vms
[blackdown-jdk-1.3.1] Blackdown JDK 1.3.1 (/etc/env.d/java/20blackdown-jdk-1.3.1)
[blackdown-jre-1.3.1] Blackdown JRE 1.3.1 (/etc/env.d/java/20blackdown-jre-1.3.1)
[ibm-jdk-1.3.0] IBM JDK 1.3.0 (/etc/env.d/java/20ibm-jdk-1.3.0)
[ibm-jdk-1.3.1] IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1)
[ibm-jre-1.3.1] IBM JRE 1.3.1 (/etc/env.d/java/20ibm-jre-1.3.1)
[sun-jdk-1.4.0] Sun JDK 1.4.0 (/etc/env.d/java/20sun-jdk-1.4.0)

The name in the brackets "[]" is the handle or ID for that particular VM. You use pass that ID to java-config --set-system-vm, thus:

# java-config --set-system-vm=ibm-jdk-1.3.1
Now using IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1)

Once you have issued java-config --set-system-vm with a particular VM ID, you will need to regenerate your /etc/profile.env, thus:

# env-update

After this, you will either want to relogin, or resource /etc/profile into your environment.

As a regular user, you can use java-config --set-user-vm, which will create $HOME/.gentoo/java-env with all required env vars. You would normally source this from your shell's startup script ($HOME/.zshenv in my case).

Setting a default CLASSPATH 

java-config can also be used to set a system-wide default CLASSPATH, and of course a user-specific default CLASSPATH.

First you want to list available java libraries that might be interesting to put in your CLASSPATH, thus:

# java-config --list-available-packages
[ant] No description (/usr/share/ant/classpath.env)
[java-gnome] No description (/usr/share/java-gnome/classpath.env)
[java-gtk] No description (/usr/share/java-gtk/classpath.env)
[log4j] "" (/usr/share/log4j/package.env)

Again, the name in brackets "[]" are the IDs that you have to pass to java-config --set-system-classpath, thus:

# java-config --set-system-classpath=log4j,java-gtk,java-gnome

Again, you will want to run env-update to update your system's environment, and you might also want to relogin or resource the /etc/profile.

For users, java-config --set-user-classpath will create $HOME/.gentoo/java-env-classpath, which is automatically included by $HOME/.gentoo/java-env.

3. Additional resources

Off-line resources 

• java-config man page
• java-config --help
• The /usr/bin/java-config script itself

Online resources 

• The gentoo-dev, gentoo-user mailing list archives
• #gentoo and #gentoo-java on irc.freenode.net