path: root/distribution/yocto-advanced/pres_yocto-advanced.tex

\input{configpres}

\title{YOCTO - Advanced}
\maketitle

\begin{frame}
\frametitle{Agenda}
\begin{itemize}
\item Using BSP layers (sabrelite)
\item Build a predefined image (sabrelite)
\item Creating a layer
\item Define a distribution
\item Create an image
\item Writing recipes
\item Yocto \& ELBE combined
\end{itemize}
\end{frame}

\subsection{Using BSP layers}

\begin{frame}[fragile]
\frametitle{folder layout}
\begin{verbatim}
meta-mylayer
+ conf
|  + layer.conf
+ classes
|  + class1.bbclass
|  + class2.bbclass
+ recipes-category1
|  + package-1
|      + package-1.bb
|  + package-2
|      + package-2.bb
+ recipes-category2
| ..
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
	\frametitle{meta-*/conf/layer.conf}
	each layer needs a configuration file
	\begin{itemize}
		\item add conf and class directories to BBPATH
			\begin{verbatim}BBPATH =. "${LAYERDIR}"\end{verbatim}
		\pause
		\item add recipe directories to BBFILES
			\begin{verbatim}BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
			${LAYERDIR}/recipes-*/*/*.bbappend"\end{verbatim}
		\pause
		\item add layer name to BBFILE\_COLLECTIONS
			\begin{verbatim}BBFILE_COLLECTIONS += "mylayer"\end{verbatim}
		\pause
		\item set root of the layer
			\begin{verbatim}BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"\end{verbatim}
		\pause
		\item set default priority of the layer
			\begin{verbatim}BBFILE_PRIORITY_mylayer = "5"\end{verbatim}
		\pause
		\item set version of layer (only increment if dependencies with other
			layers are affected)
			\begin{verbatim}LAYERVERSION_mylayer = "2"\end{verbatim}
		\pause
		\item set dependencies to other layers
			\begin{verbatim}LAYERDEPENDS_mylayer = "meta-yocto"\end{verbatim}
	\end{itemize}
\end{frame}

\begin{frame}
\frametitle{bitbake-layers}
is useful to debug relations between different layers, options are:
\begin{description}
\item [show-layers] shows the current configured layers
\item [show-recipes] lists available recipes and the layers that provide them.
\item [show-overlayed] lists overlayed recipes
\item [show-appends] lists .bbappend files
	and the recipe files to which they apply
\item [show-cross-depends] lists dependency relationships
	between recipes that cross layer boundaries
\item [flatten] flattens the layer configuration
	into a separate output directory.
\end{description}
\end{frame}

\begin{frame}
\frametitle{definitions}
\begin{itemize}
	\item It is possible for a recipe with a lower version number PV in a layer
that has a higher priority to take precedence.
	\item Also, the layer priority does not currently affect the precedence
order of .conf or .bbclass files. Future versions of BitBake might address this.
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{get an existing layer}
retrive the layer from your BSP/SoC vendor
\begin{verbatim}
poky % git clone -b daisy https://github.com/Freescale/meta-fsl-arm-extra
\end{verbatim}
have a look at it's dependencies
\begin{verbatim}
poky % cat meta-fsl-arm-extra/conf/layer.conf | grep LAYERDEPENDS
LAYERDEPENDS_fsl-arm-extra = "core fsl-arm"
\end{verbatim}
and retrieve them also
\begin{verbatim}
poky % git clone -b daisy git://git.yoctoproject.org/meta-fsl-arm
\end{verbatim}
check dependencies again
\begin{verbatim}
poky % cat meta-fsl-arm/conf/layer.conf | grep LAYERDEPENDS
\end{verbatim}
\dots no more dependencies?! \dots OK - finished.
\end{frame}

\begin{frame}[fragile]
\frametitle{generate a new build environment}
\begin{verbatim}
poky % . oe-init-build-env build-fsl
poky/build-fsl %
\end{verbatim}
\end{frame}

\subsection{Build a predefined image}
\begin{frame}
\frametitle{overview}
builds are configured using two configuration files
\begin{itemize}
	\item build-fsl/conf/bblayers.conf
	\item build-fsl/conf/local.conf
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{bblayers.conf}
additional layers are added with absolute! path to the BBLAYERS variable
\begin{verbatim}
BBLAYERS ?= " \
  /home/devel/poky/meta \
  /home/devel/poky/meta-yocto \
  /home/devel/poky/meta-yocto-bsp \
  "
\end{verbatim}
\pause
\begin{verbatim}
% bitbake-layers show-layers
layer                 path                                  priority
=====================================================================
meta                  /home/devel/poky/meta                 5
meta-yocto            /home/devel/poky/meta-yocto           5
meta-yocto-bsp        /home/devel/poky/meta-yocto-bsp       5
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{add fsl layers}
modify the BBLAYERS variable in bblayers.conf
\begin{verbatim}
BBLAYERS ?= " \
  /home/devel/poky/meta \
  /home/devel/poky/meta-yocto \
  /home/devel/poky/meta-yocto-bsp \
  /home/devel/poky/meta-fsl-arm \
  /home/devel/poky/meta-fsl-arm-extra \
  "
\end{verbatim}
\pause
\begin{verbatim}
% bitbake-layers show-layers
layer                 path                                  priority
=====================================================================
meta                  /home/devel/poky/meta                 5
meta-yocto            /home/devel/poky/meta-yocto           5
meta-yocto-bsp        /home/devel/poky/meta-yocto-bsp       5
meta-fsl-arm          /home/devel/poky/meta-fsl-arm         5
meta-fsl-arm-extra    /home/devel/poky/meta-fsl-arm-extra   4
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{overlayed recipes}
to see which recipes replace official ones:
\begin{verbatim}
poky/build-fsl % bitbake-layers show-overlayed
Parsing recipes..done.
=== Overlayed recipes ===
directfb:
  meta                 1.7.1
  meta-fsl-arm         1.6.3
directfb-examples:
  meta                 1.7.0
  meta-fsl-arm         1.6.0
xserver-xorg:
  meta                 2:1.15.0
  meta-fsl-arm         2:1.14.4
\end{verbatim}
\end{frame}

\begin{frame}
\frametitle{local.conf}
is used to configure
\begin{itemize}
	\item the target machine
	\item paths
	\item the used distribution
	\item package formats
	\item arch of developer machine
	\item additional image features
	\item use additional classes
	\item enable testing
	\item devshell terminal
	\item patch resolver
	\item disk monitoring
	\item sstate mirrors
	\item qemu configuration
	\item incompatible licenses, e.g. INCOMPATIBLE\_LICENSE = “GPLv3”
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{configure the machine}
to get a list of currently available machines configs:
\begin{verbatim}
poky/build-fsl % grep -r '@NAME' ../meta*/conf/machine
\end{verbatim}
imx6qsabrelite.conf - seems to be the one for our bord, so set
\begin{verbatim}
MACHINE ??= "imx6qsabrelite"
\end{verbatim}
in conf/local.conf
\end{frame}

