Java
This page is here to answer all things Java related to OpenEmbedded.
Where to get answers about Java support in OpenEmbedded?
The Java support in OpenEmbedded is maintained through the Jalimo project. As such we encourage you to subscribe to this project's mailing list and post your question there. Developers of OpenEmbedded-derived distributions like Angstrom are also encouraged to delegate questions of their users to Jalimo.
You can also use the mailing list to discuss new recipes prior to putting them into OpenEmbedded's bug tracker.
State of support
Virtual machine and class library
Currently (July 2008) you will be able to build packages for your target system that use either JamVM or Cacao as the virtual machine and GNU Classpath as the class library.
Support for PhoneME Advanced (CDC) and OpenJDK (with Cacao as the runtime) is planned.
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+) are available.
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.
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.
ECJ
Instead of Sun's Java Compiler 'javac' most packages in OpenEmbedded are compiled with the command-line version of the Eclipse project's ECJ. You need the package ecj-bootstrap-native to get access to the 'javac' and 'ecj' binary that are provided by it.
OpenJDK language tools
Very soon OpenEmbedded will support the OpenJDK language tools consisting of javac, javap, javah and apt. Put openjdk-langtools-native to the dependencies of your recipe and use the binaries which have 'sun-' prepended (e.g. 'sun-javac') if you need them explicitly. Albeit the tools are from OpenJDK they run on Cacao/JamVM and GNU Classpath.
Currently openjdk-langtools-native is not a provider of virtual/javac-native since it needs a Java5 capable runtime and compiler itself and ecj-bootstrap-native delivers its own 'javac'. This is going to be fixed as well.
The OpenJDK language are currently in the Jalimo overlay only.
Configuring
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 build. 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 every 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.
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 lines to your configuration:
PREFERRED_PROVIDER_virtual/java-native = "cacao-native" PREFERRED_VERSION_cacao-native = "0.99.2"
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" PREFERRED_VERSION_jamvm-native = "1.5.1"
There will also be a 'jamvm' binary in native staging directory besides the 'java' one with jamvm-native.
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.
At the moment only the package ecj-bootstrap-native provides virtual/javac-native but it is planned that in the future Sun's javac will be available.
Add the following lines to your configuration to make the Java compiler setting fixed:
PREFERRED_PROVIDER_virtual/javac-native = "ecj-bootstrap-native"
Target virtual machine aka virtual/java
The virtual package virtual/java specifies which runtime is the default virtual machine for J2SE Java program. This does not mean that you cannot install a second runtime (which is possible). At the moment Cacao and JamVM are supported runtimes. Cacao is ready for X86, PowerPC and ARM systems (others are untested AVR32 is not suppported) and has a JIT compiler. JamVM can be used on X86, PowerPC, ARM and MIPS.
When installed all runtimes provide the 'java' executable (chosen through update-alternatives).
To select Cacao as the default runtime add the following lines to your configuration:
PREFERRED_PROVIDER_virtual/java = "cacao" PREFERRED_VERSION_cacao = "0.99.2"
If you prefer JamVM add those:
PREFERRED_PROVIDER_virtual/java = "jamvm" PREFERRED_VERSION_jamv = "1.5.1"
While other versions of Cacao and JamVM are available you should try to use the suggested ones first.
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.
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.
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 latest releases and they seem to be stable. Highly recommended:
PREFERRED_VERSION_jamvm-native = "1.5.1" PREFERRED_VERSION_classpath-native = "0.97.2"
The same goes for the target device:
PREFERRED_VERSION_jamvm = "1.5.1" PREFERRED_VERSION_classpath = "0.97.2"
cacao[-native] and classpath[-native]
These are the latest releases and they seem to be stable. Highly recommended:
PREFERRED_VERSION_cacao-native = "0.99.2" PREFERRED_VERSION_classpath-native = "0.97.2"
The same goes for the target device:
PREFERRED_VERSION_cacao = "0.99.2" PREFERRED_VERSION_classpath = "0.97.2"
Cacao and GCC 4.3
It seems to me that Cacao (especially 0.99.2) is miscompiled when using GCC 4.3. You will experience that ecj-bootstrap-native will produce spurious errors when compiling classes. If that happens to you switch to JamVM.
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.
ecj-bootstrap-native and ecj-initial
Since ecj-initial and ecj-bootstrap-native can use the same jar file we skip the compilation step for the former package and really just use the jar from ecj-initial. Therefore ecj-bootstrap-native has a dependency on ecj-initial directly.
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
PhoneME Advanced
A recipe (or many) that provides PhoneME Advanced is in the making. On the target this runtime will be available as 'cvm' and 'java-cdc'.
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).
ant-native
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). Still there is work in progress to build and use it inside OpenEmbedded.