describe all tasks and a lot of variables

Signed-off-by: Manuel Traut <manut@linutronix.de>

2 files changed, 256 insertions, 89 deletions

diff --git a/distribution/yocto-advanced/pres_yocto-advanced.tex b/distribution/yocto-advanced/pres_yocto-advanced.tex
index f249803..a3c6b41 100644
--- a/distribution/yocto-advanced/pres_yocto-advanced.tex
+++ b/distribution/yocto-advanced/pres_yocto-advanced.tex
@@ -35,8 +35,94 @@ bla
 \end{frame}
 
 \begin{frame}
-\frametitle{define an image}
-bla
+\frametitle{create bootable images for x86}
+t.b.d.
+
+The boot-directdisk class creates an image that can be placed directly onto a
+hard disk using dd and then booted. The image uses SYSLINUX.
+
+The end result is a 512 boot sector populated with a Master Boot Record (MBR)
+and partition table followed by an MSDOS FAT16 partition containing SYSLINUX
+and a Linux kernel completed by the ext2 and ext3 root filesystems.
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle {bootable image for embedded device}
+t.b.d. use IMAGE\_FEATURES
+% http://www.yoctoproject.org/docs/1.6/ref-manual/ref-manual.html#ref-features-image
+
+% http://www.yoctoproject.org/docs/1.6/dev-manual/dev-manual.html#usingpoky-extend-customimage-imagefeatures
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{user and group configuration}
+use this in an image recipe:
+\begin{verbatim}
+inherit extrausers
+EXTRA_USERS_PARAMS = "\
+    useradd -p '' tester; \
+    groupadd developers; \
+    userdel nobody; \
+    groupdel -g video; \
+    groupmod -g 1020 developers; \
+    usermod -s /bin/sh tester; \
+    "
+\end{verbatim}
+or the useradd class, for an example see useradd-example.bb
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{external sources}
+e.g. for a heavily customized kernel
+\begin{itemize}
+\item kernel source directory on the development machine
+\item inherit externalsrc class
+\item set EXTERNALSRC variable to point to your external source code
+\end{itemize}
+
+this local.conf extension:
+\begin{verbatim}
+INHERIT += "externalsrc"
+EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
+\end{verbatim}
+overrides the SOURCE\_URI of pn-myrecipe.bb
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{blacklist packages}
+To blacklist a package, inherit the blacklist.bbclass globally and set
+PNBLACKLIST for each recipe you wish to blacklist.
+
+
+Specify the PN value as a variable flag (varflag) and provide a reason,
+which is reported, if the package is requested to be built as the value:
+\begin{verbatim}
+INHERIT += "blacklist"
+PNBLACKLIST[exoticware] = "Not supported by our organization."
+\end{verbatim}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{Providers}
+\begin{verbatim}
+--8<- -my-kernel\_3.16.bb --
+PROVIDES += "virtual/kernel"
+--8<------------------------
+\end{verbatim}
+
+PREFEREED\_PROVIDER\_virtual/kernel = "linux-yocto"
+\end{frame}
+
+\begin{frame}
+\frametitle{Preferences}
+\begin{itemize}
+\item PREFERRED\_VERSION is used to specify a particular version
+\item by default, files have a preference of "0"
+\item setting DEFAULT\_PREFERENCE to "-1" makes the recipe unlikely to be used
+	unless it is explicitly referenced.
+\item setting DEFAULT\_PREFERENCE to "1" makes it likely the recipe is used
+\item PREFERRED\_VERSION overrides any DEFAULT\_PREFERENCE setting
+\end{itemize}
 \end{frame}
 
 \input{tailpres}
diff --git a/distribution/yocto-basic/pres_yocto-basic.tex b/distribution/yocto-basic/pres_yocto-basic.tex
index bc09d70..e4bf5fe 100644
--- a/distribution/yocto-basic/pres_yocto-basic.tex
+++ b/distribution/yocto-basic/pres_yocto-basic.tex
@@ -10,8 +10,12 @@
 \item Recipes
 \item Layers
 \item Append files
+\item Tasks
 \item Machines
 \item Build configuration
