Java

NOTE: This page has been identified as having content that is significantly out-of-date, usually because it refers to OpenEmbedded-Classic - for new projects, you should use OpenEmbedded-Core. See OpenEmbedded Wiki Update Project for more details.

This page is here to answer all things Java related to OpenEmbedded.

State of support

Virtual machine and class library

Currently (since September 2008) you will be able to build packages for your target system that use a many VMs and their class libraries. For a full J2SE environment on the target you can build JamVM and Cacao as the virtual machine and GNU Classpath as the class library.

For J2ME you can have the "Connected Device Configuration" (CDC) in either the "Foundation" or "Personal" profile using the GPLed PhoneME Advanced virtual machine. See below for details.

For J2ME's "Mobile Information Device Profile" (MIDP2.0) you can use MIDPath.

Support for OpenJDK (with either Cacao or Hotspot/Zero as the runtime) is available through the Jalimo overlay. This will be merged soon. Future additions will also include Hotspot/Shark which is a variant of Hotspot using a generic JIT compiler based on LLVM.

It is planned to use OpenJDK as the native Java runtime. That way Java packages will be compiled against this library.

Java libraries

The number of available Java libraries is still small but can grow quickly as the necessary infrastructure is in place. Currently libraries such as dbus-java, kxml2, libmatthew, librxtx, sqlitejdbc, javasqlite, woodstox, xmlpull, SWT (3.4, Gtk+), a large bunch of the Jakarta commons libraries and stuff like BSF, POI, log4j, logkit and ORO are available.

For the Maemo platform's "hildon" environment special SWT packages are available which allow a better integration (i.e. hildon menus, hildon file chooser dialog).

PhoneME Advanced

PhoneME Advanced is provided in the 'Foundation' and 'Personal' profile through the recipes phoneme-advanced-foundation and (surprise!) phoneme-advanced-personal. The way the recipes are written both can be compiled and installed at the same time on the target device.

Note: At the moment the personal profile's AWT support relies on Qt3 which is heavily outdated. If possible you should prefer the foundation profile with SWT for the GUI or contribute to PhoneME to fix this. :)

When a PhoneME Advanced package is installed you will find the VM in $libdir_jvm (which is /usr/lib/jvm by default). The package provides a java-cdc symlink which is changeable through update-alternatives and a cvm-<profile name> symlink.

J2ME MIDP2.0

J2ME MIDP2.0 is supported through the MIDPath project. MIDPath provides the neccessary libraries (taken from PhoneME and/or the respective JSRs) and OpenEmbedded has direct support for a few devices (e.g. button mappings). Please note that while MIDPath can run most MIDP2.0 programs it is no official MIDP2.0 implementation.

MIDPath can be run on top of either PhoneME Advanced or a J2SE-like environment (JamVM/Cacao and GNU Classpath or any of the OpenJDK variants). If PhoneME is installed it is preferred.

OpenJDK

OpenJDK is the name of the F/OSS Java stack from Sun. It normally consists of the class library (often referred to as OpenJDK as well), the Hotspot runtime and many many tools (e.g. javah, rmic, javaws). OpenEmbedded support building OpenJDK with the CacaoVM. This gives many platforms which Hotspot does not directly support a fast Java VM. Please note that Cacao lacks many advanced features like JVMTI. Your only other option is the Zero port of Hotspot. Zero is a C++-based interpreter and can be run on any platform supporting libffi. This gives you a featurefull VM for many platforms at the cost of performance.

Toolchain

In order to build Java packages no virtual machine needs to be installed on the build machine. OpenEmbedded builds everything on its own.

Missing but planned to be included are popular Java build tools like Ant.

GNU Classpath Tools

Included in the package classpath-native are the tools 'gjar', 'gjavah', 'gjavap', 'gjarsigner' (and soon gjdoc). Those tools usually work without problems and should be fully compatible to the ones provided by OpenJDK.

OpenJDK language tools

OpenEmbedded supports the OpenJDK language tools consisting of 'sun-javac', 'javap', 'javah' and 'apt'. Put 'openjdk-langtools-native' to the dependencies of your recipe to use those binaries. Albeit the tools are from OpenJDK they run on Cacao/JamVM and GNU Classpath.

Note: openjdk-langtools-native is not a provider of 'virtual/javac-native' it only provides a 'sun-javac' binary. Refer to the virtual/javac-native discussion for details.

Ant

