Building your own recipes from first principles

Overview

This walk-through has the aim of taking you from a clean system through to building and packaging a project for inclusion in an image.

You may already have Yocto installed and just be looking to work with recipes for the first time, in which case you can jump forward to the section you find most relevant,
such as building an example package on the host to test or building an example package from a git commit.

The following assumptions are made. You are:

• familiar with basic Linux admin tasks
• using Ubuntu 12.04 LTS as your host build system
• working with Yocto 1.6 (daisy) release

Obtain the required packages for your host system to support Yocto

First we will install the required host packages for Ubuntu as detailed in the quickstart, i.e.

 $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath libsdl1.2-dev xterm nano

Full details of system requirements and installation can be found in the Yocto Quickstart here

Download and extract the Yocto 1.6 release

At the time of writing, the current release of Yocto (1.6) can be found here

 $ cd ~
 $ mkdir yocto
 $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.6/poky-daisy-11.0.0.tar.bz2
 $ tar xjvf poky-daisy-11.0.0.tar.bz2

This will get you the Yocto 1.6 base meta-data and the bitbake tool. You can also add in extra layers, usually of the form "meta-foo" to provide machine support and additional functionality.

Configure the build environment to build an emulator image

 $ cd ~/yocto/poky-daisy-11.0.0
 $ source oe-init-build-env build_qemux86

This will create a build tree in "build_qemux86" although you could use a different name if you so wish with no adverse effects.

It is entirely possible to have many build trees in parallel in different folders and to switch between them using oe-init-build-env.

[code]oe-init-build-env] will create a default configuration file in [code]conf/local/conf[/code] which will build an emulator image suitable for execution with [code]qemu[/code]

Build a baseline image

After configuring the environment you will be left in the build_qemux86 folder.

You should then build a baseline image, which will take some time (numbers of hours)

 $ bitbake core-image-minimal

Build an example project on the host for testing (optional)

The most straightforward way to cross-compile projects for different targets within Yocto is to make use of autotools

Projects which support [code]autotools[/code] provide a set of template files which are then used by the [code]autotools[/code] to generate [code]Makefiles[/code] and associated configuration files which are appropriate to build for the target environment.

A very basic example 'Hello World' style project called [code]bbexample[/code] has been committed to GitHub here

If you take a look at the two source files bbexample.c and bbexamplelib.c you can see the main entry point prints a Hello World message, then calls a function exported by the shared library which also prints a message.

Discussion of [code]autotools[/code] template configuration is outside the scope of this guide, but the [code]bbexample[/code] project is based on the 'Quick and Dirty' example which can be found here

The project itself builds an executable, [code]bbexample[/code] which has a dependency on a shared library [code]libbbexample.so[/code].

To build the project on the host independently of Yocto first clone the example repository

 $ mkdir ~/host
 $ cd ~/host
 $ git clone https://github.com/DynamicDevices/bbexample

Then run the autotools, configure the build, and make the project

 $ cd bbexample
 $ ./autogen.sh
 $ ./configure
 $ make

Following a successful compilation you will have a number of new files in the root of the build folder.

There is a new executable [code]bbexample[/code] which depends upon a shared library [code].libs/libbbexample.so[/code]

As this project has been built to run on the host you can

 ./bbexample

It will output

 Hello Yocto World...
 Hello World (from a shared library!)

So you have now shown that you can successfully fetch configure and build the project on the host.

Next we will look at how Yocto automates the this process of fetching, configuring and building, then also installs and packages the output files.

Build an example package based on a git repository commit

There are different ways to add new recipes to Yocto.

One way is to simply create a new recipe_version.bb file in a recipe-foo/recipe folder within one of the existing layers used by Yocto.

Placing a recipe in an existing layer (example only)

For example you could

 $ cd ~/yocto/poky-daisy-11.0.0/meta-yocto
 $ mkdir recipes-example
 $ mkdir bbexample
 $ wget https://raw.githubusercontent.com/DynamicDevices/meta-example/master/recipes-example/bbexample/bbexample_1.0.bb

The recipe will then be picked up by bitbake and you can build the recipe with

 $ bitbake bbexample 

Placing a recipe in a new layer

A preferred method for adding recipes to the build environment, and the method you should use with this guide, is to place them within a new [code]layer[/code].

