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.

For existing installs, regardless of if you have installed anything Java before, make sure you have followed the Java Upgrade Guide.

New installs should require no further preparation.

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

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

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.

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.

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.

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
The following VMs are available for generation-2:
1)      Blackdown JDK 1.4.2.03 [blackdown-jdk-1.4.2]
2)      Blackdown JRE 1.4.2.03 [blackdown-jre-1.4.2]
3)      Blackdown 32bit JRE 1.4.2.03 [emul-linux-x86-java-1.4.2]
4)      Sun 32bit JRE 1.5.0.08 [emul-linux-x86-java-1.5]
5)      Kaffe 1.1.7 [kaffe]
*)      Sun JDK 1.5.0.08 [sun-jdk-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
Now using blackdown-jdk-1.4 as your generation-2 system JVM
(By number)
# java-config --set-system-vm 6
Now using sun-jdk-1.5 as your generation-2 system JVM

As a regular user, you can use java-config --set-user-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-2/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

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:

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

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.

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 the following to your shell's profile. But we would advise against it.

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

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

Portage will allow you to install multiple versions of Java plug-ins, though only one will be used by your browser. You can check the list of available plug-ins by running:

# eselect java-nsplugin list
   [1]   sun-jre-bin-1.5
   [2]   blackdown-jre-1.4.2

In this example, sun-jre-bin is selected for the browser plug-in.

# eselect java-nsplugin set sun-jre-bin-1.5

Verify that the correct plug-in was selected:

# eselect java-nsplugin list
   [1]   sun-jre-bin-1.5  current
   [2]   blackdown-jre-1.4.2

Java.com also provides a link to verify your installed plug-in. Additionally, if you are using a Mozilla-based browser, you can verify your Java plug-in by typing about:plugins into the address bar.

If you are running a mixed 64-bit and 32-bit multilib system (for example, on AMD64), you can have both 64-bit and a 32-bit Java plug-ins installed.

First, check which plug-ins are available:

# eselect java-nsplugin list
Available 32-bit Java browser plugins
  [1]   emul-linux-x86-java-1.4.2
  [2]   emul-linux-x86-java-1.5
Available 64-bit Java browser plugins
  [1]   blackdown-jdk-1.4.2
  [2]   blackdown-jre-1.4.2

You can select a 32-bit plug-in for a 32-bit browser (for example, firefox-bin), and you can select a 64-bit plug-in for your 64-bit browser (for example, konqueror).

# eselect java-nsplugin set 32bit emul-linux-x86-java-1.4.2
# eselect java-nsplugin set 64bit blackdown-jdk-1.4.2

Verify the correct plug-ins were selected:

# eselect java-nsplugin list
Available 32-bit Java browser plugins
  [1]   emul-linux-x86-java-1.4.2  current
  [2]   emul-linux-x86-java-1.5
Available 64-bit Java browser plugins
  [1]   blackdown-jdk-1.4.2  current
  [2]   blackdown-jre-1.4.2

For more information regarding USE flags, refer to the USE flags chapter from the Gentoo Handbook.

• 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.
• For Java packages, the doc flag will build API documentation using javadoc.

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

• 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