[gentoo-dev] Changes to the way Java packages are built

[Joshua Nichols]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

= Background =

As some might have noticed, Java 1.5 has been package.masked for some
time now. There are a number of issues introduced with 1.5 that have
kept it in package.mask. Please see the Java 1.5 FAQ [1] for more details.

[1] http://www.gentoo.org/proj/en/java/tiger-faq.xml

About a year ago, work was begun on improving our part of the build
system (read: Java related eclasses and our java-config tool) in a way
to make it much more flexible in general, but specifically improve it to
get around the known issues. It took about six months to fully develop.
Unfortunately, the new system was not quite a drop-in replacement. So,
it took from then until now to determine how to migrate from the current
system  to the new one in a sane way.


= The Current System =

To give some proper background, it is worth going over the current
system briefly.

== The Java Virtual Machine ==
Each Java Virtual Machine (VM) installs an environment file into
/etc/env.d/java. These files contain information about where JAVA_HOME
is, the PATH to include, etc.

VMs traditionally get installed at /opt/${P}

We have the concept of a 'system' VM and a 'user' VM. The system VM is
the default VM that will be used for root, and for users who haven't
selected a user VM. The user VM is, as one might guess, selected on a
per user basis. It is worth noting that root always uses the system VM,
and as a result, packages use the system VM when being merged by emerge.

java-config is used to set the system and user VM. When you do so, the
appropriate file from /etc/env.d/java is copied to/etc/env.d/20java for
the system VM or to ~/.gentoo/java-env for the user VM.

java-config's notion of the current VM is tied entirely to the
environment, specifically to JAVA_HOME. Therefore, if you change the
system VM, you'd need to run env-update and then resource /etc/profile.
Likewise, changing the user VM involves sourcing ~/.gentoo/java-env.

The fact that you're tied to the environment is annoying, because as
mentioned, you need re-source the appropriate files. Now imagine you
have a ton of terminals open... you'd have to source the environment
files from each one.

== Packages ==

When a Java package is built, information about it is saved in
/usr/share/${PN}-${SLOT}/package.env (or /usr/share/${PN}/package.env if
SLOT == 0). In particular, the jars that are associated with the package
are recorded, as well as which jars from other packages are used.
java-config can later be used to query for this information.

== Eclasses ==

There are currently 3 eclasses: java, java-pkg, and java-utils.

java.eclass is used for packages which provide a VM.
java-pkg.eclass is used for most Java packages. It provides tools for
querying installed jars, and for installing various Java related files.
java-utils.eclass provides a few utility functions for dealing with Java
stuff.

= The New System =

== The Java Virtual Machine ==
In addition to the concept of a system and a user VM, the new system has
a build VM. As the name implies, the build VM is used for building
packages (instead of the system VM). Sane defaults are defined on a per
platform basis at /usr/share/java-config-2/config/jdk-defaults.conf [3].
The build VM can further be configured by
/etc/java-config-2/build/jdk.conf [4] .

[3]
https://svn.gentooexperimental.org/svn/java/java-config-ng/branches/axxo/config/jdk-defaults-x86.conf
[4]
https://svn.gentooexperimental.org/svn/java/java-config-ng/branches/axxo/config/jdk.conf

For each Java release (ie 1.3, 1.4, 1.5, etc), you can specify which
vendor and version to use at build time.

In addition to being installed to /opt/${P}, VMs also now have a symlink
in /usr/lib/jvm/${PN}-${SLOT}. The purpose of these symlinks is
explained further down.

The user and system VMs are now represented by symlinks pointing to VMs
located in /usr/lib/jvm/. The system VM lives at
/etc/java-config-2/current-system-vm, and the user VM at
~/.gentoo/java-config-2/current-user-vm . Additionally, an environment
variable, GENTOO_VM, can be used to specify the VM used at a given
instance. GENTOO_VM should be the name of a VM located in /usr/lib/jvm.
So with regard to what VM is used, first GENTOO_VM is checked, then the
user VM (for non-root users), and then lastly the system VM.


All the trusty java binaries, ie java, javac, javadoc, jar, etc, now get
wrappers installed into /usr/bin. These are actually symlinks to
/usr/bin/run-java-tool. This is a script which will figure out which
tool was invoked, and then determine which VM to used using the method
mentioned above.

== Packages ==

