Yocto Project Quick Build

Welcome!

This short document steps you through the process for a typical image build using the Yocto Project. The document also introduces how to configure a build for specific hardware. You will use Yocto Project to build a reference embedded OS called Poky.

Note

  • The examples in this paper assume you are using a native Linux system running a recent Ubuntu Linux distribution. If the machine you want to use Yocto Project on to build an image (Build Host) is not a native Linux system, you can still perform these steps by using CROss PlatformS (CROPS) and setting up a Poky container. See the Setting Up to Use CROss PlatformS (CROPS) section in the Yocto Project Development Tasks Manual for more information.

  • You may use version 2 of Windows Subsystem For Linux (WSL 2) to set up a build host using Windows 10 or later, Windows Server 2019 or later. See the Setting Up to Use Windows Subsystem For Linux (WSL 2) section in the Yocto Project Development Tasks Manual for more information.

If you want more conceptual or background information on the Yocto Project, see the Yocto Project Overview and Concepts Manual.

Compatible Linux Distribution

Make sure your Build Host meets the following requirements:

  • At least 140 Gbytes of free disk space, though much more will help to run multiple builds and increase performance by reusing build artifacts.

  • At least 32 Gbytes of RAM, though a modern build host with as much RAM and as many CPU cores as possible is strongly recommended to maximize build performance.

  • Runs a supported Linux distribution (i.e. recent releases of Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux distributions that support the Yocto Project, see the Supported Linux Distributions section in the Yocto Project Reference Manual. For detailed information on preparing your build host, see the Preparing the Build Host section in the Yocto Project Development Tasks Manual.

  • Ensure that the following utilities have these minimum version numbers:

    • Git 1.8.3.1 or greater

    • tar 1.28 or greater

    • Python 3.9.0 or greater.

    • gcc 10.1 or greater.

    • GNU make 4.0 or greater

If your build host does not satisfy all of the above version requirements, you can take steps to prepare the system so that you can still use the Yocto Project. See the Required Git, tar, Python, make and gcc Versions section in the Yocto Project Reference Manual for information.

Build Host Packages

You must install essential host packages on your build host. The following command installs the host packages based on an Ubuntu distribution:

sudo apt-get install build-essential chrpath cpio debianutils diffstat file gawk gcc git iputils-ping libacl1 locales python3 python3-git python3-jinja2 python3-pexpect python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd

Note

For host package requirements on all supported Linux distributions, see the Required Packages for the Build Host section in the Yocto Project Reference Manual.

Use Git to Clone bitbake-setup

Once you complete the setup instructions for your machine, you need to get a copy of the bitbake-setup tool to setup the Poky reference distribution on your build host. Use the following commands to clone the bitbake repository.

$ git clone https://git.openembedded.org/bitbake

Setup a build environment with the following command:

$ ./bitbake/bin/bitbake-setup init

By default, this will setup a top directory in the current directory.

If you prefer to setup your builds in a different top directory, for example $HOME/bitbake-builds, you can set it with the bitbake-setup settings command:

$ ./bitbake/bin/bitbake-setup settings set --global default top-dir-prefix $HOME

Note

Use bitbake-setup settings list to get an overview of the settings.

bitbake-setup init is an interactive program by default and will ask you to make some decisions. Depending on your answers, the output may differ from the examples below.

  1. Choose a configuration (for example, poky-master):

    Available configurations:
1. poky-master  Poky - The Yocto Project testing distribution configurations and hardware test platforms
2. oe-nodistro  OpenEmbedded - 'nodistro' basic configuration

Please select one of the above configurations by its number:
1

    Depending on the choice above, new options can be prompted to further specify which configuration to use. For example:

    Available bitbake configurations:
1. poky Poky - The Yocto Project testing distribution
2. poky-with-sstate     Poky - The Yocto Project testing distribution with internet sstate acceleration. Use with caution as it requires a completely robust local network with sufficient bandwidth.

Please select one of the above bitbake configurations by its number:
1

  2. Choose a target MACHINE (for example, qemux86-64):

    Target machines:
1. machine/qemux86-64
2. machine/qemuarm64
3. machine/qemuriscv64
4. machine/genericarm64
5. machine/genericx86-64

Please select one of the above options by its number:
1

  3. Choose a DISTRO (for example, poky):

    Distribution configuration variants:
1. distro/poky
2. distro/poky-altcfg
3. distro/poky-tiny

Please select one of the above options by its number:
1

  4. Choose a setup directory name:

    Enter setup directory name: [poky-master-poky-distro_poky-machine_qemux86-64]

    Press Enter to leave it to the default value shown in the brackets, or type a custom directory name.

Note

If you prefer to run non-interactively, you can run a command like the following:

$ bitbake-setup init --non-interactive poky-master poky-with-sstate distro/poky machine/qemux86-64

The init command creates a new Setup in the top directory. The default name is derived from the selected configuration above.

For the selected options in the above example, this would be:

poky-master-poky-distro_poky-machine_qemux86-64

This will be our example configuration in the following sections.

This directory contains:

  • The BitBake Build directory, named build. Later, when the build completes, this directory contains all the files created during the build.

    This directory also contains a README, describing the current configuration and showing some instructions.

  • The layers needed to build the Poky reference distribution, in the layers directory.

  • A config directory, representing the current configuration used for this setup.

Note

It is also possible to setup the Poky reference distro manually. For that refer to the Setting Up the Poky Reference Distro Manually section of the Yocto Project Development Tasks Manual.

Building Your Image

Use the following steps to build your image. The build process creates an entire Linux distribution, including the toolchain, from source.

Note

  • If you are working behind a firewall and your build host is not set up for proxies, you could encounter problems with the build process when fetching source code (e.g. fetcher failures or Git failures).

  • If you do not know your proxy settings, consult your local network infrastructure resources and get that information. A good starting point could also be to check your web browser settings. Finally, you can find more information on the “Working Behind a Network Proxy” page of the Yocto Project Wiki.

  1. Initialize the Build Environment: Source the init-build-env environment setup script within the BitBake build directory to setup the BitBake build environment on your host:

    $ source poky-master-poky-distro_poky-machine_qemux86-64/build/init-build-env
Poky reference distro build

  2. Examine Your Current Configuration: When you set up the build environment, an configuration file named toolcfg.conf becomes available in a conf/ sub-directory of the BitBake build directory. This file is automatically modified by the bitbake-config-build command-line tool. With this tool, list the currently enabled configuration fragments:

    $ bitbake-config-build list-fragments

    For this configuration, the default is to use two Built-in Fragments:

    These fragment values correspond to the choices made when running bitbake-setup init.

    Note

    These set up the environment similar to what was previously in the local configuration file local.conf, which is now largely empty. To setup the build how it was done previously, see the Setting Up the Poky Reference Distro Manually section of the Yocto Project Development Tasks Manual.

    The current configuration does not allow the root user to login. As this can be useful for development, you can enable the core/yocto/root-login-with-empty-password fragment:

    $ bitbake-config-build enable-fragment root-login-with-empty-password

    Note

    You can significantly speed up your build and guard against fetcher failures by using Shared State Cache mirrors and enabling Hash Equivalence. This way, you can use pre-built artifacts rather than building them. This is relevant only when your network and the server that you use can download these artifacts faster than you would be able to build them.

    To use such mirrors, enable the core/yocto/sstate-mirror-cdn fragment:

    $ bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn

    The hash equivalence server needs the websockets python module version 9.1 or later. Debian GNU/Linux 12 (Bookworm) and later, Fedora, CentOS Stream 9 and later, and Ubuntu 22.04 (LTS) and later, all have a recent enough package. Other supported distributions need to get the module some other place than their package feed, e.g. via pip. You can otherwise install a Buildtools tarball by following the instructions in the Required Git, tar, Python, make and gcc Versions section of the Yocto Project Reference Manual.

  3. Start the Build: Continue with the following command to build an OS image for the target, which is core-image-sato in this example:

    $ bitbake core-image-sato

    For information on using the bitbake command, see the BitBake section in the Yocto Project Overview and Concepts Manual, or see The BitBake Command in the BitBake User Manual.

  4. Simulate Your Image Using QEMU: Once this particular image is built, you can start QEMU, which is a Quick EMUlator that ships with the Yocto Project:

    $ runqemu qemux86-64

    If you want to learn more about running QEMU, see the Using the Quick EMUlator (QEMU) chapter in the Yocto Project Development Tasks Manual.

  5. Exit QEMU: Exit QEMU by either clicking on the shutdown icon or by typing Ctrl-C in the QEMU transcript window from which you evoked QEMU.

Customizing Your Build for Specific Hardware

So far, all you have done is quickly built an image suitable for emulation only. This section shows you how to customize your build for specific hardware by adding a hardware layer into the Yocto Project development environment.

In general, layers are repositories that contain related sets of instructions and configurations that tell the Yocto Project what to do. Isolating related metadata into functionally specific layers facilitates modular development and makes it easier to reuse the layer metadata.

Note

By convention, layer names start with the string “meta-“.

Follow these steps to add a BSP layer:

  1. Find a Layer: Many BSP layers are available. The layer index can be used to find such layers. This example adds the meta-raspberrypi BSP layer.

    First, clone the layer next the other layers:

    git clone -b whinlatter https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi

  2. Add Your Layer to the Layer Configuration File: Before you can use it, you must add the layer and its dependencies it to your bblayers.conf file, which is found in the Build Directory (conf/) directory.

    For this, the bitbake-layers add-layer can be used:

    $ bitbake-layers add-layer ../layers/meta-raspberrypi

    You can find more information on adding layers in the Adding a Layer Using the bitbake-layers Script section.

  3. Change the Configuration to Build for a Specific Machine: The MACHINE variable is defined by the machine/ fragment. For this example, the meta-raspberrypi layer provides the raspberrypi5 machine, so let’s make it the MACHINE used for the build with bitbake-config-build:

    $ bitbake-config-build enable-fragment machine/raspberrypi5

    Note

    See the “Examine Your Current Configuration” step earlier for more information on configuring the build.

    The raspberrypi5 build depends on non-free firmware (https://github.com/RPi-Distro/firmware-nonfree) that includes the Synaptics license. See the ipcompliance.md document for more information. Add the synaptics-killswitch value to the LICENSE_FLAGS_ACCEPTED variable, in the conf/local.conf file of your build directory:

    LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch"

  4. Start The Build: The configuration is now set to build for the Raspberry Pi 5. Start the build again:

    $ bitbake core-image-sato

Completing these steps has added the meta-raspberrypi layer to your Yocto Project development environment and configured it to build for the raspberrypi5 machine.

Note

The previous steps are for demonstration purposes only. If you were to attempt to build an image for the raspberrypi5 machine, you should read the README.md file in meta-raspberrypi.

Creating Your Own General Layer

Maybe you have an application or specific set of behaviors you need to isolate. You can create your own general layer using the bitbake-layers create-layer command. The tool automates layer creation by setting up a subdirectory with a layer.conf configuration file, a recipes-example subdirectory that contains an example.bb recipe, a licensing file, and a README.

The following commands run the tool to create a layer named meta-mylayer:

$ bitbake-layers create-layer ../layers/meta-mylayer
NOTE: Starting bitbake server...
Add your new layer with 'bitbake-layers add-layer ../layers/meta-mylayer'

Note

By convention, layers are placed side-by-side.

For more information on layers and how to create them, see the Creating a General Layer Using the bitbake-layers Script section in the Yocto Project Development Tasks Manual.

Where To Go Next

Now that you have experienced using the Yocto Project, you might be asking yourself “What now?”. The Yocto Project has many sources of information including the website, wiki pages, and user manuals:

  • Website: The Yocto Project Website provides background information, the latest builds, breaking news, full development documentation, and access to a rich Yocto Project Development Community into which you can tap.

  • Video Seminar: The Introduction to the Yocto Project and BitBake, Part 1 and Introduction to the Yocto Project and BitBake, Part 2 videos offer a video seminar introducing you to the most important aspects of developing a custom embedded Linux distribution with the Yocto Project.

  • Yocto Project Overview and Concepts Manual: The Yocto Project Overview and Concepts Manual is a great place to start to learn about the Yocto Project. This manual introduces you to the Yocto Project and its development environment. The manual also provides conceptual information for various aspects of the Yocto Project.

  • Yocto Project Wiki: The Yocto Project Wiki provides additional information on where to go next when ramping up with the Yocto Project, release information, project planning, and QA information.

  • Yocto Project Mailing Lists: Related mailing lists provide a forum for discussion, patch submission and announcements. There are several mailing lists grouped by topic. See the Mailing lists section in the Yocto Project Reference Manual for a complete list of Yocto Project mailing lists.

  • Comprehensive List of Links and Other Documentation: The Links and Related Documentation section in the Yocto Project Reference Manual provides a comprehensive list of all related links and other user documentation.

The Yocto Project ®
<docs@lists.yoctoproject.org>

Permission is granted to copy, distribute and/or modify this document under the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by Creative Commons.

To report any inaccuracies or problems with this (or any other Yocto Project) manual, or to send additions or changes, please send email/patches to the Yocto Project documentation mailing list at docs@lists.yoctoproject.org or log into the Libera Chat #yocto channel.