World of XorA

I thought it was about time to give an update on Ångström support of the Omap3 Zoom2 device.

Thanks to TIs donation I have been able to work on support for this device. I have also been able due to the power of OE build on the Ångström communities support of omap3 chips in general. Anyway a Gnome rootfs is running nicely on the device.

Here is the login screen.

And after logging in the desktop running.

This as you can see is with the zoom2 running free of its debug board. This does mean with current OE recipes there is no networking but we are hoping to have that fixed soon now!

This article is to detail the typical workflow I use when I am adding a new application recipe to OpenEmbedded from scratch. In this case it will be the gobject dbus binding called eggdbus.

During this article reference to the OE wiki especially the styleguide for new recipes is highly recommended.

• Styleguide
• Commit Policy
• Versioning Policy

The first step is to locate the software we are going to add and the version number of that software. In this case it the software is called eggdbus and it is version 0.6. Also at this stage check the license of the software in this case GPLv2.

Create a directory in the metadata to hold the new software.

mkdir recipes/eggdbus

Use an editor to create the recipe file for the new application. The general form of the filename is application_version.bb so in this case edit.

vi recipes/eggdbus/eggdbus_0.6.bb

Fill the beginning of the recipe with the informational fields.

DESCRIPTION = "gobject dbus binding"
HOMEPAGE = "http://cgit.freedesktop.org/~david/eggdbus"
LICENSE = "GPLv2"


The next step is to locate the download URL for the new recipe. In this case eggdbus is hosted in a sourceforge project so the download URL is.

http://cgit.freedesktop.org/~david/eggdbus/snapshot/eggdbus-0.6.tar.bz2

OpenEmbedded creates a variable ${PV} from the filename of the recipe. It is recommended to use this in the SRC_URI as it saves typing when later upgrading to later versions of the software. It also creates a ${PN} variable from the package name.

SRC_URI = "http://cgit.freedesktop.org/~david/${PN}/snapshot/${PN}-${PV}.tar.bz2"

At this stage there is enough recipe to attempt a download and check that there are no mistakes so far.

bitbake eggdbus

This build is expected to fail as the OE metadata does not yet have the MD5/SHA256 checksums for the download yet.

NOTE: Missing checksum
ERROR: eggdbus-0.6: http://cgit.freedesktop.org/~david/eggdbus/snapshot/eggdbus-0.6.tar.bz2 has no checksum defined, cannot check archive integrity
ERROR: Error in executing: /home/dp/openembedded/org.openembedded.dev/recipes/eggdbus/eggdbus_0.6.bb
ERROR: Exception: Message:1
ERROR: Printing the environment of the function
ERROR: Error in executing: /home/dp/openembedded/org.openembedded.dev/recipes/eggdbus/eggdbus_0.6.bb
ERROR: Exception: Message:1
ERROR: Printing the environment of the function
ERROR: Build of /home/dp/openembedded/org.openembedded.dev/recipes/eggdbus/eggdbus_0.6.bb do_fetch failed


OE helpfully generates the checksums it expected to see so these can be added to the meta data easilly. The cat just appends the new checksum to the end of the file. The next python command then calls a script to sort the checksums into the recommended format.

cat tmp/checksums.ini >>~/oe/org.openembedded.dev/conf/checksums.ini
python contrib/source-checker/oe-checksums-sorter.py -i conf/checksums.ini


To check this worked then re-issue the bitbake command.

bitbake eggdbus

In this case the command will succeed but builds no useful package. Depending on the application it will probably fail. This is not a problem at this stage as it is still work in progress and debugging these failures is what gives the information for the rest of the recipe.

At this stage the contents of the tarball file can be checked. The eggdbus tarball unpacks to a directory which is called eggdbus-0.6 which is what OE has already selected by default so we dont need to overide the default ${S} setting.

Eggdbus is an autotools using library so we tell OE to use its built in autotools support. If it is a well written autoconf then OE generates configure/compile/install tasks which work without modification.

inherit autotools

We can now try a build again to see if it will just build(tm).

In this case it doesnt because of gtk-doc.make. We currently dont really support this in OE anyway so we shall attempt to patch out this part.

cd tmp/work/armv7a-angstrom-linux-gnueabi/eggdbus-0.6-r0/eggdbus-0.6/
quilt new gtk-doc.patch
quilt add docs/eggdbus/Makefile.am docs/tests/Makefile.am


