\documentclass[obeyspaces,spaces,hyphens]{beamer}
\usepackage[utf8]{inputenc}
\usepackage{minted}

\mode<presentation>
\usetheme{Bootlin}

\newcommand{\codehack}[1]{{\usebeamercolor[fg]{code} {\tt #1}}}

\title{Starting with the Yocto Project}
\authors{Alexandre Belloni}
\institute{Bootlin}

\usepackage{hyperref}

\begin{document}

\begin{frame}{FOSDEM 2015}
  \begin{columns}[c]
   \column{0.6\textwidth}
     \huge
     Starting with the Yocto Project\\
     \vspace{2cm}
     \normalsize
     Alexandre Belloni\\
     {\bf Bootlin}\\
     {\em alexandre.belloni@bootlin.com}
     \column{0.4\textwidth}
     \includegraphics[width=\textwidth]{yocto-project-transp.png}
   \end{columns}
   \vfill
   Put your business card in the box to participate in the raffle!
\end{frame}

\begin{frame}{Alexandre Belloni}
  \begin{columns}
    \column{0.7\textwidth}
    \begin{itemize}
      \item Embedded Linux engineer at {\bf Bootlin}
        \begin{itemize}
          \item Embedded Linux {\bf expertise}
          \item {\bf Development}, consulting and training
          \item Strong open-source focus
        \end{itemize}
      \item Open-source contributor
        \begin{itemize}
          \item Contributing the {\bf kernel support for Atmel ARM
            processors}
          \item Contributing the {\bf kernel support for Marvell
            ARM (Berlin) processors}
          \item Maintainer of the Crystalfontz boards in the {\bf
            meta-fsl-arm} layer
        \end{itemize}
    \end{itemize}
    \column{0.3\textwidth}
    \includegraphics[width=\textwidth]{common/logo-square.pdf}
  \end{columns}
\end{frame}

\begin{frame}{What is the Yocto Project ?}
  \begin{itemize}
    \item Umbrella project, including:
      \begin{itemize}
        \item pseudo
        \item cross-prelink
        \item matchbox
        \item opkg
        \item psplash
        \item ...
      \end{itemize}
    \item The core components of the Yocto Project are:
      \begin{itemize}
        \item BitBake, the {\em build engine}. It is a task scheduler,
          like \code{make}. It interprets configuration files and
          recipes (also called {\em metadata}) to perform a set of
          tasks, to download, configure and build specified packages and
          filesystem images.
        \item OpenEmbedded-Core, a set of base {\em layers}. It is a set
          of recipes, layers and classes which are shared between all
          OpenEmbedded based systems.
        \item Poky, the {\em reference system}. It is a collection of
          projects and tools, used to bootstrap a new distribution based
          on the Yocto Project.
      \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{The Yocto Project lexicon}
  \begin{center}
    \includegraphics[width=\textwidth]{yocto-project-overview.pdf}
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{The Yocto Project lexicon}
  \begin{itemize}
    \item Organization of OpenEmbedded-Core:
    \begin{itemize}
      \item {\em Recipes} describe how to fetch, configure, compile
        and package applications and images. They have a specific
        syntax.
      \item {\em Layers} are sets of recipes, matching a common
        purpose. For Texas Instruments board support, the {\em
        meta-ti} layer is used.
      \item Multiple layers are used within a same distribution,
        depending on the requirements.
      \item It supports the ARM, MIPS (32 and 64 bits), PowerPC and
        x86 (32 and 64 bits) architectures.
      \item It supports QEMU emulated machines for these architectures.
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Building an image}
  \huge
  \begin{center}
    Building an image
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{Environment setup}
  \begin{itemize}
    \item All Poky files are left unchanged when building a custom
      image.
    \item Specific configuration files and build repositories are
      stored in a separate build directory.
    \item A script, \code {oe-init-build-env}, is provided to set up
      the build directory and the environment variables (needed to be
      able to use the \code{bitbake} command for example).
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{oe-init-build-env}
  \begin{itemize}
    \item Modifies the environment: has to be sourced!
    \item Adds environment variables, used by the build engine.
    \item Allows you to use commands provided in Poky.
    \item \code{source ./oe-init-build-env [builddir]}
    \item Sets up a basic build directory, named \code{builddir} if it
      is not found. If not provided, the default name is \code{build}.
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Common targets}
  \begin{itemize}
    \item Common targets are listed when sourcing the script:
      \begin{description}[style=nextline]
        \item[core-image-minimal] A small image to boot a device and
          have access to core command line commands and services.
        \item[core-image-sato] Image with Sato support. Sato is a
          GNOME mobile-based user interface.
        \item[meta-toolchain] Includes development headers and
          libraries to develop directly on the target.
        \item[adt-installer] Build the application development toolkit
          installer.
        \item[meta-ide-support] Generates the cross-toolchain. Useful
          when working with the SDK.
      \end{description}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{The \code{build/conf/} directory}
  \begin{itemize}
    \item The \code{conf/} directory in \code{build} holds 
      build specific configuration.
    \begin{description}
      \item[bblayers.conf] Explicitly list the available layers.
      \item[local.conf] Set up the configuration variables relative to
        the current user for the build. Configuration variables can be
        overridden there.
    \end{description}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Configuring the build}
  \begin{itemize}
    \item The \code{conf/local.conf} configuration file holds local
    user configuration variables:
    \begin{description}
      \item[BB\_NUMBER\_THREADS] How many tasks BitBake should perform
        in parallel.
      \item[PARALLEL\_MAKE] How many processes should be used when
        compiling.
      \item[MACHINE] The machine the target is built for, e.g.
        \code{beaglebone}.
      \item[PACKAGE\_CLASSES] Packages format (\code{deb}, \code{ipk}
        or \code{rpm}).
    \end{description}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Compilation}
  \begin{itemize}
    \item The compilation is handled by the BitBake {\em build
      engine}.
    \item Usage: \code{bitbake [options] [recipename/target ...]}
    \item To build a target: \code{bitbake [target]}
    \item Building a minimal image: \code{bitbake core-image-minimal}
    \begin{itemize}
      \item This will run a full build for the selected target.
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Results}
  \begin{description}
    \item[tmp/buildstats/] Build statistics for all packages built
      (CPU usage, elapsed time, host, timestamps\dots).
    \item[tmp/deploy/] Final output of the build.
    \item[tmp/deploy/images/] Contains the complete images built by
      the OpenEmbedded build system. These images are used to flash
      the target.
    \item[tmp/work/] Set of specific work directories, split by
      architecture. They are used to unpack, configure and build the
      packages. Contains the patched sources, generated objects and
      logs.
    \item[tmp/sysroots/] Shared libraries and headers used to compile
      packages for the target but also for the host.
  \end{description}
