meta-debian is a set of recipes (metadata) for the poky build system, which allows cross-building GNU/Linux images using Debian source packages. By enabling meta-debian, you can cross-build a small GNU/Linux image with Debian sources for multiple architectures.

The main purpose of meta-debian is to provide reference Linux distribution for embedded systems satisfying the following needs.

• Long-term support
• Stability
• Wide embedded CPU support
• Customizability

Currently, the following software versions are supported in meta-debian.

• Source code: Debian GNU/Linux 10 (buster)
• Build system: Yocto Project (warrior)

meta-debian can be built in a docker container or on a Linux machine (native build).

Clone meta-debian:

$ git clone -b warrior https://github.com/meta-debian/meta-debian.git

• For docker build:

  $ cd meta-debian
  $ make -C docker
  

• For native build:

  • Install essential packages poky requires into your host system according to https://www.yoctoproject.org/docs/2.7/ref-manual/ref-manual.html#required-packages-for-the-build-host

    $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
    build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \
    xz-utils debianutils iputils-ping
    

    NOTE: The following three packages have version limitation

    • git: 1.8.3.1 or greater
    • tar: 1.27 or greater
    • python: 3.4.0 or greater

  • Setup repositories

    $ git clone -b warrior git://git.yoctoproject.org/poky.git
    $ mv meta-debian poky/
    

export TEMPLATECONF=meta-debian/conf
source ./poky/oe-init-build-env

You can change the target machine by setting MACHINE variable in conf/local.conf to one of the following machines.

• qemux86 (default)
• qemux86-64
• qemuarm
• qemuarm64
• qemuppc
• qemumips

For example, the target machine is set to QEMU ARM by adding the following difinition to conf/local.conf.

MACHINE = "qemuarm"

Now, the build system is ready. Build Linux kernel and the minimal rootfs by the following command. It takes a while to complete (more than 30 minutes).

bitbake core-image-minimal

Please replace ${MACHINE} by the target machine you selected in the above step.

NOTE: Confirm that the tun module, which runqemu depends on, is correctly loaded in your system.

runqemu ${MACHINE} nographic

After boot, you can login as root without password.

To handle Debian package source code, meta-debian needs to provide some extra functions/tasks. The following contents are not all but main components which are defined and usually used in meta-debian.

Class debian-package is inherited by recipes. This class provides tasks to extract source code and apply Debian patches.

Class debian-source is inherited by conf/distro/deby.conf. This class provides an eventhandler to fetch information from Debian apt repository. This information will be used for downloading source code.

This is a task, defined by debian-package.bbclass to unpack Debian source code into one folder. This task runs after do_unpack and before do_debian_patch

This is a task, defined by debian-package.bbclass to apply Debian patches. These Debian patches can be applied by quilt, dpatch or manually with patch. This task runs after do_debian_unpack_extra and before do_patch.

This is an eventhandler, defined by debian-source.bbclass to generate Debian package source code information: PV, URI, checksum. These kinds of information are fetched from dists/buster/main/source/Sources.xz in Debian apt repository. This eventhandler runs when bb.event.ParseStarted is fired.

URI to fetch Debian package source code. By default, this variable is generated automatically in recipes-debian/sources/<source_name>.inc.

Example:

DEBIAN_SRC_URI = " \
    ${DEBIAN_MIRROR}/main/f/flex/flex_2.6.4-6.2.dsc;name=flex_2.6.4-6.2.dsc \
    ${DEBIAN_MIRROR}/main/f/flex/flex_2.6.4.orig.tar.gz;name=flex_2.6.4.orig.tar.gz \
    ${DEBIAN_MIRROR}/main/f/flex/flex_2.6.4-6.2.diff.gz;name=flex_2.6.4-6.2.diff.gz;apply=no \
"

Path to source code directory after unpacked. This variable is initialized in debian-package.bbclass with default value ${WORKDIR}/${BP}

Decide action to apply patches for the source package. Normally, this variable will only need to be set if patch type cannot be detected by debian/source/format. Possible value:

• quilt: if package uses quilt for applying patches.
• dpatch: if package uses dpatch for applying patches.
• nopatch: if there is no Debian patch.
• abnormal: if none of the three conditions above matched. Recipe will need to define its own way to apply patches by defining function debian_patch_abnormal or overwriting do_debian_patch.

