yocto-basic: updated details for recipe syntax and classes

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

1 files changed, 414 insertions, 3 deletions

diff --git a/distribution/yocto-basic/pres_yocto-basic.tex b/distribution/yocto-basic/pres_yocto-basic.tex
index 40f140b..bc09d70 100644
--- a/distribution/yocto-basic/pres_yocto-basic.tex
+++ b/distribution/yocto-basic/pres_yocto-basic.tex
@@ -4,6 +4,153 @@
 \maketitle
 
 \begin{frame}
+\frametitle{Bitbake Overview}
+\begin{itemize}
+\item Classes
+\item Recipes
+\item Layers
+\item Append files
+\item Machines
+\item Build configuration
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+\frametitle{Variable assignments}
+\begin{itemize}
+\item =
+\item ?=
+\item ??=
+\item :=
+\item += / =+
+\item .= / =.
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{Variable assignment with =}
+\begin{verbatim}
+VAR = "value"
+\end{verbatim}
+\begin{itemize}
+	\item normal assignment
+	\item values need to be surrounded by double quotes
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{early default assignment with ?=}
+\begin{verbatim}
+VAR ?= "1"
+VAR ?= "2"
+\end{verbatim}
+\begin{itemize}
+	\item VAR is set to "1" in this example
+	\item if there are multiple assignments using ?= the first one is used
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{late default assignment with ??=}
+\begin{verbatim}
+VAR ??= "1"
+VAR ??= "2"
+\end{verbatim}
+\begin{itemize}
+	\item VAR is set to "2" in this example
+	\item if there are multiple assignments using ??= the last one is used
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{assignment priorities \#1}
+\begin{verbatim}
+VAR_A ??= "12"
+VAR_A ?= "34"
+
+VAR_B ?= "12"
+VAR_B ??= "34"
+\end{verbatim}
+\begin{itemize}
+	\item VAR\_A contains "34"
+	\item VAR\_B contains "12"
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{assignment priorities \#2}
+\begin{verbatim}
+VAR ?= "12"
+VAR ??= "34"
+VAR = "56"
+VAR ?= "78"
+VAR ??= "78"
+\end{verbatim}
+\begin{itemize}
+	\item VAR contains "56"
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{immediate variable expansion with :=}
+\begin{verbatim}
+VAR_A = "11"
+VAR_B = "B:${VAR_A}"
+VAR_A = "22"
+VAR_C := "C:${VAR_A}"
+VAR_A = "33"
+echo ${VAR_A} ${VAR_B} ${VAR_C}
+\end{verbatim}
+\begin{itemize}
+	\item 33 B:33 C:22
+	\item the content of VAR\_C is expanded immediately on assignment
+	\item the content of VAR\_B is expanded on use
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{append (+=) or prepend (=+) a variable}
+\begin{verbatim}
+VAR_A = "12"
+VAR_A += "34"
+VAR_B = "56"
+VAR_B =+ "78"
+\end{verbatim}
+\begin{itemize}
+	\item VAR\_A contains "12 34"
+	\item VAR\_B contains "78 56"
+	\item there are spaces between the appended values
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{append (.=) or prepend (=.) a variable}
+\begin{verbatim}
+VAR_A = "12"
+VAR_A .= "34"
+VAR_B = "56"
+VAR_B =. "78"
+\end{verbatim}
+\begin{itemize}
+	\item VAR\_A contains "1234"
+	\item VAR\_B contains "7856"
+	\item there are no spaces between the appended values
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{assignment debugging}
+\begin{verbatim}
+$ echo 'FOO ??= "123"' >> conf/local.conf
+$ echo 'FOO ?= "456"' >> conf/local.conf
+
+$ bitbake -e | grep FOO
+# $FOO [2 operations]
+FOO="456"
+\end{verbatim}
+\end{frame}
+
+\begin{frame}
 \frametitle{Classes}
 \begin{itemize}
 \item denoted by the .bbclass extension
@@ -15,8 +162,10 @@
 
 \begin{frame}
 \frametitle{Recipes}
+\begin{itemize}
 \item a .bb file inherits classes and populates them with data
 \item bitbake is used to schedule the tasks defined in a recipe
+\end{itemize}
 \end{frame}
 
 \begin{frame}
@@ -25,6 +174,7 @@
 \item used to isolate different types of customizations from each other
 \item e.g. own layer for machine specific stuff, one for own applications
 \item .bbappend files are used to modify recipes from another layer
+\item 'conf/layer.conf' is used to define the recipe location(s)
 \end{itemize}
 \end{frame}
 
@@ -40,15 +190,256 @@
 \end{enumerate}
 \end{frame}
 
+\begin{frame}[fragile]
+\frametitle{recipe skeleton}
+\begin{verbatim}
+SUMMARY = "short description of the package (1 line)"
+DESCRIPTION = "a long version of the description of the package"
+HOMEPAGE = "http://url-of-the-os-project.org"
+LICENSE = "LGPLv2.1"
+
+LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
+                    file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
+                    file://licfile2.txt;endline=50;md5=zzzz
+
+SRC_URI = "file://mysw-1.0.tbz"
+SRC_URI[md5sum] = "xxx"
+SRC_URI[sha256sum] = "yyy"
+
+S = "${WORKDIR}/${PN}-${PV}"
+
+inherit autotools
+\end{verbatim}
+\end{frame}
+
 \begin{frame}
 \frametitle{recipe syntax}
+a recipe normaly consists of a human readable description of the project and
+references to the open-source project and:
+\begin{description}
+\item[LIC*] reference to the used licenses
+\item[SRC\_URI] list of source files (local or remote)
+\item[PV] package-version (retrived from filename name\_version.bb)
+\item[PN] package-name (retrived from filename name\_version.bb)
+\item[P] ${PN}-${PV}
+\item[S] The location in the Build Directory where unpacked recipe source code resides.
+\item[inherit] use a class (or multiple classes)
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{the LICENSE variable}
+list of source licenses for the recipe:
+\begin{itemize}
+\item do not use spaces within individual license names
+\item use spaces between license names
+\item separate license names using | (pipe) when there is a choice between
+ licenses
+\item separate license names using \& (AND) if parts of the code are licensed
+ with different licenses
+\item for standard licenses, use the names of the files in
+ meta/files/common-licenses/ or the SPDXLICENSEMAP
+ \footnote{aps commonly used license names to their SPDX counterparts found in
+ meta/files/common-licenses/. For the default SPDXLICENSEMAP mappings, see the
+ meta/conf/licenses.conf file}
+ flag names defined in meta/conf/licenses.conf
+\item use "CLOSED" for closed source software
+ (LIC\_FILES\_CHKSUM is not needed to be defined then)
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+\frametitle{LIC\_FILE\_CHKSUM variable}
+Checksums of the license text in the recipe source code.
+
+
+This variable tracks changes in license text of the source code files.
+If the license text is changed, it will trigger a build failure,
+which gives the developer an opportunity to review any license change.
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{SRC\_URI variable}
+\begin{verbatim}
+SRC_URI = "<protocol>://<host>/<path>;<OptionA=xxx>;<OptionB=xxx>"
+\end{verbatim}
+multiple urls can be set in a SRC\_URI variable:
+\begin{verbatim}
+SRC_URI = "<url1>;name=url1 <url2>;name=url2"
+\end{verbatim}
+for each url a md5 and sha256 checksum needs to be added:
+\begin{verbatim}
+SRC_URI[url1.md5sum] = xxx
+SRC_URI[url1.sha256sum] = yyy
+SRC_URI[url2.md5sum] = zzz
+SRC_URI[url2.sha256sum] = xyz
+\end{verbatim}
+To get these checksums don't specify them and run a build and copy them from
+the error message. (Don't use md5sum or sha256sum on the commandline; they
+produce a different checksum.)
+\end{frame}
+
+\begin{frame}
+\frametitle{local SRC\_URI (file://)}
+The path is relative to the FILESPATH variable. To modify the FILESPATH use
+FILESEXTRAPATH.
+
+Additional files are searched in subdirectories of the directory in which the
+recipe file (.bb) or append file (.bbappend) resides:
+\begin{description}
+\item[\${BPN}] base recipe name without any special suffix or version numbers.
+\item[\${BP} - \${BPN}-\${PV}] base recipe name and version but without any special package name suffix.
+\item[files] files within a directory, which is named files and is also alongside the recipe or append file. 
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{the BPN variable}
+\begin{itemize}
+\item bare name of the recipe
+\item version of PN but without suffixes specified in SPECIAL\_PKGSUFFIX
+  (-common, -native, -cross)
+\item version of PN but without prefixes specified in MLPREFIX (lib64-, lib32-)
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+\frametitle{remote SRC\_URI}
+\begin{description}
+\item[bzr://]Bazaar revision control repository
+\item[git://]Git revision control repository
+\item[osc://]OSC (OpenSUSE Build service) revision control repository
+\item[ccrc://]ClearCase repository
+\item[http://]Internet using http
+\item[https://]Internet using https
+\item[ftp://]Internet using ftp
+\item[cvs://]CVS revision control repository
+\item[hg://]Mercurial (hg) revision control repository
+\item[p4://]Perforce (p4) revision control repository
+\item[ssh://]secure shell
+\item[svn://]Subversion (svn) revision control repository
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{SRC\_URI patch options}
+standard options
+\begin{description}
+\item[apply=no] apply patch or not; default is yes
+\item[striplevel=0] striplevel to use when applying a patch; default is 1
+\item[patchdir=\${S}/foo] directory in which the patch should be applied;
+ default is \${S}
+\end{description}
+\end{frame}
+\begin{frame}
+\frametitle{SRC\_URI patch options \#2}
+specific options
 \begin{description}
-\item [inherit] use a class (or multiple classes)
-\item [PV] package-version (retrived from filename name\_version.bb)
-\item [PN] package-name (retrived from filename name\_version.bb)
+\item[mindate] apply patch only if SRCDATE
+ \footnote{The date of the source code used to build the package.
+ This variable applies only if the source was fetched from a
+ Source Code Manager (SCM)} is equal to or greater than mindate
+\item[maxdate] apply patch only if SRCDATE is not later than maxdate
+\item[minrev] apply the patch only if SRCREV
+ \footnote{The revision of the source code used to build the package.
+ This variable applies to Subversion, Git, Mercurial and Bazaar only}
+ is equal to or greater than minrev
+\item[maxrev] apply patch only if SRCREV is not later than maxrev
+\item[rev] apply patch only if SRCREV is equal to rev
+\item[notrev] apply patch only if SRCREV is not equal to rev
 \end{description}
 \end{frame}
 
+\begin{frame}
+\frametitle{SRC\_URI options}
+\begin{description}
+\item[unpack=no] controls if an archive is unpacked; default is yes
+\item[subdir=bla] places the file (or extracts its contents) into the
+ specified subdirectory of WORKDIR
+ \footnote{${TMPDIR}/work/${MULTIMACH\_TARGET\_SYS}/${PN}/${EXTENDPE}${PV}-${PR}; 
+ eg. poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0}
+\item[name=mydl] name to be used for association with SRC\_URI checksums when
+ you have more than one file specified in SRC\_URI
+\item[downloadfilename=my.tar.gz] the filename used when storing the downloaded file
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{inherit}
+inherit is used to use the functionality defined in a .bblcass file. Popular
+predefined classes are:
+\begin{itemize}
+\item allarch
+\item archiver
+\item autotools / autotools-brokensep
+\item bin\_package
+\item cmake
+\item cpan
+\item distutils / setuptools
+\item kernel / module
+\item mime
+\item qmake / qmake2
+\item qt4e / qt4x11
+\item scons
+\item systemd
+\item u-boot
+\item vala
+\end{itemize}
+\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}
+
+\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}
@@ -73,6 +464,26 @@ PREFEREED\_PROVIDER\_virtual/kernel = "linux-yocto"
 \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
+
+% http://www.yoctoproject.org/docs/1.6/dev-manual/dev-manual.html#usingpoky-extend-customimage-imagefeatures
+\end{frame}
+
+\begin{frame}
 \frametitle{Machines}
 bla
 \end{frame}