Edit the two Makefile.am and remove the reference to gtk-doc.make. Then generate the patch.

quilt refresh

The patches/gtk-doc.patch is now our patch. We need to copy it into our OE repo and add it to the SRC_URI.

mkdir recipes/eggdbus/files/
mv patches/gtk-doc.patch recipes/eggdbus/files/


And edit the eggdbus_0.6.bb to add the new patch to the SRC_URI.


SRC_URI = "http://cgit.freedesktop.org/~david/${PN}/snapshot/${PN}-${PV}.tar.bz2 \
file://gtk-doc.patch;patch=1 \
"


Now we attempt to build again.


bitbake eggdbus -c clean
bitbake eggdbus


This time the build fails inside the code stage, if the error is examined it will show that the build is trying to run a built program on the host. This obvously won’t work in cross compile situations so the program needs to be compiled for host.

This means a native version of the package is created. This used to mean a seperate .bb file but thanks to BBCLASSEXTEND it can be done in one file. This also means SRC_URI must be altered to use ${BPN} (Base Package Name) which is a version with -native/-sdk stipped from the end if present. So the following is changed/added to .bb file.


SRC_URI = "http://cgit.freedesktop.org/~david/${BPN}/snapshot/${BPN}-${PV}.tar.bz2 \
file://gtk-doc.patch;patch=1 \
"



BBCLASSEXTEND = "native"


On attempting to build this new native file it failed because it tries to use docbook to generate man pages. We dont really need them so disable them.


EXTRA_OECONF = " --disable-man-pages --disable-gtk-doc-html "


Now a rebuilt of eggdbus-native succeeds and host versions of the tools needed are available in the staging directory. Now some more changes are needed to the source. In the Makefile.am the programs we just built are referenced using the source directory but the ones in staging should be used so another patch to the Makefile.am files is produced. This patch should apply to the native version so more changes to recipe are needed.


BASE_SRC_URI = "http://cgit.freedesktop.org/~david/${BPN}/snapshot/${BPN}-${PV}.tar.bz2 \
file://gtk-doc.patch;patch=1 \
"

SRC_URI = "${BASE_SRC_URI} \
file://marshal.patch;patch=1 \
"

SRC_URI_virtclass-native = "${BASE_SRC_URI}"



bitbake eggdbus -c clean
bitbake eggdbus


This time the build succeeds, but one thing that isnt done yet is to tell OE what this recipe depends on. The trick used to do this is to examine the control file in the .ipk and see what is depended on.

For this recipe it is quite clear and dependencies on dbus glib. So a final change to the recipe to add dependencies.


DEPENDS = "dbus glib-2.0"


All these steps give up a complete recipe that reads as follows.


DESCRIPTION = "gobject dbus binding"
HOMEPAGE = "http://cgit.freedesktop.org/~david/eggdbus"
LICENSE = "GPLv2"

DEPENDS = "dbus glib-2.0"

BASE_SRC_URI = "http://cgit.freedesktop.org/~david/${BPN}/snapshot/${BPN}-${PV}.tar.bz2 \
file://gtk-doc.patch;patch=1 \
"

SRC_URI = "${BASE_SRC_URI} \
file://marshal.patch;patch=1 \
"

SRC_URI_virtclass-native = "${BASE_SRC_URI}"

inherit autotools

EXTRA_OECONF = " --disable-man-pages --disable-gtk-doc-html "

BBCLASSEXTEND = "native"


This article is to detail the typical workflow I use when I am adding a new application recipe to OpenEmbedded from scratch. In this case it will be the open source cloud computing application called eyeos.

During this article reference to the OE wiki especially the styleguide for new recipes is highly recommended.

• Styleguide
• Commit Policy
• Versioning Policy

The first step is to locate the software we are going to add and the version number of that software. In this case it the software is called eyeos and it is version 1.8.7.1. Also at this stage check the license of the software in this case AGPL3.

Create a directory in the metadata to hold the new software.

mkdir recipes/eyeos

Use an editor to create the recipe file for the new application. The general form of the filename is application_version.bb so in this case edit.

vi recipes/eyeos/eyeos_1.8.7.1.bb

Fill the beginning of the recipe with the informational fields.

