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 419f83f4
Show latest version
1 file
+ 102
− 53
Compare changes
  • Side-by-side
  • Inline
  • 419f83f4 
    Guide newcomers through the process of building their own images using the
sample recipes.

Signed-off-by: Emanuele Aina's avatarEmanuele Aina <emanuele.aina@collabora.com>

Update Apertis version used in README.md

README.md contains a number of references to the 18.12 release. As we
are currently releasing for v2019dev0, tweak the readme to contain
references to the correct release. This is especially important as this
serves as a getting started guide and new users may not apprieciate the
importance of setting the correct release in some of these instances.

Signed-off-by: default avatarMartyn Welch <martyn.welch@collabora.com>

Update commands to use sudo

A number of the commands shown in the getting started guide need to be
run with sudo to work in the SDK. Add this to the examples so as not to
confuse newcomers.

Signed-off-by: default avatarMartyn Welch <martyn.welch@collabora.com>
README
+ 102
− 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 SABRElite 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:
$ sudo bmaptool copy apertis-sample-development-v2019dev0-minimal-armhf.img.gz $SDCARD
You can now connect to your board via a serial connection or through the
network with SSH, the default credentials are `user:user`
$ 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-v2019dev0-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:
$ sudo debos --scratchsize 10G apertis-sample-image-sdk.yaml
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
```
You can then pick the generated VDI file and
[set it up in VirtualBox](https://wiki.apertis.org/VirtualBox).
Create SDK image from prepared ospack:
```
debos --scratchsize 10G -t type:sdk -t suite:18.06 apertis-image-sdk.yaml
```
Customizing the recipes
=======================
Building in docker
Open the sample recipes and add, remove or edit the actions there 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 SABRElite
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:v2019dev0`
* 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=v2019dev0 # 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