Gentoo Java Upgrade Guide

1.  Introduction

Hello and welcome. About now, you may be asking 'why would I want to upgrade my Java?' Or perhaps, you began the process and got directed to this page by an error during a merge? Regardless, the purpose of this document is to help you along with upgrading to the new Java system. Ah, but what is up with this new Java system?

The new Java system

For those not familar with the new Java system, here is a laundry list of new features:

• Ability to switch the current VM on the fly
• Changes to the user and system VM take effect immediately, and no longer are tied to the shell environment (ie no more running env-update && source /etc/profile after switching the sytem VM)
• Now has the concept of a 'build VM', which is used to emerge packages, and is configured independently of the system VM.
• For each version of Java, ie 1.3, 1.4, 1.5, etc, the build vm can configured as to which vendor and version of a VM to use
• The VM at emerge time will be switched on the fly according to its configuration, as well as the dependency of the package. For example, some packages won't compile with 1.5. In these cases, a 1.4 VM will be used at build time.
• Java packages which build with ant will have their build.xml rewritten at build time, in order to ensure that the correct version of Java bytecode is compiled.
• Java 1.5 is unmasked, after some time being package.masked
• Java 1.6 will be made available as soon as it is released.

Terminology / Concepts

Now that you have an idea of what you're getting to... here are a few terms and concepts 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 on your system and in the portage tree. So, for example, you would have a system vm set for Generation 1 and a system vm for Generation 2. By doing this, packages that use Generation 1 and Generation 2 can coexist while migrating to the new generation.

Generation 1

This generation consists of the existing eclasses (java-pkg, java-utils, and java) and java-config-1. Generation 1 is legacy system that is being phased out.

Generation 2

This generation consists of the new eclasses (java-pkg-2, java-pkg-opt-2, java-ant-2, and java-utils-2) and the new version of java-config. This is the generation that we are migrating towards.

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 --set-system-vm <choice of vm>.

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 merge time for building Java packages. It is changed as necessary depending on the package. For example, if a package only compiles with 1.4, a 1.4 VM will be used. 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.

2.  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 -1 java-config:0 java-config:2

3.  Check your environment

We now provide a new script, java-check-environment. This, as the name may imply, checks the health of your system's Java environment. It then suggests what actions that you should take to fix any problems found. So now run:

# java-check-environment

If java-check-environment encounters a problem, it will stop and tell you about it, and how to fix it. Follow the advice given, and then rerun java-check-environment until it does not find any other problems.

4.  Upgrade... complete!

If you've gotten this far, then you have succesfully upgraded to the new Java system. Congratulations!

Now that you've upgraded, you may want to take a look at our updated documentation:

• User Guide
• Developer Guide

5.  Common Issues and Questions

To address common problems experienced when upgrading, the Java team has setup a wiki page here. Before seeking help or reporting issues elsewhere, please refer to this page.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.