Skip to content

User Manual

Jump to bottom
Alexander Smirnov edited this page Oct 12, 2016 · 14 revisions

ISAR User Manual

Contents

Introduction

Isar is a set of scripts for building software packages and repeatable generation of Debian-based root filesystems with customizations.

Isar provides:

  • Fast target image generation: About 10 minutes to get base system image for one machine.
  • Use any apt package provider, including open-source communities like Debian, Raspbian, etc. and proprietary ones created manually.
  • Native compilation: Packages are compiled in chroot environment using the same toolchain and libraries that will installed to target filesystem.
  • Various examples and demos, that can be quickly re-used for real projects.

Getting Started

For demonstration purpose, isar includes support for two machines:

  • QEMU ARM
  • Raspberry Pi 1 Model B

The steps below describes how to build default isar configuration:

Install Host Tools

Install the following packages:

dosfstools
git
mtools
multistrap
parted
python3
qemu
qemu-user-static
sudo

Notes:

  • BitBake requires Python 3.4+.
  • The python3 package is required for the correct alternatives setting.
Setup Sudo

Isar requires sudo permissions to work with chroot and multistrap, to add them use the following steps:

 # visudo

In the editor, allow the current user to run sudo without a password, e.g.:

 <user>  ALL=NOPASSWD: ALL

Replace <user> with your user name. Use the tab character between and parameters.

Check out Isar

Clone isar repository:

$ git clone http://github.com/ilbers/isar.git
Initialize the Build Directory

To initialize isar build directory run the following commands:

 $ cd isar
 $ . isar-init-build-env ../build

../build is the build directory.

Build Isar

The following command will produce isar-image-base images for both machines:

$ bitbake multiconfig:qemuarm:isar-image-base multiconfig:rpi:isar-image-base

Created images are:

 tmp/deploy/images/isar-image-base-*

To build just for one target, pass only its name to bitbake.

Terms and Definitions

Chroot

chroot runs a command with a specified root directory. Please refer to GNU coreutils online help: http://www.gnu.org/software/coreutils/ for more information.

QEMU

QEMU is a generic and open source machine emulator and virtualizer. Please refer to origin page http://wiki.qemu.org/Main_Page for more information.

Debian

Debian is a free operating system for your machine. Please refer to origin page https://www.debian.org/index.en.html for more information.

APT

APT (for Advanced Package Tool) is a set of tools for managing Debian packages, and therefore the applications installed on your Debian system. Please refer to origin page https://wiki.debian.org/Apt for more information.

BitBake

BitBake is a generic task execution engine that allows shell and Python tasks to be run efficiently and in parallel while working within complex inter-task dependency constraints. Please refer to user manual page https://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html for more information.

How Isar Works

Isarworkflow can be split into the following stages:

Generation of Buildchroot Filesystem

This filesystem is used as build environment to compile custom packages. It is generated using APT binaries repository, selected by user in configuration file. Please refer to distro configuration chapter for more information.

Custom Package Compilation

During this stage isar processes all the custom packages selected by user and generates binary *.deb packages. Please refer to custom packages compilation section for more information.

Generation of Basic Target Filesystem

This filesystem is generated in the manner as buildchroot using APT binaries repository. Please refer to distro configuration chapter for more information.

Install Custom Packages

At this stage isar populates target filesystem by custom packages, that were built in previous stages.

Target Image Packaging

isar can produce various target filesystem images like ext4 or a complete SD card image. The list of images to produce is set in configuration file, please refer to image type selection section.

General Isar Configuration

Isar uses the following configuration files:

  • conf/local.conf
  • conf/bblayers.con

In local.conf user defines the list of machines. Then bitbake includes respective configuration files for these machines:

  • conf/multiconfig/${MACHINE}.conf

In machine config file user defines which distro has to be used for current machine. Then bitbake includes respective distro configuration file:

  • conf/distro/${DISTRO}.conf
bblayers.conf

