Build a tiny distro
Poky Linux is a great DIY Linux distro builder for embedded systems. Find out how Alexander Tolstoy uses it to prep an image for a desktop setup.
Poky Linux is a great DIY Linux distro builder for embedded systems. Find out how Alexander Tolstoy uses it to prep an image for a desktop setup.
The general sequence of baking a standard Poky Linux image is pretty straightforward – see Tam Hanna’s tutorial in LXF251. In short, you start by preparing your rhost system for building by installing development packages such as gawk, texinfo and diffstat. Then grab the Poky code from the Yoctoproject Git repository, initialise the build environment with the bundled script, and start baking
( $ bitbake
This last part is very resource intensive. You’ll need to set aside several hours, during which time your host system will be bogged down by Bitbake, and you’ll also need to make sure you have at least 70GB of free disk space, otherwise there won’t be enough room for Bitbake to do its job. All the extra software parts added on top of the minimal image also require gigabytes of free disk space, so don’t cut this corner.
These are just the minimum requirements for getting a tiny bootable Linux distribution up and running, which occupies just tens of megabytes on its own. On the other hand, most processes in Poky are well automated and therefore introduce far fewer difficulties than, say, the Linux From Scratch (www.linuxfromscratch.org) build routine.
Yocto on your desktop
While Yocto is primarily aimed at embedded systems, we’ll be looking at desktop usage. The idea is to access the benefits of Poky and bring it closer to a standard desktop workstation. As such, we can ignore everything related to board support packages (BSP), which are designed for device-specific builds (such as those for RaspberryPi), and concentrate on the generic x86-64 build. It’s this one that we can run on a regular PC.
The difference between a tiny standard image suggested by Bitbake (for example, core-image-minimal) and our goal is that the latter needs a lot of extra software pieces to be manually added in order to produce something viable. To be more specific, these additions include extra drivers in kernel for better realworld hardware support, middleware insertions for better experience (OpenSSH, NetworkManager and PulseAudio, for example), a basic graphical environment together with any extra applications you need. We’ll start our journey by obtaining the essential part of the Poky codebase.
Getting the basics
We kick things off by obtaining the code from the Yocto servers. Before we proceed with Git, let’s find out the codename of the latest Poky release by looking at
https://wiki.yoctoproject.org/wiki/Releases. At the time of writing it is Hardknott. Once we have the correct name we’re ready to fetch the Poky source code:
$ git clone -b hardknott https://git.yoctoproject.org/git/ poky
Enter the downloaded directory (usually it’s poky ) and source the oe-init-build-env file to initialise the build environment:
$ . ./oe-init-build-env
This will create the local build configuration and enable you to start baking your own Poky build. By default our target is called qemux86-64, which is perfect for testing. We can leave it intact, or change it to
genericx86-64 to prepare more general-purpose builds. The setting is stored in the conf/local.conf file. For example, to change the target machine type from Qemu to Generic X86_64, uncomment the following line:
MACHINE ?= “genericx86-64”
In addition, comment out the line with the qemux8664 value. You can leave it intact to make Bitbake build two images, but this will take up extra time and disk space. Right now there’s no need to change other defaults, and therefore we may safely proceed with building the image:
$ bitbake core-image-x11
The build process means compiling the whole Linux system and all its components from their source code. It’ll take several hours even on a powerful host, but after all tasks have been completed we’ll have a ready-to-use system stored under build/tmp/deploy/images.
Note that you can build any number of images using the same build tree. For a different image Bitbake will just add the missing parts and repack the previously built recurring packages into it. Essentially, this means you don’t need to wait as long for subsequent images to be created.
Extending the build
It’s time to enhance the default code tree with auxiliary component known as the OpenEmbedded project. This approach will add more layers and plenty of extra software. In particular, systems with those extra layers will instantly be able to build the core-image-minimalxfce, which is a perfect desktop starting-point.
To add layers provided by the OpenEmbedded project, use Git to download within a main Poky tree:
$ git clone git://git.openembedded.org/metaopenembedded -b hardknott
It’s not enough to just get hold of the code, because Bitbake hasn’t been instructed to use it. We now need to add proper lines into the bblayers.conf file. It’s possible to add this either by editing that file, or using the bitbake-layers utility with the following syntax:
$ bitbake-layers add-layer /path/to/layer
Here is the example part of bblayers.conf featuring layers provided by the Openembedded project:
BBLAYERS += " \ /path/to/poky/meta-openembedded/meta-oe \ /path/to/poky/meta-openembedded/metamultimedia \ /path/to/poky/meta-openembedded/metanetworking \ /path/to/poky/meta-openembedded/meta-gnome \ /path/to/poky/meta-openembedded/meta-python \ /path/to/poky/meta-openembedded/meta-xfce \ "
Create a practical desktop
Let’s build the image that would include the lightweight Xfce desktop. The meta-xfce layer already bundles the ready-to-use recipe under meta-openembedded/metaxfce/recipes-core/images/ and therefore we can immediately start the image-generating process with the following command:
$ bitbake core-image-minimal-xfce
The resulting image will be a modern Waylandenabled system bundled with lots of programs that we otherwise would need to add by hand. There’s a great collection of desktop accessories and frequently used tools that normally ship with the Xfce desktop.
Mastering a perfect Poky Linux image assumes constant test boots, for which the most convenient tool is the Qemu emulator. It’s perfectly safe to stay in the
Qemu sandbox during the debugging stage and switch the build target to genericx86-64 in the end. Before that, test your build using the Yocto-provided runqemu
utility. It defaults to using as little as 256MB of RAM, so use this code to expand this value – say, up to 1GB:
$ runqemu qemux86-64 qemuparams="-m 1024”
By default, the target system has only one user (root) with a blank password. In order to create a user, add the following line to the recipe file:
EXTRA_USERS_PARAMS = “useradd -P
In our case, it would be meta-openembedded/metaxfce/recipes-core/images/core-image-minimal-xfce.bb.
Layer cake
The simplest way to add extra packages to your build is to append them right into the local.conf file. For instance, let’s add OpenSSH in order to have remote access to our build. Add the following line: CORE_IMAGE_EXTRA_INSTALL += “openssh”
It’s possible to specify several packages using space as a delimiter. This technique is mostly suitable for adding a few extra packages to the stock setup.
If there are going to be a lot of extra packages, it’ll make more sense to set up a separate layer where all our additions will reside. To do so, issue the following commands from Poky’s build directory:
$ bitbake-layers create-layer --priority 7 ../metacustom $ bitbake-layers add-layer ../meta-custom
The last command will add the appropriate line into the bblayers.conf file for you, which enables you to engage the new custom layer. At the moment it’s empty, but we can move extra packages appends to metacustom/layer.conf from the global local.conf. If later on there’s a need to populate the build with custom recipes, we’ll already have a layer for them.
Modern niceties
Historically, adding a new software to Poky meant writing a recipe for building it. A recipe is an instruction that’s similar to PKGBUILD in Arch or SPEC in an RPMbased Linux distro. However, the Poky Linux ecosystem, with its rich collection of third-party layers and recipes, contains everything an average desktop user needs.
The first place to search for a specific program that’s not available in Poky right out of the box is https:// layers.openembedded.org. It lists various third-party layers that resemble PPAs in Ubuntu or COPR repos in Fedora. A layer may depend on some other layers, similar to how a repository may require another repository. Luckily, when we move down to the recipe level, there are no signs of a dependency hell that Linux users used to suffer from years ago. However, some manual effort may be required to arrange layers properly. As an example, here’s the sequence for adding the Chromium web browser to the build:
$ git clone -b master git://github.com/OSSystems/ meta-browser.git
$ git clone -b hardknott git://git.openembedded.org/ meta-python2
$ git clone -b hardknott https://github.com/kraj/metaclang.git $ bitbake-layers add-layer meta-browser metapython2 meta-clang
Then we add these two lines into the layer.conf file of the meta-custom layer:
IMAGE_INSTALL_append = " chromium” LICENSE_FLAGS_WHITELIST += “commercial_libav commercial_x264”
The second line is required because of licencing limitations of some codecs used by Chromium.
If necessary, use the IMAGE_INSTALL_append
line to add extra software to your Poky build, such as NetworkManager or Gimp. However, some system-wide software needs to be enabled in the high-priority configuration file. For example, if you want to enable Systemd, don’t use your own recipe. Instead, place the following lines directly into the main local.conf file: DISTRO_FEATURES_append = " systemd” DISTRO_FEATURES_BACKFILL_CONSIDERED +=
“sysvinit” VIRTUAL-RUNTIME_init_manager = “systemd” VIRTUAL-RUNTIME_initscripts = “systemd-compatunits”
Bitbake builds any extra packages and resolves runtime dependencies automatically. It’s just a case of waiting patiently and getting ready to test the image when everything’s completed.
Extra kernel things
You’ll never avoid altering the kernel, unless Poky defaults to a limited set of supported hardware, which won’t be of much use to desktop systems. We need to change the kernel configuration to add more device drivers. This can be done by entering the standard menu configuration interface:
$ bitbake -c menuconfig virtual/kernel
After a while, you’ll see a text UI with a tree-like menu of the Linux kernel options. At this stage it’s important to locate and enable all drivers that you’ll need on the real hardware where your build will run. Each kernel driver can be compiled either as a standalone module ( .ko under /lib/modules), or as a part of the initial RAM disk (initrd). The difference mainly comes down to the fact that a driver should be placed inside Initrd if it’s required for booting the system (if it’s a file system driver, say). Once you’ve finished configuring the kernel, save your changes and exit the menu for the next step:
$ bitbake -c savedefconfig virtual/kernel
However, as long as we have our own ‘meta-custom’ layer, let’s add the kernel configuration append file (.bbappend):
$ mkdir -p meta-custom/recipes-kernel/linux
$ touch meta-custom/recipes-kernel/linux/linuxyocto_5.10.bbappend There are lots of things we can do with the Linux kernel here, including adding patches, pushing extra files and so on, but at this stage enabling certain kernel features will suffice nicely. In the recipe directory of your layer create another subdirectory and name it files (so that it reads meta-custom/recipes-kernel/linux/files).
Create an empty text file under it with the name defconfig and populate it with lines like CONFIG_ SOMETHING=y , where y means baking the feature right into the Initrd image. Alternatively, replace y with m to make it a standalone module. To refer to the defconfig file in the append file, place the following two lines inside the latter: FILESEXTRAPATHS_prepend := “${THISDIR}/files:” SRC_URI += “file://defconfig”
The only problem left is how to determine the list of modules that you’ll actually need. If you plan to run the Poky build directly on the bare-metal system such as your current host, it makes sense to collect some data on it. For instance, you may want to run the $ make localmodconfig against the kernel source tree on your host system in order to generate the .config file with all the modules that are currently in use. Then simply transfer the file’s contents to your layer’s defconfig file to create a similar kernel setup for the target Poky build. Re-run the Bitbake image building command in order to reconstruct the kernel.
I like to boot it, boot it
Again, the Bitbake defaults produce a number of standalone files that you’re meant to manually copy to your target device. However, we get little use of Bzimage and Initrd if we’re unable to boot the system outside of Qemu. To fix it, let’s tell Bitbake to produce a bootable ISO image. Add the following line into the local.conf file: IMAGE_FSTYPES = “iso”
Rebuilding the core-image-minimal-xfce target will then produce the ISO file available under build/tmp/ deploy/images/genericx86-64. You can burn this ISO file onto a hard drive or other medium to get a bootable and ready-to-use Linux system. Other image types are available as well, including ext4 and squashfs. The official Yocto documentation provides details on how to customise the root file system size and choose the right image type depending on your needs.
As for updating the installed/flashed system, there are also several paths. Although you can update the whole system at once later on, there’s the Yoctosupported update tool swupd, which is capable of updating individual packages. It doesn’t come with either the minimal image by default or the Xfce minimal image that we described above. To use Swupd on the target, you should attach the meta-swupd layer and append the swupd-client package to your image configuration.