+\item Boundary Sabrelite Imagebuild
+\item TI Beaglebone Black Imagebuild
+\item Commands and Debug methods
 \end{itemize}
 \end{frame}
 
@@ -179,6 +183,31 @@ FOO="456"
 \end{frame}
 
 \begin{frame}
+\frametitle{Layers}
+Layers are a way to manage extensions, and customizations to the system.
+
+Layers
+\begin{itemize}
+\item extend, add, replace or modify recipes
+\item add or replace bbclass files
+\item add or modify configuration settings
+\item are added and ordered via BBLAYERS variable in build/conf/bblayers.conf
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+\frametitle{Layers}
+Best Practice: Layers should be grouped by functionality
+\begin{itemize}
+\item Custom Toolchains (compilers, debuggers, profiling tools)
+\item Distribution specifications (i.e. meta-yocto)
+\item BSP/Machine settings (i.e. meta-yocto-bsp)
+\item Functional areas (selinux, networking, etc)
+\item Project specific changes
+\end{itemize}
+\end{frame}
+
+\begin{frame}
 \frametitle{typical recipe progressing}
 \begin{enumerate}
 \item fetch source files
@@ -388,107 +417,159 @@ predefined classes are:
 \end{frame}
 
 \begin{frame}
-\frametitle{The insane class}
-t.b.d.
-\end{frame}
-
-\begin{frame}[fragile]
-\frametitle{user and group configuration}
-use this in an image recipe:
-\begin{verbatim}
-inherit extrausers
-EXTRA_USERS_PARAMS = "\
-    useradd -p '' tester; \
-    groupadd developers; \
-    userdel nobody; \
-    groupdel -g video; \
-    groupmod -g 1020 developers; \
-    usermod -s /bin/sh tester; \
-    "
-\end{verbatim}
-or the useradd class, for an example see useradd-example.bb
-\end{frame}
-
-\begin{frame}[fragile]
-\frametitle{external sources}
-e.g. for a heavily customized kernel
-\begin{itemize}
-\item kernel source directory on the development machine
-\item inherit externalsrc class
-\item set EXTERNALSRC variable to point to your external source code
-\end{itemize}
-
-this local.conf extension:
-\begin{verbatim}
-INHERIT += "externalsrc"
-EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
-\end{verbatim}
-overrides the SOURCE\_URI of pn-myrecipe.bb
-\end{frame}
+\frametitle{Append files}
+a append file must be named after the base package:
 
-\begin{frame}[fragile]
-\frametitle{blacklist packages}
-To blacklist a package, inherit the blacklist.bbclass globally and set
-PNBLACKLIST for each recipe you wish to blacklist.
+<base-pn>\_<base-pv>.bbappend
 
+<base-pv> can be replaced by \% to match all versions.
 
-Specify the PN value as a variable flag (varflag) and provide a reason,
-which is reported, if the package is requested to be built as the value:
-\begin{verbatim}
-INHERIT += "blacklist"
-PNBLACKLIST[exoticware] = "Not supported by our organization."
-\end{verbatim}
-\end{frame}
+They are typically used to modify or extend the functionality of the base
+recipe.
 
-\begin{frame}[fragile]
-\frametitle{Providers}
-\begin{verbatim}
---8<- -my-kernel\_3.16.bb --
-PROVIDES += "virtual/kernel"
---8<------------------------
-\end{verbatim}
-
-PREFEREED\_PROVIDER\_virtual/kernel = "linux-yocto"
+It's recommended by the Yocto project to use bbappend files instead of copying
+and modyfiing a recipe in an own layer.
 \end{frame}
 
 \begin{frame}