This file contains the list of meta layers, where bitbake will search for recipes, classes and configuration files. By default isar includes the following layers:

  • meta - core isar layer which contains basic functionality.
  • meta-isar - demo layer intended to show isar features to user. Also this layer can be re-used to make custom projects.
local.conf

This file contains variables that will be exported to bitbake environment and will be processed in recipes. The default isarconfiguration uses the following variables:

  • BBMULTICONFIG - list of the machines to include the respective configuration files. If this option is omitted, user has to manually define the pair MACHINE/DISTRO for specific target.
  • IMAGE_INSTALL - list of custom packages to build and install to target image, please refer to relative chapter for more information.
  • BB_NUMBER_THREADS - number of bitbake jobs that can be run in parallel. Please set this option according your host CPU cores number.

Isar Distro Configuration

In isar each machine can use its specific Linux distro to generate buildchroot and target filesystem. By default, isar provides configuration files for the following distros:

  • debian-wheezy
  • raspbian-stable

User can select appropriate distro for specific machine by setting the following variable in machine configuration file:

DISTRO = "distro-name"

Custom Package Compilation

Isar provides possibility to compile and install custom packages. Current version support only building deb packages using dpkg-buildpackage, so the origin sources should contain debian folder with necessary meta information. To add new package to image, it needs the following:

  • Create package recipe and put it in your isar layer.
  • Append IMAGE_INSTALL variable by this recipe name. If this package should be included for all the machines - put IMAGE_INSTALL to local.conf file. If you want to include this package for specific machine - put it to your machine configuration file.

Please refer to add custom application section for more information about recipe payload.

Image Type Selection

Isar can generate various images types for specific machine. There is a IMAGE_TYPE variable which contains the list of image type. The default Isar implementation supports the following types:

  • ext4 - raw ext4-filesystem image (default option for qemuarm machine).
  • rpi-sdimg - raspberry pi SD card image (default option for rpi machine).

Add a New Distro

The distro is defined by the set of the following variables:

  • DISTRO_SUITE - repository suite like stable, jessie, wheezy etc.
  • DISTRO_ARCH - machine CPU architecture.
  • DISTRO_COMPONENTS - repository components like main, contrib, non-free etc.
  • DISTRO_APT_SOURCE - repository URL.
  • DISTRO_CONFIG_SCRIPT - target filesystem finalization script. This script is called after multistrap has unpacked the base system packages. It is designed to finalize filesystem, for example to add fstab according to machine hardware configuration. The script should be placed to files folder in image recipe folder.

Below is an example for Raspbian stable:

DISTRO_SUITE = "stable"
DISTRO_ARCH = "armhf"
DISTRO_COMPONENTS = "main contrib non-free firmware"
DISTRO_APT_SOURCE = "http://archive.raspbian.org/raspbian"
DISTRO_CONFIG_SCRIPT = "raspbian-configscript.sh"

To add new distro, user should perform the following steps:

  • Create distro folder in your layer:

    $ mkdir meta-user/conf/distro

  • Create .conf file in distro folder with the name of your distribution. Isar recommends to name distribution in the following format: name-suite, for example:

    debian-wheezy
debian-jessie

  • Define in this file variables, that described above in this chapter.

Add a New Machine

Each machine in isar is described by individual configuration file. This file defines the following variables:

  • IMAGE_PREINSTALL - list of machine-specific packages, that has to be included to image. This variable must include the name of the following packages (if applicable):
    • Linux kernel.
    • U-Boot or other bootloader.
    • Machine-specific firmware.
  • KERNEL_IMAGE - the name of kernel binary that it installed to /boot folder in target filesystem. This variable is used by Isar to extract the kernel binary and put it into the deploy folder. This makes sense for embedded devices, where kernel and root filesystem are written to different flash partitions. This variable is optional.
  • INITRD_IMAGE - the name of ramdisk binary. The meaning of this variable is similar to KERNEL_IMAGE. This variable is optional.
  • MACHINE_SERIAL - the name of serial device that will be used for console output.
  • IMAGE_TYPE - the type of images to be generated for this machine.