Ant is an often used tool in the Java world. Even OpenJDK uses it. Unfortunately it is also a complex beast with many dependencies (many of which use Ant itself). Despite all this troubles Ant (1.7.1) is available and supported as an application which can be run from build recipes.

A word of warning

Every so often people on the net suggest that in order to get Java stuff running in OpenEmbedded, you need to install a JDK, Kaffe or Jikes and then make modifications to the PATH variable in order to allow the build use the runtime or compiler. These suggestions are wrong! The Java support in OpenEmbedded is (and strives to stay) completely self-hosting. You should not need a single bit of Java on your host OS to get the Java recipes to compile.

On the other hand the Java support in OE can happily co-exist with whatever 'java', 'javac' and other tools you might have installed in your OS. Due to the nature of some configure scripts, those will sometimes find these executables but in the end only the tools from OpenEmbedded's staging directory will be used (if not its a bug that needs to be fixed).

Please note that problem reports that are caused by pulling in native Java tools (those from your OS) into the OpenEmbedded build process will be closed as invalid. The reason is that the recipes are only supposed to work with the built-in toolchain.

Configuring (add info about what and where)

In this section you learn about the things you can set up. In many OpenEmbedded-based distributions some or most of these decision may have already been made for you so there is no need to specify them. However in case you want to provide the Java support in your distribution you need to know which knobs are available.

Bootstrap process

As told in the toolchain support section the whole Java support in OpenEmbedded is self-hosting. This mean you do not need to have any bit of Java on your build machine as OpenEmbedded will build this itself.

This bootstrap process contains the following steps: At first jikes-native is compiled which is a Java 1.4-capable compiler that does not need a runtime or (strictly) a class library to work. With this compiler we compile the initial runtime (package virtual/java-initial).

virtual/java-initial is a preliminary runtime. This virtual package is currently provided by cacao-initial or jamvm-initial. After that ecj-initial is built. At that point we have a 1.5-capable compiler running on a Java 1.4 compatible VM.

The compiler is then used to build virtual/java-native and finally virtual/javac-native. The former virtual package is provided by either cacao-native or jamvm-native. The latter package is currently only provided through ecj-bootstrap-native. Having built these packages provides the OpenEmbedded build environment with a Java5-capable compiler and runtime. At that point we are ready to compile any other Java package.

Bootstrap virtual machine aka virtual/java-initial

The bootstrap virtual machine has the sole purpose of running ecj-initial (the bootstrap compiler) to compile a 1.5-capable runtime and library. The bootstrap VM runs on your build host and is therefore a -native package. Inside the native staging directory the VM provides a 'java-initial' executable.

As told above there are currently two packages that provide 'virtual/java-native'. Add

 PREFERRED_PROVIDER_virtual/java-initial = "cacao-initial"
 PREFERRED_VERSION_cacao-initial = "0.98"

to your local or site configuration to choose the Cacao VM. This virtual machine has a JIT compiler and is generally faster but takes a bit longer to compile. Furthermore this VM is only tested to work correctly on X86 build hosts. If you chose Cacao there will also be a 'cacao-initial' binary in your native staging directory.

Note: There is a problem with Cacao 0.98 running on recent distributions where mmaping the zero page is not allowed. Chose jamvm-initial (see below) if you do not want to change the vm_mmap_min_adr restriction on your system.

In case Cacao is unsuitable for you add

 PREFERRED_PROVIDER_virtual/java-initial = "jamvm-initial"
 PREFERRED_VERSION_jamvm-initial = "1.4.5"

to your configuration. JamVM is an interpreting Java virtual machine. Despite interpreting only it is very fast (implements many modern interpreter techniques) and compiles quickly. Furthermore it is known to work on X86 and PowerPC build hosts.

Native virtual machine aka virtual/java-native

As for virtual/java-initial this virtual package provides a Java virtual machine which runs on your build host. Its purpose is to run any Java programs that are needed during your build process. The most prominent program that it is supposed to run is the compiler ECJ. The virtual/java-native package provides a 'java' binary inside the native staging directory. At the moment you can chose between two runtimes: Cacao and JamVM.

As for the general features it is the same as for java-initial. However for virtual/java-native later versions of the VMs are used so stability and platform support is better. For instance you can use cacao-native on PowerPC as well since the version of Cacao used properly supports it.

To chose Cacao add the following line to your configuration:

 PREFERRED_PROVIDER_virtual/java-native = "cacao-native"

Besides 'java' cacao-native install a 'cacao' binary into the native staging directory.

