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.
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:<type> 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:</type><type> 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
</type>
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}"
Now the eggdbus recipe is built.
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"