Path to Debian patches folder, by default is ${DEBIAN_UNPACK_DIR}/debian/patches. In some cases, this variable need to be unset because DEBIAN_PATCH_TYPE is quilt but there is no patch. For example, package gawk has debian/source/format is 3.0 (quilt) but there is no patch in debian subfolder.

Select snapshot.debian.org as the Debian source package download location, by default is 0. If you want to download package from snapshot.debianorg, you need to set 1.

In meta-debian, BPN is not just "a version of the PN variable with common prefixes and suffixes removed" but the real Debian source package name and usually used to specify directory path.
For examples: ${WORKDIR}/${BPN}-${PV}, ${libdir}/${BPN}, ${datadir}/${BPN}, ...

All recipes for Debian packages should be put in folder recipes-debian. The next section will show you how to create a recipe in meta-debian.

Firstly, create an empty file which will store source code information:

touch recipes-debian/sources/<source_name>.inc

Enable debian-source in <your buildir>/conf/local.conf:

DEBIAN_SOURCE_ENABLED = "1"
DEBIAN_SRC_FORCE_REGEN = "1"

When bitbake run, class debian-source will generate information about version, source URI and checksum to .inc file.

NOTE: By default, debian-source will not rerun if file Sources.xz does not change. Force it regenerate by adding DEBIAN_SRC_FORCE_REGEN = "1" into conf/local.conf in the build directory.

Recipe in meta-debian is almost similar with recipe in meta, but there are some rules need to be concerned.

