Throughout this website we are going to use a Raspberry Pi 3 Yocto Based Embedded Linux system for all tutorials and examples but before that we are going to create our first simple console based image using Yocto using the Poky reference distribution and then build on that in the next article. As this won't actually build anything that can be ran on real hardware we'll have a bit of fun with the QEMU emulator. I will not go into any great depth on Yocto and leave that to another article for another day.
Pre-requisites: Patience, sense of humour, around 30GB of free disk space and a PC that is not more than 2/3 years old preferably with at least 4 cores and a SSD drive. Yocto is tested on certain Linux distributions as listed in the Quick Start Guide.. This howto was created using Ubuntu 14.04, for other distro's refer to Reference Manual for the packages that you will need to install for Yocto to work.
First up install the required packages for your host system as described in the second link above. So for Ubuntu 14.04 we are going to install everything recommended:
sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat
sudo apt-get install libsdl1.2-dev xtermsudo apt-get install libsdl1.2-dev xterm
sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
sudo apt-get install autoconf automake libtool libglib2.0-dev libarchive-dev
sudo apt-get install python-git
Next we are going to checkout the required meta-layers, for those not au fait with Yocto think of a meta-layer a way of organising all this Yocto magic into some semblance of order. Yocto maintains a reference distribution called Poky which we are going to use to create our basic console image which is one of the images contained within Poky so we are going to create a layer for Poky. The Poky layer also contains the OpenEmbedded Build System (BitBake and OpenEmbedded Core) so there is no need to create any other layers for this how-to. As mentioned we will add a meta-layer for the Raspberry Pi in a forthcoming article to enable us to build the same image for our board, complete with ARM toolchain.
The directory structure is completely personal but I like to create a directory for the project and then within this directory create a sources directory that contains the layers and a build directory that contains all the build related stuff. The reason I like a separate sources directory is that you can use find/grep within this directory to search Yocto meta-data without having to trawl through gigabytes of build directories. Within the build directory I like to create a directory for each target machine.
Enough babbling, here are the commands to do the above. I will assume you have created a directory for this with all the relevant permissions, and are happily sitting at a terminal session in this directory.
mkdir sources
cd sources
git clone -b krogoth git://git.yoctoproject.org/poky
At the time of writing Krogoth was the latest release
Now we have our meta-layer to create our test Linux Distribution we can now bootstrap our build directory by running the following command
cd ..
. sources/poky/oe-init-build-env build
You had no conf/local.conf file. This configuration file has therefore been
created for you with some default values. You may wish to edit it to, for
example, select a different MACHINE (target hardware). See conf/local.conf
for more information as common configuration options are commented.
You had no conf/bblayers.conf file. This configuration file has therefore been
created for you with some default values. To add additional metadata layers
into your configuration please add entries to conf/bblayers.conf.
The Yocto Project has extensive documentation about OE including a reference
manual which can be found at:
http://yoctoproject.org/documentation
For more information about OpenEmbedded see their website:
http://www.openembedded.org/
### Shell environment set up for builds. ###
You can now run 'bitbake '
Common targets are:
core-image-minimal
core-image-sato
meta-toolchain
meta-ide-support
You can also run generated qemu images with a command like 'runqemu qemux86'
Hey presto we have a build directory and in this build directory we have two important files that live in the conf directory. Change to build/conf and first lets check out the bblayers.conf file which is shown below for my setup
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
/ws/yocto-test/sources/poky/meta \
/ws/yocto-test/sources/poky/meta-poky \
/ws/yocto-test/sources/poky/meta-yocto-bsp \
"
First thing we notice is that we have hard coded absolute paths which in fine if you are working on this completely by yourself but not so good if you are planning on working in a team. We can use the TOPDIR environment variable which points to our newly created build directory so we can use this to change bblayers.conf.
# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
${TOPDIR}/../sources/poky/meta \
${TOPDIR}/../sources/poky/meta-poky \
${TOPDIR}/../sources/poky/meta-yocto-bsp \
"
The other configuration file, local.conf, is used to contain variables that will control Yocto builds. The following runs local.conf through sed to remove comments and empty lines just for prime real estate HTML space, you can view the file in its entirity.
sed -e '/#/d' local.conf | sed '/^\s*$/d'
MACHINE ??= "qemux86"
DISTRO ?= "poky"
PACKAGE_CLASSES ?= "package_rpm"
EXTRA_IMAGE_FEATURES ?= "debug-tweaks"
USER_CLASSES ?= "buildstats image-mklibs"
PATCHRESOLVE = "noop"
BB_DISKMON_DIRS = "\
STOPTASKS,${TMPDIR},1G,100K \
STOPTASKS,${DL_DIR},1G,100K \
STOPTASKS,${SSTATE_DIR},1G,100K \
STOPTASKS,/tmp,100M,100K \
ABORT,${TMPDIR},100M,1K \
ABORT,${DL_DIR},100M,1K \
ABORT,${SSTATE_DIR},100M,1K \
ABORT,/tmp,10M,1K"
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
CONF_VERSION = "1"
The Yocto Reference Manual - Configuration gives more details on these variables.
As it states the MACHINE variable dictates what target device we are building for and for now we don't have one so the default is qemu that will run on the host emulating x86. We can leave the defaults for the moment and kick off a build.
todo kick off build
bitbake core-image-minimal
It will then parse all the recipes, create a dependency chain of tasks within the recipes to build and then bitbake parallelises each build task. Notice how it builds a lot of recipes with '-native' on the end, this is because it will build a lot of packages that it needs on the host system and not rely on the Host distribution you are running so that it can use specific and tested versions. It will also start building the toolchain that will be used to build the target image and once it has this with all the native packages it can start building the image for the target device.
The build will take quite a while even on an i7 with an SSD so make a cup of tea.
Mention all the bitbake build interfaces ncurses
If it doesn't build yocto provides some very useful information so along with everyone's favourite support tool 'google' and if this fails post a message on the Yocto mailing list @todo link here or IRC @todo link here, there is a thriving community with lots of developers willing to help.
There is extensive documentation on Yocto which can be found @todo link
Blurb about build servers, amazon servers, toaster, going into detail on these things later