Skip to content
Snippets Groups Projects

Newcomers introduction

Merged Newcomers introduction
wip/em/image-building-for-newcomers into apertis/v2019pre
All threads resolved!
Merged Emanuele Aina requested to merge wip/em/image-building-for-newcomers into apertis/v2019pre
All threads resolved!
Viewing commit 52917f76
Prev Next
Show latest version
1 file
+ 112
− 53
Compare changes
  • Side-by-side
  • Inline
README
+ 112
− 53
General Information
===================
Apertis Image Recipes
=====================
Here is the recipes collection for Apertis images creation.
This repository contains the recipes used to build the Apertis reference images.
To use these recipes, the debos tool needs to be installed: https://github.com/go-debos/debos
Getting started
===============
By default, this command will create a minimal Apertis image for Intel 64bit systems:
```
debos apertis-ospack.yaml && debos apertis-image-amd64.yaml
```
To experiment with Apertis, begin with the `apertis-sample-*.yaml` recipes.
They are a good starting point for building your own images based on the
reference Apertis recipes.
The target architecture can be changed with command line parameter '-t architecture:armhf'.
Architectures supported:
* arm64
* amd64
* armhf
From the Apertis SDK, build your first image:
Packages set selection via '-t type:minimal':
* minimal
* development
* sdk
$ sudo debos apertis-sample-image-development.yaml
Parameters for ospack and image versioning:
* suite: (-t suite:18.06)
* timestamp: (-t timestamp:`date +"%s"`)
The `apertis-sample-image-development.yaml` recipe builds an image suitable for
the ARM-based i.MX6 SABRE Lite board with all the development tools installed.
Copy it to a SD card and then plug the SD card in your board to boot Apertis
on it.
The image can be copied to the SD card by decompressing it and then copying the
raw bytes using tools like `dd`.
If the SD Card reader is available from the Apertis SDK, the
[`bmaptool`](https://github.com/intel/bmap-tools) command provides an
alternative that is faster, more reliable and easy to use:
$ sudo bmaptool copy apertis-sample-development-*-minimal-armhf.img.gz $SDCARD
You can now connect to your board via a serial connection, the default
credentials are `user:user`.
Depending on your network setup, your board may also be available via SSH with
the same credentials:
$ ssh user@apertis.local
With the development image you can install, remove, and update packages using
the standard Debian tools like `apt`, including the GPLv3 components that are
excluded by default from the Apertis image:
$ sudo apt install gdbserver
You can edit the recipe to customize the package selection, run custom scripts
to change the rootfs contents, and download contents from remote sources.
For images to be deployed in production, Apertis uses OSTree to manage updates
in a reliable way.
The `apertis-sample-image-production.yaml` recipe builds an image that boots
into an OSTree deployment with the ability to automatically roll-back updates
in case of boot failures:
$ sudo debos apertis-sample-image-production.yaml
$ sudo bmaptool copy apertis-sample-production-*-minimal-armhf.img.gz $SDCARD
Providing a reproducible development environment is one of the key elements for
Apertis, and the `apertis-sample-image-sdk.yaml` gives you the ability to
generate your own SDK images, bootable in VirtualBox:
Create the ospack for the SDK package set:
```
debos -t type:sdk -t architecture:amd64 -t suite:18.06 --scratchsize 10G --debug-shell apertis-ospack.yaml
```
$ sudo debos --scratchsize 10G apertis-sample-image-sdk.yaml
Create SDK image from prepared ospack:
```
debos --scratchsize 10G -t type:sdk -t suite:18.06 apertis-image-sdk.yaml
```
You can then pick the generated VDI file and
[set it up in VirtualBox](https://wiki.apertis.org/VirtualBox).
Building in docker
Customizing the recipes
=======================
Open the sample recipes and add, remove or edit their actions to make the
generated artifacts suit your needs.
Some customization examples are already provided, check the Debos documentation
for a full list of the available actions:
https://godoc.org/github.com/go-debos/debos/actions
The reference recipes
=====================
The main `Jenkinsfile` orchestrates how platform-independent ospacks and
platform-specific hwpacks are combined to generate all the reference artifacts.
Architectures supported via `-t architecture:$VALUE`:
* arm64: (uboot) currently targets ARM 64bit Renesas R-Car boards
* amd64: (uefi) supports any UEFI x86-64bit system
* armhf: (uboot) currently targets the ARM 32bit i.MX6 SABRE Lite
Package set selection via `-t type:$VALUE`:
* minimal: headless system
* target: Mildenhall HMI
* sdk: XFCE-based development environment with the Mildenhall HMI tools
* basesdk: basic XFCE-based development environment
* sysroot: cross-compilation target tarballs
* devroot: emulation-based foreign platform build environments
Deployment types:
* APT: suitable for development, prioritizes flexibility over robustness
* OSTree: suitable for production, prioritizes robustness over flexibility
Parameters for ospack and image versioning:
* suite: `-t suite:v2019pre`
* timestamp: `-t timestamp:$(date +%s)`
Building in Docker
==================
To ease testing on a wide variety of host systems (and building in Jenkins) a
docker file is provided which sets up the build environment. To build using
that:
* Pull and run the docker image:
You may pull and run the 18.06 image directly with:
```
RELEASE=18.06 # the Apertis release to be built
docker run --device /dev/kvm -w /recipes \
-u $(id -u) \
--group-add=$(getent group kvm | cut -d : -f 3) \
-i -v $(pwd):/recipes \
-t docker-registry.apertis.org/apertis/apertis-$RELEASE-image-builder \
debos apertis-ospack.yaml
```
Note: The examples are for the 18.06 release. You may change the
version if working on a different branch.
The image build will be run in the build docker image using your uid with the
additional kvm group (for debian based systems) to ensure debos/fakemachine can
use hardware virtualisation. For fedora/Redhat based systems the group-add is
likely not needed.
To build in a reproducible environment outside of the Apertis SDK, using the
pre-built Docker images in the Apertis registry is recommended:
$ RELEASE=v2019pre # the Apertis release to be built
$ docker run \
-i -t \
-u $(id -u) \
--group-add=$(getent group kvm | cut -d : -f 3) \
--device /dev/kvm \
-w /recipes \
-v $(pwd):/recipes \
docker-registry.apertis.org/apertis/apertis-$RELEASE-image-builder \
debos apertis-ospack-minimal.yaml
The image build will be run in the Docker container using your uid with the
host's kvm group to ensure debos/fakemachine can use hardware virtualisation.
Apertis Website Terms of Use Privacy Policy