We now save more information about the build environment at build time
for each package. This information is saved at
/usr/share/${PN}-${SLOT}/package.env. This is facilitate troubleshooting
bugs. Specially, we collect the VM dependency is (ie >=virtual/jdk-1.4),
what -source and -target were used , and which VM. We also keep track of
where javadocs get installed, and where Java sources get installed,
which are useful for integrating into IDEs like netbeans and eclipse.

== Eclasses ==

For each eclass we previously had, we have a updated version of the
eclass, in addition to a few totally new eclasses.

java-utils-2.eclass
	A utility eclass. All utility functions live here (as opposed to being
spread between java-pkg and java-utils). Among other things, there are
functions for figuring out which VM should be used for building, based
on the DEPEND of a package (ie the virtual/jdk atom), and set GENTOO_VM
accordingly.

java-pkg-2.eclass
	The eclass the Java-only packages should inherit. It uses phase hooks
in order to make sure that the environment is setup properly for each phase.

java-pkg-opt-2.eclass
	Similar to java-pkg-2, except this is for packages that have optional
Java support, ie a USE flag. Phase hooks are again used to ensure the
environment is setup properly for each phase.

java-ant-2.eclass
	Packages that build using ant should inherit this eclass. Essentially,
this is eclass will ensure that build.xml files get rewritten such that
javac tasks have the right source and target attributes. In other words,
it makes sure that the right version bytecode gets compiled.

java-vm-2.eclass
	This is the successor to java.eclass, but more aptly name.

= Letting the Systems Coexist =

Originally, the new eclasses were a replacement for the current
eclasses, ie java-pkg-2 used to still be java-pkg, and java-utils-2 used
to be still be java-utils. Additionally, java-config was unslotted, so
the new version of it replaced the current one. Unfortunately, it was
realized that the new system was not a 100% drop-in replacement for the
current one, so we set forth with the task to find a way to migrate from
one to the other.

The method we decided on was to have the concept of having a
'generation' for each system, where the generation consists of the
eclasses, a version of java-config, and the tools that support it. To
cope with java-config, it is now slotted, and installs
/usr/bin/java-config-<insert generation here> . There is then a wrapper
for java-config at /usr/bin/java-config, which reads a variable
WANT_JAVA_CONFIG to determine which java-config to use, or if not
specified, the most recent version. The eclasses then export the
appropriate value of WANT_JAVA_CONFIG to get the right version of
java-config they need.

The existing eclasses and java-config-1.x will be 'generation 1'. The
new eclasses and java-config-2.x will be 'generation 2'.

The first packages to be migrated to generation 2 will be the VMs. When
installed, they will also install environment files that are compatible
with generation 1. This will allow you to have both a system VM for
generation 1, in addition to the system and build VM for generation 2.
The consequence of this is that ebuilds using generation 1 will continue
to build/run as they previously did, while allowing packages to be
migrated to use generation 2 on a package-by-package basis.  So, all
existing ebuilds will continue to work, and will be replaced
incrementally during our migration.

A note on Java 1.5 here... The 1.5 JDKs don't install a generation-1
compatible environment file. This is to prevent the problems already
describe with 1.5, and should prevent them from happening. At this
point, we should be able to unmask the 1.5 JDKs. So 1.5 will be
available, but only to generation-2 packages.

The next packages to be migrated will be ones that need the features of
the new generation. In particular, this means packages which need Java
1.5 to build and/or run.

Once these packages have been migrated, the rest of the tree which uses
Java will be migrated as expediently as possible. I've written some
notes about how to migrate over on our wiki [5]
[5] https://projects.gentooexperimental.org/expj/wiki/Migrating_packages

= Using the new system =

I have written documentation on switching to the new system, from the
user's perspective, over at our wiki [6]

[6]
https://projects.gentooexperimental.org/expj/wiki/Using_migration-overlay

= Feedback =

Obviously, these aren't exactly light changes that need to be made.
Therefore, it's important to get as much feedback as possible, and to
make the upgrade process as smooth as possible.

I'd hope to get these changes put into the tree in the next week or two,
pending feedback. This development has been a long time in the making,
and the Java 1.5 problem has been a thorn in our side for long enough.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFElXOa8ATTzZyw6sMRAnGvAJkBjWKyr35P8JCJ1FNNKHfReQltqgCcCXpY
2QEXi19VASfaRP7ZIo9GLj0=
=8gDY
-----END PGP SIGNATURE-----
-- 
gentoo-dev@g.o mailing list