\end{frame}

\begin{frame}[fragile]{Summary}
  \begin{itemize}
    \item Initialize the build environment
      \begin{block}{}
      \begin{minted}{console}
$ source poky/oe-init-build-env build
      \end{minted}
      \end{block}
    \item Configure your \code{local.conf}
      \begin{block}{}
      \begin{minted}{console}
BB_NUMBER_THREADS = "16"
PARALLEL_MAKE = "-j 16"
MACHINE ?= "imx28evk"
      \end{minted}
      \end{block}
    \item build the image
      \begin{block}{}
      \begin{minted}{console}
$ bitbake core-image-minimal
      \end{minted}
      \end{block}
  \end{itemize}
\end{frame}

\begin{frame}{Layers}
  \huge
  \begin{center}
    Layers
  \end{center}
\end{frame}

\begin{frame}{Layer creation}
  To make modifications, it is necessary to create a new layer:
  \begin{itemize}
    \item create a \code{meta-<machine>} directory
    \item inside that directory, create a \code{conf/layer.conf} file
  \end{itemize}
  Alternatively, you could use:
  \begin{itemize}
    \item \code{yocto-layer create} and select a high priority
    \item or \code{yocto-bsp create}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\code{conf/layer.conf}}
  \begin{block}{}
  \begin{minted}{c}
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"

BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
    ${LAYERDIR}/recipes-*/*/*.bbappend"

BBFILE_COLLECTIONS += "crystalfontz"
BBFILE_PATTERN_crystalfontz := "^${LAYERDIR}/"
BBFILE_PRIORITY_crystalfontz = "10"

LAYERDEPENDS_crystalfontz = "fsl-arm fsl-arm-extra"
  \end{minted}
  \end{block}
\end{frame}

\begin{frame}[fragile]{Adding the layer to the build}
  \begin{itemize}
    \item The main drawback of having a layer separate from your
      silicon vendor is that your customers will have to add it to
      their configuration to use it.
    \item That configuration is done in
      \code{<builddir>/conf/bblayers.conf}. Add your layer to the
      \code{BBLAYERS} variable:
      \begin{block}{}
        \begin{minted}{c}
BBLAYERS += "${BSPDIR}/sources/meta-crystalfontz "
        \end{minted}
      \end{block}
  \end{itemize}
\end{frame}

\begin{frame}{Recipes}
  \huge
  \begin{center}
    Recipes
  \end{center}
\end{frame}

\begin{frame}{Recipes}
  \begin{center}
    \includegraphics[width=\textwidth]{yocto-recipe-basics-overview.pdf}
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{Basics}
  \begin{itemize}
    \item Recipes describe how to handle a given package.
    \item A recipe is a set of instructions to describe how to
      retrieve, patch, compile, install and generate binary packages
      for a given application.
    \item It also defines what build or runtime dependencies are
      required.
    \item The recipes are parsed by BitBake
    \item The format of a recipe file name is
      \code{<package-name>_<version>.bb}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Content of a recipe}
  \begin{itemize}
    \item A recipe contains configuration variables: name, license,
      dependencies, path to retrieve the source code\dots
    \item It also contains functions that can be run (fetch,
      configure, compile\dots) which are called {\bf tasks}.
    \item Tasks provide a set of actions to perform.
    \item \code{bitbake -c <task> <package>}
  \end{itemize}
\end{frame}

\begin{frame}{Organization of a recipe}
  \begin{center}
    \includegraphics[width=\textwidth]{yocto-recipe-basics-organisation.pdf}
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{Organization of a recipe}
  \begin{itemize}
    \item Many packages have more than one recipe, to support
      different versions. In that case the common metadata is
      included in each version specific recipe and is in a \code{.inc}
      file:
      \begin{itemize}
        \item \code{<package>.inc}: version agnostic metadata.
        \item \code{<package>_<version>.bb}: \code{require
          <package>.inc} and version specific metadata.
      \end{itemize}
    \item We can divide a recipe into three main parts:
      \begin{itemize}
        \item The header: what/who
        \item The sources: where
        \item The tasks: how
      \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{The header}
  \begin{itemize}
    \item Configuration variables to describe the package:
      \begin{description}
        \item[DESCRIPTION] describes what the software is about
        \item[HOMEPAGE] URL to the project's homepage
        \item[PRIORITY] defaults to \code{optional}
        \item[SECTION] package category (e.g. \code{console/utils})
        \item[LICENSE] the package's license
      \end{description}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{The source locations}
  \begin{itemize}
    \item We need to retrieve both the raw sources from an official
      location and the resources needed to configure, patch or install
      the package.
    \item \code{SRC_URI} defines where and how to retrieve the
      needed elements. It is a set of URI schemes pointing to the
      resource locations (local or remote).
    \item For the local files, the searched paths are defined in the
      \code{FILESPATH} variable, custom ones can be added using
      \code{FILESEXTRAPATHS}. BitBake will also search in subfolders
      listed in the \code{OVERRIDES} variables in those paths.
    \item Files ending in \code{.patch}, \code{.diff} or having the
      \code{apply=yes} parameter will be applied after the sources are
      retrieved and extracted.
    \item Patches are applied in the order they are found.
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Dependencies}
  \begin{itemize}
    \item A package can have dependencies during the build or at
          runtime. To reflect these requirements in the recipe, two
          variables are used:
    \begin{description}
      \item[DEPENDS] List of the package build-time dependencies.
      \item[RDEPENDS] List of the package runtime
        dependencies. Must be package specific (e.g. with
        \code{_${PN}}).
    \end{description}
    \item \code{DEPENDS = "package_b"}: the local \code{do_configure}
      task depends on the \code{do_populate_sysroot} task of package
      b.
    \item \code{RDEPENDS_${PN} = "package_b"}: the local
      \code{do_build} task depends on the
      \code{do_package_write_<archive-format>} task of package b.
  \end{itemize}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Tasks}
  Default tasks already exists, they are defined in classes:
  \begin{itemize}
    \item do\_fetch
    \item do\_unpack
    \item do\_patch
    \item do\_configure
    \item do\_compile
    \item do\_install
    \item do\_package
    \item do\_rootfs
  \end{itemize}
  You can get a list of existing tasks for a recipe with:
  \code{bitbake <recipe> -c listtasks}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Writing tasks 1/3}
  \begin{itemize}
    \item Functions use the sh shell syntax, with available
      OpenEmbedded variables and internal functions available.
      \begin{description}
        \item[D] The destination directory (root directory of where
          the files are installed, before creating the image).
        \item[WORKDIR] the package's working directory
      \end{description}
    \item Syntax of a task:
  \end{itemize}
  \begin{block}{}
    \begin{minted}{c}
do_task() {
    action0
    action1
    ...
}
    \end{minted}
  \end{block}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Writing tasks 2/3}
  \begin{itemize}
    \item Example:
  \end{itemize}
  \begin{block}{}
    \begin{minted}[fontsize=\small]{c}
do_compile() {
    ${CC} ${CFLAGS} ${LDFLAGS} -o hello ${WORKDIR}/hello.c
}

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

\begin{frame}[fragile]
  \frametitle{Writing tasks 3/3}
  \begin{itemize}
    \item Or using a Makefile:
  \end{itemize}
  \begin{block}{}
    \begin{minted}{c}
do_compile() {
    oe_runmake
}

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

\begin{frame}[fragile]
  \frametitle{Adding new tasks}
  Tasks can be added with \code{addtask}
  \begin{block}{}
    \begin{minted}{c}
do_mkimage () {
    uboot-mkimage ...
}

addtask mkimage after do_compile before do_install
    \end{minted}
  \end{block}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Hello world recipe}
  \begin{block}{}
    \begin{minted}[fontsize=\small]{c}
DESCRIPTION = "Hello world program"
HOMEPAGE = "http://example.net/helloworld/"
PRIORITY = "optional"
SECTION = "examples"
LICENSE = "GPLv2"

SRC_URI = "file://hello.c"

do_compile() {
    ${CC} ${CFLAGS} ${LDFLAGS} -o hello ${WORKDIR}/hello.c
}

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

\begin{frame}{Extending a recipe}
  \huge
  \begin{center}
    Extending a recipe
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{Introduction to recipe extensions}
  \begin{itemize}
    \item It is a good practice {\bf not} to modify recipes available
          in Poky.
    \item But it is sometimes useful to modify an existing recipe, to
          apply a custom patch for example.
    \item The BitBake \emph{build engine} allows to modify a recipe by
          extending it.
    \item Multiple extensions can be applied to a recipe.
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Introduction to recipe extensions}
  \begin{itemize}
    \item Metadata can be changed, added or appended.
    \item Tasks can be added or appended.
    \item Operators are used extensively, to add, append, prepend or
          assign values.
  \end{itemize}
\end{frame}

\begin{frame}{Extend a recipe}
  \begin{center}
    \includegraphics[width=\textwidth]{yocto-recipe-advanced-extend.pdf}
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{Extend a recipe}
  \begin{itemize}
    \item The recipe extensions end in \code{.bbappend}
    \item Append files must have the same root name as the recipe they
          extend.
    \begin{itemize}
      \item \code{example_0.1.bbappend} applies to
            \code{example_0.1.bb}
    \end{itemize}
    \item Append files are {\bf version specific}. If the recipe is
          updated to a newer version, the append files must also be
          updated.
    \item If adding new files, the path to their directory must
          be prepended to the \code{FILESEXTRAPATHS} variable.
    \begin{itemize}
      \item Files are looked up in paths referenced in
            \code{FILESEXTRAPATHS}, from left to right.
      \item Prepending a path makes sure it has priority over the recipe's
            one. This allows to override recipes' files.
    \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]
  \frametitle{Hello world append file}
  \begin{block}{}
    \begin{minted}{c}
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

SRC_URI += "file://custom-modification-0.patch \
            file://custom-modification-1.patch \
            "
    \end{minted}
  \end{block}
\end{frame}

\begin{frame}[fragile]{Warning}
    You can find it in some recipes but don't use the following
    construct in \code{pkg_postinst}:
    \begin{block}{}
    \begin{minted}{c}
pkg_postinst_wpa-supplicant () {
      # If we're offline, we don't need to do this.
      if [ "x$D" != "x" ]; then
              exit 0
      fi

      killall -q -HUP dbus-daemon || true
}
    \end{minted}
    \end{block}
    It can't be extended using .bbappend
\end{frame}

\begin{frame}[fragile]
  \frametitle{Debugging recipes}
  \begin{itemize}
    \item For each task, logs are available in the \code{temp}
      directory in the work folder of a recipe.
    \item A development shell, exporting the full environment can be
      used to debug build failures:
      \begin{block}{}
        \begin{minted}{console}
$ bitbake -c devshell <recipe>
        \end{minted}
      \end{block}
    \item To understand what a change in a recipe implies, you can
      activate build history in \code{local.conf}:
      \begin{block}{}
        \begin{minted}{c}
INHERIT += "buildhistory"
BUILDHISTORY_COMMIT = "1"
        \end{minted}
      \end{block}
      Then use the \code{buildhistory-diff} tool to examine
      differences between two builds.
      \begin{itemize}
        \item \code{./scripts/buildhistory-diff}
      \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}{Images}
  \huge
  \begin{center}
    Images
  \end{center}
\end{frame}

\begin{frame}{Image recipes}
  \begin{itemize}
    \item an image recipe is used to define the content of the final
      image
    \item it is the entry point of the build and defines all the
      necessary packages through dependencies
    \item image recipes are usually in \code{recipes-*/images/}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\code{images/demo-image-cfa-mini.bb}}
  \footnotesize
  \begin{block}{}
  \begin{minted}{c}
