From c134968005061da0b876893a9fadd2594fd73d8b Mon Sep 17 00:00:00 2001 From: "Crom (Thibaut CHARLES)" Date: Tue, 21 Jul 2015 14:22:25 +0200 Subject: [PATCH] Public parts taken from private repo --- .gitignore | 5 + 0-intro/env.md | 45 +++++++ 0-intro/glossary.md | 29 +++++ 0-intro/projects.md | 5 + 1-concepts/bsp.md | 11 ++ 1-concepts/class.md | 29 +++++ 1-concepts/distro.md | 9 ++ 1-concepts/image.md | 18 +++ 1-concepts/layer.md | 60 ++++++++++ 1-concepts/machine.md | 3 + 1-concepts/package.md | 10 ++ 1-concepts/recipes.md | 50 ++++++++ 2-usage/distrocreate.md | 30 +++++ 2-usage/imagecreate.md | 20 ++++ 2-usage/layercreate.md | 67 +++++++++++ 2-usage/machinecreate.md | 183 +++++++++++++++++++++++++++++ 2-usage/recipecreate.md | 103 ++++++++++++++++ 2-usage/syntax.md | 53 +++++++++ 3-buildtest/build.md | 29 +++++ 3-buildtest/qemu.md | 44 +++++++ 3-buildtest/wic.md | 76 ++++++++++++ 4-workflow/addpkg.md | 16 +++ 4-workflow/debug.md | 25 ++++ 4-workflow/distrocreate.md | 35 ++++++ 4-workflow/general.md | 25 ++++ 5-misc/buildproc.md | 84 +++++++++++++ 5-misc/deployssh.md | 3 + 5-misc/pkgmgr.md | 37 ++++++ 5-misc/rorootfs.md | 5 + 5-misc/toolchain.md | 6 + 6-maintenance/clean.md | 25 ++++ 6-maintenance/update.md | 18 +++ README.md | 16 +++ SUMMARY.md | 42 +++++++ book.json | 17 +++ style.css | 46 ++++++++ yocto-notes-public.sublime-project | 17 +++ 37 files changed, 1296 insertions(+) create mode 100644 .gitignore create mode 100644 0-intro/env.md create mode 100644 0-intro/glossary.md create mode 100644 0-intro/projects.md create mode 100644 1-concepts/bsp.md create mode 100644 1-concepts/class.md create mode 100644 1-concepts/distro.md create mode 100644 1-concepts/image.md create mode 100644 1-concepts/layer.md create mode 100644 1-concepts/machine.md create mode 100644 1-concepts/package.md create mode 100644 1-concepts/recipes.md create mode 100644 2-usage/distrocreate.md create mode 100644 2-usage/imagecreate.md create mode 100644 2-usage/layercreate.md create mode 100644 2-usage/machinecreate.md create mode 100644 2-usage/recipecreate.md create mode 100644 2-usage/syntax.md create mode 100644 3-buildtest/build.md create mode 100644 3-buildtest/qemu.md create mode 100644 3-buildtest/wic.md create mode 100644 4-workflow/addpkg.md create mode 100644 4-workflow/debug.md create mode 100644 4-workflow/distrocreate.md create mode 100644 4-workflow/general.md create mode 100644 5-misc/buildproc.md create mode 100644 5-misc/deployssh.md create mode 100644 5-misc/pkgmgr.md create mode 100644 5-misc/rorootfs.md create mode 100644 5-misc/toolchain.md create mode 100644 6-maintenance/clean.md create mode 100644 6-maintenance/update.md create mode 100644 README.md create mode 100644 SUMMARY.md create mode 100644 book.json create mode 100644 style.css create mode 100644 yocto-notes-public.sublime-project diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..31aadbe --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +_book/ +node_modules/ +*.html +*.pdf +*.sublime-workspace \ No newline at end of file diff --git a/0-intro/env.md b/0-intro/env.md new file mode 100644 index 0000000..e616360 --- /dev/null +++ b/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) diff --git a/0-intro/glossary.md b/0-intro/glossary.md new file mode 100644 index 0000000..38c4216 --- /dev/null +++ b/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) diff --git a/0-intro/projects.md b/0-intro/projects.md new file mode 100644 index 0000000..4f34b72 --- /dev/null +++ b/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, ...) \ No newline at end of file diff --git a/1-concepts/bsp.md b/1-concepts/bsp.md new file mode 100644 index 0000000..3e4c3c7 --- /dev/null +++ b/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. + +Most BSP are found in the `meta-yocto-bsp` layer: `$POKY/meta-yocto-bsp/conf/machine/` + +The BSP is bound to machine definition + +improve this \ No newline at end of file diff --git a/1-concepts/class.md b/1-concepts/class.md new file mode 100644 index 0000000..681c1b8 --- /dev/null +++ b/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. + +Classes files have the `.bbclass` extension + + +## 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 +``` diff --git a/1-concepts/distro.md b/1-concepts/distro.md new file mode 100644 index 0000000..089e470 --- /dev/null +++ b/1-concepts/distro.md @@ -0,0 +1,9 @@ +# Distribution + +The distribution defines how softwares (recipes) are packed together to build the OS. + +Most distributions are found in the `meta-yocto` layer: `$POKY/meta-yocto/conf/distro/` + +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. \ No newline at end of file diff --git a/1-concepts/image.md b/1-concepts/image.md new file mode 100644 index 0000000..be42454 --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/1-concepts/layer.md b/1-concepts/layer.md new file mode 100644 index 0000000..0f3dd67 --- /dev/null +++ b/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 \ + " +``` + +The layer can be in another directory than under `$POKY`. + + +Don't forget to add any newly created layer in this list to use it + + +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) + diff --git a/1-concepts/machine.md b/1-concepts/machine.md new file mode 100644 index 0000000..6c8b10c --- /dev/null +++ b/1-concepts/machine.md @@ -0,0 +1,3 @@ +# Machine + +Check what is the difference with BSP \ No newline at end of file diff --git a/1-concepts/package.md b/1-concepts/package.md new file mode 100644 index 0000000..675e8ca --- /dev/null +++ b/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). \ No newline at end of file diff --git a/1-concepts/recipes.md b/1-concepts/recipes.md new file mode 100644 index 0000000..3be8ba1 --- /dev/null +++ b/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` + + +Many recipes are found in each layer at `$POKY/meta*` in the `recipe-*` folders. + + +## 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} +} +``` \ No newline at end of file diff --git a/2-usage/distrocreate.md b/2-usage/distrocreate.md new file mode 100644 index 0000000..fb1c8a3 --- /dev/null +++ b/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| +|`DISTRO_EXTRA_RRECOMMENDS`|List of package that will installed if they are available, for example kernel modules| +|`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)| + +why DISTRO_EXTRA_RRECOMMENDS + + +Don't forget to update `DISTRO` in `$POKY/build/conf/local.conf` to use your distribution + diff --git a/2-usage/imagecreate.md b/2-usage/imagecreate.md new file mode 100644 index 0000000..3d2f34c --- /dev/null +++ b/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" +``` \ No newline at end of file diff --git a/2-usage/layercreate.md b/2-usage/layercreate.md new file mode 100644 index 0000000..8909045 --- /dev/null +++ b/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" +``` + + +Once created, you will need to add the layer path in the `BBLAYER` variable, usually defined in `$POKY/build/conf/local.conf` + + + +## 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 [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) +``` \ No newline at end of file diff --git a/2-usage/machinecreate.md b/2-usage/machinecreate.md new file mode 100644 index 0000000..f6612c6 --- /dev/null +++ b/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` + + +At this time, there is no practical tool to create configuration fragments. + + + +#### `.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 + + + +```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 + + + +The script `yocto-bsp create ` creates a layer named `` with a BSP for the architecture `` into.
+You can get the list of supported arch with `yocto-bsp list karch` + + +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 +``` + +Don't forget to add the layer to `BBLAYER` if you want to use it + + +### 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 +``` diff --git a/2-usage/recipecreate.md b/2-usage/recipecreate.md new file mode 100644 index 0000000..2c9f213 --- /dev/null +++ b/2-usage/recipecreate.md @@ -0,0 +1,103 @@ +# Create a Recipe + +## Creation + +It may be better to use already existing recipes and customize them. + +A recipe file must be named `_.bb` (lowercase only) + +To be enabled, the recipe must be available in the `BBFILES` variable located in the `conf/layer.conf` file + +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 + +# 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}`.
Automatically generated if the downloaded package is named `-.*`| +|`do_patch()`|Applies patches to source code.
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_).
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
Automatically generated for _Autotools_ or _CMake_| +|`do_install()`|Commands to install on the system (into `${D}${bindir}`)
Automatically generated for _Autotools_ or _CMake_| +|` pkg_postinst_()`|__Replace `` with the recipe name__
Contains the commands to execute after the package installation.
`pkg_postinst_yolo(){`
`#!/bin/sh -e`
`cp A B`
`}`| + +### 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 ` diff --git a/2-usage/syntax.md b/2-usage/syntax.md new file mode 100644 index 0000000..bb3cb98 --- /dev/null +++ b/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" +} +``` + + +- `${VAR}` is a Yocto variable. +- `$VAR` is a shell variable. +- They are very different ! + \ No newline at end of file diff --git a/3-buildtest/build.md b/3-buildtest/build.md new file mode 100644 index 0000000..3a3d099 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/3-buildtest/qemu.md b/3-buildtest/qemu.md new file mode 100644 index 0000000..5ee3863 --- /dev/null +++ b/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" +``` + + +`-cpu n270` Configure the guest CPU to be Intel Atom. `-cpu help` lists available CPUs. + + +## 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 +``` diff --git a/3-buildtest/wic.md b/3-buildtest/wic.md new file mode 100644 index 0000000..d70bcbf --- /dev/null +++ b/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` + + +You need to source `$POKY/oe-init-build-env` to use wic + + +## 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" +``` + +the syntax doesn't support ` \\\n` line escape + + +## 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.
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 ? + + +#### Bootloader +```sh +bootloader [args] +``` + +`args`|_ +---|--- +`--timeout`|Timeout in seconds before booting default option +`--append`|Kernel command line arguments to bee added when booting. \ No newline at end of file diff --git a/4-workflow/addpkg.md b/4-workflow/addpkg.md new file mode 100644 index 0000000..a4c2e83 --- /dev/null +++ b/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" +``` \ No newline at end of file diff --git a/4-workflow/debug.md b/4-workflow/debug.md new file mode 100644 index 0000000..d015174 --- /dev/null +++ b/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 +``` diff --git a/4-workflow/distrocreate.md b/4-workflow/distrocreate.md new file mode 100644 index 0000000..c503e59 --- /dev/null +++ b/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" +``` \ No newline at end of file diff --git a/4-workflow/general.md b/4-workflow/general.md new file mode 100644 index 0000000..1e3b2ac --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/5-misc/buildproc.md b/5-misc/buildproc.md new file mode 100644 index 0000000..cd08c99 --- /dev/null +++ b/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_` + + +For all packages selected with `PACKAGE_CLASSES`, packages are downloaded into `DL_DIR` + +Default: `poky/build/tmp/deploy///` + +- 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/ +└── -poky-linux or -poky-linux + └── + └── - : The package is built from here + └── - : 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/ +└── -poky-linux or -poky-linux + └── + └── - +``` + +From the work directory: +- `-`: 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//a/`) + +## `do_rootfs` + + +Unpacks the packages from the package feed area (`poky/build/tmp/deploy///`) 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 diff --git a/5-misc/deployssh.md b/5-misc/deployssh.md new file mode 100644 index 0000000..f3af963 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/5-misc/pkgmgr.md b/5-misc/pkgmgr.md new file mode 100644 index 0000000..8161661 --- /dev/null +++ b/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/ ./ +#... +``` + +Using the layer meta-ab3000, you can set the variable `DEBIAN_REPO_ADDRESS` and the main yocto repositories will be automatically set + +## Build all packages +```bash +bitbake world +``` +Will build all existing packages and prepare deb packages ready to be deployed. \ No newline at end of file diff --git a/5-misc/rorootfs.md b/5-misc/rorootfs.md new file mode 100644 index 0000000..992cd89 --- /dev/null +++ b/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) + + diff --git a/5-misc/toolchain.md b/5-misc/toolchain.md new file mode 100644 index 0000000..4062415 --- /dev/null +++ b/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 diff --git a/6-maintenance/clean.md b/6-maintenance/clean.md new file mode 100644 index 0000000..0e6aa40 --- /dev/null +++ b/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. + + diff --git a/6-maintenance/update.md b/6-maintenance/update.md new file mode 100644 index 0000000..014fa96 --- /dev/null +++ b/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 +``` + +You may need to clean some/all targets once updated \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..9a23445 --- /dev/null +++ b/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/ +``` \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..c570687 --- /dev/null +++ b/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) diff --git a/book.json b/book.json new file mode 100644 index 0000000..c3bd78d --- /dev/null +++ b/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" + } + } +} diff --git a/style.css b/style.css new file mode 100644 index 0000000..d24f526 --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/yocto-notes-public.sublime-project b/yocto-notes-public.sublime-project new file mode 100644 index 0000000..0097fd3 --- /dev/null +++ b/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" + } + ] +}