Not yet a member? Register Here

Build a Custom Raspberry Pi Distro with OpenEmbedded & Yocto

Posted by: admin
Posted On: September 5, 2012 (05:09)
Updated 5th Jan - Thanks to Alex Lennon

- Updated to use a newer revision of OpenEmbedded/Yocto

You may have read my previous article where I talked about building a virtual image to run in qemu which was similar to the Raspberry Pi's architecture and allowed for basic development. In that I mentioned that hopefully support for the real raspberry pi hardware would eventually be included, and it now is!

With the development of the Raspberry Pi hardware layer being spear headed by DJWillis ( and other generous members of the community, it is now possible to build a custom embedded image with full architecture support.

In this post I will describe how to build an image for the Raspberry Pi using the meta-raspberrypi BSP (Board Support Package) layer, the OpenEmbedded build framework and the Poky (Yocto Project Supported) distro.

OpenEmbedded is an open source build system which helps create custom Linux based systems for embedded products. It provides a complete embedded Linux build environment with tools (Bitbake application), meta data (oe-core) and documentation.

An OpenEmbedded build will create a custom Linux distribution to your exact specifications. You can tweak the build all the way down to patching the Kernel and setting the level of GCC optimisation.

So, what is the Yocto Project if OpenEmbedded is the build system? The Yocto Project is a Linux Foundation project that provides a stable and well tested version of OpenEmbedded. It also provides a small layer of it's of own which houses the Poky distro configuration - a minimal distro specification with a well tested configuration of OpenEmbedded packages and features. It also provides extensive documentation which can be viewed here: I highly recommend you browse through the documentation and get to know and understand some of the terminology of the OpenEmbedded ecosystem.

The Yocto Project helps tame OpenEmbedded to make it suitable for Beginners right through to Advanced users, however you will need some level of technical prowess and also a running Linux distribution, either in a virtual machine or natively on your PC.

From here on I will assume that you are running a Linux distribution, have access to a terminal emulator (xterm, gnome-terminal etc..), the git source control management system installed and have ample free space and bandwidth. This process can consume as much as 50GB of space on your hard drive and take a whole day to compile!

Step 1: Some terms and context to understand

The Yocto Project: Provides OpenEmbedded (oe-core layer), Bitbake (build tool) and the meta-yocto layer at a stable and well tested version.

Metadata: files which contain information on how to build packages

Bitbake: Build and metadata manager, tells the system how to build packages, inspired by Gentoo's Portage tool.

Poky: A distribution with a well tested configuration of oc-core packages and features.

Step 2: Clone the Yocto Project Git repo

We are going to download a beta version of the Yocto Project compilation which I have tested and is known to be working on the Pi.

First navigate to the directory you want to store your Yocto Project files and run the following command:

git clone git:// yoctoProject

This will clone the master version of the yocto project collection.

cd into the yoctoProject directory

cd yoctoProject

git checkout 4a36a32567ecfbc7ce7b967803e6e23314953ef5

This checks out a revision that I have tested and I know to work. This is necessary as we are using code in active development.

Step 3: Get the meta-raspberrypi layer

The meta-raspberrypi layer is a BSP layer, this is a layer which holds all the meta-data for building for the Raspberry Pi, most importantly the Kernel and architecture configuration. We're going to do a git clone of the meta-raspberrypi repository.

Clone the meta-raspberrypi repository

git clone

Checkout to the same commit as I used in this post.

cd meta-raspberrypi

git checkout 305c5259e24eaa9fb285ca983dc4f9454743fa0c

Step 3: Setup the build environment

Go back to your yoctoProject directory, if you are still in the meta-raspberrypi directory then a simple:

cd ..

Will suffice.

Next, setup the build environment variables by sourcing the build script:

source oe-init-build-env raspberryPiBuild/

You have now setup the environment, a new folder 'raspberryPiBuild' has been automatically created and you have then been placed into it.

Step 4: Configure the build

Now you have setup the environment, Bitbake can build for a number of architectures. You must configure it to build for the Raspberry Pi. Using your favourite text editor, edit the conf/local.conf file in your raspberryPiBuild directory.

nano conf/local.conf

In the conf file edit the following parameters:

If you have more than 1 CPU core uncomment (remove the hash character) BB_NUMBER_THREADS and change the "4" to the number of threads available on your CPU + 1.

I have 8 threads on my PC, so I would change it to 9.


Note: Make sure there is no empty space before the variable name.

If you have more than 1 CPU core uncomment (remove the hash character) PARALLEL_MAKE and change the "-j 4" to the number of threads available on your CPU + 1.


Note: Make sure there is no empty space before the variable name.

Next scroll down the file until you see the MACHINE definition variables. Add your own custom one right at the start that says:

MACHINE ?= "raspberrypi"

Ensure that all the following MACHINE variables are commented out.

Finally, we need to hide some packages (recipes) from bitbake as they're not yet compatible with the meta-yocto/oe-core layers we are using. So add the following line right at the bottom of the file:

BBMASK = "meta-raspberrypi/recipes-multimedia/libav|meta-raspberrypi/recipes-core/systemd"

Now save the file.

Next up, we need to add the meta-rasperrypi layer we cloned earlier to the file conf/bblayers.conf. Open this file:

nano conf/bblayers.conf

Add a line below the last entry in the BBLAYERS variable (it should end in meta-yocto) stating:


Please not the format of the other lines in the BBLAYERS variable, it will be very similar to the ones above but with the meta-raspberrypi instead of meta-*.

You can see my example below:

/home/jack/Projects/poky-rasp/meta \
/home/jack/Projects/poky-rasp/meta-yocto \
/home/jack/Projects/poky-rasp/meta-yocto-bsp \
/home/jack/Projects/poky-rasp/meta-raspberrypi \

Step 5: Build a minimal distribution

To compile your new distribution a few development tools are required, the install procedure for a few common Linux distributions are listed below. If you do not run one of these distributions then you can try running the bitbake command below anyway and it will alert you to which dependencies your system is missing and you can then install them with the package manager of your choice.

Packages required for Ubuntu:

sudo apt-get install sed wget cvs subversion git-core coreutils \
unzip texi2html texinfo libsdl1.2-dev docbook-utils gawk \
python-pysqlite2 diffstat help2man make gcc build-essential \
g++ desktop-file-utils chrpath libgl1-mesa-dev libglu1-mesa-dev \
mercurial autoconf automake groff libtool xterm

Packages required for Fedora:

sudo yum groupinstall "development tools"

sudo yum install python m4 make wget curl ftp hg tar bzip2 gzip \
unzip python-psyco perl texinfo texi2html diffstat openjade \
docbook-style-dsssl sed docbook-style-xsl docbook-dtds \
docbook-utils sed bc eglibc-devel ccache pcre pcre-devel quilt \
groff linuxdoc-tools patch linuxdoc-tools cmake help2man \
perl-ExtUtils-MakeMaker tcl-devel gettext chrpath ncurses apr \
SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \
autoconf automake libtool xterm

Packages required for openSUSE:

sudo zypper install python gcc gcc-c++ libtool \
subversion git chrpath automake make wget help2man \
diffstat texinfo mercurial freeglut-devel libSDL-devel

The meta-raspberrypi layer provides us with a very minimal image which will construct an image file that we can directly write onto our SD card.

To build the image we run

bitbake rpi-basic-image

Ensure, you are running this from your raspberryPiBuild directory.

Now, depending on the speed of your machine this could take anything from 3 hours (Quad Core i7, 3GHz) to 24hrs+.

Step 6: Running our new image

Assuming the image built without an issues we can now copy the image to our SD card. The image is placed in the 'tmp/deploy/images' directory within your raspberryPiBuild directory.

So, finally:

dd if=tmp/deploy/images/ of=/path/to/sd/card

This image will boot to a TTY and will also boot with DHCP enabled on the Ethernet port with the DropBear SSH server automatically started.

To log in using the TTY or over SSH the username is root and password is blank (i.e. just press enter when asked for password).

Final Comments

There are reams of documentation available and if you are truly interested in building a custom Linux distribution for your Pi I would suggest you start reading!

There are a lot more packages available for OpenEmbedded but it is much wilder, so take a look if you wish to explore further and play with the bleeding edge!

This guide covers only building a very basic system, there are a multitude of ways to expand the use of your new build through adding packages and image features. These will hopefully be covered at a later date, but are currently fully explained in the Yocto Project documentation if you wish to steam ahead!

Think this blog post is missing some information? Think you could do a better job of explaining some of the finer points? If so, this blog post is available at PimpMyPi GitHub where you can send changes and updates for me to incorporate!

You are posting as Anonymous

Spam Test: Yes/No, Is the Raspberry Pi edible?
22 Nov 14, 8:17
I got the following build error.
Actually when I did git check, it was giving me errors about "detached head", not sure if it's related.

Summary: 2 tasks failed:
/home/ella/demo/yocto_project/yoctoProject/meta-raspberrypi/recipes-kernel/linux-libc-headers/, do_fetch
/home/ella/demo/yocto_project/yoctoProject/meta/recipes-devtools/gcc/, do_compile
Summary: There were 7 WARNING messages shown.
Summary: There were 3 ERROR messages shown, returning a non-zero exit code.
21 Oct 14, 4:03
Apologies, ignore me. Found a more current resource:
21 Oct 14, 3:03
Hi there, I am having trouble building the image.. I get this: ERROR: Logfile of failure stored in: /home/stuharwood/git/yocto2/yoctoProject/raspberryPiBuild/tmp/work/x86_64-linux/quilt-native/0.60-r0/temp/log.do_populate_sysroot.7012
Log data follows:
| DEBUG: Executing python function sstate_task_prefunc
| DEBUG: Python function sstate_task_prefunc finished
| DEBUG: Executing python function do_populate_sysroot
| DEBUG: Executing shell function sysroot_stage_all
| tar: --same-order option cannot be used with -c
| Try 'tar --help' or 'tar --usage' for more information.
| tar: This does not look like a tar archive
| tar: Exiting with failure status due to previous errors
| DEBUG: Python function do_populate_sysroot finished
| ERROR: Function failed: sysroot_stage_all (see /home/stuharwood/git/yocto2/yoctoProject/raspberryPiBuild/tmp/work/x86_64-linux/quilt-native/0.60-r0/temp/log.do_populate_sysroot.7012 for further information)
21 Aug 14, 10:16
Thanks, it worked for me, after following the steps I was able to boot with a new fresh kernel for my raspberry pi. But, now my question is, if I want to add/ install some packages which are required for my further use through "apt-get" package manager. but, this build won't have apt-get installed So how to resolve this? Is there any way to overcome with this?
29 May 14, 1:21
when i run bitbake rpi-basic-image
it gives me the foloowing errors
please help me out i want to build this image
08 Jan 14, 11:31
How can I enable color to the terminal interface ?
27 Nov 13, 15:20
I would attempt to use a later revision of the OpenEmbedded layers, a lot of mesa changes have recently been merged.
06 Nov 13, 7:19
There is a problem with the mesa-recipe that prevent building the image.
There is a change in August that introduces a patch for mesa.
With deactivation of the mesa-recipe a can compile.
Has anyone a solution for that?
12 Jun 13, 15:59
Sometimes github plays up, if you run into fetcher failures I would suggest giving it a day and trying again.
29 Apr 13, 10:13
I have a Problem with fetching Files.. See here can you help?
22 Apr 13, 8:15
If you are attempting to use the latest master then all questions should go to the Yocto Mailing list where developers will be able help. The commits chosen in the above blog post are tested and working.
31 Mar 13, 14:47
I just received a new RasPi and used the latest yocto build and all I get is the PWR LED and a single flash of the ACT LED which leads me to believe that the PI does not recognize the boot image. Any help would be appreciated.
28 Feb 13, 13:09
What's the splash screen, the colour square? If it is hanging their then it is a firmware issue I'm afraid. Make sure you are using the correct checkouts as defined above and also that you are supplying the RasPi with enough power.
25 Feb 13, 23:35
I've generated rpi-basic-image-raspberrypi.rpi-sdimg image and flashed it to SD. Unfortunately when I boot rpi it hung at splash screen. Could anyone give some hint how it investigate it? I can't see any console output.
25 Feb 13, 22:04
Seems to work now I've got the name correct and the SD card path sorted. Thanks to all. :)
24 Feb 13, 15:52
10th Feb - rpi-basic-image-raspberrypi.rpi-sdimg is what you need. It seems to have had the machine name appended to it somehow.

12th Feb: That's oe-core policy, you'll have to hit the docs for that I'm afraid!
12 Feb 13, 9:58
Works fine!!
Now I made some changes in the local.conf file and want to rerun/rebuild the project to implement the changes.
So I run:
bitbake rpi-basic-image -c clean
bitabke rpi-basic-image
Then it's starts directley with do_rootfs which is not what I expected and the changes are not implemented.

Do I have to remove some files?
10 Feb 13, 16:22
What have I done wrong? I seem to have every file in the /images save the one required?

david@david-SG31:/media/541f2023-ee1c-446f-ac24-8ca3866b43d8/feb13_yocto_pi/yoctoProject/raspberryPiBuild/tmp/deploy/images$ ls
15 Jan 13, 13:39
I'm not sure that the Raspberry Pi kernel uses the 'Yocto Project Kernel' configuration structure. Your best bet is to ask on the openembedded-devel or the yocto mailing lists. They're very helpful!
15 Jan 13, 12:46
Excellent blog article. The instructions there worked perfectly for me to get the basic image up and running. Thanks a million!

I'm now trying to add new kernel modules to the build. Has anyone succeeded in doing that? Following instructions in the Yocto docs isn't getting me too far unfortunately. I'm trying to specify the additional CONFIG_* options with a .cfg referenced by a .bbappend in meta-raspberrypi/recipes-kernel/linux/, and the kernel seems to recompile without any problems but the .ko's don't appear in the final image :-(
14 Jan 13, 8:33
Github can sometimes be a bit odd, unfortunately this is out of my control and the problems will hopefully be fixed soon! The best advice I can give you is to send a complaint to github and keep trying every couple of hours!
10 Jan 13, 14:07
I am getting the same problem as the 1/1/13 post. Getting 404's in the log, as though github is not there. Any ideas what is going on?
05 Jan 13, 16:48
Hi everyone, this blog post has been updated (5th Jan) to use a newer revision of OpenEmbedded. Some of the issues you have been seeing should have been resolved.
01 Jan 13, 10:37

I'm stucked in this point:

WARNING: Failed to fetch URL git://;protocol=git;branch=rpi-3.2.27, attempting MIRRORS if available
ERROR: Fetcher failure: Fetch command failed with exit code 128, output:
Cloning into bare repository '/mnt/DEV/raspberrypi/poky/build/downloads/git2/'...

fatal: The remote end hung up unexpectedly
fatal: early EOF
fatal: index-pack failed

ERROR: Function failed: Fetcher failure for URL: 'git://;protocol=git;branch=rpi-3.2.27'. Unable to fetch URL from any source.
ERROR: Logfile of failure stored in: /mnt/DEV/raspberrypi/poky/build/tmp/work/armv6-vfp-poky-linux-gnueabi/linux-libc-headers-raspberrypi/3.2.27-r0/temp/log.do_fetch.3897
ERROR: Task 447 (/mnt/DEV/raspberrypi/poky/meta-raspberrypi/recipes-kernel/linux-libc-headers/, do_fetch) failed with exit code '1'
WARNING: Failed to fetch URL git://;protocol=git;branch=rpi-3.2.27, attempting MIRRORS if available
ERROR: Fetcher failure: Fetch command failed with exit code 128, output:
Cloning into bare repository '/mnt/DEV/raspberrypi/poky/build/downloads/git2/'...

fatal: The remote end hung up unexpectedly
fatal: early EOF
fatal: index-pack failed

ERROR: Function failed: Fetcher failure for URL: 'git://;protocol=git;branch=rpi-3.2.27'. Unable to fetch URL from any source.
ERROR: Logfile of failure stored in: /mnt/DEV/raspberrypi/poky/build/tmp/work/raspberrypi-poky-linux-gnueabi/linux-raspberrypi/3.2.27+git10182a3bc434b27740f81c2b836a1af943060241-r6/temp/log.do_fetch.3900
ERROR: Task 236 (/mnt/DEV/raspberrypi/poky/meta-raspberrypi/recipes-kernel/linux/, do_fetch) failed with exit code '1'
NOTE: Tasks Summary: Attempted 1462 tasks of which 1460 didn't need to be rerun and 2 failed.
Waiting for 0 running tasks to finish:

Summary: 2 tasks failed:
/mnt/DEV/raspberrypi/poky/meta-raspberrypi/recipes-kernel/linux-libc-headers/, do_fetch
/mnt/DEV/raspberrypi/poky/meta-raspberrypi/recipes-kernel/linux/, do_fetch
Summary: There were 2 WARNING messages shown.
Summary: There were 4 ERROR messages shown, returning a non-zero exit code.
29 Dec 12, 14:00
Got further this time...but still no Cigar.

WARNING: Failed to fetch URL, attempting MIRRORS if available
WARNING: ossp-uuid-native: No generic license file exists for: ossp_uuid in any provider
WARNING: Failed to fetch URL git://;protocol=git;branch=rpi-3.2.27, attempting MIRRORS if available
28 Dec 12, 21:36
Many fatal errors :(
For example ...WARNING: Failed to fetch URL
Will try again tomorrow.
28 Dec 12, 19:03
Edited bblayers.conf from Version 6 to Version 5. Now appear to be building, but using the Force more than following a sound plan at this time....
28 Dec 12, 18:51
Deleted /home/david/PI/yoctoProject/meta-yocto-bsp \
Now getting bblayer.conf version misconfiguration error....marching on...
28 Dec 12, 17:20
Please Help...

ERROR: Unable to parse /home/david/PI/yoctoProject/meta-yocto-bsp/conf/layer.conf: [Errno 2] No such file or directory: '/home/david/PI/yoctoProject/meta-yocto-bsp/conf/layer.conf'


23 Dec 12, 13:44
16 Dec 12, 10:55
I tried a few months ago to build from the instructions over at Distant Earth, but the resulting image didn't boot. This does exactly what I need! Thanks so much!
03 Oct 12, 13:55
Trying to do this with the new open-webOS. Compiling right now....task 500 of 3932 Hopefully it'll work!
18 Sep 12, 6:32
Yes, this is just standard OpenEmbedded, Yocto Tools and the Raspberry Pi BSP. Hob is sometimes a little awkward to use - I would recommend adding packages using the IMAGE_INSTALL += "application1 application2" notation.
14 Sep 12, 4:16
Great tutorial - first build works well!
Now looking to add additional packages - is the Bitbake gui, Hob, available with this repo?