Gentoo Java Upgrade Guide
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.
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
- 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
Additionally, the Build VM can be configured by
A new package, java-config-wrapper, is blocked by old versions of
java-config, so we should remove that first:
Code Listing 2.1: Remove old java-config
# emerge -C java-config
Now we should install the new versions of java-config:
Code Listing 2.2: Install new java-config
# emerge -1 java-config:0 java-config:2
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:
Code Listing 3.1: Check your 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.
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:
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, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.