Yocto Project Quick Build — The Yocto Project ® 5.3-tip documentation

Yocto Project Quick Build — The Yocto Project ® 5.3-tip documentation
single
5.3-tip
Yocto Project Quick Build
View page source
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
supported version of 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
Here are the packages needed to build an image on a headless system
with a supported Ubuntu or Debian Linux 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
You also need to ensure you have the
en_US.UTF-8
locale enabled:
$ locale --all-locales | grep en_US.utf8
If this is not the case, you can reconfigure the
locales
package to add it
(requires an interactive shell):
$ sudo dpkg-reconfigure locales
Note
If you are not in an interactive shell,
dpkg-reconfigure
will
not work as expected. To add the locale you will need to edit
/etc/locale.gen
file to add/uncomment the
en_US.UTF-8
locale.
A naive way to do this as root is:
$ echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
$ locale-gen
If your build system has the
oss4-dev
package installed, you
might experience QEMU build failures due to the package installing
its own custom
/usr/include/linux/soundcard.h
on the Debian
system. If you run into this situation, try either of these solutions:
$ sudo apt build-dep qemu
$ sudo apt remove oss4-dev
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
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.
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-whinlatter OpenEmbedded - 'nodistro' basic configuration, release 5.3 'whinlatter'
3. poky-whinlatter Poky - The Yocto Project testing distribution configurations and hardware test platforms, release 5.3 'whinlatter'
4. oe-nodistro-master OpenEmbedded - 'nodistro' basic configuration
...

Please select one of the above configurations by its number:
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:
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:
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:
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.
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.
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
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
distro/poky
sets the
DISTRO
to
Poky
distro/
fragment).
machine/qemux86-64
sets the
MACHINE
to
qemux86-64
machine/
fragment).
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.
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.
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.
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
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
whinlatter
https
//
git
yoctoproject
org
meta
raspberrypi
../
layers
meta
raspberrypi
Add Your Layer to the Layer Configuration File:
Before you can use
it, you must add the layer and its dependencies 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.
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
) 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"
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 Your Own Layer
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.