DESCRIPTION = "Image for Crystalfontz boards"
LICENSE = "MIT"

IMAGE_INSTALL = "packagegroup-core-boot \
    ${ROOTFS_PKGMANAGE_BOOTSTRAP} \
    ${CORE_IMAGE_EXTRA_INSTALL}"

IMAGE_INSTALL += "init-ifupdown busybox-udhcpd iw"

IMAGE_INSTALL += "evtest tslib tslib-conf tslib-tests \
    tslib-calibrate"

IMAGE_LINGUAS = " "

inherit core-image
  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}{Image recipes}
  \begin{itemize}
    \item use \code{IMAGE_INSTALL} to specify which packages you need
      on your target
    \item you can use packagegroups, they are useful when needing
      features with complex dependencies
    \item inherit the base image class \code{core-image}
    \item you can also include already existing image recipes
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\code{images/demo-image-cfa.bb} (1)}
  \scriptsize
  \begin{block}{}
  \begin{minted}{c}
include recipes-sato/images/core-image-sato.bb

IMAGE_FEATURES += "debug-tweaks"
WEB = "web-webkit"

IMAGE_INSTALL += " linux-firmware init-ifupdown busybox-udhcpd"

# we don't need the full tools-testapps
IMAGE_INSTALL += " evtest tslib tslib-conf tslib-tests tslib-calibrate xev"
IMAGE_INSTALL += " iw connman-client"

