Public parts taken from private repo

.gitignore

@@ -0,0 +1,5 @@
+_book/
+node_modules/
+*.html
+*.pdf
+*.sublime-workspace

0-intro/env.md

@@ -0,0 +1,45 @@
+# Environment
+
+
+## Software requirements
+
+### Yocto
+
+_Required packages:_
+- `git`
+- `graphviz`
+- `python2` (`python` command should call `python2` instead of `python3`)
+
+
+
+## Yocto setup
+
+```sh
+# For YPCore - Fido
+git clone -b fido git://git.yoctoproject.org/poky.git
+cd poky
+export POKY=$PWD
+
+# This should be executed for each new shell:
+source $POKY/oe-init-build-env
+```
+
+
+### Toaster
+
+Toaster is a graphical tool to visualize build process and results.
+It will launch a web server on the port 8000.
+
+#### Setup
+
+_Required packages:_
+- `pip 2.x` (available in most distributions)
+- `django 1.5`: `pip install django==1.5`
+- `south`: `pip install south==0.8.4`
+
+Toaster must be launched with __`bash`__ (`zsh` does not work)
+```sh
+source toaster start
+```
+
+Access the toaster interface with your web browser at [127.0.0.1:8000](127.0.0.1:8000)

0-intro/glossary.md

@@ -0,0 +1,29 @@
+
+
+# Glossary
+
+Term|Definition
+---|---
+BitBake, Poky|Build system
+Layer|A folder containing configuration files related to one system (starts with `meta-`)
+Task|A set of functions/commands to do something. Can be written in shell or python.
+Recipe (`.bb`)|A set of tasks to download, build and package a software
+Append Files (`.bbappend`)|Files appended to existing recipes
+Classes|Configuration fragments priving tools to be included in recipes
+Package|A built recipe prepared as an installable package (.deb)
+Image|The final file for your distribution, generally a disk image (iso, hddimg, etc...)
+
+
+[More...](http://www.yoctoproject.org/docs/1.8/dev-manual/dev-manual.html#yocto-project-terms)
+
+# Variables
+
+These variables __are not used by Yocto__. They are used in this book for convenience.
+
+Variable|Value|More
+---|---|---:
+`$POKY`|Path to cloned poky directory.|[More](env.md#yocto-setup)
+`$LAYER`|Path to your custom layer|[More](../2-usage/layercreate.md#manual-creation)
+`$DISTRO`|The distribution you are building (ex: `poky-tiny`)|[More](../2-usage/distrocreate.md)
+`$MACHINE`|The machine you are building for (ex: `genericx86`)|[More](../2-usage/machinecreate.md)
+`$IMAGE`|The image you are building (ex: `core-image-minimal`)|[More](../2-usage/imagecreate.md)

0-intro/projects.md

@@ -0,0 +1,5 @@
+# Projects using Yocto
+
+- [Angstrom distribution](https://github.com/Angstrom-distribution/setup-scripts)
+- [Tizen](https://wiki.tizen.org/wiki/Build_Tizen_with_Yocto_Project)
+- Many community-created distributions (for Raspberry Pi, Beaglebone, ...)

1-concepts/bsp.md

@@ -0,0 +1,11 @@
+# Board Support Package (BSP)
+
+
+The Board Support Package allows to tune the builds for specific architectures/processors, defines kernel configuration and more generally how to handle the interface between the OS and the motherboard.
+BSP are packed into layers.
+
+<info data-markdown>Most BSP are found in the `meta-yocto-bsp` layer: `$POKY/meta-yocto-bsp/conf/machine/`</info>
+
+<warn data-markdown>The BSP is bound to machine definition</warn>
+
+<todo>improve this</todo>

1-concepts/class.md

@@ -0,0 +1,29 @@
+# Classes
+
+Classes provides functions and tools that can be used in recipes.
+To use a class, you must make the recipe inherit from the class.
+
+<info data-markdown>Classes files have the `.bbclass` extension</info>
+
+
+## Example: module class
+See: `$POKY/meta/classes/module.bbclass`
+
+This class provides functions to build and install kernel modules
+
+It defines these functions
+- `module_do_compile`
+- `module_do_install`
+- From _module-base_
+	- `do_make_scripts`
+- From _kernel-module-split_
+	- `pkg_postinst_modules`
+	- `pkg_postrm_modules`
+	- `autoload_postinst_fragment`
+	- `do_install_append`
+	- `split_kernel_module_packages`
+
+When writing a kernel module recipe, you have to inherit from this class using:
+```sh
+inherit module
+```

1-concepts/distro.md

@@ -0,0 +1,9 @@
+# Distribution
+
+The distribution defines how softwares (recipes) are packed together to build the OS.
+
+<info data-markdown>Most distributions are found in the `meta-yocto` layer: `$POKY/meta-yocto/conf/distro/`</info>
+
+Most softwares added by the distribution are "high level", and should not rely on hardware components.
+
+Hardware-related softwares (ie drivers, bootloaders, etc.) should be added in the machine configuration file.

1-concepts/image.md

@@ -0,0 +1,18 @@
+# Image
+
+The image defines the final disk image that will be flashed on the target device.
+Generated disk/partition images put in `$POKY/build/tmp/deploy/images/$MACHINE`
+
+Available images can be listed with:
+```sh
+ls $POKY/meta*/recipes-*/images/*.bb
+```
+
+
+## Bitbake
+
+Generally when you use bitbake, you build an image:
+```sh
+IMAGE=core-image-minimal
+bitbake $IMAGE
+```

1-concepts/layer.md

@@ -0,0 +1,60 @@
+# Layer
+
+A layer is a bundle of configuration files.
+
+It can contain:
+
+- Recipes to build specific software
+- Machines
+- Distributions
+- Classes
+- Images
+- ...
+
+
+## Layer list
+Layers are listed in `$POKY/build/conf/bblayers.conf` using __absolute__ path:
+```sh
+BBLAYERS = " \
+	/home/me/poky/meta \
+	/home/me/poky/meta-yocto \
+	/home/me/poky/meta-yocto-bsp \
+	/home/me/poky/build/meta-ab3000 \
+	"
+```
+<info data-markdown>
+The layer can be in another directory than under `$POKY`.
+</info>
+<warn data-markdown>
+Don't forget to add any newly created layer in this list to use it
+</warn>
+
+Generally this folder is versioned (with git).
+
+The layers shipped with Yocto are in `$POKY/meta*`.
+
+
+## Layer configuration
+_Minimal configuration:_
+```sh
+BBPATH .= ":${LAYERDIR}"
+
+BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+	${LAYERDIR}/recipes-*/*/*.bbappend"
+
+BBFILE_COLLECTIONS += "ab3000"
+BBFILE_PATTERN_ab3000 = "^${LAYERDIR}/"
+BBFILE_PRIORITY_ab3000 = "6"
+```
+
+Variable|Use
+---|---
+`BBFILES`|Where to search for recipes & recipe append files (ie `recipes-group/recipename/recipename.bb`)
+`BBFILE_COLLECTIONS`|Layer name. Will be used to get/set variables only for this layer (ie `VAR_ab3000`)
+
+
+
+
+
+[More about layers](http://www.yoctoproject.org/docs/1.7.1/dev-manual/dev-manual.html#understanding-and-creating-layers)
+

1-concepts/machine.md

@@ -0,0 +1,3 @@
+# Machine
+
+<todo>Check what is the difference with BSP</todo>

1-concepts/package.md

@@ -0,0 +1,10 @@
+# Package
+
+Once the recipe has been built, the produced files are put in a package.
+There are multiple packages format: `ipk`,`rpm`,`deb`,`tar`, ...
+
+These packages are automatically installed to the final disk image.
+
+They can also be installed later on the system with a package manager
+
+See [Package Management (deb)](../5-misc/pkgmgr.md) for how to serve those packages (as a debian mirror).

1-concepts/recipes.md

@@ -0,0 +1,50 @@
+# Recipes
+
+A recipe describes how to build, package and install one software.
+
+It defines a list of variables like the software name, license checksum, etc...
+
+It can also define/override tasks like `do_compile` or `do_install`
+
+<info data-markdown>
+Many recipes are found in each layer at `$POKY/meta*` in the `recipe-*` folders.
+</info>
+
+## Recipes list
+
+To list all available recipes across every available layer:
+```sh
+bitbake-layers show-recipes
+```
+
+## Example
+```sh
+SUMMARY = "My lovely software"
+
+# Name
+PN = "lovely-software"
+PV = "1"
+PR = "r0"
+
+# License info
+LICENSE = "GPLv2"
+LIC_FILES_CHKSUM = "file://${S}/LICENSE;md5=2f24da3987abb0e21842f5b694ec2133"
+
+# This program depends on libcurl
+DEPENDS = "curl"
+RDEPENDS_${PN} = "curl"
+
+# Task to build the software
+do_compile(){
+	oe_runmake \
+		INCFLAGS="${BUILDSDK_CFLAGS} -DNDEBUG" \
+		LDFLAGS="${BUILDSDK_LDFLAGS} -lpthread" \
+		all
+}
+
+# Task to install it on the target system
+do_install(){
+	install -d ${D}${bindir}
+	install -m 0755 ${B}/binary ${D}${bindir}
+}
+```

2-usage/distrocreate.md

@@ -0,0 +1,30 @@
+# Create a Distribution
+
+## Manual creation
+
+```sh
+mkdir $LAYER/conf/distro
+
+DISTRO="my-distro"
+touch $LAYER/conf/distro/$DISTRO.conf
+```
+
+Variables in the distribution conf file:
+
+|Variable|Role|
+|---|---|
+|`DISTRO_NAME`|Name of the distribution|
+|`DISTRO_VERSION`|Version of the distribution|
+|`DISTRO_FEATURES`|Lists softwares (recipes) that are included in the distribution. [Examples](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#ref-features-distro)|
+|`DISTRO_EXTRA_RDEPENDS`|Runtime package dependencies for the distribution</todo>|
+|`DISTRO_EXTRA_RRECOMMENDS`|List of package that will installed if they are available, for example kernel modules</todo>|
+|`TCLIBC`|_libc_ implementation (`eglibc` or `uclibc` only)|
+|`NO_RECOMMENDATIONS`|If set to `1`, no recommended package will be installed|
+|`BAD_RECOMMENDATIONS`|Recommended packages that must not be installed|
+|`PACKAGE_EXCLUDE`|List of package that must not be installed (will error if one package listed here is required by another package that should be installed)|
+
+<todo>why DISTRO_<strong>EXTRA</strong>_RRECOMMENDS
+
+<info data-markdown>
+Don't forget to update `DISTRO` in `$POKY/build/conf/local.conf` to use your distribution
+</info>

2-usage/imagecreate.md

@@ -0,0 +1,20 @@
+# Create an image
+
+Images are not very different from other recipes.
+
+They should be put in any `recipe-*/images`.
+
+# Example
+
+```sh
+SUMMARY = "My custom image"
+LICENSE = "MIT"
+
+# Based on another image
+inherit core-image
+IMAGE_INSTALL = "packagegroup-core-boot ${ROOTFS_PKGMANAGE_BOOTSTRAP} ${CORE_IMAGE_EXTRA_INSTALL}"
+IMAGE_LINGUAS = " "
+
+# Additionnal recipes to install
+IMAGE_INSTALL += "top"
+```

2-usage/layercreate.md

@@ -0,0 +1,67 @@
+# Creating a Layer
+
+The layer is nothing more than a folder with a single configuration file to indicate its name and where to find its resources.
+
+The layer can be put anywhere on the system.
+
+## Manual creation
+
+There are other ways to create layers that are specific to certain usages (BSP, Distribution, ...), but this is the manual way to create a minimal layer.
+
+```sh
+#The path to your layer
+LAYER=$POKY/build/meta-mylayer
+
+mkdir $LAYER
+cd $LAYER
+```
+
+Write `$LAYER/conf/layer.conf` (replace `mylayer` by your layer name):
+```sh
+BBPATH .= ":${LAYERDIR}"
+
+# Register the layer recipes into the variable BBFILES
+BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+            ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+BBFILE_COLLECTIONS += "mylayer"
+BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
+BBFILE_PRIORITY_mylayer = "5"
+```
+
+<warn data-markdown>
+Once created, you will need to add the layer path in the `BBLAYER` variable, usually defined in `$POKY/build/conf/local.conf`
+</warn>
+
+
+## Layer organization
+
+| Path | Role |
+|---|---|
+|`conf/layer.conf`| Layer configuration |
+|`conf/machine/*.conf`| Machines |
+|`conf/distro/*.conf`| Distributions |
+|`classes/`| Classes |
+|`recipes-*/`| Recipes |
+|`README`| Readme file (optional) |
+
+
+## Layer management tools
+```sh
+bitbake-layers <command> [arguments]
+# Available commands:
+#   help
+#     display general help or help on a specified command
+#   show-recipes
+#     list available recipes, showing the layer they are provided by
+#   show-cross-depends
+#     figure out the dependency between recipes that crosses a layer boundary.
+#   show-appends
+#     list bbappend files and recipe files they apply to
+#   flatten
+#     flattens layer configuration into a separate output directory.
+#   show-layers
+#     show current configured layers
+#   show-overlayed
+#     list overlayed recipes (where the same recipe exists in another layer)
+```

2-usage/machinecreate.md

@@ -0,0 +1,183 @@
+# Create a Machine / Board Support Package
+
+## Creation
+
+In the layer directory:
+```sh
+mkdir $LAYER/conf/machine
+
+MACHINE=my-machine
+touch $LAYER/conf/machine/$MACHINE.conf
+```
+
+See below for an interactive script to create a machine.
+
+### Machine conf. file
+
+Edit `$LAYER/conf/machine/$MACHINE.conf` to set variables:
+
+| Variable | Role | Link |
+|---|---|---|
+| `TARGET_ARCH` | CPU architecture (`arm`, `i386`, `x86_64`, etc.) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-TARGET_ARCH)
+| `PREFERRED_PROVIDER_virtual/kernel` | Linux kernel recipe to use (`linux-yocto`) |
+| `MACHINE_FEATURES` | See [Combined Features](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-COMBINED_FEATURES) |
+| `SERIAL_CONSOLES` | Serial consoles to enable & their configurations (`115200;ttyS0 115200;ttyS1`) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-SERIAL_CONSOLES) |
+| `KERNEL_IMAGETYPE` | Type of the kernel image (default: `zImage`) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-KERNEL_IMAGETYPE) |
+| `IMAGE_FSTYPES` | Type of the output filesystem image (default: `ext3 tar.bz2`) | [More](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-IMAGE_TYPES) |
+
+### Kernel config file
+
+Bitbake builds the kernel `.config` file using configuration fragments from the kernel recipe.
+
+There are two ways to setup kernel configuration:
+- Using `.scc` files
+- Using `.cfg` files
+
+Both files can be added to `SRC_URI` in the kernel recipe to be used.
+
+See `$POKY/meta/recipes-kernel/linux` for recipe examples
+
+#### `.cfg` files
+
+`.cfg` files contains fragments of kernel `.config` file.
+
+If multiple cfg files are added to the recipe, the values contained in the last included will override other values that were already set.
+
+You can view the resulting kernel `.config` with the standard kernel menuconfig UI:
+```sh
+bitbake virtual/kernel -c menuconfig
+```
+
+_Extracting a config fragment:_
+
+- Go to `$POKY/build/tmp/work/*/$KERNEL_RECIPE_NAME/*/$KERNEL_RECIPE_NAME-*-build`
+- Use a diff tool (`vimdiff`, `meld`, `kdiff3`) to list differences between `.config` and `.config.old`
+
+<info data-markdown>
+At this time, there is no practical tool to create configuration fragments.
+</info>
+
+
+#### `.scc` files
+
+`.scc` files are like a wrapper around .cfg files.
+
+They can include multiple `.cfg` or `.scc`, define which kernel branch to use, the architecture and other things.
+
+```
+define KMACHINE my-machine
+define KTYPE tiny
+define KARCH i386
+
+kconf hardware general.cfg
+kconf hardware liveboot.cfg
+
+include ktypes/tiny/tiny.scc
+branch my-machine
+
+include my-machine.scc
+```
+
+[More](http://www.yoctoproject.org/docs/1.8/mega-manual/mega-manual.html#scc-reference)
+
+### Formfactor
+
+<todo></todo>
+
+```cfg
+HAVE_TOUCHSCREEN=0
+HAVE_KEYBOARD=1
+
+# Display rotation, size, colors, ...
+DISPLAY_CAN_ROTATE=0
+DISPLAY_ORIENTATION=0
+#DISPLAY_WIDTH_PIXELS=640
+#DISPLAY_HEIGHT_PIXELS=480
+#DISPLAY_BPP=16
+DISPLAY_DPI=150
+DISPLAY_SUBPIXEL_ORDER=vrgb
+```
+
+## Interactive script
+
+
+<info data-markdown>
+The script `yocto-bsp create <layer_name> <target_arch>` creates a layer named `<layer_name>` with a BSP for the architecture `<target_arch>` into.<br/>
+You can get the list of supported arch with `yocto-bsp list karch`
+</info>
+
+This is an interactive script to create a BSP contained in a new layer:
+```bash
+yocto-bsp create my-machine i386
+# Checking basic git connectivity...
+# Done.
+#
+# Would you like to use the default (3.14) kernel? (y/n) [default: y]
+# Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
+# Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.14.git...
+# Please choose a machine branch to base this BSP on: [default: standard/base]
+# 	1) standard/arm-versatile-926ejs
+# 	2) standard/base
+# 	3) standard/beagleboard
+# 	4) standard/beaglebone
+# 	5) standard/ck
+# 	6) standard/common-pc/base
+# 	7) standard/edgerouter
+# 	8) standard/fsl-mpc8315e-rdb
+# 	9) standard/mti-malta32
+# 	10) standard/mti-malta64
+# 	11) standard/qemuarm64
+# 	12) standard/qemuppc
+# 	13) standard/routerstationpro
+# 2
+# Do you need SMP support? (y/n) [default: y] n
+# Which machine tuning would you like to use? [default: tune_core2]
+# 	1) i586 tuning optimizations
+# 	2) Atom tuning optimizations
+# 	3) Core2 tuning optimizations
+# 2
+# Do you need support for X? (y/n) [default: y] n
+# Does your BSP have a touchscreen? (y/n) [default: n] n
+# Does your BSP have a keyboard? (y/n) [default: y] y
+#
+# New i386 BSP created in meta-my-machine
+```
+
+<warn data-markdown>Don't forget to add the layer to `BBLAYER` if you want to use it</warn>
+
+
+### Generated tree
+
+```text
+poky/build/meta-my-machine
+├── binary
+├── conf
+│   ├── layer.conf                     => Layer configuration file
+│   └── machine
+│       └── my-machine.conf                => Machine configuration file
+├── COPYING.MIT
+├── README
+├── README.sources
+├── recipes-bsp
+│   └── formfactor
+│       ├── formfactor
+│       │   └── my-machine
+│       │       └── machconfig         => Input device support
+│       └── formfactor_0.0.bbappend
+├── recipes-graphics                   => Empty, can be deleted
+│   └── xorg-xserver
+│       └── xserver-xf86-config
+│           └── my-machine
+└── recipes-kernel
+		└── linux
+				├── files
+				│   ├── my-machine.cfg     => Kernel configuration file
+				│   ├── my-machine-preempt-rt.scc
+				│   ├── my-machine.scc
+				│   ├── my-machine-standard.scc
+				│   ├── my-machine-tiny.scc
+				│   ├── my-machine-user-config.cfg
+				│   ├── my-machine-user-features.scc
+				│   └── my-machine-user-patches.scc
+				└── linux-yocto_3.14.bbappend      => Kernel recipe
+```

2-usage/recipecreate.md

@@ -0,0 +1,103 @@
+# Create a Recipe
+
+## Creation
+
+It may be better to use already existing recipes and customize them.
+
+<info data-markdown>A recipe file must be named `<name>_<version>.bb` (lowercase only)</info>
+
+<warn data-markdown>To be enabled, the recipe must be available in the `BBFILES` variable located in the `conf/layer.conf` file</warn>
+
+Recipe skeleton
+```sh
+SUMMARY = ""
+HOMEPAGE = ""
+LICENSE = ""
+
+LIC_FILES_CHKSUM = ""
+
+# Source download URI
+SRC_URI = ""
+SRC_URI[md5sum] = ""
+SRC_URI[sha256sum] = ""
+
+# Source folder
+S = "${WORKDIR}/${PN}-${PV}"
+
+# Classes to use
+inherit <classname>
+
+# Task definition
+do_compile() {
+	${CC} helloworld.c -o helloworld
+}
+```
+
+## Configuration
+
+### Variable list
+
+|Variable|Content|
+|---|---|
+|`PN`| Recipe name |
+|`PV`| Recipe version |
+|`PR`| Recipe revision |
+|`WORKDIR`| Directory where sources are extracted and the recipe is built |
+|`SRCREV `| Commit hash, Tag or branch to checkout if the sources are a repository |
+|`SRC_URI`| Files to download (new-line separated list) |
+|`DEPENDS`| Recipe build-time dependency list |
+|`RDEPENDS_${PN}`| Recipe run-time dependency list |
+
+#### Function list
+
+|Task/Function|Role|
+|---|---|
+|`do_unpack()`|Unpacks the downloaded source code to `${S}`.<br/>Automatically generated if the downloaded package is named `<recipe_name>-<recipe_version>.*`|
+|`do_patch()`|Applies patches to source code.<br/>If `SRC_URI` contains a `.patch` or `.diff` file, it will automatically apply it to source code.|
+|`do_configure()`|Configures the project (ie `./configure` for _Autotools_).<br/>Automatically generated if the project uses _Autotools_ or _CMake_. [More](http://www.yoctoproject.org/docs/1.8/dev-manual/dev-manual.html#new-recipe-configuring-the-recipe)|
+|`do_compile()`|Commands to build the recipe<br/>Automatically generated for _Autotools_ or _CMake_|
+|`do_install()`|Commands to install on the system (into `${D}${bindir}`)<br/>Automatically generated for _Autotools_ or _CMake_|
+|` pkg_postinst_<RECIPENAME>()`|__Replace `<RECIPENAME>` with the recipe name__<br/>Contains the commands to execute after the package installation.<br/>`pkg_postinst_yolo(){`<br/>`#!/bin/sh -e`<br/>`cp A B`<br/>`}`|
+
+### Useful classes
+
+To use some Yocto tools in recipes, you may need to inherit some packages:
+
+|Tool|Inheritance|
+|---|---|
+|Autotools|`inherit autotools gettext`|
+|SysVInit|`inherit update-rc.d`|
+
+[Full class list](http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#ref-classes)
+
+
+## Enabling services
+
+If `do_install()` exists in the recipe add code to the end of the function, else write a `do_install_append()` function that will contain the service initialization code.
+
+[Details](http://www.yoctoproject.org/docs/1.8/dev-manual/dev-manual.html#new-recipe-enabling-system-services)
+
+### SysVinit
+
+You must add to the recipe:
+```sh
+inherit update-rc.d
+
+# List of packages that contains initscripts
+# Optional, default: ${PN}
+#INITSCRIPT_PACKAGES
+
+# Name of the init script installed in /etc/init.d
+# Mandatory
+INITSCRIPT_NAME = "${PN}"
+
+# Parameters to pass to the init command
+# Mandatory
+INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
+```
+
+
+
+## Build the recipe
+
+`bitbake <recipe_name>`

2-usage/syntax.md

@@ -0,0 +1,53 @@
+# Configuration file syntax
+
+```sh
+# VAR value (the brackets are mandatory)
+${VAR}
+
+# Set value if not defined (ie set default value)
+VAR ?= "defvalue"
+
+# Set value at the end of parsing if the value is not defined
+VAR ??= "defvalue"
+
+# Set VAR to "value" immediately
+VAR := "value"
+
+
+# Append "value" to VAR
+# Warning: inserts a space between current value and appended value
+VAR += "value"
+# Same with prepend:
+VAR =+ "value"
+
+# Same to append/prepend but without space
+VAR .= "value"
+VAR =. "value"
+
+# Same to append/prepend
+#   but without space and deferred at the end of parsing
+VAR_append = "value"
+VAR_prepend = "value"
+
+# Remove elements (words) in a space-separated value list
+VAR_remove = "value"
+
+
+# Like bash functions
+my_function() {
+	echo "Hello world"
+}
+# Note that _append suffix also works with functions
+
+
+# Function written in python
+python my_function2() {
+	print "Hello world"
+}
+```
+
+<warn data-markdown>
+- `${VAR}` is a Yocto variable.
+- `$VAR` is a shell variable.
+- They are very different !
+</warn>

3-buildtest/build.md

@@ -0,0 +1,29 @@
+# Build
+
+```bash
+cd $POKY # YPCore cloned repository
+source ./oe-init-build-env
+
+# bitbake $TARGET
+
+# Build apt recipe
+bitbake apt
+
+# Build core-image-minimal image
+bitbake core-image-minimal
+```
+
+`TARGET` can be:
+
+- The name of the image you want to build (`meta/recipes-*/images`).
+- The name of a recipe to build, using the distribution and machine set in `$POKY/build/local.conf`
+
+
+
+## Additional steps for images : `wic`
+
+The image generated by bitbake is adapted for emulation purpose or read only disks.
+
+With `wic`, you can setup the target partition table.
+
+See section [wic](wic.md)

3-buildtest/qemu.md

@@ -0,0 +1,44 @@
+# Qemu
+
+
+## Using `runqemu`
+
+`runqemu` is a script provided by Yocto, that launches qemu for a specific image.
+
+Running in qemu can be done with
+```bash
+MACHINE=qemux86
+runqemu core-image-minimal $MACHINE ext3 qemuparams="-cpu n270"
+# Note: runqemu is a script available by sourcing oe-init-build-env
+#       qemuparams="-cpu n270" is needed to emulate specific CPU
+#       See runqemu $MACHINE qemuparams="-cpu help"
+```
+
+<info data-markdown>
+`-cpu n270` Configure the guest CPU to be Intel Atom. `-cpu help` lists available CPUs.
+</info>
+
+## Directly using qemu
+
+### Directly booting the kernel
+```sh
+cd $POKY/tmp/deploy/images/$MACHINE
+qemu -kernel bzImage $IMAGE-$MACHINE.ext3 -cpu n270
+```
+
+Interesting parameters:
+
+Param|_
+---|---
+`-append`|Kernel command line parameters
+`-hda`|Set disk image for sda device.
+
+
+
+
+### Booting using target bootloader
+You need to generate an image using WIC.
+
+```sh
+qemu build/*-sda.direct -cpu n270
+```

3-buildtest/wic.md

@@ -0,0 +1,76 @@
+# WIC
+
+## Generate image
+```sh
+wic create $WKS -e $IMAGE -o .
+```
+`$WKS`: File containing the configuration of the partition table.
+
+The generated disk image will be put in `build/$WKS-*.$DISK.direct`
+
+<info data-markdown>
+You need to source `$POKY/oe-init-build-env` to use wic
+</info>
+
+## Available images
+To list available configuration files:
+```sh
+wic list images
+```
+
+
+# WKS config file
+
+A WKS configuration file contains a list of commands to create the partitions and configure the bootloader.
+
+## Sample config
+```sh
+# short-description: Create a 'pcbios' direct disk image
+# long-description: Creates a partitioned legacy BIOS disk image that the user
+# can directly dd to boot media.
+
+part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
+part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 --size=200M
+
+bootloader  --timeout=0  --append="rootwait rootfstype=ext3 video=vesafb vga=current console=tty0"
+```
+<info data-markdown>
+the syntax doesn't support ` \\\n` line escape
+</info>
+
+## Header
+```sh
+# short-description: your description
+# long-description: long description...
+```
+
+These descriptions are optional and will be displayed when using `wic list images`
+
+## Commands
+#### Partition
+```sh
+part $MOUNTPOINT [args]
+```
+
+`args`|_
+---|---
+`$MOUNTPOINT`|Mount point. Can be a path (eg `/`, `/boot`) or `swap`
+`--source`|Source data provided by a plugin. To list plugins: `wic list source-plugins`
+`--size`|Partition size in MB.<br/>If not provided, the partition will have the minimum possible size.
+`--ondisk`|Disk name on the target system (eg `sda`, `sdb`, ...)
+`--fstype`|File system type (eg `ext4`, `ext2`, `btrfs`, `swap`, ...)
+`--fsoptions`|Mount options to be added in fstab.
+`--label`|Partition name
+`--align`|Partition alignment in KB (ex: 1024)
+`--active`| Mark partition as active <todo>?</todo>
+
+
+#### Bootloader
+```sh
+bootloader [args]
+```
+
+`args`|_
+---|---
+`--timeout`|Timeout in seconds before booting default option
+`--append`|Kernel command line arguments to bee added when booting.

4-workflow/addpkg.md

@@ -0,0 +1,16 @@
+# Adding packages/recipes to image
+
+
+## Quick and Dirty
+Add to your `local.conf`:
+```sh
+IMAGE_INSTALL_append += " package"
+```
+
+
+## Associated to an image, machine or distro
+
+In the image, machine or distro configuration file:
+```sh
+IMAGE_INSTALL_append += " package"
+```

4-workflow/debug.md

@@ -0,0 +1,25 @@
+# Debugging Yocto builds
+
+```sh
+# Build $TARGET and display logs on error
+bitbake $TARGET -v
+
+
+# Display all environment variables, how they are
+#  set and the functions for building $TARGET
+bitbake -e $TARGET
+
+# To filter informations related to a variable
+bitbake -e $TARGET | grep "^VARIABLE\b" -B 20
+
+
+# View packages & their dependencies:
+bitbake -u depexp -g $TARGET
+
+
+# Create a dependency graph for $TARGET
+bitbake -g $TARGET
+
+#Convert and open a graph file:
+dot -Tsvg $FILE.dot -o /tmp/graph.svg && xdg-open /tmp/graph.svg
+```

4-workflow/distrocreate.md

@@ -0,0 +1,35 @@
+# Creation of a distribution based on poky-tiny
+
+_poky-tiny_ is a distribution that is packed with Yocto and is aimed to provide a very minimal OS for embeded systems.
+
+Its is built to fit on a 8MB disk, and goes down to 1.5MB when compressed.
+
+[More](https://wiki.yoctoproject.org/wiki/Poky-Tiny)
+
+
+## Layer
+
+The distribution must be put in a layer.
+
+Since Yocto layers are versionned, it is better to create a new custom layer containing the distribution, and eventually additionnal softwares, machines, etc.
+
+## Distro config
+
+`$LAYER/conf/distro/my-distro.conf`:
+```sh
+# Based on poky-tiny
+require conf/distro/poky-tiny.conf
+
+DISTRO = "my-distro"
+DISTRO_NAME = "my-distro"
+DISTRO_VERSION = "0"
+
+# Install dropbear SSH server
+IMAGE_INSTALL_append += " dropbear"
+
+# Dropbear has also a feature to activate:
+EXTRA_IMAGE_FEATURES = "ssh-server-dropbear"
+
+# Install syslinux:
+IMAGE_INSTALL_append += " syslinux"
+```

4-workflow/general.md

@@ -0,0 +1,25 @@
+# Introduction
+
+Typically you start by using an existing distribution, then override some variables to define which software you want or don't want and how to configure them.
+
+
+## Add new software
+
+When needed you can write a new recipe to add a specific software that is not in Yocto recipes.
+
+
+## Customize existing recipe
+
+To customize an existing recipe, you have to create a folder and a `.bbappend` file with the same name as the recipe:
+```raw
+$POKY
+└─ meta
+   └─ recipes-devtools
+      └─ apt
+         └─ apt_0.9.9.4.bb => Original recipe
+
+$LAYER
+└─ recipes-*
+   └─ apt
+      └── apt_0.9.9.4.bbappend => Override
+```

5-misc/buildproc.md

@@ -0,0 +1,84 @@
+# Build process - Tasks
+
+This describes all tasks that are executed when building a recipe or distribution.
+
+## `do_package_write_<pkgtype>`
+
+
+For all packages selected with `PACKAGE_CLASSES`, packages are downloaded into `DL_DIR`
+
+Default: `poky/build/tmp/deploy/<pkgtype>/<arch>/`
+
+- pkgtype: rpm, ipk, deb
+- arch: genericx86, ...
+
+Those packages can also be built from sources with the folowing commands.
+
+## `do_fetch` & `do_unpack`
+
+
+Downloads and extracts the package sources.
+
+```text
+poky/build/tmp/work/
+└── <PACKAGE_ARCH>-poky-linux or <MACHINE>-poky-linux
+		└── <PACKAGE_NAME>
+				└── <RECIPE_VERSION>-<RECIPE_REVISION> : The package is built from here
+						└── <PACKAGE_NAME>-<RECIPE_VERSION> : Package sources
+```
+
+## `do_patch`
+
+
+Apply some yocto-related patches to package source
+The patches are listed in `SRC_URI` in the recipe file
+
+## `do_configure`, `do_compile`, `do_install`
+
+
+
+In most cases:
+- `do_configure`: `./configure`
+- `do_compile`: `make`
+- `do_install`: `make install`
+
+The work directory is:
+```text
+poky/build/tmp/work/
+└── <PACKAGE_ARCH>-poky-linux or <MACHINE>-poky-linux
+		└── <PACKAGE_NAME>
+				└── <RECIPE_VERSION>-<RECIPE_REVISION>
+```
+
+From the work directory:
+- `<PACKAGE_NAME>-<RECIPE_VERSION>`: Built files
+- `image` : installed files (eg `./configure --prefix`)
+
+
+## `do_package` & `do_packagedata`
+
+
+`do_package` analyses the `image` dir:
+- splits out debugging symbols
+- checks shared library dependencies
+- looks at package relationships
+
+`do_packagedata` creates the package metadata file.
+
+From working dir:
+- `package`: The destination directory for packages before they are split
+- `pkgdata`: A temporary work area used by the do_package task
+- `packages-split`: The parent directory for packages after they have been split
+
+These folders are used by `do_package_write_*` and generated packages are put into the package feed area (`poky/build/tmp/deploy/<pkgtype>/a<rch>/`)
+
+## `do_rootfs`
+
+
+Unpacks the packages from the package feed area (`poky/build/tmp/deploy/<pkgtype>/<arch>/`) to build the root filesystem, depending on the configuration :
+
+- `IMAGE_INSTALL`: Which base package to install
+- `PACKAGE_EXCLUDE`: Which packages to not install
+- `IMAGE_FEATURES`: Which features to install. Features maps to specific packages to be installed.
+- `PACKAGE_CLASSES`: Package type to use (deb, ipk, tar, ...)
+- `IMAGE_LINGUAS`: Languages to install

5-misc/deployssh.md

@@ -0,0 +1,3 @@
+# Deploy a recipe to a target via ssh
+
+http://www.yoctoproject.org/docs/1.8/mega-manual/mega-manual.html#devtool-deploying-your-software-on-the-target-machine

5-misc/pkgmgr.md

@@ -0,0 +1,37 @@
+# Package Management (deb)
+
+## Image configuration
+
+```bash
+IMAGE_FEATURES += "package-management"
+
+# For debian packages, install apt commands
+IMAGE_INSTALL += "apt"
+```
+
+## Serve packages
+
+When building a recipe, the generated package will be put in `$POKY/build/tmp/deploy/deb`
+This directory must be served by a web server.
+
+Each time you create/modify a package, you will need to re-generate the package index by executing
+```bash
+bitbake package-index
+```
+
+## source.list
+
+You must add the repository address to a file in `/etc/apt/sources.list.d/` on the target:
+```bash
+deb http://192.168.42.1/all/ ./
+deb http://192.168.42.1/m_ab3000/ ./
+#...
+```
+
+<info>Using the layer meta-ab3000, you can set the variable `DEBIAN_REPO_ADDRESS` and the main yocto repositories will be automatically set</info>
+
+## Build all packages
+```bash
+bitbake world
+```
+Will build all existing packages and prepare deb packages ready to be deployed.

5-misc/rorootfs.md

@@ -0,0 +1,5 @@
+# Read-only root filesystem
+
+[Information](http://www.yoctoproject.org/docs/1.8/dev-manual/dev-manual.html#creating-a-read-only-root-filesystem)
+
+

5-misc/toolchain.md

@@ -0,0 +1,6 @@
+# Custom toolchain
+
+With the variable `TCMODE`, you can setup any toolchain to be used to build the system.
+By default, Yocto fetch & build its own toolchain.
+
+See http://www.yoctoproject.org/docs/1.7.1/ref-manual/ref-manual.html#var-TCMODE

6-maintenance/clean.md

@@ -0,0 +1,25 @@
+# Cleaning
+
+
+## Clean a single target
+
+```bash
+TARGET=binutils-cross-i586
+bitbake $TARGET -c cleanall
+```
+
+## Clean everything
+
+```bash
+bitbake world -c cleanall
+cd $POKY
+rm -rf build/sstate-cache build/tmp
+```
+
+
+## About _tmp_ & _sstate_
+
+- `build/tmp` contains sources, build files, created packages, temporary rootfs, staging area, etc. You may need to remove it sometime.
+- `build/sstate-cache` contains downloaded files, ie source tarballs. You are unlikely to have to remove this folder.
+
+

6-maintenance/update.md

@@ -0,0 +1,18 @@
+# Update Yocto
+
+## Get new fixes
+```bash
+cd $POKY
+git pull origin
+```
+
+## Get a new version
+```bash
+cd $POKY
+git fetch origin
+
+VERSION=dizzy
+git checkout -b $VERSION origin/$VERSION
+```
+
+<warn>You may need to clean some/all targets once updated</warn>

README.md

@@ -0,0 +1,16 @@
+# Yocto
+
+This is a book about using Yocto to create custom distributions.
+
+To launch a local web server to read the book, install [gitbook](https://github.com/GitbookIO/gitbook)
+
+```bash
+# Install gitbook
+npm install gitbook-cli -g
+
+# Launch the server
+gitbook serve
+
+# Open the web browser to read this book
+xdg-open http://127.0.0.1:4000/
+```

SUMMARY.md

@@ -0,0 +1,42 @@
+# Summary
+
+
+* ===== Yocto =====
+	* [Introduction](0-intro/projects.md)
+		* [Projects using Yocto](0-intro/projects.md)
+		* [Environment & Setup](0-intro/env.md)
+		* [Glossary & Variables](0-intro/glossary.md)
+	* [Concepts](1-concepts/layer.md)
+		* [Layer](1-concepts/layer.md)
+		* [Package](1-concepts/package.md)
+		* [Recipes](1-concepts/recipes.md)
+		* [Board Support Package (BSP)](1-concepts/bsp.md)
+		* [Machine](1-concepts/machine.md)
+		* [Distribution](1-concepts/distro.md)
+		* [Classes](1-concepts/class.md)
+		* [Image](1-concepts/image.md)
+	* [Usage](2-usage/syntax.md)
+		* [Configuration file syntax](2-usage/syntax.md)
+		* [Creating a Layer](2-usage/layercreate.md)
+		* [Create a Recipe](2-usage/recipecreate.md)
+		* [Create a Machine / Board Support Package](2-usage/machinecreate.md)
+		* [Create a Distribution](2-usage/distrocreate.md)
+		* [Create an image](2-usage/imagecreate.md)
+	* [Build & test](3-buildtest/build.md)
+		* [Build](3-buildtest/build.md)
+		* [wic](3-buildtest/wic.md)
+		* [Qemu](3-buildtest/qemu.md)
+	* [Workflow](4-workflow/general.md)
+		* [General](4-workflow/general.md)
+		* [Debugging Yocto builds](4-workflow/debug.md)
+		* [Adding packages/recipes to image](4-workflow/addpkg.md)
+		* [Creation of a distribution based on poky-tiny](4-workflow/distrocreate.md)
+	* [Misc](5-misc/buildproc.md)
+		* [Build process - Tasks](5-misc/buildproc.md)
+		* [Read-only root filesystem](5-misc/rorootfs.md)
+		* [Custom toolchain](5-misc/toolchain.md)
+		* [Deploy a recipe to a target via ssh](5-misc/deployssh.md)
+		* [Package Management (deb)](5-misc/pkgmgr.md)
+	* [Maintenance](6-maintenance/update.md)
+		* [Update Yocto](6-maintenance/update.md)
+		* [Cleaning](6-maintenance/clean.md)

book.json

@@ -0,0 +1,17 @@
+{
+	"gitbook": "2.x.x",
+	"plugins": ["nestedmd", "autocover"],
+	"styles": {
+		"website": "style.css",
+		"ebook": "style.css",
+		"pdf": "style.css",
+		"mobi": "style.css",
+		"epub": "style.css"
+	},
+	"pluginsConfig": {
+		"autocover": {
+			"title": "Yocto",
+			"author": "Thibaut CHARLES"
+		}
+	}
+}

style.css

@@ -0,0 +1,46 @@
+info, good, warn, err{
+	margin: 10px 0 10px 0;
+	border-left: 4px solid #000;
+	border-radius: 3px;
+	padding: 5px;
+	padding-left: 15px;
+	display: block;
+}
+info p, good p, warn p, err p{
+	margin-bottom: 2px !important;
+}
+
+info {
+	background-color: rgba(0, 200, 255, 0.1);
+	border-left-color: #8BE8FF;
+}
+good {
+	background-color: rgba(0, 255, 22, 0.1);
+	border-left-color: #6DFF7B;
+}
+warn {
+	background-color: rgba(255, 128, 0, 0.1);
+	border-left-color: #FFE28B;
+}
+err {
+	background-color: rgba(255, 0, 0, 0.1);
+	border-left-color: #DFB5B4;
+}
+
+todo::before{
+	color: #F00;
+	content: "TODO";
+	background-color: #0FF;
+	font-weight: bold;
+	padding: 2px;
+	margin-right: 5px;
+}
+
+pre{
+	border-left: 4px solid #A49C8E !important;
+}
+
+
+tbody tr:hover{
+	background-color: #FBFBFB !important;
+}

yocto-notes-public.sublime-project

@@ -0,0 +1,17 @@
+{
+	"folders":
+	[
+		{
+			"path": ".",
+			"folder_exclude_patterns": ["_book","node_modules"]
+		}
+	],
+	"build_systems":
+    [
+        {
+            "name": "Serve via Gitbook",
+            "shell": "true",
+            "shell_cmd": "kill `lsof -i:4000 -t` ; cd $project_path && gitbook serve"
+        }
+    ]
+}