\begin{frame}[fragile]
\frametitle{package format}
as we realized with toaster, rpm packaging consumes a lot of CPU time, so lets
try ipk, by setting
\begin{verbatim}
PACKAGE_CLASSES ?= "package_ipk"
\end{verbatim}
in conf/local.conf
\end{frame}

\begin{frame}[fragile]
\frametitle{set extra image features}
we want an image suitable for development, so set
\begin{verbatim}
EXTRA_IMAGE_FEATURES = "debug-tweaks tools-debug eclipse-debug tools-profile"
\end{verbatim}
in conf/local.conf
\end{frame}

\begin{frame}[fragile]
\frametitle{build an predefined image}
use
\begin{verbatim}
ls ../*/*/images/
\end{verbatim}
to get a list of predefined images; however none of them fits my needs\dots
\begin{verbatim}
poky/build-fsl % cd ..
poky % git clone -b daisy https://github.com/Freescale/meta-fsl-demos.git
poky % git clone -b daisy git://git.openembedded.org/meta-openembedded
poky % cd -
\end{verbatim}
and edit conf/bblayers.conf, to match
\begin{verbatim}
BBLAYERS ?= " \
  /home/devel/poky/meta \
  /home/devel/poky/meta-yocto \
  /home/devel/poky/meta-yocto-bsp \
  /home/devel/poky/meta-fsl-arm \
  /home/devel/poky/meta-fsl-arm-extra \
  /home/devel/poky/meta-openembedded/meta-oe \
  /home/devel/poky/meta-fsl-demos \
  "
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{build a fsl demo image}
\begin{verbatim}
poky/build-fsl % source toaster start
poky/build-fsl % bitbake qt-in-use-image
Currently 4 running tasks (26 of 4459):
\end{verbatim}
\dots coffee break!
\end{frame}