Below is an example of machine configuration file for Raspberry Pi baord:

IMAGE_PREINSTALL = "linux-image-rpi-rpfv \
                    raspberrypi-bootloader-nokernel"
KERNEL_IMAGE = "vmlinuz-4.4.0-1-rpi"
INITRD_IMAGE = "initrd.img-4.4.0-1-rpi"
MACHINE_SERIAL = "ttyAMA0"
IMAGE_TYPE = "rpi-sdimg"

To add new machine user should perform the following steps:

  • Create machine folder in your layer:

    $ mkdir meta-user/conf/machine

  • Create .conf file in machine folder with the name of your machine.

  • Define in this file variables, that described above in this chapter.

Add a New Image

Image in isar contains the following artifacts:

  • Image recipe - describes set of rules how to generate target image.
  • Multistrap configuration file - contains information about distro, suite, APT source etc.
  • Multistrap setup script - performs pre-install filesystem configuration.
  • Multistrap config script - performs post-install filesystem configuration.

In image recipe, the following variable defines the list of packages that will be included to target image: IMAGE_PREINSTALL. These packages will be taken from APT source.

The user may use met-isar/recipes-core-images as a template for new image recipes creation.

Add a New Image Type

General Information

The image recipe in isar creates a folder with target root filesystem. The default its location is:

tmp/work/${IMAGE}/${MACHINE}/rootfs

Each image type in isar is implemented as a bitbake class. The goal of these classes is to pack root filesystem folder to appropriate format.

Create Custom Image Type

As already mentioned above, isar uses bitbaketo process tasks. So all the isar activity can be represented as an execution of tasks chain. This chain is generated using task dependencies, so the next task in chain requires completion of previous ones. The last task of image recipe is do_populate, so the class that implement new image type should continue execution from this point. According to bitbake syntax this can be implemented like the following.

Create new class:

$ vim meta-user/classes/my-image.bbclass

And put these lines:

do_my_image() {
}
addtask my_image before do_build after do_populate

The content of do_my_image function can be implemented in both: bash or python.

And the in machine configuration file set the following:

IMAGE_TYPE = "my-image"
Reference Classes

Isar contains two image type classes, that can be used for reference:

  • ext4-img
  • rpi-sdimg

Add a Custom Application

Before creating new recipe it's highly recommended to take a look into bitbake user manual, that is mentioned in terms and definitions section.

Current isar version supports of building packages in debian format only, so this means that user is responsible for creation of debian folder with necessary metadata in application source tree.

The typical isar recipe looks like the following:

DESCRIPTION = "Sample application for ISAR"

LICENSE = "gpl-2.0"
LIC_FILES_CHKSUM = "file://${LAYERDIR_isar}/licenses/COPYING.GPLv2;md5=751419260aa954499f7abaabaa882bbe"

PV = "1.0"

SRC_URI = "git://github.com/ilbers/hello.git"
SRCREV = "ad7065ecc4840cc436bfcdac427386dbba4ea719"

SRC_DIR = "git"

inherit dpkg

The following variables are used in the recipe:

  • DESCRIPTION - textual description of the package.

  • LICENSE - application license file.

  • LIC_FILES_CHKSUM - reference to the license file with its checksum. Isar recommends to store license files for your applications into layer your layer folder meta-user/licenses/. Then you may reference it in recipe using the following path:

    LIC_FILES_CHKSUM = file://${LAYERDIR_isar}/licenses/...

This approach will prevent you from having multiple instances of the same license file within layer folder.

  • PV - application version.
  • SRC_URI - the link where to fetch application source. Please check bitbake user manual for supported download formats.
  • SRC_DIR - the folder name where application sources will be unpacked. For git repository the folder should be set to git. Please check bitbake user manual for supported download formats.
  • SRC_REV - the source code revision to fetch. Please check bitbake user manual for supported download formats.

The last line in the example above adds recipe to isar work chain.

Clone this wiki locally