• Recipe name PN should be same with recipe name in layer meta and has version suffix _debian:

  meta-debian/recipes-debian/*/<PN>_debian.bb
  

• Always inherit debian-package and include sources/<source_name>.inc in recipe.

  inherit debian-package
  require recipes-debian/sources/<source_name>.inc
  

• Recipe should include available .inc from meta if possible. File .inc should be included before inherit debian-package, so SRC_URI can be overridden. Ex:

  require recipes-devtools/binutils/binutils.inc
  ...
  inherit debian-package
  

• Recipe also can reuse patches/local-files from meta if append FILESPATH. Ex:

  FILESPATH_append = ":${COREBASE}/meta/recipes-devtools/sample/sample"
  SRC_URI += "file://sample.patch"
  

  Note: Security fixes should be managed by Debian in source package, so don't reuse patches, which relate to CVE or security bugs, in meta-debian. It is better to wait for Debian maintainers apply patch into source code.

• This version of meta-debian aims to be compatible with Poky more than Debian, so recipe should configure and split packages same as Poky recipe to avoid conflict.

Assume we want to create recipe for icu.

• Generate source code information

  touch meta-debian/recipes-debian/sources/icu.inc
  
  # Enable debian-source
  echo 'DEBIAN_SOURCE_ENABLED = "1"' >> <build-dir>/conf/local.conf
  # Force debian-source re-generate in case Sources.xz doesn't change
  echo 'DEBIAN_SRC_FORCE_REGEN = "1"' >> <build-dir>/conf/local.conf
  

• Create recipe with name icu_debian.bb

  mkdir meta-debian/recipes-debian/icu
  vim meta-debian/recipes-debian/icu_debian.bb
  

• Add LICENSE and LIC_FILES_CHKSUM in recipe

  LICENSE = "ICU"
  LIC_FILES_CHKSUM = "file://LICENSE;md5=63752c57bd0b365c9af9f427ef79c819"
  

• Handle Debian source code

  inherit debian-package
  require recipes-debian/sources/icu.inc
  

  Unlike other package, icu put buildable source in the sub-folder source. So we need to overwrite S and update LIC_FILES_CHKSUM to a correct path.

  LICENSE = "ICU"
  LIC_FILES_CHKSUM = "file://../LICENSE;md5=63752c57bd0b365c9af9f427ef79c819"
  
  inherit debian-package
  require recipes-debian/sources/icu.inc
  
  S = "${DEBIAN_UNPACK_DIR}/source"
  

• Reuse codes from meta Layer meta already provide icu.inc with setup for bitbake. Reuse it.

  require recipes-support/icu/icu.inc
  

  If recipe wants to use patch from meta, it need to append FILESPATH to point to icu patch directory.

  FILESPATH_append = ":${COREBASE}/meta/recipes-support/icu/icu"
  SRC_URI += "file://fix-install-manx.patch"
  

• Configure and split packages For icu, all of configurations are put in icu.inc and we already include it, so nothing left to do.

require recipes-support/icu/icu.inc

LICENSE = "ICU"
LIC_FILES_CHKSUM = "file://../LICENSE;md5=63752c57bd0b365c9af9f427ef79c819"

inherit debian-package
require recipes-debian/sources/icu.inc

FILESPATH_append = ":${COREBASE}/meta/recipes-support/icu/icu"
SRC_URI += "file://fix-install-manx.patch"

S = "${DEBIAN_UNPACK_DIR}/source"

meta-debian can be used with meta-ti or meta-raspberrypi. The next sections will show how to use meta-debian with those layers to build image for BeagleBone Black and Raspberry Pi.

Get meta-ti at https://git.yoctoproject.org/cgit/cgit.cgi/meta-ti/.

Tested with:

poky        : warrior:f2b442c5c8e3925a4d3fc9693f1e47863dade2a9
meta-ti     : master:59e66caff2568ab32f59596f1aeab8ea27649941
meta-debian : warrior:e87428eec5edfa6ec741eed8827d7044df043625

1. Setup build directory.

   $ export TEMPLATECONF=meta-debian/conf
   $ source ./poky/oe-init-build-env build-bbb
   

2. Add meta-ti and meta-debian/bsp/meta-ti to conf/bblayers.conf.

   $ vi conf/bblayers.conf
   ...
   BBLAYERS ?= " \
     /path/to/poky/meta \
     /path/to/poky/meta-poky \
     /path/to/poky/meta-ti \
     /path/to/poky/meta-debian \
     /path/to/poky/meta-debian/bsp/meta-ti \
     "
   

3. Set MACHINE to beaglebone.

   $ vi conf/local.conf
   ...
   MACHINE ??= "beaglebone"
   ...
   

4. Build. By default, DISTRO is set to 'deby-tiny', so only core-image-minimal is available to build

   $ bitbake core-image-minimal
   

   In conf/local.conf, DISTRO can be changed to 'deby' for building core-image-base.

After finish building, in tmp/deploy/images/beaglebone/, these files should be available:

• MLO
• u-boot.img (U-Boot)
• zImage (Kernel)
• am335x-boneblack.dtb (Kernel device tree)
• core-image-minimal-beaglebone.cpio.gz (rootfs)

1. Create two partitions on the SD card: BOOT (FAT32) and ROOT (ext4).

2. Install the root file system.

   $ cd /mount/dir/of/ROOT
   $ zcat /path/to/core-image-minimal-beaglebone.cpio.gz | sudo cpio -idm --no-absolute-filenames
   

3. Install the bootloader. If ROOT is the 2nd partition, mmcroot should be /dev/mmcblk0p2.

   $ sudo cp MLO u-boot.img /mount/dir/of/BOOT
   $ sudo cat <<\EOF > /mount/dir/of/BOOT/uEnv.txt
   bootpart=0:2
   bootdir=/boot
   bootfile=zImage
   console=ttyO0,115200n8
   fdtaddr=0x81000000
   fdtfile=am335x-boneblack.dtb
   loadaddr=0x80008000
   mmcroot=/dev/mmcblk0p2 ro
   mmcrootfstype=ext4 rootwait
   mmcargs=setenv bootargs console=${console} root=${mmcroot} rootfstype=${mmcrootfstype}
   loadfdt=load mmc ${bootpart} ${fdtaddr} ${bootdir}/${fdtfile}
   loadimage=load mmc ${bootpart} ${loadaddr} ${bootdir}/${bootfile}
   uenvcmd=if run loadfdt; then echo Loaded ${fdtfile}; if run loadimage; then run mmcargs; bootz ${loadaddr} - ${fdtaddr}; fi; fi;
   
   EOF
   

4. Connect serial cable to the board on jumper J1. We tested with Adafruit 4 Pin Cable which has 4 wires: Black, Green, White, Red. Just leave the RED wire unconnected.

   J1   : [GND]   *   *   [RX]    [TX]   *
   Cable: [Black]         [Green] [White]
   

   Boot the board.

   $ sudo picocom -b 115200 /dev/ttyUSB0
   picocom v3.1
   
   port is        : /dev/ttyUSB0
   flowcontrol    : none
   baudrate is    : 115200
   ...<many logs>
   
   U-Boot 2018.03-00002-gac9cce7c6a (Apr 05 2018 - 13:07:46 -0500), Build: jenkins-github_Bootloader-Builder-47
   
   CPU  : AM335X-GP rev 2.1
   I2C:   ready
   DRAM:  512 MiB
   ....<many logs>
   
   Starting kernel ...
   
   [    0.000000] Booting Linux on physical CPU 0x0
   [    0.000000] Linux version 4.19.13-cip1 (oe-user@oe-host) (gcc version 8.3.0 (GCC)) #1 SMP Thu Mar 21 06:02:24 UTC 2019
   [    0.000000] CPU: ARMv7 Processor [413fc082] revision 2 (ARMv7), cr=10c5387d
   .....<many logs>
   starting pid 64, tty '': '/etc/init.d/rcS'
   starting pid 66, tty '/dev/ttyS0': '/sbin/getty 115200 ttyS0'
   
   Deby 10.0 beaglebone /dev/ttyS0
   
   beaglebone login:
   

   Then login with root (no password).

Get meta-raspberrypi at https://git.yoctoproject.org/cgit/cgit.cgi/meta-raspberrypi.

Tested with:

poky             : warrior:b164f0dc3e69ba9cb552b48834cd6c50f50c5000
meta-raspberrypi : warrior:1c842e21c22e999b8a317e33d7748102ef13b6b4
meta-debian      : warrior:7df267bd32b8229e1a67ab537c30e3f3eaeaa3d8

1. Setup build directory.

   $ export TEMPLATECONF=meta-debian/bsp/meta-raspberrypi/conf
   $ source ./poky/oe-init-build-env build-pi
   

2. Set MACHINE to raspberrypi3, which is the current tested version.

   $ vi conf/local.conf
   ...
   MACHINE ??= "raspberrypi3"
   ...
   

   Note: Add ENABLE_UART = "1" to conf/local.conf if you want serial console support. There are also other build configurations.

3. Build. By default, DISTRO is set to 'deby-tiny', so only core-image-minimal is available to build

   $ bitbake core-image-minimal
   

   In conf/local.conf, DISTRO can be changed to 'deby' for building core-image-base.

After finish building, tmp/deploy/images/raspberrypi3/core-image-minimal-raspberrypi3.rpi-sdimg should be available.

1. Burn sdimg file to SD card using etcher or dd:

   # Assume /dev/sdb is target SD card
   $ sudo dd if=core-image-minimal-raspberrypi3.rpi-sdimg of=/dev/sdb
   

2. Enable UART (Optional).
   If you didn't add ENABLE_UART = "1" when build image and want to use serial console, you can enable it by edit config files in boot partition.

   • In file cmdline.txt, add console=serial0,115200 in the same line with old content.
   • In file config.txt, add enable_uart=1 in a new line.

3. Boot the SD card on the board and login with root (no password).

Poky is using apt version 1.2.24. Debian 10 apt (1.8.2) does not provide option --force-yes which is required by meta/lib/oe/package_manager.py.

Poky has its own prelink-cross package. Debian 10 prelink (0.0.20131005-1+b10) does not support changing root directory which is required by meta/classes/image-prelink.bbclass.

For now, to keep meta-debian minimal and reduce effort of maintenance, meta-debian only provides recipes to support PACKAGECONFIG features which are enabled by default. More recipes may be added in future if there are any requests.

Below is the packages version comparison between Debian 10 and Poky. The comparison is done with Poky 2.6 (thud), 2.7 (warrior) and 2.8 (master).

Note: Poky 2.8 has not released yet, so we use the current branch master instead.

meta-debian : 51c6c0a175b8e3a91bec803a0a792fed00029e6e
poky 2.6    : 50f33d3bfebcbfb1538d932fb487cfd789872026
poky 2.7    : 0e392026ffefee098a890c39bc3ca1f697bacb52
poky 2.8    : c23c8ebc7f66a92110bfc9e3c4d633a432d1353b

Note: Packages with version NA mean they are not provided.

Poky 2.8 is planned to be released in Oct 2019, so the number of packages with different version may continue increase in future.

• https://github.com/meta-debian/meta-debian

• meta-debian@googlegroups.com

• meta-debian+subscribe@googlegroups.com
• https://groups.google.com/forum/#!forum/meta-debian/join

License of meta-debian is same as meta in poky i.e. All metadata is MIT licensed unless otherwise stated. Source code included in tree for individual recipes is under the LICENSE stated in the associated recipe (.bb file) unless otherwise stated.

See COPYING.MIT for more details about MIT license.