\begin{frame}[fragile]
\frametitle{build a fsl demo image}
\dots back from coffee break
\begin{verbatim}
ERROR: No new tasks can be executed since the disk space monitor action is
"STOPTASKS"!
\end{verbatim}
what happened??
\begin{verbatim}
poky/build-fsl % df -h
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda4       367G  348G  850M 100% /
poky/build-fsl % du -sm .
31026   .
poky/build-fsl % du -sm ../build
29172   ../build/
\end{verbatim}
\dots so the solution is to cleanup the disk and run
\begin{verbatim}
poky/build-fsl % bitbake qt-in-use-image
\end{verbatim}
again.
\end{frame}

\begin{frame}[fragile]
\frametitle{build a fsl demo image}
\dots one more error
\begin{verbatim}
ERROR: To use 'gpu-viv-bin-mx6q' you need to accept the Freescale EULA
at '/home/local/src/poky/meta-fsl-arm/EULA'. Please read it and in case
you accept it, write: ACCEPT_FSL_EULA = "1" in your local.conf.
ERROR: Function failed: do_unpack
ERROR: Logfile of failure stored in: /home/local/src/poky/build-fsl/tmp
/work/cortexa9hf-vfp-neon-mx6-poky-linux-gnueabi/gpu-viv-bin-mx6q/1_3.1
0.17-1.0.0-hfp-r0/temp/log.do_unpack.6795
ERROR: Task 1105 (/home/local/src/poky/meta-fsl-arm/recipes-graphics/gp
u-viv-bin-mx6q/gpu-viv-bin-mx6q_3.10.17-1.0.0-hfp.bb, do_unpack) failed
with exit code '1'
\end{verbatim}
to solve this issue:
\begin{verbatim}
poky/build-fsl % echo 'ACCEPT\_FSL\_EULA = "1"' >> conf/local.conf
\end{verbatim}
\dots and run
\begin{verbatim}
poky/build-fsl % bitbake qt-in-use-image
\end{verbatim}
again.
\end{frame}

\begin{frame}[fragile]
\frametitle{flashing the image}
if the build is completed the image can be transfered to a sdcard:
\begin{verbatim}
poky/build-fsl % sudo dd \
if=tmp/deploy/images/imx6qsabrelite/qt-in-use-image-imx6qsabrelite.sdcard \
of=/dev/mmcblk0 bs=1M
412+0 records in
412+0 records out
432013312 bytes (432 MB) copied, 90.4824 s, 4.8 MB/s
\end{verbatim}
\end{frame}

\subsection{Creating a layer}
\begin{frame}[fragile]
\frametitle{with yocto helper script}
\begin{verbatim}
poky/build-fsl % cd ..
poky % yocto-layer create linutronix
Please enter the layer priority you'd like to use for the layer: [default: 6]
<return>
Would you like to have an example recipe created? (y/n) [default: n]
<return>
Would you like to have an example bbappend file created? (y/n) [default: n]
<return>
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{manage the layer with git}
\begin{verbatim}
poky % cd meta-linutronix
poky/meta-linutronix % git init .
poky/meta-linutronix % git add *
poky/meta-linutronix % git commit -sam 'inital version'
\end{verbatim}
\end{frame}

