Gentoo Java Upgrade Guide

1.0 2006-06-24 Before you start

Here are some terms you might find useful before starting.

Generation

This is a new concept. The idea is that a generation is a set of tools and eclasses for building Java packages. So at some point, we begin migrating from the existing generation to a new one. During this time, both generations coexist. So, for example, you would have a system vm set for Generation X _and_ a system vm for Generation X+1. By doing this, packagesthat use Generation X and Generation X+1 can coexist while migrating to the new generation.

Generation 1

This generation consists of the existing java-pkg and java eclasses and java-config-1.x

Generation 2

This is the new generation that has been in development for nearly a year.

Generation 1 System VM

This is the VM that is used to emerge Java packages using the eclasses from Generation 1. It is set using java-config-1 -S

Generation 2 System VM

With Generation 2, the System VM is only used for root and for users that haven't set a user VM.

Generation 2 Build VM

Generation 2 introduces a new class of VM. The Build VM is used at build time to build Java packages. By default, packages will attempt to use the lowest VM possible. The vendor used depends on the platform. These defaults are defined at /usr/share/java-config-2/config/jdk-defaults.conf. Additionally, the Build VM can be configured by /etc/java-config-2/build/jdk.conf.

Keywords

If you are using the stable tree, ie x86, ppc, or amd64 as opposed to ~x86, ~ppc, or ~amd64, you will need to add some entries to your /etc/portage/package.keywords:

        =sys-apps/portage-2.1*
        dev-java/ant-core
        dev-java/ant-tasks
        dev-java/ant
        dev-java/blackdown-jdk
        dev-java/blackdown-jre
        dev-java/eclipse-ecj
        dev-java/ibm-jdk-bin
        dev-java/ibm-jre-bin
        dev-java/java-config
        dev-java/java-config-wrapper
        dev-java/javatoolkit
        dev-java/jikes
        dev-java/jrockit-jdk-bin
        dev-java/kaffe
        dev-java/sun-jdk
        dev-java/sun-jre-bin

Update java-config

A new package, java-config-wrapper, is blocked by old versions of java-config, so we should remove that first:

        emerge -C java-config

Now we should install the new versions of java-config:

        emerge =java-config-1* =java-config-2*

Check your environment

We now provide a new script, /usr/bin/java-check-environment. This, as the name may imply, checks the java environment. It then suggests what actions that you should take to fix any problems found. So now run...

        /usr/bin/java-check-environment

which leads us to...

Update Virtual machines

The first section checks for old java-config files in /etc/env.d/java. The instructions should be self-explanatory. Just remove the files it indicates. After that, re-merge the packages that it indicates.

Delete old user configs

The next section that java-check-environment will friendily warn you about is that you have Generation-1 configurations in your home directory. These files are no longer supported in their current form. As advised, you should run:

            java-config-2 -L
            java-config-2 -s

Make sure you have a Generation-1 system-vm set

The next possible set of errors is that you don't have a Generation-1 System VM. For axxo-overlay users, you most likely don't have this. To fix this, run:

            java-config-1 -L
            java-config-1 -S

Of course, as per usual, you will need to run

            env-update && source /etc/profile

To make sure you get the right environment.

1.5 JDK set as your Generation-1 VM

The next check is if you have a 1.5 JDK for a system vm for Generation-1. You should be using a 1.4 JDK instead. If you have been following this guide to this point, simply follow the instructions above for setting a new system vm for Generation-1.

Chances are good that you have some bytecode compiled for 1.5. This can lead to problems with UnsupportedClassVersionErrors?. To attempt to fix this, try running:

            /usr/bin/java-1.5-fixer

Known Issues

Applications try to use JAVA_HOME, which is set to the Generation-1 VM

Some applications figure out how to call java from JAVA_HOME. As is, JAVA_HOME will be what your system-vm for generation-1 is set to (ie /etc/env.d/20java). This will be an issue until the particular application is converted to using the new eclasses.

One workaround is to do the following to set JAVA_HOME:

        if [[ -L $HOME/.gentoo/java-config-2/current-user-vm ]]; then
           export JAVA_HOME=$HOME/.gentoo/java-config-2/current-user-vm
        elif [[ -L /etc/java-config-2/current-system-vm ]]; then
           export JAVA_HOME=/etc/java-config-2/current-system-vm
        fi

You could include this in your .bash_profile, but it isn't recommended. This is because you remain tethered to your environment, which the new system helps eliminate. For example, if you don't have a user-vm set, you'll get the system-vm. If you later set a user-vm, you'll need to source ~/.bash_profile to get the right JAVA_HOME.

DO NOT USE THIS IN YOUR ROOT USER'S bash_profile!!! It will likely break generation-1 packages if you have a 1.5 VM as the generation-2 system vm.

The better approach would be to migrate the application to the new build system, and ensure that it works properly. If you do run into any particular applications that suffer from this problem, please contact nichoj in #gentoo-java or drop a message to the gentoo-java mailing list.