MAR Development Manual

MAR GNU/Linux is built with the Yocto Project. There is no quick start guide for building MAR GNU/Linux from scratch, since building a Linux from source code is not a very easy thing as you build software using CMake and Autotools.

1. Read the documentation for Yocto. You may want to checkout version 5.0.4 codename Scarthgap.

2. Prepare a Debian virtual machine.

   Note: You should to use a headless, Debian 12, virtual machine.

   It is meaningless to use GUI to compile and test a headless target machine. If you are not familiar with command line interface (e.g. bash), then you should learn Linux first.

   You should use Debian 12.x. Although the Yocto documentation says they have tested on other distributions, we have found that bitbake cannot work well on Ubuntu 24.04.

   You should use a virtual machine to separate the toolchain from your production environment.

   Please allocate at least 200 GiB for the virtual machine to avoid re-partitioning your virtual hard disk. If you want to build SDK/eSDK, please allocate more. If you are using VMware, please use SATA for virtual disk to avoid virtual hard disk driver problems when re-partitioning. Please manually partition the disk; it is a good idea to put swap partition before your root partition so that it is easier to re-partition. Below is a reasonable partitioning plan.

   Device         Start       End   Sectors   Size Type
   /dev/sda1       2048   1050623   1048576   512M EFI System
   /dev/sda2  [omitted] [omitted] [omitted]     8G Linux swap
   /dev/sda3  [omitted] [omitted] [omitted]   256G Linux filesystem
   

   Install Debian (without GUI) and add yourself to sudoers.

   You should use apt for your software package manager. Update and upgrade apt as usual.

   sudo apt update
   sudo apt upgrade
   

   Install or update your editor as well. Vim works well, while emacs will need additional configuration for bitbake support.

3. Install Yocto.

   a) Install essential tools.

   sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd liblz4-tool file locales libacl1
   

   b) Change locale. Don't skip this step. Don't use en_GB even if you are in the UK and use the British keyboard layout.

   sudo locale-gen en_US.UTF-8
   

   c) Clone poky – the reference distribution.

   git clone git://git.yoctoproject.org/poky
   cd poky
   

   We are using scarthgap branch.

   git checkout -t origin/scarthgap -b my-scarthgap
   git pull
   

4. Clone meta-marfb and its dependencies.

   Switch to folder poky.

   Clone the following and switch each of their branch to scarthgap.

   • https://github.com/agherzan/meta-raspberrypi.git
   • https://github.com/openembedded/meta-openembedded.git

   Clone https://git.soton.ac.uk/qs2g22/meta-marfb.git and switch to a version.

   The poky directory should contain (some files omitted):

   poky/
      ├── bitbake
      ├── build
      ├── meta
      ├── meta-marfb
      ├── meta-openembedded
      ├── meta-poky
      ├── meta-raspberrypi
      ├── meta-selftest
      ├── meta-skeleton
      ├── meta-yocto-bsp
      └── oe-init-build-env
   
       and other files.
   

5. Source the build environment.

   In folder poky,

   . oe-init-build-env
   

   (. is the shorthand for source, the full command is source oe-init-build-env.)

   It will bring you to poky/build.

6. Add layers.

   We need to use the following layers. Layers usually start with meta-.

   bitbake-layers add-layer ../meta-raspberrypi
   bitbake-layers add-layer ../meta-marfb
   bitbake-layers add-layer ../meta-openembedded/meta-oe
   bitbake-layers add-layer ../meta-openembedded/meta-python
   bitbake-layers add-layer ../meta-openembedded/meta-networking
   bitbake-layers add-layer ../meta-openembedded/meta-multimedia
   bitbake-layers add-layer ../meta-openembedded/meta-webserver
   

7. Update local configuration.

   Only for the first time we need to change our local configuration.

   Edit conf/local.conf and do the following changes:

   • Change MACHINE ??= "qemux86-64" near line 39 to MACHINE ??= "raspberrypi0-wifi" or MACHINE ??= "raspberrypi0-2w-64".
   • Change DISTRO ?= "poky" near line 95 to DISTRO ?= "marfb".
   • Change CONF_VERSION near line 289. You will need to test and find out your own CONF_VERSION that makes bitbake happy, usually it should be CONF_VERSION = "1" or CONF_VERSION = "2".
   • Add the following lines.
     • LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch" –which means we accept the firmware's license. Please read https://meta-raspberrypi.readthedocs.io/en/latest/ipcompliance.html#linux-firmware-rpidistro and decide first, at your own risk.
     • BB_NUMBER_THREADS = "8" Bitbake should be smart enough to find out this first, so you don't always need to add this.
     • PARALLEL_MAKE = "-j 8" Similar to BB_NUMBER_THREADS.

8. Build!

   Run the following command to build.

   bitbake mar-image-minimal
   

   mar-image-minimal is the image for MAR GNU/Linux to be built.

   Note: CAVEAT! It will take several hours to build for the first time. Take a nap, have lunch, go for a walk or do your coursework.

   Note: There may be errors when you build for the first time. We have tested raspberrypi0-wifi worked well. Try re-run the command several times and the problems should be solved.

   Note: If unfortunately your disk is full, then you need to re-partition your disk. Allocate more space in your virtual machine manager, then use parted, fdisk, resize2fs, etc. to re-partition. If unfortunately your swap partition is after rootfs, then you need to swapoff, delete swap, resize, create new swap, swapon and update /etc/fstab. If unfortunately you used NVME and VMware the re-partitioning will be more complex and unpredictable.

9. Burn.

   A .wic.bz2 (bzipped OpenEmbedded image, not to be confused with Windows image creator) image is created under build/tmp-glibc/deploy/images/<machine>/mar-image-minimal-<machine>.rootfs.wic.bz2. Burn this image using Etcher to your SD card. You may want to scp it to host first.

   Depending on the layers, tmp-glibc can also be tmp.

   There are many other images, filesystem folders and other stuff under image/<machine> folder. Some of them are symbolic links.

10. Done!

This is an init script to replace SysVinit which is to replace systemd and to make the booting very fast.

Please refer to the fastinit manual (man pages).

cd poky/meta-marfb/recipes-core/fastinit
man ./fastinit.8
man ./chlevel.1
man ./level3d.8
man ./print_motd.1
# and any other manuals

The documentation for the C++ code for MAR Vision, generated automatically using Doxygen, is available here.