DESCRIPTION = "The Open Source Clouds Web Desktop"
HOMEPAGE = "http://eyeos.org/"
LICENSE = "AGPL3"

The next step is to locate the download URL for the new recipe. In this case eyeos is hosted in a sourceforge project so the download URL is.

http://sourceforge.net/projects/eyeos/files/eyeos/1.8.7.1/eyeOS_1.8.7.1.zip/download

OpenEmbedded actually has sourceforge mirror handling build in. So when the SRC_URI is constructed for the reciped a shortcut can be taken. OpenEmbedded also creates a variable ${PV} from the filename of the recipe. It is recommended to use this in the SRC_URI as it saves typing when later upgrading to later versions of the software. It also creates a ${PN} variable from the package name. But in this case this is not used as it differs in case in the URL.

SRC_URI = "${SOURCEFORGE_MIRROR}/eyeos/eyeOS_${PV}.zip"

At this stage there is enough recipe to attempt a download and check that there are no mistakes so far.

bitbake eyeos

This build is expected to fail as the OE metadata does not yet have the MD5/SHA256 checksums for the download yet.

NOTE: Missing checksum
ERROR: eyeos-1.8.7.1: http://downloads.sourceforge.net/eyeos/eyeOS_1.8.7.1.zip has no checksum defined, cannot check archive integrity
ERROR: Error in executing: /home/graeme/openembedded/org.openembedded.dev/recipes/eyeos/eyeos_1.8.7.1.bb
ERROR: Exception: Message:1
ERROR: Printing the environment of the function
ERROR: Error in executing: /home/graeme/openembedded/org.openembedded.dev/recipes/eyeos/eyeos_1.8.7.1.bb
ERROR: Exception: Message:1
ERROR: Printing the environment of the function
ERROR: Build of /home/graeme/openembedded/org.openembedded.dev/recipes/eyeos/eyeos_1.8.7.1.bb do_fetch failed
ERROR: Task 2 (/home/graeme/openembedded/org.openembedded.dev/recipes/eyeos/eyeos_1.8.7.1.bb, do_fetch) failed
NOTE: Tasks Summary: Attempted 445 tasks of which 444 didn't need to be rerun and 1 failed.
ERROR: '/home/graeme/openembedded/org.openembedded.dev/recipes/eyeos/eyeos_1.8.7.1.bb' failed

OE helpfully generates the checksums it expected to see so these can be added to the meta data easilly. The cat just appends the new checksum to the end of the file. The next python command then calls a script to sort the checksums into the recommended format.

cat tmp/checksums.ini >>~/oe/org.openembedded.dev/conf/checksums.ini
python contrib/source-checker/oe-checksums-sorter.py -i conf/checksums.ini


To check this worked then re-issue the bitbake command.

bitbake eyeos

In this case the command will succeed but builds no useful package. Depending on the application it will probably fail. This is not a problem at this stage as it is still work in progress and debugging these failures is what gives the information for the rest of the recipe.

At this stage the contents of the zip file can be checked. The eyeos zip unpacks to a directory which is called eyeOS which is different from OEs guessed at directory of eyeos-1.8.7.1 so the recipe needs updated to tell OE the real directory.

S = "${WORKDIR}/eyeOS"

Being a web application eyeOS doesnt have Makefile or autotools based installation so the compile/install stages will have to be hand written for this recipe.

The eyeOS installation is really simple from the OE point of view.

