-
Notifications
You must be signed in to change notification settings - Fork 73
User Manual
- Introduction
- Getting Started
- Terms and Definitions
- How Isar Works
- General Isar Configuration
- Isar Distro Configuration
- Custom Package Compilation
- Image Type Selection
- Add a New Distro
- Add a New Machine
- Add a New Image
- Add a New Image Type
- Add a Custom Application
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.
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 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.
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.
Clone isar
repository:
$ git clone http://github.com/ilbers/isar.git
To initialize isar
build directory run the following commands:
$ cd isar
$ . isar-init-build-env ../build
../build
is the build directory.
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
.
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 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 is a free operating system for your machine. Please refer to origin page https://www.debian.org/index.en.html for more information.
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 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.
Isar
workflow can be split into the following stages:
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.
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.
This filesystem is generated in the manner as buildchroot
using APT
binaries repository. Please refer to distro configuration chapter for more information.
At this stage isar
populates target filesystem by custom packages, that were built in previous stages.
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.
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
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
- coreisar
layer which contains basic functionality. -
meta-isar
- demo layer intended to showisar
features to user. Also this layer can be re-used to make custom projects.
This file contains variables that will be exported to bitbake
environment and will be processed in recipes. The default isar
configuration 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 pairMACHINE
/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 ofbitbake
jobs that can be run in parallel. Please set this option according your host CPU cores number.
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"
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 - putIMAGE_INSTALL
tolocal.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.
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 forqemuarm
machine). -
rpi-sdimg
- raspberry pi SD card image (default option forrpi
machine).
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 aftermultistrap
has unpacked the base system packages. It is designed to finalize filesystem, for example to addfstab
according to machine hardware configuration. The script should be placed tofiles
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.
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 byIsar
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 oframdisk
binary. The meaning of this variable is similar toKERNEL_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.
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.
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.
As already mentioned above, isar
uses bitbake
to 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"
Isar
contains two image type classes, that can be used for reference:
ext4-img
rpi-sdimg
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 foldermeta-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 checkbitbake
user manual for supported download formats. -
SRC_DIR
- the folder name where application sources will be unpacked. Forgit
repository the folder should be set togit
. Please checkbitbake
user manual for supported download formats. -
SRC_REV
- the source code revision to fetch. Please checkbitbake
user manual for supported download formats.
The last line in the example above adds recipe to isar
work chain.