ELBE Overview

This site is being reworked at the moment!

ELBE (Embedded Linux Build Environment) is a buildsystem to generate root-filesystems for embedded devices. This is only a short explanation what ELBE is and a brief tutorial for using ELBE, please go to the official documentation of ELBE for a detailed documentation. This article was made when version 12.4 was the current version of ELBE.

Overview

ELBE uses a virtual machine to create root-filesystems, this VM is called "initvm". At the first time of running ELBE the initvm has to be initialized (a complete automatic installation of Debian is made), subsequent runs of ELBE can reuse that initvm.

Basic structure of ELBE building a root-filesystem (as of version 12.4). Orange are inputs for ELBE, green are things that the result of ELBE. "buildenv.img" is a special case because the initvm is created at "elbe initvm create" and it is reused by "elbe initvm submit". Loosely based on both diagrams at https://elbe-rfs.org/docs/sphinx/releases_v12.4/article-elbeoverview-en.html#overview

Recepies what a built root-filesystem should contain are supplied in form of a xml-file. ELBE doesn't build the software for the root-filesystem, it does instead use pre-built software in form of Debian packages (.deb). Usually the official Debian repositories are used, but it is possible to use custom repositories to get special packages into the root-filesystem. Resulting root-filesystems are basicly customized Debian installations, which can be maintained through Debian's tools like APT. This is the biggest difference of ELBE to other buildsystems like Yocto or Buildroot.

It is possible to define "finetuning"-commands in the xml-file, which are executed when the creation of the root-filesystem is completed. With this it is possible to remove files, add additional users and much more ...

Xml-files can be appended with a bzip2 compressed archive. At the end of the buildprocess, the content of the archive will be extracted into the root-filesystem.

The form of the finished root-filesystem is customizeable. The following variants are possible:

• Tarball: The root-filesystem can be packed as a tarball (usually compressed with gzip). The tarball can be extracted onto an empty partition or can be used for the DHCOM Update Mechanism.
• Disk-/SD-card-image: An image with full partition table can be created. This can be a image of a hard disk or a sd-card. The size, type, label and mountpoint of each partition can be customized via the xml-file.
• UBIFS-Image: ELBE can output images for "Unsorted Block Image"-devices (UBI). These are needed if you want to use the NAND-Flash of our DHSOM modules for the root-filesystem. More information about that type of filesystem can be found under UBI/UBIFS Filesystem.

As an addition ELBE is able to create a cdrom image which can be used as a input to reconstruct the exact root-filesystem that was created.

ELBE can also create a Software Development Kit (SDK) for the built root-filesystem. The SDK contains the toolchain with the cross compiler and other tools and the corresponding sysroot with needed headers. These can be used to create software for the specific root-filesystem. The SDK is very similar to Yocto's Standard-SDK and can be used in the same way. An explanation how to use the SDK with some IDEs/buildsystems can be found here: Link following

Installation

There are multiple ways to install ELBE:

Debian Package

The developers of ELBE have their own package repository which can be used to install ELBE.

To add the repository to the /etc/apt/sources.list.d directory and install the public key for the repo:

echo 'deb http://debian.linutronix.de/elbe buster main' >> /etc/apt/sources.list.d/elbe.list
wget http://debian.linutronix.de/elbe/elbe-repo.pub && apt-key add elbe-repo.pub

Now you can install ELBE with:

apt update
apt install elbe

Important: You have to add your user to the libvirt groups if you want to use ELBE without root:

adduser <user> libvirt && adduser <user> libvirt-qemu

Cloning the git repository of ELBE

There is also the possibility to clone the git repository of ELBE. To do this the following packages have to be installed on the system:

apt install python python-debian python-mako python-lxml python-apt python-gpg python-suds python-libvirt qemu-utils qemu-kvm p7zip-full make libvirt-daemon libvirt-daemon-system libvirt-clients

Then you can clone the repo with:

git clone https://github.com/Linutronix/elbe

Important: You have to add your user to the libvirt groups if you want to use ELBE without root:

adduser <user> libvirt && adduser <user> libvirt-qemu

Usage

The ELBE buildsystem consists of the program elbe which is implemented in Python. Similar to git, it can be called with several sub commands. If you installed ELBE through the Debian package, the program is inside your PATH environment and can be called by "elbe", else you have to call it by the complete path. The most important commands are:

elbe initvm create --directory /example example.xml

This command initializes a new initvm in the directory "/example" and builds a new root-filesystem based on "example.xml" . This command can only be used if there isn't any initvm defined yet. If you cloned ELBE from git, you can add the switch "--devel", then ELBE copies the local ELBE version into the initvm (instead of downloading ELBE from their repository).

elbe initvm submit --directory /example example.xml

This command builds a new root-filesystem based on "example.xml" and reuses an existing initvm at the directory "/example".

elbe chg_archive example.xml example-archive.tar.bz2

This command appends the xml-file "example.xml" with the archive "example-archive.tar.bz2". The binary content of the archive is stored in BASE64 encoding inside a xml tag.

If you add --build-sdk at the "initvm create/submit"-command then as an addition to creating the root-filesystem, the SDK (for developing software for the root-filesystem) is created too. Usually CD-Images with all binary packages and all source packages (for the exact recreation of the rootfilesystem) are created. The creation of these can be skipped with the commandline switches --skip-build-bin and --skip-build-sources.

If an error happens while building the rootfilesystem, no files are returned. It is possible to get the log and other files of the build with an extra command. The complete call of the command (which differs for each build) is printed as exit-message of the ELBE build.

XML-Example

This is a simple example for a xml file. If you start the build process a root-filesystem for a device of the "ARM EABI with hard float"-architecture (usually ARMv7) based on Debian 10 is built. In extra to the main mirror, the security and buster-updates mirror is also configured, so that the root-filesystem can get security updates. After the package installation is finished, the cached Debian package files are removed to slim down the image. At the end, the finished root-filesystem is packed into gzip-compressed tarball "rootfs.tar.gz". Note that the resulting root-filesystem has no kernel, bootloader and device tree, these have to be supplied externally.

<ns0:RootFileSystem xmlns:ns0="https://www.linutronix.de/projects/Elbe"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        created="2009-05-20T08:50:56" revision="4"
        xsi:schemaLocation="https://www.linutronix.de/projects/Elbe dbsfed.xsd">
        <project>
                <name>armhf-example</name>
                <version>1.0</version>
                <buildtype>armhf</buildtype>
                <mirror>
                        <primary_host>ftp.de.debian.org</primary_host>
                        <primary_path>/debian</primary_path>
                        <primary_proto>http</primary_proto>
                        <url_list>
                                <url>
                                        <source>http://security.debian.org/debian-security buster/updates main</source>
                                        <binary>http://security.debian.org/debian-security buster/updates main</binary>
                                </url>
                                <url>
                                        <source>http://ftp.de.debian.org/debian buster-updates main</source>
                                        <binary>http://ftp.de.debian.org/debian buster-updates main</binary>
                                </url>
                        </url_list>
                </mirror>
                <suite>buster</suite>
        </project>
        <target>
                <hostname>armhf-example</hostname>
                <passwd>foo</passwd>
                <console>ttyS0,115200</console>
                <package>
                        <tar>
                                <name>rootfs.tar.gz</name>
                        </tar>
                </package>
                <finetuning>
                        <rm>/var/cache/apt/archives/*.deb</rm>
                </finetuning>
                <pkg-list>
                        <pkg>bash</pkg>
                        <pkg>less</pkg>
                        <pkg>git</pkg>
                        <pkg>openssh-server</pkg>
                        <pkg>nfs-common</pkg>
                        <pkg>curl</pkg>
                        <pkg>vim</pkg>
                        <pkg>iperf3</pkg>
                        <pkg>i2c-tools</pkg>
                </pkg-list>
        </target>
</ns0:RootFileSystem>

Further Reading

• ELBE homepage
• Official documentation of the current ELBE version
• ELBE repository at Github