Merge remote-tracking branch 'remotes/origin/devel/manut/yocto'

Integration of Manu's latest Yocto topics (autotools)

1 files changed, 681 insertions, 0 deletions

diff --git a/distribution/yocto-basic/yocto-workflow.tex b/distribution/yocto-basic/yocto-workflow.tex
new file mode 100644
index 0000000..3810acb
--- /dev/null
+++ b/distribution/yocto-basic/yocto-workflow.tex
@@ -0,0 +1,681 @@
+\subsection{Workflow}
+\begin{frame}[fragile]
+\includegraphics[width=\textwidth]{images/yocto-workflow}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{retrieve poky}
+\begin{verbatim}
+% git clone http://git.yoctoproject.org/git/poky
+% cd poky
+% git checkout origin/krogoth -b krogoth -t
+\end{verbatim}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{prepare environment}
+\begin{itemize}
+\item bitbake is typically not installed into regular search paths
+\item the environment of the bash is modified to find the commands
+\item non-bash shells are not supported
+\end{itemize}
+\begin{verbatim}
+% . ./oe-init-buildenv <builddir>
+\end{verbatim}
+\begin{itemize}
+\item is used to modify the environment and change the CWD to <builddir>
+\item ./oe-init-buildenv-memres is used to keep the bitbake-server running
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+\frametitle{classes}
+\begin{itemize}
+\item denoted by the .bbclass extension
+\item base.bbclass is automatically included by all other classes and recipes.
+\item common tasks and there execution order is defined in base.bbclass
+\item tasks can be added, overridden, extended or used by other classes
+\end{itemize}
+\end{frame}
+
+\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}
+\frametitle{layers}
+\begin{itemize}
+\item a folder containing recipes, configs and classes
+\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 extend, add, replace or modify recipes
+\item add or replace class files
+\item 'conf/layer.conf' is used to configure the layer
+\item are added and ordered via BBLAYERS variable in build/conf/bblayers.conf
+\item 'bitbake-layers show-layers' is used to show used layers
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+\frametitle{layers \#2}
+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
+\item a layer is typically organized as a git repository
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+	\frametitle{directory layout}
+	\begin{verbatim}
+poky
+├── bitbake
+├── documentation
+├── meta
+├── meta-selftest
+├── meta-skeleton
+├── meta-yocto
+├── meta-yocto-bsp
+└── scripts
+\end{verbatim}
+\end{frame}
+
+\subsection{Variable assignments}
+\begin{frame}
+\frametitle{available operators}
+\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}
+\pause
+\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}
+\pause
+\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}
+\pause
+\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}
+\pause
+\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}
+\pause
+\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}
+\pause
+\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}
+\pause
+\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}
+\pause
+\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}
+
+\subsection{Recipes}
+\begin{frame}
+\frametitle{typical progressing}
+\begin{enumerate}
+\item fetch source files
+\item extract sources
+\item patch sources
+\item configure sources
+\item compilation
+\item packaging
+\end{enumerate}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{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{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.
+\vspace{2em}
+
+
+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}
+\pause
+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}[fragile]
+\frametitle{local SRC\_URI (file://)}
+The path is relative to the FILESPATH variable. To modify the FILESPATH use
+FILESEXTRAPATH.
+\vspace{2em}
+
+
+Additional files are searched in subdirectories of the directory in which the
+recipe file (.bb) or append file (.bbappend) resides.
+
+To find out which paths can be used, it is best practice to use
+\begin{verbatim}
+$ bitbake -e <recipe-name> | grep FILESPATH
+\end{verbatim}
+\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}
+\begin{itemize}
+	\item patches are applied in the order they appear in SRC\_URI
+	\item quilt is used to apply the patches
+\end{itemize}
+\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}
+\begin{description}
+\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 autotools
+\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}
+
+\subsection{Append files}
+\begin{frame}
+\frametitle{basics}
+\begin{itemize}
+	\item are typically used to modify or extend the functionality of the base
+		recipe
+	\item it's recommended by the Yocto project to use bbappend files instead
+		of copying and modyfiing a recipe in an own layer
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]
+\frametitle{naming}
+an append file must be named after the base package:
+\begin{verbatim}
+<base-pn>_<base-pv>.bbappend
+\end{verbatim}
+\end{frame}
+
+\subsection{Classes}
+\begin{frame}
+\frametitle{basics}
+\begin{itemize}
+	\item python can be used to write functions
+	\item e.g. write your own image generation class
+\end{itemize}
+\end{frame}
+
+\subsection{Tasks}
+\begin{frame}
+\frametitle{basics}
+\begin{itemize}
+	\item are defined and ordered in classes
+	\item can be overriden by classes and recipes
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+	\frametitle{download \& patch}
+\begin{description}
+\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\_fetch] fetches the source code
+\item [do\_fetchall] fetches all remote sources required to build a target
+\item [do\_unpack] unpacks the source code into a working directory
+\item [do\_patch] locates patch files and applies them to the source code
+\end{description}
+\end{frame}
+
+\begin{frame}
+	\frametitle{configure \& compile}
+\begin{description}
+\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\_compile] compiles the source in the compilation directory
+\item [do\_install] copies files from the compilation directory to a holding
+	area
+\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
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{packaging}
+\begin{description}
+\item [do\_packagedata] creates package metadata used by the build system to
+	generate the final packages
+\item [do\_package] analyzes the content of the holding area and splits it
+	into subsets based on available packages and files
+\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\_package\_index] creates or updates the index in the Package Feed
+	area
+\end{description}
+\end{frame}
+
+\begin{frame}
+	\frametitle{deploy}
+\begin{description}
+\item [do\_rootfs] creates the root filesystem (file and directory structure)
+	for an image
+\item [do\_vmdkimg] creates a .vmdk image for use with VMware and compatible
+	virtual machine hosts"
+\item [do\_deploy] writes deployable output files to the deploy directory
+\item [do\_populate\_sdk] creates the file and directory structure for an
+	installable SDK
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{cleanup}
+\begin{description}
+\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\_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
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{kernel}
+\begin{description}
+\item [do\_kernel\_checkout] checks out source/meta branches for a linux-yocto
+	style kernel
+\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\_kernel\_configme] assembles the kernel configuration for a
+	linux-yocto style kernel
+\item [do\_menuconfig] runs 'make menuconfig' for the kernel
+\item [do\_diffconfig] compares the old and new config files after running
+	do\_menuconfig for the kernel
+\item [do\_savedefconfig] creates a minimal Linux kernel configuration file
+\item [do\_kernel\_configcheck] validates the kernel configuration for a
+	linux-yocto style kernel
+\item [do\_sizecheck] checks the size of the kernel image against
+	KERNEL\_IMAGE\_MAXSIZE (if set)
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{kernel}
+\begin{description}
+\item [do\_compile\_kernelmodules] compiles loadable modules for the Linux
+	kernel
+\item [do\_strip] strips unneeded sections out of the Linux kernel image
+\item [do\_kernel\_link\_vmlinux] creates a symbolic link in arch/\$arch/boot
+	for vmlinux kernel images
+\item [do\_bundle\_initramfs] combines an initial ramdisk image and kernel
+	together to form a single image
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{licenses}
+\begin{description}
+\item [do\_populate\_lic] writes license information for the recipe that is
+	collected later when the image is constructed
+\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
+\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{special stuff}
+\begin{description}
+\item [do\_uboot\_mkimage] creates a uImage file from the kernel for the
+	U-Boot bootloader
+\item [do\_generate\_qt\_config\_file] writes a qt.conf file for building a
+	Qt-based application
+\item [do\_devshell] starts a shell with the environment set up for
+	development/debugging
+\item [do\_listtasks] lists all defined tasks for a target
+\end{description}
+\end{frame}
+
+\subsection{Machines}
+\begin{frame}
+\frametitle{basics}
+a machine config is used to describe a board
+\begin{itemize}
+	\item machine configs are stored in the layers: conf/machine/*
+	\item settings can be splitted in different include *.inc files
+	\item e.g. one include for CPU that is used by the SoC inc file,
+that is used by the Board .conf file
+	\item the include files can be stored in different layers
+\end{itemize}
+\end{frame}
+
+\begin{frame}
+	\frametitle{u-boot \& kernel}
+\begin{description}
+	\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'
+\end{description}
+\end{frame}
+
+\begin{frame}
+	\frametitle{hardware}
+\begin{description}
+	\item[SOC\_FAMILY] groups together machines based upon the same family of SOC
+		(System On Chip)
+	\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
+		\footnote{acpi, alsa, apm, bluetooth, ext2, irda, keyboard, pci, pcmcia,
+		screen, serial, touchscreen, usbgadget, usbhost, wifi}
+	\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.
+	\end{description}
+\end{frame}
+
+\begin{frame}
+\frametitle{compiler settings}
+\begin{description}
+\item [DEFAULTTUNE] e.g. armv6hf or cortexa8hf-neon, x86-64, \dots
+\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{software}
+\begin{description}
+\item [PREFERRED\_VERSION\_xserver-xorg] compatible xserver version
+\item [PREFERRED\_PROVIDER\_virtual/kernel] recommended kernel
+\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, e.g. to hook in own image generation code
+\end{description}
+\end{frame}