10 Setting Up the Poky Reference Distro Manually

While the default way to setup the Poky reference distro is to use bitbake-setup, it is also possible to manually setup the environment. This document guides through this setup step-by-step.

Note

This document will produce a setup similar to what is described in Yocto Project Quick Build, which shows how to setup Poky with bitbake-setup.

10.1 Use Git to Clone The Layers

Go to Releases wiki page, and choose a release (such as yocto-5.2), corresponding to either the latest stable release or a Long Term Support release.

Once you complete the setup instructions for your machine (see the System Requirements section of the Yocto Project Reference Manual), you need to get a copy of the different layers needed to setup the Poky reference distribution on your build host. Use the following commands:

$ mkdir layers/
$ git clone -b yocto-5.2 https://git.openembedded.org/bitbake ./layers/bitbake
$ git clone -b yocto-5.2 https://git.openembedded.org/openembedded-core ./layers/openembedded-core
$ git clone -b yocto-5.2 https://git.yoctoproject.org/meta-yocto ./layers/meta-yocto

10.2 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: From your current working directory, setup a build environment with the following command:
```
$ TEMPLATECONF=$PWD/layers/meta-yocto/meta-poky/conf/templates/default source ./layers/openembedded-core/oe-init-build-env
```
Among other things, the script creates the Build Directory, which is build in this case and is located in the Source Directory. After the script runs, your current working directory is set to the Build Directory. Later, when the build completes, the Build Directory contains all the files created during the build.
Examine Your Local Configuration File: When you set up the build environment, a local configuration file named local.conf becomes available in a conf sub-directory of the Build Directory. For this example, the defaults are set to build for a qemux86-64 target, which is suitable for emulation. The package manager used is set to the RPM package manager.
Tip

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, uncomment the below lines in your conf/local.conf file in the Build Directory:
```
BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws"
SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
BB_HASHSERVE = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
```
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.