-\frametitle{Preferences}
-\begin{itemize}
-\item PREFERRED\_VERSION is used to specify a particular version
-\item by default, files have a preference of "0"
-\item setting DEFAULT\_PREFERENCE to "-1" makes the recipe unlikely to be used
-	unless it is explicitly referenced.
-\item setting DEFAULT\_PREFERENCE to "1" makes it likely the recipe is used
-\item PREFERRED\_VERSION overrides any DEFAULT\_PREFERENCE setting
-\end{itemize}
+\frametitle{Tasks}
+\begin{description}
+\item [do\_bundle\_initramfs] combines an initial ramdisk image and kernel
+	together to form a single image
+\item [do\_checkuri] validates the SRC\_URI value
+\item [do\_checkuriall] validates the SRC\_URI value for all recipes required
+	to build a target"
+\item [do\_clean] removes all output files for a target
+\item [do\_cleanall] removes all output files, shared state cache, and
+	downloaded source files for a target
+\item [do\_cleansstate] removes all output files and shared state cache for a
+	target
+\item [do\_compile] compiles the source in the compilation directory
+\item [do\_compile\_kernelmodules] compiles loadable modules for the Linux
+	kernel
+\item [do\_compile\_ptest\_base] compiles the runtime test suite included in
+	the software being built
+\item [do\_configure] configures the source by enabling and disabling any
+	build-time and configuration options for the software being built
+\item [do\_configure\_ptest\_base] configures the runtime test suite included
+	in the software being built
+\item [do\_deploy] writes deployable output files to the deploy directory
+\item [do\_devshell] starts a shell with the environment set up for
+	development/debugging
+\item [do\_diffconfig] compares the old and new config files after running
+	do\_menuconfig for the kernel
+\item [do\_fetch] fetches the source code
+\item [do\_fetchall] fetches all remote sources required to build a target
+\item [do\_generate\_qt\_config\_file] writes a qt.conf file for building a
+	Qt-based application
+\item [do\_install] copies files from the compilation directory to a holding
+	area
+\item [do\_install\_ptest\_base] copies the runtime test suite files from the
+	compilation directory to a holding area
+\item [do\_kernel\_checkout] checks out source/meta branches for a linux-yocto
+	style kernel
+\item [do\_kernel\_configcheck] validates the kernel configuration for a
+	linux-yocto style kernel
+\item [do\_kernel\_configme] assembles the kernel configuration for a
+	linux-yocto style kernel
+\item [do\_kernel\_link\_vmlinux] creates a symbolic link in arch/\$arch/boot
+	for vmlinux kernel images
+\item [do\_listtasks] lists all defined tasks for a target
+\item [do\_menuconfig] runs 'make menuconfig' for the kernel
+\item [do\_package] analyzes the content of the holding area and splits it
+	into subsets based on available packages and files
+\item [do\_package\_index] creates or updates the index in the Package Feed
+	area
+\item [do\_package\_write] creates the actual packages and places them in the
+	Package Feed area
+\item [do\_package\_write\_deb] creates the actual DEB packages and places
+	them in the Package Feed area
+\item [do\_package\_write\_ipk] creates the actual IPK packages and places
+	them in the Package Feed area
+\item [do\_package\_write\_rpm] creates the actual RPM packages and places
+	them in the Package Feed area
+\item [do\_package\_write\_tar] creates tar archives for packages and places
+	them in the Package Feed area
+\item [do\_packagedata] creates package metadata used by the build system to
+	generate the final packages
+\item [do\_patch] locates patch files and applies them to the source code
+\item [do\_populate\_lic] writes license information for the recipe that is
+	collected later when the image is constructed
+\item [do\_populate\_sdk] creates the file and directory structure for an
+	installable SDK
+\item [do\_populate\_sysroot] copies a subset of files installed by
+	do\_install into the sysroot in order to make them available to other
+	recipes
+\item [do\_rm\_work] removes work files after the build system has finished
+	with them
+\item [do\_rm\_work\_all] top-level task for removing work files after the
+	build system has finished with them
+\item [do\_rootfs] creates the root filesystem (file and directory structure)
+	for an image
+\item [do\_savedefconfig] creates a minimal Linux kernel configuration file
+\item [do\_sizecheck] checks the size of the kernel image against
+	KERNEL\_IMAGE\_MAXSIZE (if set)
+\item [do\_spdx] a build stage that takes the source code and scans it on a
+	remote FOSSOLOGY server in order to produce an SPDX document
+\item [do\_strip] strips unneeded sections out of the Linux kernel image
+\item [do\_testimage] boots an image and performs runtime tests within the
+	image
+\item [do\_testimage\_auto] boots an image and performs runtime tests within
+	the image immediately after it has been built
+\item [do\_uboot\_mkimage] creates a uImage file from the kernel for the
+	U-Boot bootloader
+\item [do\_unpack] unpacks the source code into a working directory
+\item [do\_validate\_branches] ensures that the source/meta branches are on
+	the locations specified by their SRCREV values for a linux-yocto style
+	kernel"
+\item [do\_vmdkimg] creates a .vmdk image for use with VMware and compatible
+	virtual machine hosts"
+\end{description}
 \end{frame}
 
 \begin{frame}