EXTRA_IMAGE_FEATURES += " \
    nfs-server \
    qt4-pkgs \
"

# more debugging and profiling
EXTRA_IMAGE_FEATURES += " \
    tools-debug \
    tools-profile \
"

  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}[fragile]{\code{images/demo-image-cfa.bb} (2)}
  \scriptsize
  \begin{block}{}
  \begin{minted}{c}
IMAGE_INSTALL += " \
    cpufrequtils \
    nano \
    packagegroup-qt-in-use-demos \
    qt4-demos \
    qt4-examples \
    cfa-config-extra \
    "

export IMAGE_BASENAME = "demo-image-cfa"
  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}{Image recipes}
  \begin{description}
    \item[IMAGE\_FEATURES] The primary list of features to include in an image.
    \item[EXTRA\_IMAGE\_FEATURES] List of additional features to
      include in an image, typically to be put in your
      \code{local.conf} file.
  \end{description}
  Available features: dbg-pkgs, dev-pkgs, doc-pkgs, nfs-server,
  read-only-rootfs, splash, ssh-server-dropbear, ssh-server-openssh,
  staticdev-pkgs, tools-debug, tools-profile, tools-sdk,
  tools-testapps, x11, x11-base, x11-sato
\end{frame}

\begin{frame}[fragile]{Image tweaks}
  There is a mechanism to describe what functionalities are available
  on the target, the formfactor configuration file.
  \begin{itemize}
    \item extend it with a .bbappend: \code{recipes-bsp/formfactor/formfactor_0.0.bbappend}
  \begin{block}{}
  \begin{minted}{c}
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
  \end{minted}
  \end{block}
    \item it install a file named \code{machconfig}
  \end{itemize}
  \begin{block}{}
  \begin{minted}{console}
$ tree recipes-bsp/formfactor/
recipes-bsp/formfactor/
|-- formfactor
|   |-- cfa10057
|   |   `-- machconfig
|   `-- cfa10058
|       `-- machconfig
`-- formfactor_0.0.bbappend
  \end{minted}
  \end{block}
\end{frame}

\begin{frame}[fragile]{\code{cfa10058/machconfig}}
  \begin{block}{}
  \begin{minted}{c}
# Display options
HAVE_TOUCHSCREEN=1
  \end{minted}
  \end{block}
  Other available variables: \code{HAVE_KEYBOARD},
  \code{HAVE_KEYBOARD_PORTRAIT}, \code{HAVE_KEYBOARD_LANDSCAPE},
  \code{DISPLAY_CAN_ROTATE}, \code{DISPLAY_ORIENTATION},
  \code{DISPLAY_WIDTH_PIXELS}, \code{DISPLAY_HEIGHT_PIXELS},
  \code{DISPLAY_BPP}, \code{DISPLAY_WIDTH_MM},
  \code{DISPLAY_HEIGHT_MM}, \code{DISPLAY_SUBPIXEL_ORDER}.
\end{frame}

\begin{frame}[fragile]{Adding extra configuration}
  You can create a recipe to simply install a few configuration files
  in your final filesystem. This is what \code{cfa-config-extra} is
  doing:
  \code{recipes/cfa-config-extra/cfa-config-extra.bb}
  \tiny
  \begin{block}{}
  \begin{minted}{c}
DESCRIPTION = "Extra files for demo-image-cfa"
LICENSE = "GPLv2"
PR = "r1"
S="${WORKDIR}"
LIC_FILES_CHKSUM = "file://LICENSE;md5=c746876a5e2eaefef09efb9d7c1c463d"

SRC_URI += "file://qtbrowser.desktop \
            file://webkit.png \
            file://qtmediaplayer.desktop \
            file://qtmediaplayer.png \
            file://qtdemo.desktop \
            file://qtdemo.png \
            file://LICENSE"

inherit allarch

do_install () {
    install -d ${D}/${datadir}/pixmaps
    install -d ${D}/${datadir}/applications
    install -m 0644 ${WORKDIR}/webkit.png ${D}/${datadir}/pixmaps
    install -m 0644 ${WORKDIR}/qtbrowser.desktop ${D}/${datadir}/applications
    install -m 0644 ${WORKDIR}/qtmediaplayer.png ${D}/${datadir}/pixmaps
    install -m 0644 ${WORKDIR}/qtmediaplayer.desktop ${D}/${datadir}/applications
    install -m 0644 ${WORKDIR}/qtdemo.png ${D}/${datadir}/pixmaps
    install -m 0644 ${WORKDIR}/qtdemo.desktop ${D}/${datadir}/applications
}
  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}[fragile]{Useful package tweaks}
  \code{recipes-connectivity/connman}, to be extended to install and
  \code{connman.defaults} file, especially to prevent \code{connman}
  from configuring some interfaces.
  \code{recipes-connectivity/connman/connman_1.17.bbappend}
  \scriptsize
  \begin{block}{}
  \begin{minted}{bash}
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += " file://connman.defaults"

