Gentoo Java Upgrade

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE guide SYSTEM "/dtd/guide.dtd"><guide link="/doc/en/java_upgrade_guide.xml" lang="en"><title>Gentoo Java Upgrade Guide</title><author title="Author">  <mail link="nichoj@gentoo.org">Joshua Nichols</mail></author><author title="Author">  <mail link="kartk@gentoo.org">Karl Trygve Kalleberg</mail></author><abstract>  This guide shows you how to upgrade java to the new generation of java on Gentoo.  Along with related concepts and tools.</abstract><!-- The content of this document is licensed under the CC-BY-SA license --><!-- See http://creativecommons.org/licenses/by-sa/2.5 --><license/><version>1.0</version><date>2006-06-24</date><chapter>  <title>Before you start</title>  <section>    <body>      <p>        Here are some terms you might find useful before starting.      </p>      <dl>        <dt>Generation</dt>        <dd>          <ul>            <li>              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.            </li>          </ul>        </dd>        <dt>Generation 1</dt>        <dd>          <ul>            <li>              This generation consists of the existing java-pkg and java eclasses and              java-config-1.x             </li>          </ul>        </dd>        <dt>Generation 2</dt>        <dd>          <ul>            <li>              This is the new generation that has been in development for nearly a year.             </li>          </ul>        </dd>      </dl>      <dl>        <dt>Generation 1 System VM</dt>        <dd>          <ul>            <li>              This is the VM that is used to emerge Java packages using the eclasses from              Generation 1. It is set using <c>java-config-1 -S <choice of vm></c>            </li>          </ul>        </dd>        <dt>Generation 2 System VM</dt>        <dd>          <ul>            <li>              With Generation 2, the System VM is only used for root and for users that              haven't set a user VM.            </li>          </ul>        </dd>        <dt>Generation 2 Build VM</dt>        <dd>          <ul>            <li>              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 <path>/usr/share/java-config-2/config/jdk-defaults.conf</path>. Additionally,              the Build VM can be configured by              <path>/etc/java-config-2/build/jdk.conf</path>.             </li>          </ul>        </dd>      </dl>    </body>  </section></chapter><chapter>  <title>Keywords</title>  <section>    <body>      <p>        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        <path>/etc/portage/package.keywords</path>:      </p>      <pre caption="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      </pre>    </body>  </section></chapter><chapter>  <title>Update java-config</title>  <section>    <body>      <p>        A new package, java-config-wrapper, is blocked by old versions of java-config,        so we should remove that first:      </p>      <pre caption="Remove old java-config">        emerge -C java-config      </pre>      <p>        Now we should install the new versions of java-config:      </p>      <pre caption="Install new java-config">        emerge =java-config-1* =java-config-2*      </pre>    </body>  </section></chapter><chapter>  <title>Check your environment</title>  <section>    <body>      <p>        We now provide a new script, <c>/usr/bin/java-check-environment</c>.         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...      </p>      <pre caption="Check your environment">        /usr/bin/java-check-environment      </pre>      <p>        which leads us to...      </p>      <section>        <title>Update Virtual machines</title>        <body>          <p>            The first section checks for old java-config files in <path>/etc/env.d/java</path>. The instructions             should be self-explanatory. Just remove the files it indicates. After that, re-merge             the packages that it indicates.          </p>        </body>      </section>      <section>        <title>Delete old user configs</title>        <body>          <p>            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:          </p>          <pre caption="Delete old user configs">            java-config-2 -L            java-config-2 -s <Choice of VM>          </pre>        </body>      </section>      <section>        <title>Make sure you have a Generation-1 system-vm set</title>        <body>          <p>            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:          </p>          <pre caption="Set generation 1 vm">            java-config-1 -L            java-config-1 -S <System-vm-of-choice-here>          </pre>          <p>            Of course, as per usual, you will need to run          </p>          <pre caption="Update environment variables">            env-update && source /etc/profile          </pre>          <p>            To make sure you get the right environment.          </p>        </body>      </section>      <section>        <title>1.5 JDK set as your Generation-1 VM</title>        <body>          <p>            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.          <p>          </p>            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:           </p>          <pre caption="Run 1.5 fixer script">            /usr/bin/java-1.5-fixer          </pre>        </body>      </section>    </body>  </section></chapter><chapter>  <title>Known Issues</title>  <section>    <title>Applications try to use JAVA_HOME, which is set to the Generation-1 VM</title>    <body>      <p>        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        <path>/etc/env.d/20java</path>). This will be an issue until the particular        application is converted to using the new eclasses.      </p>      <p>        One workaround is to do the following to set JAVA_HOME:      </p>      <pre caption="Check your environment">        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      </pre>      <p>        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.      </p>      <p>        <b>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.</b>      </p>      <p>        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.       </p>    </body>  </section></chapter>