View source for How to create a custom yocto meta layer

=Introduction=

This wiki will provide a detailed guide on how to create a custom Yocto meta-layer.

==Create Base Meta-Layer==

This section contains steps to create the base custom meta-layer.
After completion, the custom base meta-layer will contain the following parts:

* Custom layer configuration
* Custom distro configuration
* Custom machine
* Custom config template files
* Custom image recipe

===Step 1. Add base layer.conf file===

The layer configuration file provides Yocto with the configuration for the custom meta-layer.
It shall be stored in a directory called '''conf''' inside the base meta-layer directory, and it shall be named layer.conf.
According to the [https://docs.yoctoproject.org/dev/dev-manual/layers.html Yocto documentation] it is recommended to start from an existing layer.conf file from a different meta-layer and change it according to the custom requirements.

For instance, here is an example of how the directory structure should look after creating the layer.conf file.

<syntaxhighlight lang="bash">
meta-proventusnova/
├── conf
│   └── layer.conf
└── README.md
</syntaxhighlight>

An example layer.conf file based on [https://github.com/OE4T/tegra-demo-distro/blob/scarthgap-l4t-r35.x/layers/meta-tegrademo/conf/layer.conf NVIDIA OE4T tegra_demo_distro] is shown in the following code snipped.

<syntaxhighlight lang="bash">
BBPATH =. "${LAYERDIR}:"
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb ${LAYERDIR}/recipes-*/*/*.bbappend"
BBFILES_DYNAMIC += "swupdate:${LAYERDIR}/dynamic-layers/meta-swupdate/recipes-*/*/*.bb \
                    swupdate:${LAYERDIR}/dynamic-layers/meta-swupdate/recipes-*/*/*.bbappend"

BBFILE_COLLECTIONS += "proventusnova"
BBFILE_PATTERN_proventusnova = "^${LAYERDIR}/"
BBFILE_PRIORITY_proventusnova = "50"

LAYERVERSION_proventusnova = "4"
LAYERSERIES_COMPAT_proventusnova = "scarthgap"

# This is used by the tegra-distro-sanity bbclass
# to identify the distro layer directory during
# bblayers checks.
TD_DISTRO_LAYERDIR = "${LAYERDIR}"

</syntaxhighlight>

===Step 2. Add base distro config===

In order to add the initial distro configuration, it is necessary to create distro configuration file inside the '''meta-layer/conf/distro''' directory.

Here is an example of how the directory structure should look like:

<syntaxhighlight lang="bash">
meta-proventusnova/
├── conf
│   ├── distro
│   │   └── proventusnova.conf
│   └── layer.conf
└── README.md
</syntaxhighlight>

The same as with the layer.conf, it is easier to start with an existing distro configuration file and modify it in order to fit the project requirements. For example, the following corresponds to a distro configuration file based on the [https://github.com/OE4T/tegra-demo-distro/blob/scarthgap-l4t-r35.x/layers/meta-tegrademo/conf/distro/tegrademo.conf NVIDIA tegra_demo_distro]:

<syntaxhighlight lang="bash">
DISTRO = "proventusnova"
DISTRO_NAME = "ProventusNova Custom Distro"
DISTRO_VERSION_BASE = "1.0"
DISTRO_VERSION = "${DISTRO_VERSION_BASE}+snapshot-${METADATA_REVISION}"
DISTRO_CODENAME = "proventusnova"
SDK_VENDOR = "-proventusnova"
SDK_VERSION := "${@'${DISTRO_VERSION}'.replace('snapshot-${METADATA_REVISION}','snapshot')}"
SDK_VERSION[vardepvalue] = "${SDK_VERSION}"

MAINTAINER = "ProventusNova team <support@proventusnova.com>"

TARGET_VENDOR = "-proventusnova"

# New ${DISTRO}-<version> setting for sanity checks.
# Increment version number (and the corresponding
# setting int the template bblayers.conf.sample file)
# each time the layer settings are changed.
REQUIRED_PROVENTUSNOVA_BBLAYERS_CONF_VERSION = "${DISTRO}-1"

LOCALCONF_VERSION = "2"

PROVENTUSNOVA_DEFAULT_DISTRO_FEATURES = "largefile opengl ptest multiarch wayland vulkan systemd pam virtualization usrmerge"

DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${PROVENTUSNOVA_DEFAULT_DISTRO_FEATURES}"

# Jetson platforms do not use linux-yocto, but for QEMU testing
# align with the poky distro.
PREFERRED_VERSION_linux-yocto ?= "5.19%"
PREFERRED_VERSION_linux-yocto-rt ?= "5.19%"

SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}"
SDKPATHINSTALL = "/opt/${DISTRO}/${SDK_VERSION}"

TCLIBCAPPEND = ""

PACKAGE_CLASSES ?= "package_rpm"

SANITY_TESTED_DISTROS ?= " \
            ubuntu-20.04 \n \
            ubuntu-22.04 \n \
            ubuntu-24.04 \n \
            "

# Most NVIDIA-supplied services expect systemd
INIT_MANAGER = "systemd"

require conf/distro/include/no-static-libs.inc
require conf/distro/include/yocto-uninative.inc
require conf/distro/include/security_flags.inc
INHERIT += "uninative"

LICENSE_FLAGS_ACCEPTED += "commercial_faad2 commercial_x264"

USE_REDUNDANT_FLASH_LAYOUT_DEFAULT ?= "1"

INHERIT += "tegra-support-sanity"
ESDK_CLASS_INHERIT_DISABLE:append = " tegra-support-sanity"

BB_SIGNATURE_HANDLER ?= "OEEquivHash"
BB_HASHSERVE ??= "auto"

</syntaxhighlight>

===Step 3. Add base machine===

This step might not be required, if there is already a machine that can be used from a different meta-layer.
However, it is still recommended to create a custom machine configuration based on that machine in order to keep better order of the machine used in the custom Yocto build.

To create a custom machine, it is necessary to add a machine.conf file in the '''meta-layer/conf/machine''' directory.
For example, this is how the directory structure should look when adding a new machine to the custom meta-layer:

<syntaxhighlight lang="bash">
meta-proventusnova/
├── conf
│   ├── distro
│   │   └── proventusnova.conf
│   ├── layer.conf
│   └── machine
│       └── proventusnova-jetson-orin-nx-16-devkit.conf
└── README.md
</syntaxhighlight>

And, as a reference, here is a custom machine based on [https://github.com/OE4T/meta-tegra/blob/scarthgap/conf/machine/p3509-a02-p3767-0000.conf NVIDIA meta-tegra  p3509-a02-p3767-0000] machine.

<syntaxhighlight lang="bash">
#@TYPE: Machine
#@NAME: Nvidia Jetson Orin NX 16GB (P3767-0000)
#@DESCRIPTION: Nvidia Jetson Orin NX 16GB module in P3509 carrier

TEGRA_FLASHVAR_PINMUX_CONFIG ?= "tegra234-mb1-bct-pinmux-p3767-hdmi-a03.dtsi"
TEGRA_FLASHVAR_PMC_CONFIG ?= "tegra234-mb1-bct-padvoltage-p3767-hdmi-a03.dtsi"
TEGRA_PLUGIN_MANAGER_OVERLAYS ?= "tegra234-carveouts.dtbo tegra-optee.dtbo tegra234-p3768-0000+p3767-0000-dynamic.dtbo tegra234-dcb-p3767-0000-hdmi.dtbo"
TEGRA_DCE_OVERLAY ?= "tegra234-dcb-p3767-0000-hdmi.dtbo"

require conf/machine/include/orin-nx.inc

</syntaxhighlight>

===Step 4. Add initial config template files===

Bitbake will require 2 configuration files for building an image:

'''bblayers.conf''': This file contains information about the location of the required meta-layers for the project.

'''local.conf''': This file contains general build configuration for bitbake. For instance, in this file it is possible to determine where to store downloads, cache and even which package management configuration to use.

Now, in order to simplify the configuration of a custom Yocto build, it is possible to include template configuration files on the custom meta-layer. This practice is encouraged in order to increase build repeatability.

These 2 files are generally created inside '''meta-layer/conf/templates/template-name'''.
For reference, this is how the directory structure would look like after the files are created:

<syntaxhighlight lang="bash">
meta-proventusnova/
├── conf
│   ├── distro
│   │   └── proventusnova.conf
│   ├── layer.conf
│   ├── machine
│   │   └── proventusnova-jetson-orin-nx-16-devkit.conf
│   └── templates
│       └── proventusnova
│           ├── bblayers.conf.sample
│           └── local.conf.sample
└── README.md
</syntaxhighlight>

Here is an example of a custom bblayers.conf.sample file based on [https://github.com/OE4T/tegra-demo-distro/blob/scarthgap-l4t-r35.x/layers/meta-tegrademo/conf/templates/tegrademo/bblayers.conf.sample NVIDIA tegra-demo-distro]:

<syntaxhighlight lang="bash">
# Version of layers configuration, specific to
# each defined distro in the repository.
# Format: ${DISTRO}-<version>
TD_BBLAYERS_CONF_VERSION = "proventusnova-1"

BBPATH = "${TOPDIR}"
BBFILES ?= ""

BBLAYERS ?= " \
  ##OEROOT##/meta \
  ##OEROOT##/../meta-tegra \
  ##OEROOT##/../meta-tegra-community \
  ##OEROOT##/../meta-virtualization \
  ##OEROOT##/../meta-openembedded/meta-oe \
  ##OEROOT##/../meta-openembedded/meta-python \
  ##OEROOT##/../meta-openembedded/meta-networking \
  ##OEROOT##/../meta-openembedded/meta-filesystems \
  "

</syntaxhighlight>

And, this is an example of a custom local.conf.sample file based on [https://github.com/OE4T/tegra-demo-distro/blob/scarthgap-l4t-r35.x/layers/meta-tegrademo/conf/templates/tegrademo/local.conf.sample NVIDIA tegra-demo-distro]:

<syntaxhighlight lang="bash">
#
# Machine Selection
#
MACHINE ??= "proventusnova-jetson-orin-nx-16-devkit.conf"

#
# Where to place downloads
#
DL_DIR ?= "${TOPDIR}/../downloads"

#
# Where to place shared-state files
#
SSTATE_DIR ?= "${TOPDIR}/../sstate-cache"

#
# Where to place the build output
#
TMPDIR = "${TOPDIR}/tmp"

#
# Default policy (distro) config
#
DISTRO ?= "proventusnova"

#
# Package Management configuration
#
PACKAGE_CLASSES ?= "package_deb"

#
# SDK target architecture
#
SDKMACHINE ?= "x86_64"

#
# Extra image configuration defaults
#
EXTRA_IMAGE_FEATURES ?= "debug-tweaks"

#
# Additional image features
#
USER_CLASSES ?= "buildstats"

#
# Interactive shell configuration
#
PATCHRESOLVE = "noop"

#
# Disk Space Monitoring during the build
#
BB_DISKMON_DIRS ??= "\
    STOPTASKS,${TMPDIR},1G,100K \
    STOPTASKS,${DL_DIR},1G,100K \
    STOPTASKS,${SSTATE_DIR},1G,100K \
    STOPTASKS,/tmp,100M,100K \
    HALT,${TMPDIR},100M,1K \
    HALT,${DL_DIR},100M,1K \
    HALT,${SSTATE_DIR},100M,1K \
    HALT,/tmp,10M,1K"

#
# Qemu configuration
#
PACKAGECONFIG:append:pn-qemu-system-native = " sdl"

# CONF_VERSION is increased each time build/conf/ changes incompatibly and is used to
# track the version of this file when it was generated.
CONF_VERSION = "2"

</syntaxhighlight>

===Step 5. Add base image recipe===

In order to create a custom image, it is necessary to add a custom image recipe file.
This file is usually added inside the '''meta-layer/recipes-layer/images''' directory.

For example:

<syntaxhighlight lang="bash">
meta-proventusnova/
├── conf
│   ├── distro
│   │   └── proventusnova.conf
│   ├── layer.conf
│   ├── machine
│   │   └── proventusnova-jetson-orin-nx-16-devkit.conf
│   └── templates
│       ├── bblayers.conf.sample
│       └── local.conf.sample
├── README.md
└── recipes-proventusnova
    └── images
        └── proventusnova-image-base.bb
</syntaxhighlight>

Once again, a custom image recipe can be based on another image recipe. And, it can also import other image recipes in order to include their base configurations.

As reference, the following image recipe was based on [https://github.com/OE4T/tegra-demo-distro/blob/scarthgap-l4t-r35.x/layers/meta-tegrademo/recipes-demo/images/demo-image-base.bb NVIDIA tegra-demo-distro demo-image-base recipe]:

<syntaxhighlight lang="bash">
DESCRIPTION = "ProventusNova base image"
LICENSE = "CLOSED"

inherit core-image

IMAGE_FEATURES += "ssh-server-openssh debug-tweaks"

CORE_IMAGE_BASE_INSTALL += "systemd"
TOOLCHAIN_HOST_TASK += "nativesdk-packagegroup-cuda-sdk-host"

inherit nopackages

</syntaxhighlight>