The process of getting from source code to an image suitable for loading into a target device with Apertis is a clearly defined multi-step process. The initial step is to build the source and package the resulting artefacts into .deb packages. For the vast majority of packages this is already done and provided by Apertis in the package repositories. This page will not cover this step of the process an will assume all required packages have been successfully built and are available in the package repositories.

There are two further steps to generating an image:

• Building an Operating System package (OSpack)
• Combining the OSpack with a Hardware package (HWpack) to create an image

Both the process of building OSpacks and images from them is carried out using Debos. It is strongly recommended to utilise the appropriate Docker image builder container to perform these steps, though the Apertis SDK image running in a VM can be used with reduced reliability.

# Building OSpacks

The OSpack is a root file system containing all the generic software for a particular image type and hardware architecture (e.g. the arm architecture). Apertis provides stock Debos recipes in the form of .yaml files in the apertis-image-recipes gitlab repository, with a name of the form apertis-ospack-*.yaml, each one providing a different balance of packages for different tasks.

It is best to build these packages images from the appropriate image-builder docker container. This is documented in the apertis-image-recipes README.md.

# Building an image with a HWpack

Unlike the OSpack, that is generic, the HWpack contains the bits needed to boot on a specific target. The HWpack configuration typically extracts an OSpack, creates an image containing the required partition layout for the specific hardware, writes the extracted OSpack into it, adds extra components necessary for the target and may perform some tweaks to the image (tweaking configuration files etc). Finally the image is compressed to minimise storage space.

Existing Apertis examples can be found in the Apertis Image Recipes repository called apertis-image-*.yaml. The Debos documentation also provides a simple example.

## Image creation

Image creation is the point where a set of standard packages are combined to build a solution for a specific use case. This goal is accomplish thanks to Debos, a flexible tool to configure the build of Debian-based operating systems. Debos uses tools like debootstrap already present in the environment and relies on virtualisation to securely do privileged operations without requiring root access.

Ospacks and how they should be processed to generate images are defined through YAML files.

This is an example configuration for an ARMv7 image, image-armhf.yaml:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43  architecture: armhf actions: - action: unpack file: ospack-armhf.tar.gz compression: gz - action: apt description: Install hardware support packages recommends: false packages: - linux-image-4.9.0-0.bpo.2-armmp-unsigned - u-boot-common - action: image-partition imagename: "apertis-armhf.img" imagesize: 4G partitiontype: gpt mountpoints: - mountpoint: / partition: root flags: [ boot ] partitions: - name: root fs: ext4 start: 0% end: 100% - action: filesystem-deploy description: Deploy the filesystem onto the image - action: run chroot: true command: update-u-boot - action: run description: Create bmap file postprocess: true command: bmaptool create apertis-armhf.img > apertis-armhf.img.bmap - action: run description: Compress image file postprocess: true command: gzip -f apertis-armhf.img 

And this is the ospack-armhf.yaml configuration for the ARMv7 ospack:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37  architecture: armhf actions: - action: debootstrap suite: "17.06" keyring-package: apertis-archive-keyring components: - target mirror: https://repositories.apertis.org/apertis variant: minbase - action: apt description: Install basic packages packages: [ procps, sudo, openssh-server, adduser ] - action: run description: Setup user account chroot: true script: setup-user.sh - action: run description: Configure the hostname chroot: true command: echo apertis > /etc/hostname - action: overlay description: Overlay systemd-networkd configuration source: networkd - action: run description: Configure network services chroot: true script: setup-networking.sh - action: pack compression: gz file: ospack-armhf.tar.gz 

Additionally at this stage customizations can be applied by using overlays. This process allows the default content of packages to be combined with custom modifications to provide the desired solution. A common case is to apply overlays to change some default system settings found in /etc such as default hostname or default package configuration.

As an example of this mechanism, the following section is used to customize the behaviour of dpkg

 1 2   - action: overlay source: overlays/dpkg-exclusions 

Thanks to this action, the contents of the overlays/dpkg-exclusions directory will be applied to the image, which in this case consist of the file:

etc/dpkg/dpkg.cfg.d/apertis-exclusions


This file will be added to the rootfs, which in this instance will change the default behaviour of dpkg to suit the needs of the image

Collections of images are built every night and published on the deployable image hosting website, such that developers can always download the latest image to deploy it to a target device and start using it immediately.