Building PELUX

PELUX is built on top of multiple sources, they are described on an xml file called pelux.xml. To clone all the sources at once, repo is used.

Fetching sources

Create a directory for the PELUX build. On that directory, run repo init, and it will create a .repo directory which will later be used for fetching the sources. Run repo sync to fetch all sources on a new directory called sources.

# Initialize repo on the given repository
repo init -u https://github.com/Pelagicore/pelux-manifests.git

#Fetch the sources based on the .repo directory
repo sync

Now all the repositories required for building PELUX have been cloned under sources/ directory.

A note on image types

PELUX images are available with the -dev suffix, which include some extra development and debugging tools. Images are also available as -update to generate update artifacts for the SOTA System. The -dev and -update images can also be merged to build -dev-update which includes both features on the image.

It should be noted that the regular image is not a production-ready image. For a production project, it is recommended to create an image that can be based on the PELUX image, to begin with, but one will probably want to create a custom image eventually, as the project evolves further and further away from vanilla PELUX. For example, a PELUX-based image has an empty root password and an ssh server installed by default.

Image variants

PELUX can be built for intel, arp-intel, rpi, and qemu. Our variants are dependent on the target we are building for. If the variant contains only the target, a minimal image will be available to be built with no graphics layer. If the variant contains the target name, and the suffix -qtauto, the minimal image will be available to be build as well as the image containing Qt Automotive.

The only variant which does not offer a graphical UI is QEMU.

All the variants set different configurations, therefore it is important to specify the correct variant before sourcing for bitbake.

Intel variants

  • intel

  • intel-qtauto

RaspberryPi variants

  • rpi

  • rpi-qtauto

ARP variants

  • arp-intel

  • arp-intel-qtauto

QEMU variants

  • qemu-x86-64_nogfx

When sourcing, you can tell the oe-init-build-dev script, to use a specific directory for configuration of a variant.

TEMPLATECONF tells the oe-init-build-env script which path to fetch configuration samples from.

TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/<VARIANT-NAME> source sources/poky/oe-init-build-env build

The script will create configurations if there are no configurations present. A printout about creating conf/local.conf and conf/bblayers.conf is normal.

Available images

We support Intel, ARP-Intel and Raspberry Pi builds. The qt-auto layer can be found on all of them.

Once you have synced the repo, run the following to configure the environment for Qt Automotive images.

# For intel-qtauto:
TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/intel-qtauto source sources/poky/oe-init-build-env build
# For rpi-qtauto:
TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/rpi-qtauto source sources/poky/oe-init-build-env build
# For arp-intel-qtauto:
TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/arp-intel-qtauto source sources/poky/oe-init-build-env build

For arp-intel-qtauto, intel-qtauto and rpi-qtauto variants, we support the following images:

Minimal Images

  • core-image-pelux-minimal

  • core-image-pelux-minimal-dev

  • core-image-pelux-minimal-update

  • core-image-pelux-minimal-dev-update

Qt Automotive + Neptune 3 UI images

  • core-image-pelux-qtauto-neptune

  • core-image-pelux-qtauto-neptune-dev

  • core-image-pelux-qtauto-neptune-update

  • core-image-pelux-qtauto-neptune-dev-update

In case you want to build only the pelux base image, that can be done by removing qtauto suffix from the variant name.

# For intel:
TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/intel source sources/poky/oe-init-build-env build
# For rpi:
TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/rpi source sources/poky/oe-init-build-env build
# For arp-intel:
TEMPLATECONF=`pwd`/sources/meta-pelux/conf/variant/arp-intel source sources/poky/oe-init-build-env build

For arp-intel, intel and rpi variants, we support the following images:

Minimal images

  • core-image-pelux-minimal

  • core-image-pelux-minimal-dev

  • core-image-pelux-minimal-update

  • core-image-pelux-minimal-dev-update

Building the image

Finally, build the desired image. See the variables description above for information on the different images.

Note

Building an image takes some time, therefore consider building the sdk installer or reduce the future builds by setting up and using Yocto cache

bitbake <image>

When the build is complete the result will be available in tmp/deploy/images/<machine>/. It is possible to generate a number of different image formats, ranging from just the rootfs as a tarball to ready disk-images containing EFI-bootloader, configuration and rootfs and that can be written directly to a storage device. For PELUX, the preferred format is .wic images, which are complete disk-images. By default, a compressed wic image and a bmap file will be built for faster deployment.

Building with Docker

In the current setup in our CI system, we use Docker, however only in a GNU/Linux system. It should still work under Windows or OSX, but we have not tried it.

Dependencies:

  • Docker CE

  • Virtualization enabled in BIOS

Note

Ubuntu and Debian both have very old versions of Docker in their apt repositories. Follow the steps at docker.io to install the latest version of Docker.

Full build procedure:

  1. Clone the pelux-manifests git repository with submodule

git clone --recurse-submodules https://github.com/Pelagicore/pelux-manifests.git
cd pelux-manifests

  1. Build and run Docker container

Note

If the image was built previously you can reuse it and omit build command To verify image existence please run 'docker images pelux'

docker build --build-arg userid=$(id -u) --build-arg groupid=$(id -g) -t pelux .
docker run -t -d --name pelux-build -v $(pwd):/docker -w /docker pelux /bin/bash

  1. Run inside the Docker container

At this point, we recommend using docker exec pelux-build <command> and to follow the same instructions as when building locally (but inside the Docker container).

Note

You need 50-100 GB of free space in working directory depending on the variant you build

docker exec pelux-build bash -c "/docker/build-in-docker.sh -v <VARIANT> -i <IMAGE> -b <BRANCH>"

IMAGE and VARIANT options mentioned above BRANCH is optional; default - master

  1. Move the built images to the host

The directory where you cloned pelux-manifests is bind-mounted to /docker inside the container, so you can simply run:

docker exec pelux-build bash -c "ln -s build/tmp/deploy/images /docker/images"

  1. Stop and remove container

docker stop pelux-build
docker rm pelux-build

Particular layer build procedure:

  1. Clone the pelux-manifests git repository with submodule

git clone --recurse-submodules https://github.com/Pelagicore/pelux-manifests.git
cd pelux-manifests

  1. Copy layer directory to pelux-manifests

cp -r ../<LAYER_NAME> .

  1. Build and run Docker container

Note

If image was built previously you can reuse it and omit build command To verify image existence please run 'docker images pelux'

docker build --build-arg userid=$(id -u) --build-arg groupid=$(id -g) -t pelux .
docker run -t -d --name pelux-build -v $(pwd):/docker -w /docker pelux /bin/bash

  1. Run inside the Docker container

At this point, we recommend using docker exec pelux-build <command> and to follow the same instructions as when building locally (but inside the Docker container).

Note

You need 50-100 GB of free space in working directory depending on variant you build

docker exec pelux-build bash -c "/docker/build-in-docker.sh -v <VARIANT> -i <IMAGE> -b <BRANCH> -l <LAYER_NAME>"

IMAGE and VARIANT options mentioned above LAYER_NAME is the name of the directory we copied in step 2 BRANCH is optional; default - master

  1. Move the built images to the host

The directory where you cloned pelux-manifests is bind-mounted to /docker inside the container, so you can simply run:

docker exec pelux-build bash -c "ln -s build/tmp/deploy/images /docker/images"

  1. Stop and remove container

docker stop pelux-build
docker rm pelux-build

For more detailed steps, refer to the Jenkinsfile in pelux-manifests, where we have automated our building of PELUX.