World of XorA

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.