-\frametitle{create bootable images for x86}
-t.b.d.
-
-The boot-directdisk class creates an image that can be placed directly onto a
-hard disk using dd and then booted. The image uses SYSLINUX.
-
-The end result is a 512 boot sector populated with a Master Boot Record (MBR)
-and partition table followed by an MSDOS FAT16 partition containing SYSLINUX
-and a Linux kernel completed by the ext2 and ext3 root filesystems.
-\end{frame}
-
-\begin{frame}[fragile]
-\frametitle {bootable image for embedded device}
-t.b.d. use IMAGE\_FEATURES
-% http://www.yoctoproject.org/docs/1.6/ref-manual/ref-manual.html#ref-features-image
+\frametitle{Machines}
+machine configs are stored in the layers: conf/machine/*
 
-% http://www.yoctoproject.org/docs/1.6/dev-manual/dev-manual.html#usingpoky-extend-customimage-imagefeatures
-\end{frame}
+Settings can be splitted in different include *.inc files. E.g. one include for
+CPU that is used by the SoC inc file, that is used by the Board .conf file.
 
-\begin{frame}
-\frametitle{Machines}
-bla
+Typically these variables are set in the machine config:
+\begin{description}
+	\item[SOC\_FAMILY] groups together machines based upon the same family of SOC
+		(System On Chip)
+	\item [UBOOT\_MACHINE] value passed on the make command line when building a
+		U-Boot image
+	\item [UBOOT\_MAKE\_TARGET] target called in the Makefile
+	\item [UBOOT\_ENTRYPOINT] entry point for the U-Boot image
+	\item [PREFERRED\_PROVIDER\_virtual/kernel] default kernel
+	\item [KERNEL\_DEVICETREE] default devicetree
+	\item [KERNEL\_IMAGETYPE] type of kernel to build for a device,
+		defaults to 'zImage'
+	\item [MACHINEOVERRIDES] lists overrides specific to the current machine.
+		By default, this list includes the value of MACHINE. This can be used in
+		recipes; e.g. MACHINEOVERRIDES =. "mymachine" and in the recipe
+		SRC\_URI\_append\_mymachine = "file://mymachine-quirk.patch"
+	\item [MACHINE\_FEATURES] list of hardware features the MACHINE supports
+	\item [MACHINE\_EXTRA\_RRECOMMENDS] list of machine-specific packages to
+		install as part of the image being built that are not essential for booting
+		the machine. The image being built has no build dependencies on the packages
+		in this list.
+	\item [SERIAL\_CONSOLE] speed and device for the serial port used to attach
+		the serial console. This variable is given to the kernel as the 'console'
+		parameter. After booting occurs, getty is started on that port so remote
+		login is possible.
+	\item [PREFERRED\_VERSION\_xserver-xorg] compatible xserver version
+	\item [DEFAULTTUNE] e.g. armv6hf or cortexa8hf-neon, x86-64, \dots
+	\item [IMAGE\_FSTYPES] formats for the rootfs, e.g. "ext3 tar.bz2"
+	\item [IMAGE\_CLASSES] list of classes that all images should inherit, default
+		is image\_types
+	\item [TUNE\_FEATURES] e.g. "armv7a vfp neon"
+	\item [TUNEVALID] Descriptions, stored as flags, of valid tuning features
+	\item [TUNECONFLICTS] list of conflicting features for a given feature
+\end{description}
 \end{frame}
 
-
 \begin{frame}
 \frametitle{Configuration}
 bla