\subsection{Define a distribution}
\begin{frame}
\frametitle{why define a distribution?}
\begin{itemize}
\item naming of the toolchain (codenames, vendor)
\item version numbers
\item enable default features
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{distro features: file-systems}
\begin{description}
\item[cramfs] CramFS support
\item[ext2] tools for supporting for devices with internal HDD/Microdrive
	for storing files (instead of Flash only devices)
\item[nfs] NFS client support (for mounting NFS exports on device)
\item[smbfs] SMB networks client support
	(for mounting Samba/Microsoft Windows shares on device)
\end{description}
\end{frame}

\begin{frame}
\frametitle{distro features: hardware support}
\begin{description}
\item[alsa] ALSA/sound support
	(OSS compatibility kernel modules installed if available)
\item[bluetooth] bluetooth support (integrated BT only)
\item[irda] IrDA support
\item[wifi] WiFi support (integrated only).
\item[keyboard] keyboard support (e.g. keymaps will be loaded during boot)
\end{description}
\end{frame}

\begin{frame}
\frametitle{distro features: grahpics}
\begin{description}
\item[opengl] the Open Graphics Library, which is a cross-language,
	multi-platform application programming interface used for rendering two
	and three-dimensional graphics
\item[directfb] DirectFB support
\end{description}
\end{frame}

\begin{frame}
\frametitle{distro features: networking}
\begin{description}
\item[ipsec] IPSec support
\item[ipv6] IPv6 support
\item[ppp] PPP dialup support
\end{description}
\end{frame}

\begin{frame}
\frametitle{distro features: bus support}
\begin{description}
\item[pci] PCI bus support
\item[pcmcia] PCMCIA/CompactFlash support
\item[usbgadget] USB Gadget Device support (for USB networking/serial/storage)
\item[usbhost] USB Host support
	(allows to connect external keyboard, mouse, storage, network etc)
\end{description}
\end{frame}

\begin{frame}
\frametitle{distro features: software}
\begin{description}
\item[systemd] support for this init manager, which is a full replacement of
	for init with parallel starting of services, reduced shell overhead,
	and other features. This init manager is used by many distributions
\item[wayland] the Wayland display server protocol
	and the library that supports it
\item[x11] X server and libraries
\end{description}
\end{frame}

\begin{frame}[fragile]
\frametitle{use a DISTRO\_FEATURE}
Normally the distro features are used in package groups in a core layer.
e.g. 'meta/recipes-core/packagegroups/packagegroup-base.bb':
\begin{verbatim}
PACKAGES = ' \
	..
	${@base_contains("DISTRO_FEATURES", "opengl", "packagegroup-opengl", "", d)} \
	..
	'
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{exkurs: package groups}
are recipes that are used to group packages together:
\begin{verbatim}
DESCRIPTION = “My Package Group”
LICENSE = “MIT”
LIC_FILES_CHECKSUM = “file://<licfile>;md5=<chksum>
inherit packagegroup
PROVIDES = “${PACKAGES}”
PACKAGES = “packagegroup-mypkg-apps packagegroup-mypkg-tools”
RDEPENDS_packagegroup-mypkg-apps = “sqlite3 python-core python-sqlite3”
RDEPENDS_pacakgegroup-mypkg-tools = “sudo gzip tar”
\end{verbatim}
it can be used, to simplify image definitions
\end{frame}

