Gentoo Java Guide Karl Trygve Kalleberg Joshua Nichols Joshua Saddler This guide will introduce you to Java and explain how to use Java with Gentoo Linux. 0.4 2006-06-24 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.

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.

Installing a JRE/JDK
The choices

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

The Blackdown Java Kitdev-java/backdown-jdkdev-java/blackdown-jreSun's Java Kitdev-java/sun-jdkdev-java/sun-jre-binThe IBM Java Kitdev-java/ibm-jdk-bindev-java/ibm-jre-binThe Compaq Java Kit for Alpha/Linux/GNUdev-java/compaq-jdkdev-java/compaq-jreBEA WebLogic's J2SE Development Kitdev-java/jrockit-jdk-bin
Vendor JDK JRE

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

Both the Sun and the IBM are generally faster, but getting them is a bit more hassle, 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 inform you how to download the appropriate files.

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.

A JDK also includes a JRE, so if you install a JDK you shouldn't have to also have to install a 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 there, you can rerun the emerge command, at which point the JRE/JDK will be begin to install.

Configuring your JRE/JDK
Overview

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 help.
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 * 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.

(By handle (preferred))
# 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.

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 will a lower priority if they aren't present with 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:

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.
Name Handle Package Description
Setting a default CLASSPATH
The options explained in this section should be considered deprecated and will be 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:

# 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:

# 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 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 advise against it.

# export CLASSPATH="${CLASSPATH}:$(java-config --classpath log4j,xerces-2)" 
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 doc flag will typically install API documentation, as generated by javadoc.
  • The source flag will install a zip of the package's source code. This is typically used to provide your IDE with the source code for the package.
Additional resources
Off-line resources
  • java-config man page
  • java-config --help
Online resources
  • The Java Project Page
  • The gentoo-java, gentoo-user, and gentoo-dev mailing list archives
  • #gentoo and #gentoo-java on irc.freenode.net
  • Wikipedia's entry for Java