Creating a build directory

Before building your first Yocto image, we need to create a build directory for it.

The build process, on a host system as outlined before, can take up to 1 hour and needs around 20 GB of hard drive space for a console-only image. A graphical image, such as core-image-sato, can take up to 4 hours for the build process and occupy around 50 GB of space.

How to do it...

The first thing we need to do is create a build directory for our project, where the build output will be generated. Sometimes, the build directory may be referred to as the project directory, but build directory is the appropriate Yocto term.

There is no right way to structure the build directories when you have multiple projects, but a good practice is to have one build directory per architecture or machine type. They can all share a common downloads folder, and even a shared state cache (this will be covered later on), so keeping them separate won't affect the build performance, but it will allow you to develop on multiple projects simultaneously.

To create a build directory, we use the oe-init-build-env script provided by Poky. The script needs to be sourced into your current shell, and it will set up your environment to use the OpenEmbedded/Yocto build system, including adding the BitBake utility to your path.

You can specify a build directory to use or it will use build by default. We will use qemuarm for this example:

$ cd /opt/yocto/poky
$ source oe-init-build-env qemuarm  

The script will change to the specified directory.

As oe-init-build-env only configures the current shell, you will need to source it on every new shell. But, if you point the script to an existing build directory, it will set up your environment but won't change any of your existing configurations.

BitBake is designed with a client/server abstraction, so we can also start a persistent server and connect a client to it. To instruct a BitBake server to stay resident, configure a timeout in seconds in your build directory's conf/local.conf configuration file as follows:

BB_SERVER_TIMEOUT = "n"  

With n being the time in seconds for BitBake to stay resident.

With this setup, loading cache and configuration information each time is avoided, which saves some overhead.

How it works...

The oe-init-build-env script calls scripts/oe-setup-builddir script inside the Poky directory to create the build directory.

On creation, the qemuarm build directory contains a conf directory with the following three files:

• bblayers.conf: This file lists the metadata layers to be considered for this project.
• local.conf: This file contains the project-specific configuration variables. You can set common configuration variables to different projects with a site.conf file, but this is not created by default. Similarly, there is also an auto.conf file which is used by autobuilders. BitBake will first read site.conf, then auto.conf, and finally local.conf.
• templateconf.cfg: This file contains the directory that includes the template configuration files used to create the project. By default it uses the one pointed to by the templateconf file in your Poky installation directory, which is meta-poky/conf by default.

To start a build from scratch, that's all the build directory needs.
Erasing everything apart from these files will recreate your build from scratch, as shown here:
$ cd /opt/yocto/poky/qemuarm
$ rm -Rf tmp sstate-cache

There's more...

You can specify different template configuration files to use when you create your build directory using the TEMPLATECONF variable, for example:

$ TEMPLATECONF=meta-custom/config source oe-init-build-env <build-dir> 

The TEMPLATECONF variable needs to refer to a directory containing templates for both local.conf and bblayer.conf, but named local.conf.sample and bblayers.conf.sample.

For our purposes, we can use the unmodified default project configuration files.