If you favor JamVM (or are having trouble with Cacao) use:

 PREFERRED_PROVIDER_virtual/java-native = "jamvm-native"

There will also be a 'jamvm' binary in native staging directory besides the 'java' one with jamvm-native.

Note: Native versions of jamvm are unsupported on amd64/x86_64 hosts since OpenEmbedded lacks a native libffi. If you desperately need jamvm on your platform consider installing the development package for libffi of your distro.

Native Java compiler aka virtual/javac-native

The virtual/javac-native package provides the 'javac' binary which is to be found within the native staging directory. This compiler is used to build all of the Java packages within OpenEmbedded.

There are two recipes which provide this functionality:

ecj-bootstrap-native uses the commandline variant of the Eclipse IDE's integrated compiler. In order to use that compiler add the following to your configuration:

 PREFERRED_PROVIDER_virtual/javac-native = "ecj-bootstrap-native"

The second option is OpenJDK's Java compiler which is the F/OSS variant of good old 'javac'. If you experience trouble with ecj you should try OpenJDK's Java compiler by setting the following in your configuration:

 PREFERRED_PROVIDER_virtual/javac-native = "openjdk-javac-native"

Note: OpenJDK's javac is actually build in the package openjdk-language-tools-native (provides a 'sun-javac' binary). The reason for this is to allow 'ecj-bootstrap-native' and 'openjdk-language-tools-native' to coexist in the staging dir.

ecj-bootstrap-native, ecj-initial and libecj-bootstrap

Since ecj-initial and ecj-bootstrap-native use the same jar file the compilation step for both packages is done through in the libecj-bootstrap recipe. Therefore in order to decide which ECJ version to use for compilation you need to set a version preference for that recipe:

 PREFERRED_VERSION_libecj-bootstrap = "3.4"

Target virtual machine

Note: There used to be a virtual/java package. It turned out that by having this it prevented offering multiple J2SE-compatible VMs for the target device.

From a distributors point of view you can build the jamvm, cacao, phoneme or openjdk recipes and provide them to your users. Those can then either install the packages directly by its name or rely on a chosing of the packaging.

At the moment Cacao and JamVM are supported runtimes. Cacao is ready for x86, PowerPC and ARM systems (others are untested and AVR32 is not suppported) and has a JIT compiler. JamVM can be used on x86, PowerPC, ARM and MIPS. PhoneME Advanced should support x86, PowerPC, ARM, MIPS and Sparc.

Additionally OpenJDK can be built using either Cacao (same properties as above) or the Zero port of Hotspot. Zero is an C++-based interpreter capable of running on any platform that is supported by libffi.

When installed all J2SE runtimes provide the 'java' executable (chosen through update-alternatives). PhoneME Advanced gives you a 'java-cdc' executable.

Runtime provider

Warning: When we talk of 'runtime provider' here this is meant in the OpenEmbedded sense (PROVIDES = build provides, RPROVIDES = runtime provides) The Cacao, JamVM or OpenJDK packages are set to provide 'java2-runtime'. Packages which need a J2SE-capable VM should RDEPEND on this. By inheriting the 'java-library' class in your recipe this is done automatically.

PhoneME on the other hand is set to provide 'java-cdc-runtime'.

GNU Classpath for headless machines aka classpath-minimal

Through setting the provider for 'classpath' you can decide whether you build a full class library with support for AWT/Swing (having a gtk+ dependency) or a variant that works without that and is primarily meant for headless devices. It might also be handy if you decide not to use AWT/Swing and use SWT instead. To chose the minimal variant add this to your configuration:

 PREFERRED_PROVIDER_classpath = "classpath-minimal"

Otherwise you need to add this line:

 PREFERRED_PROVIDER_classpath = "classpath"

Currently the Angstrom distribution does not set a preference and you have to provide your own.

Writing a Java recipe

This section is going to tell you, how to write a proper recipe to build a Java library or program.

At the moment this is a stub and you will only find some scattered information which at a later point will be merged into a consistent whole.

java-native.bbclass

If you use the java-library bbclass in a recipe foo and generate a native variant (e.g. foo-native) you should use

 inherit java-native

instead of native. By doing so, you make sure, that any jars created by the recipe are properly installed into staging.

ant-native

If you need Ant to build your recipe add ant-native to your recipes dependencies. This will allow you to call the built-in Ant executable.

Information on specific libraries

swt3.4-gtk and swt3.4-gtk-hildon

