Gentoo Java Guide

-0.3 -2005-12-12 +0.4 +2006-06-24 What is Java? @@ -32,21 +34,22 @@

-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. -The ability to compile once and run in various platforms is achieved through -the use of just-in-time compilers (JIT), which compile Java bytecodes into -native code when a given program is run. +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 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. +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.

@@ -60,55 +63,98 @@

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

blackdown-jre and blackdown-jdk, the Blackdown Java Kit
sun-jre-bin and sun-jdk, Sun's Java Kit
ibm-jre-bin and ibm-jdk-bin, the IBM Java Kit
compaq-jre and compaq-jdk, the Compaq Java Kit for Alpha/Linux/GNU
jrockit-jdk-bin, BEA WebLogic's J2SE Development Kit

- -

-The default is the Blackdown JRE/JDK -pair, as it is freely ("free as in beer") available without any registration -fuss. + + + + + + + + The Blackdown Java Kit + dev-java/backdown-jdk + dev-java/blackdown-jre + + + Sun's Java Kit + dev-java/sun-jdk + dev-java/sun-jre-bin + + + The IBM Java Kit + dev-java/ibm-jdk-bin + dev-java/ibm-jre-bin + + + The Compaq Java Kit for Alpha/Linux/GNU + dev-java/compaq-jdk + dev-java/compaq-jre + + + BEA WebLogic's J2SE Development Kit + dev-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 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). +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 notify you of where to go to -download them. +Our ebuilds for the Sun and IBM JRE/JDKs will inform you how to download the +appropriate files.

-Installing the Sun/IBM JRE/JDKs +Installing a JRE/JDKs

-If you run emerge =sun-jdk-1.4.2.06 or =ibm-jdk-bin-1.4.2, you will -be notified that you are required to download the actual tarballs 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. +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.

-ibm-jdk-bin is currently masked, you may have to unmask it to use it. +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 that is done, you can rerun the emerge -command, then the JRE/JDK will be installed properly into /opt. +/usr/portage/distfiles. Once there, you can rerun the emerge +command, at which point the JRE/JDK will be begin to install.

@@ -122,75 +168,280 @@

-Gentoo has the ability to have multiple JDKs and JREs installed without them -conflicting. +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 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. +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 available JREs and JDKs on your system. Here is an example of output: +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
-[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)
+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 name in the brackets "[]" is the handle or ID for that -particular VM. You use pass that ID to java-config --set-system-vm. Here is -an example of how to set the system VM. +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.

-# 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)
+(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 will have to be root to run --set-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. +

-Once you have issued java-config --set-system-vm with a particular VM -ID, you will need to regenerate your /etc/profile.env. You can do -it like this: +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.

-# env-update +

+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 +

+ +

-After this, you will either want to relogin, or resource -/etc/profile into your environment. +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"
+

-As a regular user, you can use java-config --set-user-vm, which will -create ~/.gentoo/java-env with all required env vars. You would -normally source this from your shell's startup script (generally -~/.bashrc). +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: +

+ + + + + + + + + + javac + javac + N/A + + This is the default compiler that will be used, and comes with each JDK. + + + + jikes + jikes + dev-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 Java + ecj-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)" 
+

@@ -214,12 +465,20 @@

The java flag adds support for Java in a variety of programs.
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 nsplugin flag adds a symlink to the javaplugin for - Mozilla-like browsers (including Firefox) if you are using, for example, - Blackdown's Java kit, IBM Java Kit or Sun's Java Kit. 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.

@@ -236,7 +495,6 @@

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

@@ -246,13 +504,17 @@

The Gentoo Java Project Page
+ The Java Project + Page +
The gentoo-dev, - gentoo-user - and gentoo-java + link="http://news.gmane.org/gmane.linux.gentoo.java">gentoo-java, + gentoo-user, and + gentoo-dev mailing list archives
#gentoo and #gentoo-java on irc.freenode.net