\begin{frame}[fragile]
\frametitle{linutronix distribution}
distros are defined in a layer, e.g.
meta-linutronix/conf/distro/linutronix.conf:
\begin{verbatim}
DISTRO = "linutronix"
DISTRO_NAME = "linutronix 1.0 (for foo devices)"
DISTRO_VERSION = "1.0"
DISTRO_CODENAME = "bar"
SDK_VENDOR = "-linutronix"
SDK_VERSION := "${@'${DISTRO_VERSION}'}"
MAINTAINER = "Manuel Traut <manut@linutronix.de>"
TARGET_VENDOR = "-linutronix"
LOCALCONF_VERSION = "1"
LAYER_CONF_VERSION ?= "6"
DISTRO_FEATURES_append = " opengl"
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{add distro to git repo}
\begin{verbatim}
poky/meta-linutronix % git add conf/distro/linutronix.conf
poky/meta-linutronix % git commit -sam 'add linutronix distro'
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{enable linutronix layer}
\begin{verbatim}
poky/meta-linutronix % cd ../build-fsl
poky/build-fsl % edit conf/bblayers.conf
\end{verbatim}
to match
\begin{verbatim}
BBLAYERS ?= " \
  /home/local/src/poky/meta \
  /home/local/src/poky/meta-yocto \
  /home/local/src/poky/meta-yocto-bsp \
  /home/local/src/poky/meta-fsl-arm \
  /home/local/src/poky/meta-fsl-arm-extra \
  /home/local/src/poky/meta-openembedded/meta-oe \
  /home/local/src/poky/meta-fsl-demos \
  /home/local/src/poky/meta-linutronix \
  "
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{use linutronix distro}
edit DISTRO var in conf/local.conf
\begin{verbatim}
DISTRO ?= "linutronix"
\end{verbatim}
\end{frame}

\subsection{Creating images}
\begin{frame}[fragile]
\frametitle{based on core-image class}
\begin{verbatim}
poky/build-fsl % bitbake-layers show-recipes | grep ssh
Parsing recipes..done.
libssh:
openssh:
packagegroup-core-ssh-dropbear:
packagegroup-core-ssh-openssh:
\end{verbatim}
create the file
'meta-linutronix/recipes-bsp/linutronix-image/linutronix-image.bb'
\begin{verbatim}
IMAGE_INSTALL += "openssh"
inherit core-image
\end{verbatim}
to build the image, use:
\begin{verbatim}
poky/build-fsl % bitbake linutronix-image
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
	\frametitle{image features}
t.b.d. use IMAGE\_FEATURES
% http://www.yoctoproject.org/docs/1.6/ref-manual/ref-manual.html#ref-features-image

% http://www.yoctoproject.org/docs/1.6/dev-manual/dev-manual.html#usingpoky-extend-customimage-imagefeatures
\end{frame}

\subsection{Writing recipes}
\begin{frame}[fragile]
\frametitle{adding a kernel}
create the file 'meta-linutronix/recipes-bsp/linux-sabrelite/linux-sabrelite\_3.16.bb':
\begin{verbatim}
SECTION = "kernel"
DESCRIPTION = "Linux 3.16 for sabrelite"
LICENSE = "GPLv2"
KERNEL_IMAGETYPE = "uImage"

inherit kernel
require recipes-kernel/linux/linux-dtb.inc
require recipes-kernel/linux/setup-defconfig.inc

COMPATILBE_MACHINE = "imx6qsabrelite"
KERNEL_DEVICETREE_imx6qsabrelite = "arch/arm/boot/dts/imx6q-sabrelite.dts"

S = "${WORKDIR}/git
BRANCH = "master"
SRCREV = "19583ca584d6f574384e17fe7613dfaeadcdc4a6"
PV = "3.16"
# cause a rebuild on new kernel version
MACHINE_KERNEL_PR_append = "d+gitr${SRCPV}"
SRC_URI = " \
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux;protocol=git;branch=${BRANCH} \
file://defconfig \
"
KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
# to modify cmdline, use APPEND += ""
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{adding a defconfig}
copy your .config file to
'meta-linutronix/recipes-bsp/linux-sabrelite/files/imx6qsabrelite/defconfig'
\end{frame}

