View source for Yocto

= Prerequisites =
<pre class=terminal>
sudo apt install gcc g++ \
  python3-distutils python-is-python3
</pre>
<br />

= Images =

Images are recipes that ultimately inherit from '''meta/classes/image.bbclass''' and set the global variable '''IMAGE_INSTALL'''. Most images, however, will inherit from ''meta/classes/core-image.bbclass'' which inherits directly from ''image.bbclass'', provides a mapping from ''IMAGE_FEATURES'' to package groups, and adds the two package groups ''packagegroup-core-boot'' and ''packagegroup-base-extended'' to ''IMAGE_INSTALL''.

Images are defined in recipe files with the file extension 'bb'. In order to separate them from package recipes, there is a convention to put image recipes into a folder named ''images''. Making use of this, we can list all images defined by all layers via
<pre class="terminal">
cd poky
ls meta*/recipes*/images/*.bb
</pre>
<br />

=== ''IMAGE_FEATURES'' ===
The ''IMAGE_FEATURES'' variable is defined in ''meta/classes/image.bbclass'' with an empty value. It accepts only a predefined set of features (e.g., ''x11'', ''debug-tweaks'', ''dev-pkgs'', ''dbg-pkgs''). This affects how recipes will execute their tasks and which packages will be selected to go into the image. The image recipe ''meta/recipes-core/images/core-image-base.bb'', for example, adds the ''splash'' feature.
<br />

=== ''IMAGE_INSTALL'' ===
Holds a list of package groups whose packages (from the package feed area) will go into the filesystem image.
<br />

== Reference images ==
The following reference images are defined in the ''meta'' layer:
{| style="padding: 10px;"
! style="width: 20px" | || || 
|-
| || ''core-image-minimal'' || small image that just boots the target device
|-
| || ''core-image-minimal-dev'' || ''core-image-minimal'' with headers and libraries allowing development work
|-
| || style="padding-right: 10px" | ''core-image-minimal-initramfs'' || ''core-image-minimal'' with kernel support for in-RAM filesystem
|-
| || '''core-image-base''' || '''console-only system fully supporting the target hardware'''
|-
| || ''core-image-full-cmdline'' || console-only image that includes many system tools
|-
| || ''core-image-x11'' ||  image with basic X11 and a terminal
|-
|}

These image definitions are provided as a starting point for creating project-specific, custom image definitions.
<br />
<br />

== Creating a Custom Image ==
* In your custom layer, create the ''images'' subdirectory in one of your ''recipes-...' directory.
* In the ''images'' directory, create two image recipe files that inherit from ''core-image'':
<pre class="code">
SUMMARY = "My deployment image"
LICENSE = "MIT"

inherit core-image
IMAGE_FEATURES += "splash"
</pre>
and
<pre class="code">
SUMMARY = "My development image"

inherit core-image
require my-image.bb

IMAGE_FEATURES += "ssh-server-dropbear tools-debug debug-tweaks"

CORE_IMAGE_EXTRA_INSTALL += "i2c-tools "
</pre>
where the first image recipe is for deployment and the second is for development. Note that the development version includes the deployment version with the ''require'' statement, and adds to IMAGE_FEATURES and CORE_IMAGE_EXTRA_INSTALL.
<br />

== Image Filesystem Packaging ==
The system image generated by Bitbake can be packaged in the form of an image file, whose contents can be transferred on a boot medium (SD card or eMMC) such that the primary boot loader of the target device can discover the system and boot it.

Unless you restrict the type of packaging used for the image file, Yocto will generate multiple rootfs packages, each with a large footprint. To restrict the generated image files to a desired type, edit ''conf/local.conf'' of your project build directory and set the type.
<pre class="code">
#IMAGE_FSTYPES = "tar.gz"
#IMAGE_FSTYPES = "tar.bz2"
IMAGE_FSTYPES = "wic.bz2 wic.bmap"
</pre>
The wic ([https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html kickstart]) format with accompanying [https://github.com/intel/bmap-tools bmap] is recommended.
<br />

== Installing the Rootfs Image ==
Using [https://github.com/intel/bmap-tools bmaptool] we can copy the generated ''wic'' image (with matching bmap file) to a mounted SD card or eMMC storage.
<pre class="terminal">
sudo bmaptool copy tmp/deploy/images/raspberrypi4-64/<wic.bz2 file> <drive>
</pre>
where ''<wic.bz2 file>'' is the root filesystem image wic.bz2 file, and ''<drive>'' is the drive at which the storage is mounted (for example, ''/dev/sdb'').
<br />
<br />

= Package Groups =
Package groups are recipes that inherit from '''meta/classes/packagegroup.bbclass''' and set the content of the global variable '''PACKAGES'''. Package groups are defined in recipe files with the file extension 'bb'.
<br />
<br />
Note that the ''packagegroup'' must be inherited before ''PACKAGES is defined.
<pre class="code">
inherit packagegroup

PACKAGES = '...'
</pre>
<br />

= Useful Image Features =
<br />

== Distro Features ==
Distro features are system features that affect multiple recipes. '''Large parts of the Poky image may need to be rebaked after making changes to the distro features!'''
<br />

=== systemd ===
In the ''conf/local.conf'' file of your project build directory (or ''layer.conf'' file of your layer) add 
<pre class="code">
DISTRO_FEATURES:append = " systemd"
</pre>
<br />

=== NFS ===
In Embedded Linux projects, NFS is often included in development images to enable faster code-deploy turnaround times.
<br />
In the ''conf/local.conf'' file of your project build directory (or ''layer.conf'' file of your layer) add 
<pre class="code">
DISTRO_FEATURES:append = " nfs"
</pre>
<br />

=== [https://vulkan.org Vulkan] and [https://opengl.org OpenGL] ===
<pre class="code">
DISTRO_FEATURES:append = " vulkan opengl x11 wayland"
</pre>
<br />

=== Bluetooth and NFC ===
<pre class="code">
DISTRO_FEATURES:append = " bluetooth nfc"
</pre>
<br />

= devtool =

Use '''devtool''' to make changes to an existing recipe and automatically generate an append recipe from those changes.
<br />
<br />

== Initialization Manager ==
After the kernel is done with its basic booting tasks, it passes control to the initialization manager. To use the ''systemd'' initialization manager (used by the Linux distributions Debian and Ubuntu) instead of ''SysVinit'', make the following entries in ''${TOPDIR}/conf/distro/distro.conf''
<pre class="code">
DISTRO_FEATURES_append = " systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_init_manager = "systemd"
VIRTUAL-RUNTIME_initscripts = ""
</pre>
<br />