do_install_append() {
    if ${@base_contains('DISTRO_FEATURES','sysvinit','true','false',d)}; then
        install -d ${D}${sysconfdir}/default
        install -m 0755 ${WORKDIR}/connman.defaults \
            ${D}${sysconfdir}/default/connman
    fi
}
  \end{minted}
  \end{block}
  \normalsize
  \code{recipes-connectivity/connman/connman/connman.defaults}
  \begin{block}{}
  \begin{minted}{c}
EXCLUDED_INTERFACES="usb0"
  \end{minted}
  \end{block}
\end{frame}

\begin{frame}[fragile]{Useful package tweaks}
  \code{recipes-core/busybox}, to be extended to install various
  configuration files for the \code{busybox applets}
  \code{recipes-core/busybox/busybox_1.21.1.bbappend}:
  \footnotesize
  \begin{block}{}
  \begin{minted}{c}
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

SRC_URI_append_cfa10036 = " \
   file://udhcpd.conf \
"

do_install_append_cfa10036 () {
    install -m 0755 ${WORKDIR}/udhcpd.conf ${D}${sysconfdir}/
}
  \end{minted}
  \end{block}
  \normalsize
  This recipe is better than the previous one as it restrict changes
  to a particular machine.
\end{frame}

\begin{frame}[fragile]{Useful package tweaks}
  \code{recipes-core/psplash}, can be extended to change the splash
  screen, needs more to change the color of the progress bar:
  \code{recipes-core/psplash/psplash_git.bbappend}:
  \tiny
  \begin{block}{}
  \begin{minted}{c}
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
DEPENDS += "gdk-pixbuf-native"
PRINC = "8"
SRC_URI += "file://psplash-colors.h \
         file://psplash-bar-img.png"

# NB: this is only for the main logo image; if you add multiple images here,
# poky will build multiple psplash packages with 'outsuffix' in name for
# each of these ...
SPLASH_IMAGES = "file://psplash-poky-img.png;outsuffix=default"

# The core psplash recipe is only designed to deal with modifications to the
# 'logo' image; we need to change the bar image too, since we are changing
# colors
do_configure_append () {
        cd ${S}
        cp ../psplash-colors.h ./
        # strip the -img suffix from the bar png -- we could just store the
        # file under that suffix-less name, but that would make it confusing
        # for anyone updating the assets
        cp ../psplash-bar-img.png ./psplash-bar.png
        ./make-image-header.sh ./psplash-bar.png BAR
}
  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}{BSP}
  \huge
  \begin{center}
    BSP
  \end{center}
\end{frame}

\begin{frame}{Machine configuration}
  Create a \code{<machine>.conf} file in \code{conf/machine/}. As we
  want to support multiple similar boards (all based on
  \code{cfa10036}), an include was created in
  \code{conf/machine/include/}.
\end{frame}

\begin{frame}[fragile]{\code{conf/machine/include/cfa10036.inc}}
  \begin{block}{}
  \footnotesize
  \begin{minted}{c}
# Common definitions for cfa-10036 boards
include conf/machine/include/mxs-base.inc

SOC_FAMILY = "mxs:mx28:cfa10036"

PREFERRED_PROVIDER_virtual/kernel ?= "linux-cfa"
IMAGE_BOOTLOADER = "barebox"
BAREBOX_BINARY = "barebox"
IMXBOOTLETS_MACHINE = "cfa10036"
KERNEL_IMAGETYPE = "zImage"
KERNEL_DEVICETREE = "imx28-cfa10036.dtb"

# we need the kernel to be installed in the final image
IMAGE_INSTALL_append = " kernel-image kernel-devicetree"

SDCARD_ROOTFS ?= "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3"
IMAGE_FSTYPES ?= "tar.bz2 ext3 barebox.mxsboot-sdcard sdcard"

SERIAL_CONSOLE = "115200 ttyAMA0"
MACHINE_FEATURES = "usbgadget usbhost vfat"
  \end{minted}
  \normalsize
  \end{block}
\end{frame}

\begin{frame}[fragile]{\code{conf/machine/cfa10036.conf}}
  The machine configuration for the module is simple:
  \begin{block}{}
  \begin{minted}{c}
#@TYPE: Machine
#@NAME: Crystalfontz CFA-10036
#@SOC: i.MX28
#@DESCRIPTION: Machine configuration for CFA-10036
#@MAINTAINER: Alexandre Belloni <alexandre.belloni@bootlin.com>

include conf/machine/include/cfa10036.inc
  \end{minted}
  \end{block}
  It is always a good idea to put a contact as maintainer.