do_install() {
    install -d ${D}/www/pages/eyeos
    cp -r ${S}/* ${D}/www/pages/eyeos
}

There are two final things to do now before the recipe is finished. OE needs to be told which directories to package. It has some built in defaults like /bin /usr/bin /lib /usr/lib but our eyeOS install is outside these areas. We also need to tell OE that there is no CPU dependant code in the packages this recipe generates.

PACKAGE_ARCH = "all"
FILES_${PN} += "/www/pages/eyeos"

All these steps give up a complete recipe that reads as follows.

DESCRIPTION = "The Open Source Clouds Web Desktop"
HOMEPAGE = "http://eyeos.org/"
LICENSE = "AGPL3"

SRC_URI = "${SOURCEFORGE_MIRROR}/eyeos/eyeOS_${PV}.zip"

S = "${WORKDIR}/eyeOS"

do_install() {
    install -d ${D}/www/pages/eyeos
    cp -r ${S}/* ${D}/www/pages/eyeos
}

PACKAGE_ARCH = "all"
FILES_${PN} += "/www/pages/eyeos"


So the final stage the final packages can be built fromt the recipe. First a clean to make sure anything worked on is gone then a build.

bitbake eyeos -c clean
bitbake eyeos


The package produced from this recipe is now ready to be installed on target for testing.

This article is to detail the workflow I personally use when I am doing kernel development for devices supported by OE. I find OE very useful for this as I can use it to build the toolchain and ultimately to control my patch tree until I am ready to send the patches upstream.

So I select a kernel which I wish to develop with, in my case this is in

recipes/elphel/linux-elphel_git.bb

So I first make sure I am starting from clean

bitbake linux-elphel -c clean

Then take the kernel as far as the configuration stage, this makes sure all patches in the metadata are applied and that the defconfig has been copied to .config and make oldconfig has been run.

bitbake linux-elphel -c configure

Now I switch to another window where I shall be actually editing the code. I change to the temporary working directory of the kernel I am working with. This path below will change depending on kernel version or name. Kernels are always found in the machine workdir so tmp/-angstrom-linux-gnueabi/

cd tmp/work/elphel-10373-angstrom-linux-gnueabi/linux-elphel-2.6.31+2.6.32-rc8+r4+gitr2a97b06f43c616abb203f4c0eb40518c44c8d7fe-r28/

At this point I normally elect to use quilt to temporarily manage my patches so.

quilt new new-feature.patch

And to add files to this patch, I make sure to do this before I make any edits as the diff ends up being the diff from when this is first called to the current state.

quilt add driver/camera/random.c

Then load the file into my favourite editor.

vi driver/camera/random.c

I make the changes I require then it is time to create a patch from these changes so I then do.

quilt refresh

The above steps created a patches/ directory inside this is one or more patches and a file called series. series is a list of all the patches in the order they should be applied (quilt takes care of this).

So now I want to actually build this code to make sure it compiles so I switch back to my original terminal and issue.

bitbake linux-elphel -c compile

If this stage fails I continue editing the files to correct the errors remebering to refresh the patches as I go. The above command can be issued repeatedly until is succeeds. When it does I then wish to make the kernel image used on the the board I am playing with so.

bitbake linux-elphel -c deploy

I take the uImage file from tmp/deploy/images/ and send it to the board for booting however it is done in my setup. For this kernel I will write it into flash on the Elphel camera.

It is almost certain that this first attempt as create the new feature will have some problems. In this case I return to the terminal where I was editing the code and fix it (still not forgetting to refresh the patches). To force the compile stage to happen again I issue the command.

bitbake linux-elphel -c compile -f

The -f means force and forces bitbake to return to that stage. When the compile is successful I can again issue the following command to deploy the image again.

bitbake linux-elphel -c deploy

I repeat this cycle as needed until I have my new feature working as I wish.

When I am happy with the changes that have been made to the kernel I will have a patch file in patches/new-feature.patch that is suitable for adding directly to the OpenEmbedded meta data or which can be applied to a git tree ready for sending upstream.

I shall leave the git instructions to the git manual. For the case where I want to apply it to the OE meta data then I edit the original bitbake recipe, adding the patch to the SRC_URI in the form

file://new-feature.patch;patch=1

For example a finished line.

SRC_URI = "git://elphel.git.sourceforge.net/gitroot/elphel/linuxdavinci;branch=elphel-10373;protocol=git \
file://new-feature.patch;patch=1 \
file://defconfig"

I copy the patch into a suitable directory in the metadata. More information on how the build system searches directories for patches can be found on the OE wiki and the bitbake manual. In this case.

recipes/linux-elphel/new-feature.patch

Now I test everything is ok with a clean rebuild so.

bitbake linux-elphel -c clean
bitbake linux-elphel


This should successfully complete the build and I should have a kernel with my new feature. If at a later date I find my new feature does not quite work as expected I can use a variation of the same process to update it. Instead of issuing the quilt new/add commands I just start editing the files in the patch again and a quilt refresh will refresh the last patch applied to the source which is most likely my new feature. If it is not or I have done this process multiple times I can use quilt pop and push to move between patches.