Some effort has been done to integrate Gtk+-based SWT 3.4 into the Hildon environment (that is what Maemo provides). Distributions targeting Maemo should set the preferred provider for swt3.4-gtk like this:

 PREFERRED_PROVIDER_swt3.4-gtk = "swt3.4-gtk-hildon"

Important: If you do not want the hildon variant it is best to declare

 PREFERRED_PROVIDER_swt3.4-gtk = "swt3.4-gtk"

as well. So bitbake will not chose the wrong one by accident (which would otherwise pull in all kinds of unwanted dependencies).

Caveats, known issues, hints, miscellaneous information

Version suggestions

Everyone and his dog knows that combining glibc 2.8, gcc 2.95 and Linux kernel 2.6.26 is not going to work. In the GNU Classpath realm we also have a set of versions that do not fit together. Here are some suggestions for your PREFERRED_VERSIONs. Stick to these if you are unsure. You can always find out which version are supposed to be compatible by reading the READMEs of the VMs.

openjdk

To prevent building of cacao for target add this in your local.conf

 PREFERRED_PROVIDER_openjdk-6-jre = "openjdk-6-jre"

jamvm-initial and classpath-initial

Use this and nothing else:

 PREFERRED_VERSION_jamvm-initial = "1.4.5"
 PREFERRED_VERSION_classpath-initial = "0.93"

cacao-initial and classpath-initial

Use this and nothing else:

 PREFERRED_VERSION_cacao-initial = "0.98"
 PREFERRED_VERSION_classpath-initial = "0.93"

jamvm[-native] and classpath[-native]

These are the releases that appear to be stable.

 PREFERRED_VERSION_jamvm-native = "1.5.3"
 PREFERRED_VERSION_classpath-native = "0.98"

For the target device:

 PREFERRED_VERSION_jamvm = "1.5.2"
 PREFERRED_VERSION_classpath = "0.98"

cacao[-native] and classpath[-native]

These releases appear to be stable:

 PREFERRED_VERSION_cacao-native = "0.99.3"
 PREFERRED_VERSION_classpath-native = "0.97.2"

For the target device take these:

 PREFERRED_VERSION_cacao = "0.99.4"
 PREFERRED_VERSION_classpath = "0.98"

Extra binaries and symlinks

Since both Cacao and JamVM can be installed in staging you can use this and modify the 'java' or 'java-initial' symlink if you want to switch to a certain VM.

Debugging Cacao on the target

You need to debug the Cacao JVM on your target device using GDB and need some pointers on how to get started? Read this page from the Jalimo Wiki.

Future plans

Default Bytecode compliance level

Soon an option will be introduced to set the default bytecode compliance level. For any Java package that does not explicitly provide this level (not many do this) the one you set in your configuration will be used.

OpenJDK + Cacao

The flexibility of the Cacao runtime allows it to run it with OpenJDK's class library. This allows you to use the official class library and a JIT-capable runtime on an ARM device (as of today Hotspot has no JIT on ARM).

Since the middle of August 2008 OpenJDK + Cacao can be build and is included in the Debian armel sid repositories (package cacao-oj6-sdk). Xerxes Rånby is showing some webbapplets running using OpenJDK + CACAO on his blog: http://labb.zafena.se/?p=1

Since December 2008 OpenJDK + Cacao can be crosscompiled with OpenEmbedded as demonstrated by Robert Schuster! Check out http://rschuster.blogs.evolvis.org/2008/12/21/serving-cross-compiled-openjdk-with-icedtea/ and the answers http://rschuster.blogs.evolvis.org/2008/12/23/comments-on-latest-post-on-openjdk/

Ant integration for build recipes

Although ant can be used as a standalone tool there is no direct support for it in the recipe. E.g. the Debian buildsystem (CDBS) has support classes that can be used for Ant-based Java sourcepackages. It would be nice to have this too for OpenEmbedded.

FAQ

This space is for *your* questions and those that appeared more often on the mailing list. Things will be added here by the Jalimo folk/OE-Java maintainers or by you asking a question.

Q: I do get all these editions, configurations and profiles that exist in the Java world wrong. Any pointer on this?

I found these articles in Wikipedia helpful to clarify the situation Java platform, Java ME.

Q: I need to solve a specific Java problem in OE and want to throw money at this. Whom can I contact?

The Jalimo project has done a lot of Java work in OE and are available for contract work. You can also ask for experienced devs on the openembedded-devel mailing list.