\end{frame}

\begin{frame}[fragile]{\code{conf/machine/cfa10057.conf}}
  For a carrier board, add the corresponding device tree and the
  supported features.
  \begin{block}{}
  \begin{minted}{c}
#@TYPE: Machine
#@NAME: Crystalfontz CFA-10057
#@SOC: i.MX28
#@DESCRIPTION: Machine configuration for CFA-10057, also called CFA-920
#@MAINTAINER: Alexandre Belloni <alexandre.belloni@bootlin.com>

include conf/machine/include/cfa10036.inc

KERNEL_DEVICETREE += "imx28-cfa10057.dtb"

MACHINE_FEATURES += "touchscreen"
  \end{minted}
  \end{block}
\end{frame}

\begin{frame}{Kernel support}
  For the kernel, you have multiple choices:
  \begin{itemize}
    \item patches over silicon vendor kernel tree
      \begin{itemize}
        \item available as an include
        \item using a \code{.bbappend}
      \end{itemize}
    \item custom git tree
    \item mainline git
  \end{itemize}
  You also probably have to provide a configuration file.
\end{frame}

\begin{frame}[fragile]{Patches, include}
  The compilation logic is provided by your silicon vendor as an include
  file:
  \begin{itemize}
    \item create a \code{recipes-kernel/linux/}
    \item write a new recipe \code{linux-<vendor>_<version>.bb}
    \item copy your patches to \code{recipes-kernel/linux/linux-<vendor>-<version>}
    \item Example: for \code{linux-congatec}:
      \footnotesize
      \begin{block}{}
      \begin{minted}{console}
$ ls recipes-kernel/linux/linux-congatec*
recipes-kernel/linux/linux-congatec_3.0.35.bb

recipes-kernel/linux/linux-congatec-3.0.35:
0001-Add-linux-support-for-congatec-evaluation-board-qmx6q.patch
0001-perf-tools-Fix-getrusage-related-build-failure-on-gl.patch
0002-ARM-7668-1-fix-memset-related-crashes-caused-by-rece.patch
0003-ARM-7670-1-fix-the-memset-fix.patch
[...]
defconfig
      \end{minted}
      \end{block}
      \normalsize
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Patches, include: recipe}
  \scriptsize
  \begin{block}{}
  \begin{minted}{c}
SUMMARY = "Linux Kernel based on Freescale Linux kernel to add support for Congatec boards"
include recipes-kernel/linux/linux-imx.inc

SRCREV = "bdde708ebfde4a8c1d3829578d3f6481a343533a"
LOCALVERSION = "-4.1.0+yocto"
SRCBRANCH = "imx_3.0.35_4.1.0"

SRC_URI += "file://drm-vivante-Add-00-sufix-in-returned-bus-Id.patch \
            file://epdc-Rename-mxcfb_epdc_kernel.h-to-mxc_epdc.h.patch \
            file://0001-perf-tools-Fix-getrusage-related-build-failure-on-gl.patch \
            file://0002-ARM-7668-1-fix-memset-related-crashes-caused-by-rece.patch \
            file://0003-ARM-7670-1-fix-the-memset-fix.patch \
            file://0004-ENGR00271136-Fix-build-break-when-CONFIG_CLK_DEBUG-i.patch \
            file://0005-ENGR00271359-Add-Multi-touch-support.patch \
            file://0006-Add-support-for-DVI-monitors.patch \
            file://0001-Add-linux-support-for-congatec-evaluation-board-qmx6q.patch \
            file://ENGR00278350-gpu-viante-4.6.9p13-kernel-part-integra.patch \
"

COMPATIBLE_MACHINE = "(cgtqmx6)"
  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}[fragile]{Patches, include: recipe}
  \begin{description}
    \item[SRCREV] The revision of the source code used to build the package.
    \item[SRCBRANCH] New in \code{daisy}, when using git it is
      required to specify in which branch the commit resides.
      \code{SRCBRANCH} is used in \code{SRC_URI}, in
      \code{linux-imx.inc}
    \item[SRC\_URI] The list of source files. Here patches are added
      in the original \code{SRC_URI}
    \item[COMPATIBLE\_MACHINE] A regular expression used to match
      against the \code{MACHINEOVERRIDES} variable which in turn
      includes \code{MACHINE}. Used to ensure the recipe won't build
      for other machines.
  \end{description}
\end{frame}