Layers isolate particular sets of build meta-data based on machine, functionality or similar, and help to keep the environment clean.

An example layer, meta-example, has been created using the [code]yocto-layer[/code] command and committed into a GitHub repository here.

To use a new layer such as this you first clone the git repository and then add the layer to your bitbake configuration in [code]conf/bblayers.conf[/code]

 $ cd ~/yocto/poky-daisy-11.0.0
 $ git clone https://github.com/DynamicDevices/meta-example
 $ cd ~/yocto/poky-daisy-11.0.0/build_qemux86
 $ nano conf/bblayers.conf

Your [code]bblayers.conf[/code] should look similar to this

 # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
 # changes incompatibly
 LCONF_VERSION = "6"
 
 BBPATH = "${TOPDIR}"
 BBFILES ?= ""
 
 BBLAYERS ?= " \
   /home/user/yocto/poky-daisy-11.0.0/meta \
   /home/user/yocto/poky-daisy-11.0.0/meta-yocto \
   /home/user/yocto/poky-daisy-11.0.0/meta-yocto-bsp \
   "
 BBLAYERS_NON_REMOVABLE ?= " \
   /home/user/yocto/poky-daisy-11.0.0/meta \
   /home/user/yocto/poky-daisy-11.0.0/meta-yocto \
   "

Make the new layer visible to [code]bitbake[/code] by adding a line to [code]BBLAYERS[/code]

 BBLAYERS ?= " \
   /home/user/yocto/poky-daisy-11.0.0/meta \
   /home/user/yocto/poky-daisy-11.0.0/meta-yocto \
   /home/user/yocto/poky-daisy-11.0.0/meta-yocto-bsp \
   /home/user/yocto/poky-daisy-11.0.0/meta-example \
   "

Now bitbake can see the recipes in the new layer,

The bbexample recipe

The recipe we are going to build is /home/user/yocto/poky-daisy-11.0.0/meta-example/recipes-example/bbexample/bbexample_1.0.bb.

The main points to note are that

• SRC_URI is set to point to the git repository
• SRC_REV corresponds to a particular commit into that repository (it is also possible to specify a branch)
• There is a LICENSE variable defined to indicate the type of license to the build environment (MIT) and another variable, LIC_FILES_CHKSUM, points to a file within the source tree that will be retrieved, with a corresponding md5 check-sum to ensure that somebody has actually verified the source license file corresponds to that given to the build environment. Also that this file, and thus potentially the license, has not changed over time.
• The source directory for the recipe build, S is set to "${WORKDIR}/git" which is the default location to which the retrieved git repository will be checked out and unpacked.
• We inherit a class called autotools which provides the functionality to enable bitbake to automatically build projects with autotools support.
• There is a marked absence of a do_install function, which you may have seen elsewhere, as this is dealt with by the autotools support

To start the build

 $ bitbake bbexample

Bitbake will work through a number of tasks, including fetching the source from the git repository, unpacking, configuring, compiling, installing and packaging the output.

As we are building for the emulator, qemux86, and building RPM packages (the default), output packages will be in

 ~/yocto/poky-daisy-11.0.0/build_qemux86/tmp/deploy/rpm/???/bbexample-1.0-r0.0.armv6_vfp.rpm

For other machine targets the ??? will be replaced by a different machine-specific name. To find the location of the package you can use

 $ cd ~/yocto/poky-daisy-11.0.0/build_qemux86/tmp/deploy/rpm
 $ find -name bbexample*

(Or instead of bbexample use a prefix of the name of the recipe you are building)

This will show you both the main package and the subsidiary packages which bitbake builds for each recipe such as -dev, -doc and so forth. For more on this see here

Having found the package you can check that the contents are as expected with

 $ rpm -qlp ???/bbexample-1.0-r0.0.armv6_vfp.rpm

For the bbexample recipe we expect to see the cross-compiled executable [code]bbexample[/code] and the shared library it needs [code]libbbexample.so.1[/code]

 /usr
 /usr/bin
 /usr/bin/bbexample
 /usr/lib
 /usr/lib/libbbexample.so.1
 /usr/lib/libbbexample.so.1.0.0

You could then add the output of this recipe to your output image by adding something like this to your [code]conf/local.conf[/code]

IMAGE_INSTALL_append = " bbexample"

Build an example package based on a remote source archive

TBD

Build an example package based on a local source archive

TBD