Gentoo Java User Guide

1. What 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. is a JRE for each supported OS that runs natively on the OS.

In order to run Java bytecodes, 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.

2. Installing a JRE/JDK

The choices 

Gentoo provides numerous JREs and JDKs. Among the current alternatives, we have:

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

Both the Sun JRE/JDK and the IBM JRE/JDK 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 JRE/JDKs will notify you of where to go to download them.

Installing a JRE/JDKs 

To install your profile's default JDK, you can run emerge virtual/jdk or emerge virtual/jre for the JRE.

Installing the Sun/IBM JRE/JDKs 

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

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

3. Configuring your JRE/JDK

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 JRE/JDK 

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:

# java-config --list-available-vms
1) Blackdown JDK 1.3.1 [blackdown-jdk-1.3] (/etc/env.d/java/20blackdown-jdk-1.3)
2) Blackdown JDK 1.4.2.02 [blackdown-jdk-1.4] (/etc/env.d/java/20blackdown-jdk-1.4)
3) Blackdown JRE 1.4.2.02 [blackdown-jre-1.4] (/etc/env.d/java/20blackdown-jre-1.4)
4) IBM JDK 1.4.2 [ibm-jdk-bin-1.4] (/etc/env.d/java/20ibm-jdk-bin-1.4)
5) IBM JRE 1.4.2 [ibm-jre-bin-1.4] (/etc/env.d/java/20ibm-jre-bin-1.4)
6) WebLogic JRockit 1.4.2.05 [jrockit-jdk-bin-1.4] (/etc/env.d/java/20jrockit-jdk-bin-1.4)
7) WebLogic JRockit 1.5.0.03 [jrockit-jdk-bin-1.5] (/etc/env.d/java/20jrockit-jdk-bin-1.5)
8) Sun JDK 1.3.1.13 [sun-jdk-1.3] (/etc/env.d/java/20sun-jdk-1.3)
9) Sun JDK 1.4.2.09 [sun-jdk-1.4] (/etc/env.d/java/20sun-jdk-1.4)
*) Sun JDK 1.5.0.04 [sun-jdk-1.5] (/etc/env.d/java/20sun-jdk-1.5)
11) Sun JRE 1.4.2.09 [sun-jre-bin-1.4] (/etc/env.d/java/20sun-jre-bin-1.4)
12) Sun JRE 1.5.0.04 [sun-jre-bin-1.5] (/etc/env.d/java/20sun-jre-bin-1.5)

The * indicated 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 pass that handle or the number to java-config --set-system-vm. Here is an example of how to set the system VM.

(By handle)
# java-config --set-system-vm blackdown-jdk-1.4
(By number)
# java-config --set-system-vm 2

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

Preferred VM 

While merging java packages, the vm that is used can and will be changed automatically.

Because of the high number of available vms we do not have the resources to test and make sure 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 and ignore your 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, while leaving your system-vm choice intact.

Off-course its all about choice, you can override these defaults in /etc/java-config/jdk.conf and have complete control over which vm will get used.
Some examples:

# I Always want it to use sun-jdk
*=sun-jdk

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

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.
Here is an example of output:

# 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 name in brackets "[]" are the IDs that you have to pass to java-config --set-system-classpath.
Here is an example:

# java-config --set-system-classpath log4j,xerces-2

You will have to update your environment by relogging in 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 [[ -f "${HOME}/.gentoo/java-env-classpath" ]]; then
       source ${HOME}/.gentoo/java-env-classpath
fi

If you really want a system wide or user default classpath you can add something like like the following to your shell's profile. But we would advice against it.

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

4. 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.

5. Additional resources

Off-line resources 

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

Online resources 

• The gentoo-java, gentoo-user, gentoo-dev mailing list archives
• #gentoo and #gentoo-java on irc.freenode.net
• Wikipedia's entry for Java