\begin{frame}[fragile]{\code{SRC_URI}: file://}
  \begin{itemize}
    \item When using \code{file://} in \code{SRC-URI}, OpenEmbedded will
      search files relative to the subdirectories listed in
      \code{FILESPATH}
    \item By default, this is:
      \begin{itemize}
        \item \code{${BPN}}, the base recipe name
        \item \code{${BP}}, which is \code{${BPN}-${PV}}, \code{${PV}}
          being the package version
        \item \code{files}
      \end{itemize}
    \item also looks in a subdirectory named \code{${MACHINE}} inside
      those directories
    \item if set, also looks for subdirectories named from
      \code{${MACHINEOVERRIDES}} and \code{${DISTROOVERRIDES}}
    \item Don't modify \code{FILESPATH} directly, use
      \code{FILESEXTRAPATHS}
  \end{itemize}
\end{frame}

\begin{frame}{custom git tree}
  When using a custom git tree, you'll have to write your own recipe.
  But this doesn't have to be difficult:
  \begin{itemize}
    \item inherit the kernel class, it already takes care of
      downloading, unpacking, configuring and compiling your kernel.
    \item if using device trees, include
      \code{recipes-kernel/linux/linux-dtb.inc}
    \item define \code{SRC_URI}
    \item define \code{S}
    \item define \code{COMPATIBLE_MACHINE}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\code{recipes-kernel/linux/linux-cfa_3.10.bb}}
  \scriptsize
  \begin{block}{}
  \begin{minted}{c}
DESCRIPTION = "Linux kernel for Crystalfontz boards"
SECTION = "kernel"
LICENSE = "GPLv2"

LIC_FILES_CHKSUM = "file://COPYING;md5=d7810fab7487fb0aad327b76f1be7cd7"

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

SRCBRANCH = "cfa-3.10.25"
SRC_URI = "git://github.com/crystalfontz/cfa_10036_kernel;branch=${SRCBRANCH} \
           file://defconfig"

SRCREV = "61dbe8ef338ce4cc1c10d5a6cdd418c047fb136d"

S = "${WORKDIR}/git"

COMPATIBLE_MACHINE = "cfa10036"
  \end{minted}
  \end{block}
  \normalsize
\end{frame}

\begin{frame}{Bootloader support}
  \begin{itemize}
    \item using \code{imxbootlets} to start \code{Barebox}
    \item the recipes are going in the \code{recipes-bsp} folder
    \item those recipes are extended using \code{.bbappend}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\code{imx-bootlets/imx-bootlets_10.12.01.bbappend}}
  \begin{itemize}
    \item extends
      \code{recipes-bsp/imx-bootlets/imx-bootlets_10.12.01.bb} from
      \code{meta-fsl-arm}
  \end{itemize}
  \small
  \begin{block}{}
  \begin{minted}{c}
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

SRC_URI_append_cfa10036 = " file://cfa10036-support.patch"
  \end{minted}
  \end{block}
  \normalsize
  \begin{itemize}
    \item use immediate expansion \code{:=}
    \item conditionally adds the cfa10036 support patch when
      \code{MACHINEOVERRIDES} matches
    \item don't forget the space at the beginning of the string when
      using \code{_append}
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{\code{barebox/barebox_2013.08.0.bbappend}}
  \begin{itemize}
    \item extends
      \code{recipes-bsp/barebox/barebox_2013.08.0.bb} from
      \code{meta-fsl-arm}
  \end{itemize}
  \small
  \begin{block}{}
  \begin{minted}{c}
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}-${PV}:"

COMPATIBLE_MACHINE_cfa10036 = "cfa10036"
  \end{minted}
  \end{block}
  \normalsize
  \begin{itemize}
    \item simply adds the subdirectory, it contains the configuration
  \end{itemize}
  \begin{block}{}
  \begin{minted}{console}
$ tree recipes-bsp/barebox/barebox-2013.08.0/
recipes-bsp/barebox/barebox-2013.08.0/
`-- cfa10036
    `-- defconfig
  \end{minted}
  \end{block}
\end{frame}

\begin{frame}{Documentation}
  \begin{itemize}
    \item \url{https://www.yoctoproject.org/documentation}
    \item in particular the variable glossary:
      \url{http://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html\#ref-variables-glossary}
    \item and the BSP developer's guide:
      \url{http://www.yoctoproject.org/docs/current/bsp-guide/bsp-guide.html}
    \item Freescale BSP:
      \url{http://freescale.github.io}
  \end{itemize}
\end{frame}

\begin{frame}{Training}
  \begin{itemize}
    \item We teach a 3 day course on Yocto Project and OpenEmbedded
      development
    \item Either on your company site
    \item Or in a public session, next ones: March 9-11, 2015 in Lyon,
      in French or May 20-22, 2015 in Paris, in English
    \item Info and materials available at:
      \url{http://bootlin.com/training/yocto/}
    \item training@bootlin.com
  \end{itemize}
\end{frame}

\begin{frame}
  \begin{center}
    \LARGE
    Questions?\\
    \vspace{2.5cm}
    \small
    Alexandre Belloni\\
    \code{alexandre.belloni@bootlin.com}\\
    \vspace{0.5cm}
    Slides under CC-BY-SA 3.0\\
    \scriptsize
    \url{http://bootlin.com/pub/conferences/2015/fosdem/belloni-starting-with-YP/}
  \end{center}
\end{frame}

\end{document}
