Silicon Blade

Lesson

Creating a Distribution

Creating your own distribution

The Yocto Project Getting Started Lesson 3 of 11

Creating your own distribution gives you control over the default behaviour of your system. Instead of inheriting the choices made by the poky reference distribution, you can decide which init system to use, which features to enable, and how your platform should behave by default.

Why Create a Distribution?

Creating your own distribution gives you more control over the whole platform.

That includes:

  • choosing package alternatives
  • setting compile-time options
  • enabling or disabling features
  • selecting default runtime behaviour for your system

Create a Distribution Layer

It is good practice to create a layer for your distribution. This is where you should be describing the type of system you are wanting to create along with system level policies.

Layer Configuration

All layers need a configuration, layer.conf file to define them. This will live under <layer>/conf/layer.conf.

To start with, we can use a boilerplate configuration file:

# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"

# We have recipes-* directories, add to BBFILES
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
            ${LAYERDIR}/recipes-*/*/*.bbappend"

BBFILE_COLLECTIONS += "meta-my-distro"
BBFILE_PATTERN_meta-my-distro = "^${LAYERDIR}/"

# Significantly increase the priority of our layers
BBFILE_PRIORITY_meta-my-distro = "21"

LAYERDEPENDS_meta-my-distro = "core"
LAYERSERIES_COMPAT_meta-my-distro = "scarthgap wrynose"
BBPATH

BBPATH .= ":${LAYERDIR}" adds your layer to the BitBake search path so that it can find your files

BBFILES

This defines how BitBake will find your recipes. "${LAYERDIR}/recipes-*/*/*.bb means that your recipes will live under <layer>/recipes-<SOMETHING>/<NAME>/<RECIPE>.bb. We will look at this more later.

BBFILE_PATTERN_meta-yourlayer

Ensures BitBake knows which files belong to your layer, so helps with searching.

BBFILE_PRIORITY_meta-yourlayer

Sets the priority of the layer. This is mainly important if multiple layers define the same recipe, as to while layer ‘wins’. This is from 1 (low) - 99 (high)

LAYERDEPENDS_meta-yourlayer

Defines if the layer depends on any other layers. BitBake will throw an error if a dependant layer does not exist.

LAYERSERIES_COMPAT_meta-yourlayer

A list of Yocto releases that will work with your layer.

Distribution Configuration

Your distribution configuration lives in your own distro layer under <layer>/conf/distro.

For example, if your layer is called meta-my_distro, the structure would look like this:

The filename becomes the distribution name you refer to from local.conf (without the .conf extension).

Required Settings

At a minimum, your distribution configuration should define its identity.

DISTRO

The distribution identifier used by the build system.

DISTRO_NAME

A human-readable name for the distribution.

DISTRO_VERSION

A version string for the distribution configuration.

Create the Distribution File

Create the directory and configuration file:

mkdir -p layers/project/meta-my_distro/conf/distro
nano meta-my_distro/conf/distro/mydistro.conf

Then add the basic distribution definition:

DISTRO = "mydistro"
DISTRO_NAME = "mydistro (First Distribution)"
DISTRO_VERSION = "1.0"

This gives you a blank distribution that is ready for customisation.

Distro Features

Distribution features are often used by recipes to select build options or runtime behaviour.

They are commonly checked during recipe configuration, for example to decide whether support for a feature such as systemd, x11, or wayland should be enabled.

Common Features

Some common distro features are:

  • bluetooth
  • overlayfs
  • ppp
  • systemd
  • wifi
  • wayland
  • x11

There are many more. The Yocto Project reference manual documents the available feature flags and what they influence.

Example: Configure the Distribution to Use systemd

The following example enables systemd as the init manager and removes any trace of sysvinit.

MY_DEFAULT_DISTRO_FEATURES = "systemd"
MY_DEFAULT_EXTRA_RDEPENDS = "packagegroup-core-boot"

DISTRO_FEATURES = "${DISTRO_FEATURES_DEFAULT} ${MY_DEFAULT_DISTRO_FEATURES}"

VIRTUAL-RUNTIME_init_manager = "systemd"

# Prevent SysVinit from being automatically added back
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"

# Remove initscripts completely
VIRTUAL-RUNTIME_initscripts = ""

DISTRO_EXTRA_RDEPENDS += "${MY_DEFAULT_EXTRA_RDEPENDS}"
DISTRO_EXTRA_RRECOMMENDS += "${MY_DEFAULT_EXTRA_RRECOMMENDS}"

This is a useful pattern because it keeps the distribution defaults in one place, rather than scattering them between image recipes and local developer overrides.

Add the Layer to your Project

Add the line

${YOCTOROOT}/project/meta-my-distro

to the BBLAYERS variable of build/conf/bblayers.conf so that it now looks like

BBLAYERS ?= " \
  ${YOCTOROOT}/third-party/bitbake \
  ${YOCTOROOT}/third-party/openembedded-core \
  ${YOCTOROOT}/project/meta-my-distro \
"

The setup lesson covers the details of how layers are organised and enabled.

Configure the Build to Use Your Distro

Once the distro file exists, you can make use of it by adding it to build/conf/local.conf.

Add the line:

DISTRO = "mydistro"

After that, rebuild your image and test it:

bitbake my-production-image
runqemu nographic qemux86

Sanity Checks

Yocto includes sanity checking to catch common configuration problems.

Examples include:

  • broken paths
  • invalid configuration values
  • unsupported host setup details
  • other common project misconfigurations

These checks are useful and should normally be treated as a warning that something important needs attention.

Disabling Checks

Specific QA checks can be skipped using INSANE_SKIP.

INSANE_SKIP:${PN} = "already-stripped"

Summary

Creating your own distribution is one of the key steps in moving from a reference Yocto setup to a maintainable product build.

The main steps are:

  • create a distro configuration file in conf/distro
  • define the distro identity variables
  • enable the features and runtime behaviour you want
  • select that distro from local.conf
  • rebuild and test the image

Check your understanding

Quick quiz: distributions

Check the main ideas behind distro-level configuration.

Question 1 Your team keeps setting init-system and feature policy in several image recipes. What is the cleaner long-term fix?
Question 2 You create `conf/distro/mydistro.conf`, but the build still behaves like the reference setup. Which change actually selects your distro?
Question 3 A QA check fires for one package and someone suggests adding `INSANE_SKIP` immediately. What is the best response?