\begin{frame}[fragile]
\frametitle{using a specific kernel}
add
\begin{verbatim}
PREFERRED_PROVIDER_virtual/kernel = "linux-sabrelite"
\end{verbatim}
to meta-linutronix/conf/distro/linutronix.conf
\end{frame}

\begin{frame}[fragile]
\frametitle{Providers}
\begin{verbatim}
--8<- -my-kernel\_3.16.bb --
PROVIDES += "virtual/kernel"
--8<------------------------
\end{verbatim}

PREFERRED\_PROVIDER\_virtual/kernel = "linux-yocto"


\pause
\vspace{2em}
also a preferred version can be set:

PREFERRED\_VERSION\_virtual/kernel = "3.16"
\end{frame}

\begin{frame}
\frametitle{Preferences}
\begin{itemize}
\item by default, files have a preference of "0"
\item setting DEFAULT\_PREFERENCE to "-1" makes the recipe unlikely to be used
	unless it is explicitly referenced.
\item setting DEFAULT\_PREFERENCE to "1" makes it likely the recipe is used
\item PREFERRED\_VERSION overrides any DEFAULT\_PREFERENCE setting
\end{itemize}
\end{frame}

\begin{frame}
\frametitle{adding an own application}
\begin{itemize}
	\item recipe already available? check http://layers.openembedded.org
	\item look for a similar recipe
	\item proper bbclass available?
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{as simple as posible}
use this folder layout
\begin{verbatim}
poky/meta-linutronix/recipes-hello % tree
hello
├── files
│   └── hello.c
└── hello.bb
\end{verbatim}
\end{frame}

\begin{frame}[fragile]
\frametitle{as simple as posible \#2}
this is the content of hello.bb
\begin{verbatim}
DESCRIPTION = "Simple helloworld application"
SECTION = "examples"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda
2f7b4f302"
PR = "r0"
SRC_URI = "file://hello.c"
S = "${WORKDIR}"

do_compile() {
  ${CC} hello.c -o hello
}

do_install() {
  install -d ${D}${bindir}
  install -m 0755 hello ${D}${bindir}
}
\end{verbatim}
\end{frame}


\begin{frame}
\frametitle{use PR Service}
bla
\end{frame}

\begin{frame}
\frametitle{adding a bootscript}
bla
\end{frame}

\begin{frame}[fragile]
\frametitle{user and group configuration}
use this in an image recipe:
\begin{verbatim}
inherit extrausers
EXTRA_USERS_PARAMS = "\
    useradd -p '' tester; \
    groupadd developers; \
    userdel nobody; \
    groupdel -g video; \
    groupmod -g 1020 developers; \
    usermod -s /bin/sh tester; \
    "
\end{verbatim}
or the useradd class, for an example see useradd-example.bb
\end{frame}

\begin{frame}[fragile]
\frametitle{external sources}
e.g. for a heavily customized kernel
\begin{itemize}
\item kernel source directory on the development machine
\item inherit externalsrc class
\item set EXTERNALSRC variable to point to your external source code
\end{itemize}

this local.conf extension:
\begin{verbatim}
INHERIT += "externalsrc"
EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
\end{verbatim}
overrides the SOURCE\_URI of pn-myrecipe.bb
\end{frame}

\begin{frame}[fragile]
\frametitle{blacklist packages}
To blacklist a package, inherit the blacklist.bbclass globally and set
PNBLACKLIST for each recipe you wish to blacklist.


Specify the PN value as a variable flag (varflag) and provide a reason,
which is reported, if the package is requested to be built as the value:
\begin{verbatim}
INHERIT += "blacklist"
PNBLACKLIST[exoticware] = "Not supported by our organization."
\end{verbatim}
\end{frame}

\subsection{Yocto \& ELBE}
\begin{frame}
\frametitle{Yocto \& ELBE combined}
	bla
\end{frame}

\input{tailpres}