From 7032a45ced955efc7d369b3ccf6491654d6549b0 Mon Sep 17 00:00:00 2001 From: Manuel Traut Date: Tue, 17 May 2016 15:55:39 +0200 Subject: yocto-basics: split slides Signed-off-by: Manuel Traut --- distribution/yocto-basic/yocto-workflow.tex | 681 ++++++++++++++++++++++++++++ 1 file changed, 681 insertions(+) create mode 100644 distribution/yocto-basic/yocto-workflow.tex (limited to 'distribution/yocto-basic/yocto-workflow.tex') 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 +\end{verbatim} +\begin{itemize} +\item is used to modify the environment and change the CWD to +\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 = ":///;;" +\end{verbatim} +\pause +multiple urls can be set in a SRC\_URI variable: +\begin{verbatim} +SRC_URI = ";name=url1 ;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 | 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} +_.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} -- cgit v1.2.3