JavaRecipeHowto

Overview

This page describes how to create a recipe for a pre-existing Java project or library that is not currently available in OpenEmbedded or Jalimo. It assumes a basic working knowledge of OpenEmbedded and Java tools such as javac. An example library will be built from sources: Concierge, an OSGi framework.

Prerequisites

Before proceeding with this howto, you'll need to verify that your OpenEmbedded build environment is working properly. This falls into two categories, the core BitBake system and the OpenEmbedded recipes, and the Java tools that are built inside of OpenEmbedded.

General Open Embedded

After installing OpenEmbedded, go to the root of the installation and run bitbake to confirm your environment is working properly:

$ bitbake
NOTE: Handling BitBake files: \ (5485/5485) [100 %]
NOTE: Parsing finished. 5249 cached, 0 parsed, 236 skipped, 0 masked.
NOTE: Cache is clean, not saving.
Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help'
for usage information.

If you get a parse error or sanity check error, please consult the general OE troubleshooting page.

Java Native Tools

The next step is to build the host-side tools that will be used to compile Java libraries. While this process is somewhat complex, involving tools such as ecj, gnu classpath, and cacao, it is necessary. First, try building cacao-native. In OpenEmbedded the convention is to append "-native" to a package if it's intended to be used on the host rather than something intended for the target. This should pull in the dependencies.

$ bitbake cacao-native

...

NOTE: package cacao-native-0.99.3: completed
NOTE: Tasks Summary: Attempted 265 tasks of which 248 didn't need to be rerun and 0 failed.
NOTE: build 200810031648: completed

BitBake Classes

BitBake classes are how the core bitbake program can be extended for specific tasks. The Jalimo group has added two bbclasses: java.bbclass, java-library.bbclass. These classes make it easier to write recipes that require or generate Java code by handing mapping to OE-hosts JVM, and managing classpath dependencies. These classes also define conventions for where JVMs, and Java libraries should live on the target image.

Creating a recipe

Now it's time to write our own recipe for a Java library. This will allow a package to be built and deployed to an OE image, and lets other people benefit from the work. In this example we will be writing a recipe for Concierge, a light and simple OSGi framework.

General Items

The first step is to decide where your recipe should live. It's a good idea when adding or modifying recipes to isolate them in such a way that they are easily installed on top of existing OE installations. However for now we will just add our recipe into the Jalimo oe-overlay directory. On my machine this directory is:

$OEROOT/jalimo/oe-overlay/packages

In packages I will create a directory concierge and a file concierge.bb. There are a few items that are common to all recipes, some metadata used to identify the package, it's license, and where it comes from. Here is our initial recipe concierge.bb:

DESCRIPTION = "A lightweight R3 OSGi Framework"
AUTHOR = "Jan Rellermeyer"
LICENSE = "BSD"
HOMEPAGE = "http://concierge.sourceforge.net"

Inheriting java-library

The next step is to add the java-library functionality into your recipe so that compiling and jarring the code is easy.

inherit java-library

We need to use another tool called fastjar-native which will take our compiled code and create a Jar. In Bitbake the way to describe that you depend on another recipe is the DEPENDS variable:

DEPENDS = "fastjar-native"

Pulling in your Sources

An OE variable SRC_URI defines where BitBake looks for package sources from. Looking on the Concierge homepage, it appears that the sources live in an svn server here:

svn://concierge.svn.sourceforge.net/svnroot/concierge

Now we have to make a decision about what version we want to build. It is possible to write recipes for different versions of packages. The common practice is to create an ".inc" file that includes common functionality across all the versions. For now we will only be providing one version so this isn't necessary. Looking in the tags folder shows that the latest release is 1.0.0 RC3. We will define our SRC_URI variable to load sources for this tag:

SRC_URI = "svn://concierge.svn.sourceforge.net/svnroot/concierge/tags/Concierge/1.0.0.RC3/;module=framework;proto=https;rev=220;localdir=${PN}"

Note the parameters in the string. These parameters are read by BitBake to determine what exactly to download and where to put the sources. ${PN} defines 'Package Name' and is a good way of keeping recipe code clean and reusable.