diff options
Diffstat (limited to 'documentation/mega-manual/mega-manual.html')
| -rw-r--r-- | documentation/mega-manual/mega-manual.html | 12646 |
1 files changed, 12646 insertions, 0 deletions
diff --git a/documentation/mega-manual/mega-manual.html b/documentation/mega-manual/mega-manual.html new file mode 100644 index 0000000000..1b4419f3b9 --- /dev/null +++ b/documentation/mega-manual/mega-manual.html @@ -0,0 +1,12646 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title></title><link rel="stylesheet" href="mega-style.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><hr /></div> + + <div class="article"><div class="titlepage"><hr /></div><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 90px"><td align="right"><img src="figures/yocto-project-transp.png" align="right" width="135" /></td></tr></table><div class="section" title="1. The Yocto Project Quick Start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="fake-title"></a>1. The Yocto Project Quick Start</h2></div></div></div><p>Copyright © 2010-2012 Linux Foundation</p></div><div class="section" title="2. Welcome!"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="welcome"></a>2. Welcome!</h2></div></div></div><p> + Welcome to the Yocto Project! + The Yocto Project is an open-source collaboration project focused on embedded Linux + developers. + Among other things, the Yocto Project uses a build system based on the Poky project + to construct complete Linux images. + The Poky project, in turn, draws from and contributes back to the OpenEmbedded project. + </p><p> + If you don't have a system that runs Linux and you want to give the Yocto Project a test run, + you might consider using the Yocto Project Build Appliance. + The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto + Project using a non-Linux development system. + See the <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Yocto + Project Build Appliance</a> for more information. + </p><p> + On the other hand, if you know all about open-source development, Linux development environments, + Git source repositories and the like and you just want some quick information that lets you try out + the Yocto Project on your Linux system, skip right to the + "<a class="link" href="#super-user" title="6. Super User">Super User</a>" section at the end of this quick start. + </p><p> + For the rest of you, this short document will give you some basic information about the environment and + let you experience it in its simplest form. + After reading this document, you will have a basic understanding of what the Yocto Project is + and how to use some of its core components. + This document steps you through a simple example showing you how to build a small image + and run it using the Quick EMUlator (QEMU emulator). + </p><p> + For more detailed information on the Yocto Project, you should check out these resources: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Website:</em></span> The <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a> + provides the latest builds, breaking news, full development documentation, and a rich Yocto + Project Development Community into which you can tap. + </p></li><li class="listitem"><p><span class="emphasis"><em>FAQs:</em></span> Lists commonly asked Yocto Project questions and answers. + You can find two FAQs: <a class="ulink" href="https://wiki.yoctoproject.org/wiki/FAQ" target="_top">Yocto Project FAQ</a> on + a wiki, and the + <a class="link" href="#faq" target="_top">FAQ</a> chapter in + the Yocto Project Reference Manual. + </p></li><li class="listitem"><p><span class="emphasis"><em>Developer Screencast:</em></span> The + <a class="ulink" href="http://vimeo.com/36450321" target="_top">Getting Started with the Yocto Project - New + Developer Screencast Tutorial</a> provides a 30-minute video for the user + new to the Yocto Project but familiar with Linux build systems.</p></li></ul></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in a released tarball and the + Yocto Project Quick Start on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div></div><div class="section" title="3. Introducing the Yocto Project Development Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yp-intro"></a>3. Introducing the Yocto Project Development Environment</h2></div></div></div><p> + The Yocto Project through the OpenEmbedded build system provides an open source development + environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of + platforms including x86-64 and emulated ones. + You can use components from the Yocto Project to design, develop, build, debug, simulate, + and test the complete software stack using Linux, the X Window System, GNOME Mobile-based + application frameworks, and Qt frameworks. + </p><div class="mediaobject" align="center"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="center"><img src="figures/yocto-environment.png" align="middle" width="100%" /></td></tr></table><div class="caption"><p>The Yocto Project Development Environment</p></div></div><p> + Here are some highlights for the Yocto Project: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Provides a recent Linux kernel along with a set of system commands and libraries suitable for the embedded environment.</p></li><li class="listitem"><p>Makes available system components such as X11, Matchbox, GTK+, Pimlico, Clutter, + GuPNP and Qt (among others) so you can create a richer user interface experience on + devices that use displays or have a GUI. + For devices that don't have a GUI or display, you simply would not employ these + components.</p></li><li class="listitem"><p>Creates a focused and stable core compatible with the OpenEmbedded + project with which you can easily and reliably build and develop.</p></li><li class="listitem"><p>Fully supports a wide range of hardware and device emulation through the QEMU + Emulator.</p></li></ul></div><p> + The Yocto Project can generate images for many kinds of devices. + However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS, + and PPC-based architectures as well as specific hardware such as the + <span class="trademark">Intel</span>® Desktop Board DH55TC. + Because an image developed with the Yocto Project can boot inside a QEMU emulator, the + development environment works nicely as a test platform for developing embedded software. + </p><p> + Another important Yocto Project feature is the Sato reference User Interface. + This optional GNOME mobile-based UI, which is intended for devices with + restricted screen sizes, sits neatly on top of a device using the + GNOME Mobile Stack and provides a well-defined user experience. + Implemented in its own layer, it makes it clear to developers how they can implement + their own user interface on top of a Linux image created with the Yocto Project. + </p></div><div class="section" title="4. What You Need and How You Get It"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yp-resources"></a>4. What You Need and How You Get It</h2></div></div></div><p> + You need these things to develop in the Yocto Project environment: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A host system running a supported Linux distribution (i.e. recent releases of + Fedora, openSUSE, CentOS, and Ubuntu). + If the host system supports multiple cores and threads, you can configure the + Yocto Project build system to decrease the time needed to build images + significantly. + </p></li><li class="listitem"><p>The right packages.</p></li><li class="listitem"><p>A release of the Yocto Project.</p></li></ul></div><div class="section" title="4.1. The Linux Distribution"><div class="titlepage"><div><div><h3 class="title"><a id="the-linux-distro"></a>4.1. The Linux Distribution</h3></div></div></div><p> + The Yocto Project team is continually verifying more and more Linux + distributions with each release. + In general, if you have the current release minus one of the following + distributions you should have no problems. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Ubuntu</p></li><li class="listitem"><p>Fedora</p></li><li class="listitem"><p>openSUSE</p></li><li class="listitem"><p>CentOS</p></li></ul></div><p> + For a list of the distributions under validation and their status, see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_top">Distribution + Support</a> wiki page. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + For notes about using the Yocto Project on a RHEL 4-based host, see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/BuildingOnRHEL4" target="_top">BuildingOnRHEL4</a> + wiki page. + </div><p> + </p><p> + The OpenEmbedded build system should be able to run on any modern distribution with Python 2.6 or 2.7. + Earlier releases of Python are known to not work and the system does not support Python 3 at this time. + This document assumes you are running one of the previously noted distributions on your Linux-based + host systems. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + If you attempt to use a distribution not in the above list, you may or may not have success - you + are venturing into untested territory. + Refer to + <a class="ulink" href="http://www.openembedded.org/index.php?title=OEandYourDistro&action=historysubmit&diff=4309&okdid=4225" target="_top">OE and Your Distro</a> and + <a class="ulink" href="http://www.openembedded.org/index.php?title=Required_software&action=historysubmit&diff=4311&oldid=4251" target="_top">Required Software</a> + for information for other distributions used with the OpenEmbedded project, which might be + a starting point for exploration. + If you go down this path, you should expect problems. + When you do, please go to <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">Yocto Project Bugzilla</a> + and submit a bug. + We are interested in hearing about your experience. + </p></div></div><div class="section" title="4.2. The Packages"><div class="titlepage"><div><div><h3 class="title"><a id="packages"></a>4.2. The Packages</h3></div></div></div><p> + Packages and package installation vary depending on your development system. + In general, you need to have root access and then install the required packages. + The next few sections show you how to get set up with the right packages for + Ubuntu, Fedora, openSUSE, and CentOS. + </p><div class="section" title="4.2.1. Ubuntu"><div class="titlepage"><div><div><h4 class="title"><a id="ubuntu"></a>4.2.1. Ubuntu</h4></div></div></div><p> + The packages you need for a supported Ubuntu distribution are shown in the following command: + </p><pre class="literallayout"> + $ sudo apt-get install sed wget subversion git-core coreutils \ + unzip texi2html texinfo libsdl1.2-dev docbook-utils fop gawk \ + python-pysqlite2 diffstat make gcc build-essential xsltproc \ + g++ desktop-file-utils chrpath libgl1-mesa-dev libglu1-mesa-dev \ + autoconf automake groff libtool xterm libxml-parser-perl dblatex + </pre></div><div class="section" title="4.2.2. Fedora"><div class="titlepage"><div><div><h4 class="title"><a id="fedora"></a>4.2.2. Fedora</h4></div></div></div><p> + The packages you need for a supported Fedora distribution are shown in the following + commands: + </p><pre class="literallayout"> + $ sudo yum groupinstall "development tools" + $ sudo yum install python m4 make wget curl ftp tar bzip2 gzip \ + unzip perl texinfo texi2html diffstat openjade \ + docbook-style-dsssl sed docbook-style-xsl docbook-dtds fop libxslt \ + docbook-utils sed bc eglibc-devel ccache pcre pcre-devel quilt \ + groff linuxdoc-tools patch cmake \ + perl-ExtUtils-MakeMaker tcl-devel gettext chrpath ncurses apr \ + SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \ + autoconf automake libtool xterm dblatex + </pre></div><div class="section" title="4.2.3. openSUSE"><div class="titlepage"><div><div><h4 class="title"><a id="opensuse"></a>4.2.3. openSUSE</h4></div></div></div><p> + The packages you need for a supported openSUSE distribution are shown in the following + command: + </p><pre class="literallayout"> + $ sudo zypper install python gcc gcc-c++ libtool fop \ + subversion git chrpath automake make wget xsltproc \ + diffstat texinfo freeglut-devel libSDL-devel dblatex + </pre></div><div class="section" title="4.2.4. CentOS"><div class="titlepage"><div><div><h4 class="title"><a id="centos"></a>4.2.4. CentOS</h4></div></div></div><p> + The packages you need for a supported CentOS distribution are shown in the following + commands: + </p><pre class="literallayout"> + $ sudo yum -y groupinstall "development tools" + $ sudo yum -y install tetex gawk sqlite-devel vim-common redhat-lsb xz \ + m4 make wget curl ftp tar bzip2 gzip python-devel \ + unzip perl texinfo texi2html diffstat openjade zlib-devel \ + docbook-style-dsssl sed docbook-style-xsl docbook-dtds \ + docbook-utils bc glibc-devel pcre pcre-devel \ + groff linuxdoc-tools patch cmake \ + tcl-devel gettext ncurses apr \ + SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \ + autoconf automake libtool xterm dblatex + </pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + Depending on the CentOS version you are using, other requirements and dependencies + might exist. + For details, you should look at the CentOS sections on the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_top">Poky/GettingStarted/Dependencies</a> + wiki page. + </p></div></div></div><div class="section" title="4.3. Yocto Project Release"><div class="titlepage"><div><div><h3 class="title"><a id="releases"></a>4.3. Yocto Project Release</h3></div></div></div><p> + You can download the latest Yocto Project release by going to the + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Yocto Project Download page</a>. + Just go to the page and click the "Yocto Downloads" link found in the "Download" + navigation pane to the right to view all available Yocto Project releases. + Then, click the "Yocto Release" link for the release you want from the list to + begin the download. + Nightly and developmental builds are also maintained at + <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly/" target="_top">http://autobuilder.yoctoproject.org/nightly/</a>. + However, for this document a released version of Yocto Project is used. + </p><p> + You can also get the Yocto Project files you need by setting up (cloning in Git terms) + a local copy of the <code class="filename">poky</code> Git repository on your host development + system. + Doing so allows you to contribute back to the Yocto Project project. + For information on how to get set up using this method, see the + "<a class="link" href="#local-yp-release" target="_top">Yocto + Project Release</a>" item in the Yocto Project Development Manual. + </p></div></div><div class="section" title="5. A Quick Test Run"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="test-run"></a>5. A Quick Test Run</h2></div></div></div><p> + Now that you have your system requirements in order, you can give the Yocto Project a try. + This section presents some steps that let you do the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Build an image and run it in the QEMU emulator</p></li><li class="listitem"><p>Use a pre-built image and run it in the QEMU emulator</p></li></ul></div><div class="section" title="5.1. Building an Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-image"></a>5.1. Building an Image</h3></div></div></div><p> + In the development environment you will need to build an image whenever you change hardware + support, add or change system libraries, or add or change services that have dependencies. + </p><div class="mediaobject" align="center"><img src="figures/building-an-image.png" align="middle" /><div class="caption"><p>Building an Image</p></div></div><p> + Use the following commands to build your image. + The OpenEmbedded build process creates an entire Linux distribution, including the toolchain, + from source. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + The build process using Sato currently consumes about 50GB of disk space. + To allow for variations in the build process and for future package expansion, we + recommend having at least 100GB of free disk space. + </p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + By default, the build process searches for source code using a pre-determined order + through a set of locations. + If you encounter problems with the build process finding and downloading source code, see the + "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server" target="_top">How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server?</a>" in the Yocto Project Reference Manual. + </p></div><p> + </p><pre class="literallayout"> + $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-1.2+snapshot-8.0.tar.bz2 + $ tar xjf poky-1.2+snapshot-8.0.tar.bz2 + $ source poky-1.2+snapshot-8.0/oe-init-build-env poky-1.2+snapshot-8.0-build + </pre><p> + </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p> + To help conserve disk space during builds, you can add the following statement + to your project's configuration file, which for this example + is <code class="filename">poky-1.2+snapshot-8.0-build/conf/local.conf</code>. + Adding this statement deletes the work directory used for building a package + once the package is built. + </p><pre class="literallayout"> + INHERIT += "rm_work" + </pre><p> + </p></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>In the previous example, the first command retrieves the Yocto Project + release tarball from the source repositories using the + <code class="filename">wget</code> command. + Alternatively, you can go to the + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Yocto Project website's Downloads page</a> + to retrieve the tarball.</p></li><li class="listitem"><p>The second command extracts the files from the tarball and places + them into a directory named <code class="filename">poky-1.2+snapshot-8.0</code> in the current + directory.</p></li><li class="listitem"><p>The third command runs the Yocto Project environment setup script. + Running this script defines OpenEmbedded build environment settings needed to + complete the build. + The script also creates the + <a class="link" href="#build-directory" target="_top">build directory</a>, + which is <code class="filename">poky-1.2+snapshot-8.0-build</code> in this case. + After the script runs, your current working directory is set + to the build directory. + Later, when the build completes, the build directory contains all the files + created during the build. + </p></li></ul></div><p> + Take some time to examine your <code class="filename">local.conf</code> file + in your project's configuration directory. + The defaults in that file should work fine. + However, there are some variables of interest at which you might look. + </p><p> + By default, the target architecture for the build is <code class="filename">qemux86</code>, + which produces an image that can be used in the QEMU emulator and is targeted at an + <span class="trademark">Intel</span>® 32-bit based architecture. + To change this default, edit the value of the <code class="filename">MACHINE</code> variable + in the configuration file before launching the build. + </p><p> + Another couple of variables of interest are the + <a class="link" href="#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a> and the + <a class="link" href="#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a> variables. + By default, these variables are commented out. + However, if you have a multi-core CPU you might want to uncomment + the lines and set both variables equal to twice the number of your + host's processor cores. + Setting these variables can significantly shorten your build time. + </p><p> + Another consideration before you build is the package manager used when creating + the image. + By default, the OpenEmbedded build system uses the RPM package manager. + You can control this configuration by using the + <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a></code> variable. + For additional package manager selection information, see + "<a class="link" href="#ref-classes-package" target="_top">Packaging - <code class="filename">package*.bbclass</code></a>" + in the Yocto Project Reference Manual. + </p><p> + Continue with the following command to build an OS image for the target, which is + <code class="filename">core-image-sato</code> in this example. + For information on the <code class="filename">-k</code> option use the + <code class="filename">bitbake --help</code> command or see the + "<a class="link" href="#usingpoky-components-bitbake" target="_top">BitBake</a>" section in + the Yocto Project Reference Manual. + </p><pre class="literallayout"> + $ bitbake -k core-image-sato + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + BitBake requires Python 2.6 or 2.7. For more information on this requirement, + see the + <a class="link" href="#faq" target="_top">FAQ</a> in the Yocto Project Reference + Manual. + </p></div><p> + The final command runs the image: + </p><pre class="literallayout"> + $ runqemu qemux86 + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + Depending on the number of processors and cores, the amount or RAM, the speed of your + Internet connection and other factors, the build process could take several hours the first + time you run it. + Subsequent builds run much faster since parts of the build are cached. + </p></div><p> + </p></div><div class="section" title="5.2. Using Pre-Built Binaries and QEMU"><div class="titlepage"><div><div><h3 class="title"><a id="using-pre-built"></a>5.2. Using Pre-Built Binaries and QEMU</h3></div></div></div><p> + If hardware, libraries and services are stable, you can get started by using a pre-built binary + of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. + This scenario is useful for developing application software. + </p><div class="mediaobject" align="center"><img src="figures/using-a-pre-built-image.png" align="middle" /><div class="caption"><p>Using a Pre-Built Image</p></div></div><p> + For this scenario, you need to do several things: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Install the appropriate stand-alone toolchain tarball.</p></li><li class="listitem"><p>Download the pre-built image that will boot with QEMU. + You need to be sure to get the QEMU image that matches your target machine’s + architecture (e.g. x86, ARM, etc.).</p></li><li class="listitem"><p>Download the filesystem image for your target machine's architecture. + </p></li><li class="listitem"><p>Set up the environment to emulate the hardware and then start the QEMU emulator. + </p></li></ul></div><div class="section" title="5.2.1. Installing the Toolchain"><div class="titlepage"><div><div><h4 class="title"><a id="installing-the-toolchain"></a>5.2.1. Installing the Toolchain</h4></div></div></div><p> + You can download a tarball with the pre-built toolchain, which includes the + <code class="filename">runqemu</code> + script and support files, from the appropriate directory under + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/</a>. + Toolchains are available for 32-bit and 64-bit development systems from the + <code class="filename">i686</code> and <code class="filename">x86-64</code> directories, respectively. + Each type of development system supports five target architectures. + The names of the tarballs are such that a string representing the host system appears + first in the filename and then is immediately followed by a string representing + the target architecture. + </p><pre class="literallayout"> + poky-eglibc-<<span class="emphasis"><em>host_system</em></span>>-<<span class="emphasis"><em>arch</em></span>>-toolchain-gmae-<<span class="emphasis"><em>release</em></span>>.tar.bz2 + + Where: + <<span class="emphasis"><em>host_system</em></span>> is a string representing your development system: + i686 or x86_64. + + <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: + i586, x86_64, powerpc, mips, or arm. + + <<span class="emphasis"><em>release</em></span>> is the version of Yocto Project. + </pre><p> + For example, the following toolchain tarball is for a 64-bit development + host system and a 32-bit target architecture: + </p><pre class="literallayout"> + poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2 + </pre><p> + The toolchain tarballs are self-contained and must be installed into <code class="filename">/opt/poky</code>. + The following commands show how you install the toolchain tarball given a 64-bit development + host system and a 32-bit target architecture. + The example assumes the toolchain tarball is located in <code class="filename">~/toolchains/</code>. + You must have your working directory set to root before unpacking the tarball: + </p><p> + </p><pre class="literallayout"> + $ cd / + $ sudo tar -xvjf ~/toolchains/poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2 + </pre><p> + </p><p> + For more information on how to install tarballs, see the + "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" and + "<a class="link" href="#using-the-toolchain-from-within-the-build-tree" target="_top">Using BitBake and the Build Directory</a>" sections in the Yocto Project Application Developer's Guide. + </p></div><div class="section" title="5.2.2. Downloading the Pre-Built Linux Kernel"><div class="titlepage"><div><div><h4 class="title"><a id="downloading-the-pre-built-linux-kernel"></a>5.2.2. Downloading the Pre-Built Linux Kernel</h4></div></div></div><p> + You can download the pre-built Linux kernel suitable for running in the QEMU emulator from + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu</a>. + Be sure to use the kernel that matches the architecture you want to simulate. + Download areas exist for the five supported machine architectures: + <code class="filename">qemuarm</code>, <code class="filename">qemumips</code>, <code class="filename">qemuppc</code>, + <code class="filename">qemux86</code>, and <code class="filename">qemux86-64</code>. + </p><p> + Most kernel files have one of the following forms: + </p><pre class="literallayout"> + *zImage-qemu<<span class="emphasis"><em>arch</em></span>>.bin + vmlinux-qemu<<span class="emphasis"><em>arch</em></span>>.bin + + Where: + <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: + x86, x86-64, ppc, mips, or arm. + </pre><p> + </p><p> + You can learn more about downloading a Yocto Project kernel in the + "<a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a>" + bulleted item in the Yocto Project Development Manual. + </p></div><div class="section" title="5.2.3. Downloading the Filesystem"><div class="titlepage"><div><div><h4 class="title"><a id="downloading-the-filesystem"></a>5.2.3. Downloading the Filesystem</h4></div></div></div><p> + You can also download the filesystem image suitable for your target architecture from + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu</a>. + Again, be sure to use the filesystem that matches the architecture you want + to simulate. + </p><p> + The filesystem image has two tarball forms: <code class="filename">ext3</code> and + <code class="filename">tar</code>. + You must use the <code class="filename">ext3</code> form when booting an image using the + QEMU emulator. + The <code class="filename">tar</code> form can be flattened out in your host development system + and used for build purposes with the Yocto Project. + </p><pre class="literallayout"> + core-image-<<span class="emphasis"><em>profile</em></span>>-qemu<<span class="emphasis"><em>arch</em></span>>.ext3 + core-image-<<span class="emphasis"><em>profile</em></span>>-qemu<<span class="emphasis"><em>arch</em></span>>.tar.bz2 + + Where: + <<span class="emphasis"><em>profile</em></span>> is the filesystem image's profile: + lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, sato-dev, or sato-sdk. + For information on these types of image profiles, see the + "<a class="link" href="#ref-images" target="_top">Images</a>" chapter + in the Yocto Project Reference Manual. + + <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: + x86, x86-64, ppc, mips, or arm. + </pre><p> + </p></div><div class="section" title="5.2.4. Setting Up the Environment and Starting the QEMU Emulator"><div class="titlepage"><div><div><h4 class="title"><a id="setting-up-the-environment-and-starting-the-qemu-emulator"></a>5.2.4. Setting Up the Environment and Starting the QEMU Emulator</h4></div></div></div><p> + Before you start the QEMU emulator, you need to set up the emulation environment. + The following command form sets up the emulation environment. + </p><pre class="literallayout"> + $ source /opt/poky/1.3/environment-setup-<<span class="emphasis"><em>arch</em></span>>-poky-linux-<<span class="emphasis"><em>if</em></span>> + + Where: + <<span class="emphasis"><em>arch</em></span>> is a string representing the target architecture: + i586, x86_64, ppc603e, mips, or armv5te. + + <<span class="emphasis"><em>if</em></span>> is a string representing an embedded application binary interface. + Not all setup scripts include this string. + </pre><p> + </p><p> + Finally, this command form invokes the QEMU emulator + </p><pre class="literallayout"> + $ runqemu <<span class="emphasis"><em>qemuarch</em></span>> <<span class="emphasis"><em>kernel-image</em></span>> <<span class="emphasis"><em>filesystem-image</em></span>> + + Where: + <<span class="emphasis"><em>qemuarch</em></span>> is a string representing the target architecture: qemux86, qemux86-64, + qemuppc, qemumips, or qemuarm. + + <<span class="emphasis"><em>kernel-image</em></span>> is the architecture-specific kernel image. + + <<span class="emphasis"><em>filesystem-image</em></span>> is the .ext3 filesystem image. + + </pre><p> + </p><p> + Continuing with the example, the following two commands setup the emulation + environment and launch QEMU. + This example assumes the root filesystem (<code class="filename">.ext3</code> file) and + the pre-built kernel image file both reside in your home directory. + The kernel and filesystem are for a 32-bit target architecture. + </p><pre class="literallayout"> + $ cd $HOME + $ source /opt/poky/1.3/environment-setup-i586-poky-linux + $ runqemu qemux86 bzImage-qemux86.bin \ + core-image-sato-qemux86.ext3 + </pre><p> + </p><p> + The environment in which QEMU launches varies depending on the filesystem image and on the + target architecture. + For example, if you source the environment for the ARM target + architecture and then boot the minimal QEMU image, the emulator comes up in a new + shell in command-line mode. + However, if you boot the SDK image, QEMU comes up with a GUI. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Booting the PPC image results in QEMU launching in the same shell in + command-line mode.</div><p> + </p></div></div></div><div class="section" title="6. Super User"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="super-user"></a>6. Super User +</h2></div></div></div><p> + This section + <sup>[<a id="id1482592" href="#ftn.id1482592" class="footnote">1</a>]</sup> + gives you a very fast description of how to use the Yocto Project to build images + for a BeagleBoard xM starting from scratch. + The steps were performed on a 64-bit Ubuntu 10.04 system. + </p><div class="section" title="6.1. Getting the Yocto Project"><div class="titlepage"><div><div><h3 class="title"><a id="getting-yocto"></a>6.1. Getting the Yocto Project</h3></div></div></div><p> + Set up your <a class="link" href="#source-directory" target="_top">source directory</a> + one of two ways: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Tarball:</em></span> + Use if you want the latest stable release: + </p><pre class="literallayout"> + $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-1.2+snapshot-8.0.tar.bz2 + $ tar xvjf poky-1.2+snapshot-8.0.tar.bz2 + </pre></li><li class="listitem"><p><span class="emphasis"><em>Git Repository:</em></span> + Use if you want to work with cutting edge development content: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/poky + </pre></li></ul></div><p> + The remainder of the section assumes the Git repository method. + </p></div><div class="section" title="6.2. Setting Up Your Host"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-your-host"></a>6.2. Setting Up Your Host</h3></div></div></div><p> + You need some packages for everything to work. + Rather than duplicate them here, look at the "<a class="link" href="#packages" title="4.2. The Packages">The Packages</a>" + section earlier in this quick start. + </p></div><div class="section" title="6.3. Initializing the Build Environment"><div class="titlepage"><div><div><h3 class="title"><a id="initializing-the-build-environment"></a>6.3. Initializing the Build Environment</h3></div></div></div><p> + From the parent directory of local source directory, initialize your environment + and provide a meaningful + <a class="link" href="#build-directory" target="_top">build directory</a> + name: + </p><pre class="literallayout"> + $ source poky/oe-init-build-env mybuilds + </pre><p> + At this point, the <code class="filename">mybuilds</code> directory has been created for you + and it is now your current working directory. + If you don't provide your own directory name it defaults to <code class="filename">build</code>. + </p></div><div class="section" title="6.4. Configuring the local.conf File"><div class="titlepage"><div><div><h3 class="title"><a id="configuring-the-local.conf-file"></a>6.4. Configuring the local.conf File</h3></div></div></div><p> + Initializing the build environment creates a <code class="filename">conf/local.conf</code> configuration file + in the build directory. + You need to manually edit this file to specify the machine you are building and to optimize + your build time. + Here are the minimal changes to make: + </p><pre class="literallayout"> + BB_NUMBER_THREADS = "8" + PARALLEL_MAKE = "-j 8" + MACHINE ?= "beagleboard" + </pre><p> + Briefly, set <a class="link" href="#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a> + and <a class="link" href="#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a> to + twice your host processor's number of cores. + </p><p> + A good deal that goes into a Yocto Project build is simply downloading all of the source + tarballs. + Maybe you have been working with another build system (OpenEmbedded, Angstrom, etc) for which + you've built up a sizable directory of source tarballs. + Or perhaps someone else has such a directory for which you have read access. + If so, you can save time by adding the <code class="filename">PREMIRRORS</code> + statement to your configuration file so that local directories are first checked for existing + tarballs before running out to the net: + </p><pre class="literallayout"> + PREMIRRORS_prepend = "\ + git://.*/.* file:///home/you/dl/ \n \ + svn://.*/.* file:///home/you/dl/ \n \ + cvs://.*/.* file:///home/you/dl/ \n \ + ftp://.*/.* file:///home/you/dl/ \n \ + http://.*/.* file:///home/you/dl/ \n \ + https://.*/.* file:///home/you/dl/ \n" + </pre><p> + </p></div><div class="section" title="6.5. Building the Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-the-image"></a>6.5. Building the Image</h3></div></div></div><p> + At this point, you need to select an image to build for the BeagleBoard xM. + If this is your first build using the Yocto Project, you should try the smallest and simplest + image: + </p><pre class="literallayout"> + $ bitbake core-image-minimal + </pre><p> + Now you just wait for the build to finish. + </p><p> + Here are some variations on the build process that could be helpful: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Fetch all the necessary sources without starting the build: + </p><pre class="literallayout"> + $ bitbake -c fetchall core-image-minimal + </pre><p> + This variation guarantees that you have all the sources for that BitBake target + should you to disconnect from the net and want to do the build later offline. + </p></li><li class="listitem"><p>Specify to continue the build even if BitBake encounters an error. + By default, BitBake aborts the build when it encounters an error. + This command keeps a faulty build going: + </p><pre class="literallayout"> + $ bitbake -k core-image-minimal + </pre></li></ul></div><p> + </p><p> + Once you have your image, you can take steps to load and boot it on the target hardware. + </p></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id1482592" href="#id1482592" class="para">1</a>] </sup> + Kudos and thanks to Robert P. J. Day of + <a class="ulink" href="http://www.crashcourse.ca" target="_top">CrashCourse</a> for providing the basis + for this "expert" section with information from one of his + <a class="ulink" href="http://www.crashcourse.ca/wiki/index.php/Yocto_Project_Quick_Start" target="_top">wiki</a> + pages. + </p></div></div></div> + +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/dev-title.png" align="left" width="100%" /></td></tr></table> + + <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="dev-manual"></a></h1></div><div><div class="authorgroup"> + <div class="author"><h3 class="author"><span class="firstname">Scott</span> <span class="surname">Rifenbark</span></h3><div class="affiliation"> + <span class="orgname">Intel Corporation<br /></span> + </div><code class="email"><<a class="email" href="mailto:scott.m.rifenbark@intel.com">scott.m.rifenbark@intel.com</a>></code></div> + </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1482939"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top"> + Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by + Creative Commons. + </p> + + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + Yocto Project Development Manual on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> + <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">The initial document released with the Yocto Project 1.1 Release.</td></tr> + <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + </table></div></div></div><hr /></div> + + + <div class="chapter" title="Chapter 1. The Yocto Project Development Manual"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-intro"></a>Chapter 1. The Yocto Project Development Manual</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#intro">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#what-this-manual-provides">1.2. What this Manual Provides</a></span></dt><dt><span class="section"><a href="#what-this-manual-does-not-provide">1.3. What this Manual Does Not Provide</a></span></dt><dt><span class="section"><a href="#other-information">1.4. Other Information</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro"></a>1.1. Introduction</h2></div></div></div><p> + Welcome to the Yocto Project Development Manual! + This manual gives you an idea of how to use the Yocto Project to develop embedded Linux + images and user-space applications to run on targeted devices. + Reading this manual gives you an overview of image, kernel, and user-space application development + using the Yocto Project. + Because much of the information in this manual is general, it contains many references to other + sources where you can find more detail. + For example, detailed information on Git, repositories and open source in general + can be found in many places. + Another example is how to get set up to use the Yocto Project, which our Yocto Project + Quick Start covers. + </p><p> + The Yocto Project Development Manual, however, does provide detailed examples on how to create a + Board Support Package (BSP), change the kernel source code, and reconfigure the kernel. + You can find this information in the appendices of the manual. + </p></div><div class="section" title="1.2. What this Manual Provides"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="what-this-manual-provides"></a>1.2. What this Manual Provides</h2></div></div></div><p> + The following list describes what you can get from this guide: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Information that lets you get set + up to develop using the Yocto Project.</p></li><li class="listitem"><p>Information to help developers who are new to the open source environment + and to the distributed revision control system Git, which the Yocto Project + uses.</p></li><li class="listitem"><p>An understanding of common end-to-end development models and tasks.</p></li><li class="listitem"><p>Development case overviews for both system development and user-space + applications.</p></li><li class="listitem"><p>An overview and understanding of the emulation environment used with + the Yocto Project (QEMU).</p></li><li class="listitem"><p>An understanding of basic kernel architecture and concepts.</p></li><li class="listitem"><p>Many references to other sources of related information.</p></li></ul></div><p> + </p></div><div class="section" title="1.3. What this Manual Does Not Provide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="what-this-manual-does-not-provide"></a>1.3. What this Manual Does Not Provide</h2></div></div></div><p> + This manual will not give you the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Step-by-step instructions if those instructions exist in other Yocto + Project documentation. + For example, the Yocto Project Development Manual contains detailed + instruction on how to obtain and configure the + <span class="trademark">Eclipse</span>™ Yocto Plug-in.</p></li><li class="listitem"><p>Reference material. + This type of material resides in an appropriate reference manual. + For example, system variables are documented in the + Yocto Project Reference Manual.</p></li><li class="listitem"><p>Detailed public information that is not specific to the Yocto Project. + For example, exhaustive information on how to use Git is covered better through the + Internet than in this manual.</p></li></ul></div><p> + </p></div><div class="section" title="1.4. Other Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="other-information"></a>1.4. Other Information</h2></div></div></div><p> + Because this manual presents overview information for many different topics, you will + need to supplement it with other information. + The following list presents other sources of information you might find helpful: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a>: + </em></span> The home page for the Yocto Project provides lots of information on the project + as well as links to software and documentation.</p></li><li class="listitem"><p><span class="emphasis"><em> + Yocto Project Quick Start:</em></span> This short document lets you get started + with the Yocto Project quickly and start building an image.</p></li><li class="listitem"><p><span class="emphasis"><em> + Yocto Project Reference Manual:</em></span> This manual is a reference + guide to the OpenEmbedded build system known as "Poky." + The manual also contains a reference chapter on Board Support Package (BSP) + layout.</p></li><li class="listitem"><p><span class="emphasis"><em> + Yocto Project Application Developer's Guide:</em></span> + This guide provides information that lets you get going with the Application + Development Toolkit (ADT) and stand-alone cross-development toolchains to + develop projects using the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> + Yocto Project Board Support Package (BSP) Developer's Guide:</em></span> + This guide defines the structure for BSP components. + Having a commonly understood structure encourages standardization.</p></li><li class="listitem"><p><span class="emphasis"><em> + Yocto Project Kernel Architecture and Use Manual:</em></span> + This manual describes the architecture of the Yocto Project kernel and provides + some work flow examples.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://www.youtube.com/watch?v=3ZlOu-gLsh0" target="_top"> + Eclipse IDE Yocto Plug-in</a>:</em></span> A step-by-step instructional video that + demonstrates how an application developer uses Yocto Plug-in features within + the Eclipse IDE.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/FAQ" target="_top">FAQ</a>:</em></span> + A list of commonly asked questions and their answers.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://www.yoctoproject.org/download/yocto/yocto-project-1.1-release-notes-poky-8.0" target="_top"> + Release Notes</a>:</em></span> Features, updates and known issues for the current + release of the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top"> + Hob</a>:</em></span> A graphical user interface for BitBake. + Hob's primary goal is to enable a user to perform common tasks more easily.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top"> + Build Appliance</a>:</em></span> A bootable custom embedded Linux image you can + either build using a non-Linux development system (VMware applications) or download + from the Yocto Project website. + See the <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> + page for more information.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">Bugzilla</a>:</em></span> + The bug tracking application the Yocto Project uses. + If you find problems with the Yocto Project, you should report them using this + application.</p></li><li class="listitem"><p><span class="emphasis"><em> + Yocto Project Mailing Lists:</em></span> To subscribe to the Yocto Project mailing + lists, click on the following URLs and follow the instructions: + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> for a + Yocto Project Discussions mailing list.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> for a + Yocto Project Discussions mailing list about the Poky build system.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> + for a mailing list to receive official Yocto Project announcements for developments and + as well as Yocto Project milestones.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em>Internet Relay Chat (IRC):</em></span> + Two IRC channels on freenode are available + for Yocto Project and Poky discussions: <code class="filename">#yocto</code> and + <code class="filename">#poky</code>, respectively.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://o-hand.com" target="_top">OpenedHand</a>:</em></span> + The company that initially developed the Poky project, which is the basis + for the OpenEmbedded build system used by the Yocto Project. + OpenedHand was acquired by Intel Corporation in 2008.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span> + A multinational semiconductor chip manufacturer company whose Software and + Services Group created and supports the Yocto Project. + Intel acquired OpenedHand in 2008.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span> + The build system used by the Yocto Project. + This project is the upstream, generic, embedded distribution from which the Yocto + Project derives its build system (Poky) from and to which it contributes.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top"> + BitBake</a>:</em></span> The tool used by the OpenEmbedded build system + to process project metadata.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top"> + BitBake User Manual</a>:</em></span> A comprehensive guide to the BitBake tool. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>: + </em></span> An open-source machine emulator and virtualizer.</p></li></ul></div><p> + </p></div></div> + + <div class="chapter" title="Chapter 2. Getting Started with the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-start"></a>Chapter 2. Getting Started with the Yocto Project</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#introducing-the-yocto-project">2.1. Introducing the Yocto Project</a></span></dt><dt><span class="section"><a href="#getting-setup">2.2. Getting Set Up</a></span></dt><dt><span class="section"><a href="#building-images">2.3. Building Images</a></span></dt><dt><span class="section"><a href="#using-pre-built-binaries-and-qemu">2.4. Using Pre-Built Binaries and QEMU</a></span></dt></dl></div><p> + This chapter introduces the Yocto Project and gives you an idea of what you need to get started. + You can find enough information to set up your development host and build or use images for + hardware supported by the Yocto Project by reading the + Yocto Project Quick Start. +</p><p> + The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides + some higher-level concepts you might want to consider. +</p><div class="section" title="2.1. Introducing the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="introducing-the-yocto-project"></a>2.1. Introducing the Yocto Project</h2></div></div></div><p> + The Yocto Project is an open-source collaboration project focused on embedded Linux development. + The project currently provides a build system, which is + referred to as the OpenEmbedded build system in the Yocto Project documentation. + The Yocto Project provides various ancillary tools suitable for the embedded developer + and also features the Sato reference User Interface, which is optimized for + stylus driven, low-resolution screens. + </p><p> + You can use the OpenEmbedded build system, which uses + <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">BitBake</a>, to develop complete Linux + images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, + x86 and x86-64. + While the Yocto Project does not provide a strict testing framework, + it does provide or generate for you artifacts that let you perform target-level and + emulated testing and debugging. + Additionally, if you are an <span class="trademark">Eclipse</span>™ + IDE user, you can install an Eclipse Yocto Plug-in to allow you to + develop within that familiar environment. + </p></div><div class="section" title="2.2. Getting Set Up"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="getting-setup"></a>2.2. Getting Set Up</h2></div></div></div><p> + Here is what you need to get set up to use the Yocto Project: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Host System:</em></span> You should have a reasonably current + Linux-based host system. + You will have the best results with a recent release of Fedora, + OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project + and officially supported. + You should also have about 100 gigabytes of free disk space for building images. + </p></li><li class="listitem"><p><span class="emphasis"><em>Packages:</em></span> The OpenEmbedded build system + requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). + See "<a class="link" href="#packages" target="_top">The Packages</a>" + section in the Yocto Project Quick Start for the exact package + requirements and the installation commands to install them + for the supported distributions.</p></li><li class="listitem"><p><a id="local-yp-release"></a><span class="emphasis"><em>Yocto Project Release:</em></span> + You need a release of the Yocto Project. + You set up a with local <a class="link" href="#source-directory">source directory</a> + one of two ways depending on whether you + are going to contribute back into the Yocto Project or not. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Regardless of the method you use, this manual refers to the resulting local + hierarchical set of files as the "source directory." + </div><p> + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em>Tarball Extraction:</em></span> If you are not going to contribute + back into the Yocto Project, you can simply download a Yocto Project release you want + from the website’s <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">download page</a>. + Once you have the tarball, just extract it into a directory of your choice.</p><p>For example, the following command extracts the Yocto Project 1.3 + release tarball + into the current working directory and sets up the local source directory + with a top-level folder named <code class="filename">poky-1.2+snapshot-8.0</code>: + </p><pre class="literallayout"> + $ tar xfj poky-1.2+snapshot-8.0.tar.bz2 + </pre><p>This method does not produce a local Git repository. + Instead, you simply end up with a snapshot of the release.</p></li><li class="listitem"><p><span class="emphasis"><em>Git Repository Method:</em></span> If you are going to be contributing + back into the Yocto Project or you simply want to keep up + with the latest developments, you should use Git commands to set up a local + Git repository of the upstream <code class="filename">poky</code> source repository. + Doing so creates a repository with a complete history of changes and allows + you to easily submit your changes upstream to the project. + Because you cloned the repository, you have access to all the Yocto Project development + branches and tag names used in the upstream repository.</p><p>The following transcript shows how to clone the <code class="filename">poky</code> + Git repository into the current working directory. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>You can view the Yocto Project Source Repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a></div><p> + The command creates the local repository in a directory named <code class="filename">poky</code>. + For information on Git used within the Yocto Project, see the + "<a class="link" href="#git" title="3.6. Git">Git</a>" section. + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/poky + Initialized empty Git repository in /home/scottrif/poky/.git/ + remote: Counting objects: 141863, done. + remote: Compressing objects: 100% (38624/38624), done. + remote: Total 141863 (delta 99661), reused 141816 (delta 99614) + Receiving objects: 100% (141863/141863), 76.64 MiB | 126 KiB/s, done. + Resolving deltas: 100% (99661/99661), done. + </pre><p>For another example of how to set up your own local Git repositories, see this + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP" target="_top"> + wiki page</a>, which describes how to create both <code class="filename">poky</code> + and <code class="filename">meta-intel</code> Git repositories.</p></li></ul></div></li><li class="listitem"><p><a id="local-kernel-files"></a><span class="emphasis"><em>Yocto Project Kernel:</em></span> + If you are going to be making modifications to a supported Yocto Project kernel, you + need to establish local copies of the source. + You can find Git repositories of supported Yocto Project Kernels organized under + "Yocto Project Linux Kernel" in the Yocto Project Source Repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>.</p><p>This setup involves creating a bare clone of the Yocto Project kernel and then + copying that cloned repository. + You can create the bare clone and the copy of the bare clone anywhere you like. + For simplicity, it is recommended that you create these structures outside of the + source directory (usually <code class="filename">poky</code>).</p><p>As an example, the following transcript shows how to create the bare clone + of the <code class="filename">linux-yocto-3.2</code> kernel and then create a copy of + that clone. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>When you have a local Yocto Project kernel Git repository, you can + reference that repository rather than the upstream Git repository as + part of the <code class="filename">clone</code> command. + Doing so can speed up the process.</div><p>In the following example, the bare clone is named + <code class="filename">linux-yocto-3.2.git</code>, while the + copy is named <code class="filename">my-linux-yocto-3.2-work</code>: + </p><pre class="literallayout"> + $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.2 linux-yocto-3.2.git + Initialized empty Git repository in /home/scottrif/linux-yocto-3.2.git/ + remote: Counting objects: 2468027, done. + remote: Compressing objects: 100% (392255/392255), done. + remote: Total 2468027 (delta 2071693), reused 2448773 (delta 2052498) + Receiving objects: 100% (2468027/2468027), 530.46 MiB | 129 KiB/s, done. + Resolving deltas: 100% (2071693/2071693), done. + </pre><p>Now create a clone of the bare clone just created: + </p><pre class="literallayout"> + $ git clone linux-yocto-3.2.git my-linux-yocto-3.2-work + Initialized empty Git repository in /home/scottrif/my-linux-yocto-3.2-work/.git/ + Checking out files: 100% (37619/37619), done. + </pre></li><li class="listitem"><p><a id="poky-extras-repo"></a><span class="emphasis"><em> + The <code class="filename">poky-extras</code> Git Repository</em></span>: + The <code class="filename">poky-extras</code> Git repository contains metadata needed + only if you are modifying and building the kernel image. + In particular, it contains the kernel BitBake append (<code class="filename">.bbappend</code>) + files that you + edit to point to your locally modified kernel source files and to build the kernel + image. + Pointing to these local files is much more efficient than requiring a download of the + kernel's source files from upstream each time you make changes to the kernel.</p><p>You can find the <code class="filename">poky-extras</code> Git Repository in the + "Yocto Metadata Layers" area of the Yocto Project Source Repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. + It is good practice to create this Git repository inside the source directory.</p><p>Following is an example that creates the <code class="filename">poky-extras</code> Git + repository inside the source directory, which is named <code class="filename">poky</code> + in this case: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/poky-extras poky-extras + Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ + remote: Counting objects: 618, done. + remote: Compressing objects: 100% (558/558), done. + remote: Total 618 (delta 192), reused 307 (delta 39) + Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done. + Resolving deltas: 100% (192/192), done. + </pre></li><li class="listitem"><p><a id="supported-board-support-packages-(bsps)"></a><span class="emphasis"><em>Supported Board + Support Packages (BSPs):</em></span> + The Yocto Project provides a layer called <code class="filename">meta-intel</code> and + it is maintained in its own separate Git repository. + The <code class="filename">meta-intel</code> layer contains many supported + <a class="link" href="#bsp-layers" target="_top">BSP Layers</a>.</p><p>Similar considerations exist for setting up the <code class="filename">meta-intel</code> + layer. + You can get set up for BSP development one of two ways: tarball extraction or + with a local Git repository. + It is a good idea to use the same method that you used to set up the source directory. + Regardless of the method you use, the Yocto Project uses the following BSP layer + naming scheme: + </p><pre class="literallayout"> + meta-<BSP_name> + </pre><p> + where <BSP_name> is the recognized BSP name. + Here are some examples: + </p><pre class="literallayout"> + meta-crownbay + meta-emenlow + meta-n450 + </pre><p> + See the + "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" + section in the Yocto Project Board Support Package (BSP) Developer's Guide for more + information on BSP Layers. + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em>Tarball Extraction:</em></span> You can download any released + BSP tarball from the same + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">download site</a> used + to get the Yocto Project release. + Once you have the tarball, just extract it into a directory of your choice. + Again, this method just produces a snapshot of the BSP layer in the form + of a hierarchical directory structure.</p></li><li class="listitem"><p><span class="emphasis"><em>Git Repository Method:</em></span> If you are working + with a local Git repository for your source directory, you should also use this method + to set up the <code class="filename">meta-intel</code> Git repository. + You can locate the <code class="filename">meta-intel</code> Git repository in the + "Yocto Metadata Layers" area of the Yocto Project Source Repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>.</p><p>Typically, you set up the <code class="filename">meta-intel</code> Git repository inside + the source directory. + For example, the following transcript shows the steps to clone the + <code class="filename">meta-intel</code> + Git repository inside the local <code class="filename">poky</code> Git repository. + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/meta-intel.git + Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ + remote: Counting objects: 3380, done. + remote: Compressing objects: 100% (2750/2750), done. + remote: Total 3380 (delta 1689), reused 227 (delta 113) + Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. + Resolving deltas: 100% (1689/1689), done. + </pre><p>The same + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP" target="_top"> + wiki page</a> referenced earlier covers how to + set up the <code class="filename">meta-intel</code> Git repository.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em>Eclipse Yocto Plug-in:</em></span> If you are developing + applications using the Eclipse Integrated Development Environment (IDE), + you will need this plug-in. + See the + "<a class="link" href="#setting-up-the-eclipse-ide" title="5.2.2.1. Setting Up the Eclipse IDE">Setting up the Eclipse IDE</a>" + section for more information.</p></li></ul></div><p> + </p></div><div class="section" title="2.3. Building Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-images"></a>2.3. Building Images</h2></div></div></div><p> + The build process creates an entire Linux distribution, including the toolchain, from source. + For more information on this topic, see the + "<a class="link" href="#building-image" target="_top">Building an Image</a>" + section in the Yocto Project Quick Start. + </p><p> + The build process is as follows: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Make sure you have set up the source directory described in the + previous section.</p></li><li class="listitem"><p>Initialize the build environment by sourcing a build environment + script.</p></li><li class="listitem"><p>Optionally ensure the <code class="filename">conf/local.conf</code> configuration file, + which is found in the + <a class="link" href="#build-directory">build directory</a>, + is set up how you want it. + This file defines many aspects of the build environment including + the target machine architecture through the + <code class="filename"><a class="link" href="#var-MACHINE" target="_top">MACHINE</a></code> variable, + the development machine's processor use through the + <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" target="_top">BB_NUMBER_THREADS</a></code> and + <code class="filename"><a class="link" href="#var-PARALLEL_MAKE" target="_top">PARALLEL_MAKE</a></code> variables, and + a centralized tarball download directory through the + <code class="filename"><a class="link" href="#var-DL_DIR" target="_top">DL_DIR</a></code> variable.</p></li><li class="listitem"><p>Build the image using the <code class="filename">bitbake</code> command. + If you want information on BitBake, see the user manual at + <a class="ulink" href="http://docs.openembedded.org/bitbake/html" target="_top">http://docs.openembedded.org/bitbake/html</a>.</p></li><li class="listitem"><p>Run the image either on the actual hardware or using the QEMU + emulator.</p></li></ol></div><p> + </p></div><div class="section" title="2.4. Using Pre-Built Binaries and QEMU"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-pre-built-binaries-and-qemu"></a>2.4. Using Pre-Built Binaries and QEMU</h2></div></div></div><p> + Another option you have to get started is to use pre-built binaries. + The Yocto Project provides many types of binaries with each release. + See the <a class="link" href="#ref-images" target="_top">Images</a> + chapter in the Yocto Project Reference Manual + for descriptions of the types of binaries that ship with a Yocto Project + release. + </p><p> + Using a pre-built binary is ideal for developing software applications to run on your + target hardware. + To do this, you need to be able to access the appropriate cross-toolchain tarball for + the architecture on which you are developing. + If you are using an SDK type image, the image ships with the complete toolchain native to + the architecture. + If you are not using an SDK type image, you need to separately download and + install the stand-alone Yocto Project cross-toolchain tarball. + </p><p> + Regardless of the type of image you are using, you need to download the pre-built kernel + that you will boot in the QEMU emulator and then download and extract the target root + filesystem for your target machine’s architecture. + You can get architecture-specific binaries and filesystem from + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top">machines</a>. + You can get stand-alone toolchains from + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/" target="_top">toolchains</a>. + Once you have all your files, you set up the environment to emulate the hardware + by sourcing an environment setup script. + Finally, you start the QEMU emulator. + You can find details on all these steps in the + "<a class="link" href="#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>" + section of the Yocto Project Quick Start. + </p><p> + Using QEMU to emulate your hardware can result in speed issues + depending on the target and host architecture mix. + For example, using the <code class="filename">qemux86</code> image in the emulator + on an Intel-based 32-bit (x86) host machine is fast because the target and + host architectures match. + On the other hand, using the <code class="filename">qemuarm</code> image on the same Intel-based + host can be slower. + But, you still achieve faithful emulation of ARM-specific issues. + </p><p> + To speed things up, the QEMU images support using <code class="filename">distcc</code> + to call a cross-compiler outside the emulated system. + If you used <code class="filename">runqemu</code> to start QEMU, and the + <code class="filename">distccd</code> application is present on the host system, any + BitBake cross-compiling toolchain available from the build system is automatically + used from within QEMU simply by calling <code class="filename">distcc</code>. + You can accomplish this by defining the cross-compiler variable + (e.g. <code class="filename">export CC="distcc"</code>). + Alternatively, if you are using a suitable SDK image or the appropriate + stand-alone toolchain is present in <code class="filename">/opt/poky</code>, + the toolchain is also automatically used. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Several mechanisms exist that let you connect to the system running on the + QEMU emulator: + <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>QEMU provides a framebuffer interface that makes standard + consoles available.</p></li><li class="listitem"><p>Generally, headless embedded devices have a serial port. + If so, you can configure the operating system of the running image + to use that port to run a console. + The connection uses standard IP networking.</p></li><li class="listitem"><p>SSH servers exist in some QEMU images. + The <code class="filename">core-image-sato</code> QEMU image has a Dropbear secure + shell (ssh) server that runs with the root password disabled. + The <code class="filename">core-image-basic</code> and <code class="filename">core-image-lsb</code> QEMU images + have OpenSSH instead of Dropbear. + Including these SSH servers allow you to use standard <code class="filename">ssh</code> and + <code class="filename">scp</code> commands. + The <code class="filename">core-image-minimal</code> QEMU image, however, contains no ssh + server.</p></li><li class="listitem"><p>You can use a provided, user-space NFS server to boot the QEMU session + using a local copy of the root filesystem on the host. + In order to make this connection, you must extract a root filesystem tarball by using the + <code class="filename">runqemu-extract-sdk</code> command. + After running the command, you must then point the <code class="filename">runqemu</code> + script to the extracted directory instead of a root filesystem image file.</p></li></ul></div></div></div></div> + + <div class="chapter" title="Chapter 3. The Yocto Project Open Source Development Environment"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-newbie"></a>Chapter 3. The Yocto Project Open Source Development Environment</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#open-source-philosophy">3.1. Open Source Philosophy</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-collaborate">3.2. Using the Yocto Project in a Team Environment</a></span></dt><dt><span class="section"><a href="#yocto-project-repositories">3.3. Yocto Project Source Repositories</a></span></dt><dt><span class="section"><a href="#yocto-project-terms">3.4. Yocto Project Terms</a></span></dt><dt><span class="section"><a href="#licensing">3.5. Licensing</a></span></dt><dt><span class="section"><a href="#git">3.6. Git</a></span></dt><dd><dl><dt><span class="section"><a href="#repositories-tags-and-branches">3.6.1. Repositories, Tags, and Branches</a></span></dt><dt><span class="section"><a href="#basic-commands">3.6.2. Basic Commands</a></span></dt></dl></dd><dt><span class="section"><a href="#workflows">3.7. Workflows</a></span></dt><dt><span class="section"><a href="#tracking-bugs">3.8. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#how-to-submit-a-change">3.9. How to Submit a Change</a></span></dt><dd><dl><dt><span class="section"><a href="#pushing-a-change-upstream">3.9.1. Using Scripts to Push a Change Upstream and Request a Pull</a></span></dt><dt><span class="section"><a href="#submitting-a-patch">3.9.2. Using Email to Submit a Patch</a></span></dt></dl></dd></dl></div><p> + This chapter helps you understand the Yocto Project as an open source development project. + In general, working in an open source environment is very different from working in a + closed, proprietary environment. + Additionally, the Yocto Project uses specific tools and constructs as part of its development + environment. + This chapter specifically addresses open source philosophy, licensing issues, code repositories, + the open source distributed version control system Git, and best practices using the Yocto Project. +</p><div class="section" title="3.1. Open Source Philosophy"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="open-source-philosophy"></a>3.1. Open Source Philosophy</h2></div></div></div><p> + Open source philosophy is characterized by software development directed by peer production + and collaboration through an active community of developers. + Contrast this to the more standard centralized development models used by commercial software + companies where a finite set of developers produces a product for sale using a defined set + of procedures that ultimately result in an end product whose architecture and source material + are closed to the public. + </p><p> + Open source projects conceptually have differing concurrent agendas, approaches, and production. + These facets of the development process can come from anyone in the public (community) that has a + stake in the software project. + The open source environment contains new copyright, licensing, domain, and consumer issues + that differ from the more traditional development environment. + In an open source environment, the end product, source material, and documentation are + all available to the public at no cost. + </p><p> + A benchmark example of an open source project is the Linux Kernel, which was initially conceived + and created by Finnish computer science student Linus Torvalds in 1991. + Conversely, a good example of a non-open source project is the + <span class="trademark">Windows</span>® family of operating + systems developed by <span class="trademark">Microsoft</span>® Corporation. + </p><p> + Wikipedia has a good historical description of the Open Source Philosophy + <a class="ulink" href="http://en.wikipedia.org/wiki/Open_source" target="_top">here</a>. + You can also find helpful information on how to participate in the Linux Community + <a class="ulink" href="http://ldn.linuxfoundation.org/book/how-participate-linux-community" target="_top">here</a>. + </p></div><div class="section" title="3.2. Using the Yocto Project in a Team Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-changes-collaborate"></a>3.2. Using the Yocto Project in a Team Environment</h2></div></div></div><p> + It might not be immediately clear how you can use the Yocto Project in a team environment, + or scale it for a large team of developers. + The specifics of any situation determine the best solution. + Granted that the Yocto Project offers immense flexibility regarding this, practices do exist + that experience has shown work well. + </p><p> + The core component of any development effort with the Yocto Project is often an + automated build and testing framework along with an image generation process. + You can use these core components to check that the metadata can be built, + highlight when commits break the build, and provide up-to-date images that + allow developers to test the end result and use it as a base platform for further + development. + Experience shows that buildbot is a good fit for this role. + What works well is to configure buildbot to make two types of builds: + incremental and full (from scratch). + See <a class="ulink" href="http://autobuilder.yoctoproject.org:8010/" target="_top">the buildbot for the + Yocto Project</a> for an example implementation that uses buildbot. + </p><p> + You can tie incremental builds to a commit hook that triggers the build + each time a commit is made to the metadata. + This practice results in useful acid tests that determine whether a given commit + breaks the build in some serious way. + Associating a build to a commit can catch a lot of simple errors. + Furthermore, the tests are fast so developers can get quick feedback on changes. + </p><p> + Full builds build and test everything from the ground up. + These types of builds usually happen at predetermined times like during the + night when the machine load is low. + </p><p> + Most teams have many pieces of software undergoing active development at any given time. + You can derive large benefits by putting these pieces under the control of a source + control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded + build system that the Yocto Project uses. + You can then set the autobuilder to pull the latest revisions of the packages + and test the latest commits by the builds. + This practice quickly highlights issues. + The build system easily supports testing configurations that use both a + stable known good revision and a floating revision. + The build system can also take just the changes from specific source control branches. + This capability allows you to track and test specific changes. + </p><p> + Perhaps the hardest part of setting this up is defining the software project or + the metadata policies that surround the different source control systems. + Of course circumstances will be different in each case. + However, this situation reveals one of the Yocto Project's advantages - + the system itself does not + force any particular policy on users, unlike a lot of build systems. + The system allows the best policies to be chosen for the given circumstances. + </p></div><div class="section" title="3.3. Yocto Project Source Repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yocto-project-repositories"></a>3.3. Yocto Project Source Repositories</h2></div></div></div><p> + The Yocto Project team maintains complete source repositories for all Yocto Project files + at <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi</a>. + This web-based source code browser is organized into categories by function such as + IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. + From the interface, you can click on any particular item in the "Name" column and + see the URL at the bottom of the page that you need to set up a Git repository for + that particular item. + Having a local Git repository of the source directory (poky) allows you to + make changes, contribute to the history, and ultimately enhance the Yocto Project's + tools, Board Support Packages, and so forth. + </p><p> + Conversely, if you are a developer that is not interested in contributing back to the + Yocto Project, you have the ability to simply download and extract release tarballs + and use them within the Yocto Project environment. + All that is required is a particular release of the Yocto Project and + your application source code. + </p><p> + For any supported release of Yocto Project, you can go to the Yocto Project website’s + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">download page</a> and get a + tarball of the release. + You can also go to this site to download any supported BSP tarballs. + Unpacking the tarball gives you a hierarchical source directory that lets you develop + using the Yocto Project. + </p><p> + Once you are set up through either tarball extraction or creation of Git repositories, + you are ready to develop. + </p><p> + In summary, here is where you can get the project files needed for development: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a id="source-repositories"></a><span class="emphasis"><em><a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">Source Repositories:</a></em></span> + This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto + Metadata Layers. + You can create local copies of Git repositories for each of these areas.</p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/source-repos.png" align="middle" width="540" /></td></tr></table><p> + </p></li><li class="listitem"><p><a id="index-downloads"></a><span class="emphasis"><em><a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a></em></span> + This area contains index releases such as + the <span class="trademark">Eclipse</span>™ + Yocto Plug-in, miscellaneous support, poky, pseudo, cross-development toolchains, + and all released versions of Yocto Project in the form of images or tarballs. + Downloading and extracting these files does not produce a local copy of the + Git repository but rather a snapshot of a particular release or image.</p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/index-downloads.png" align="middle" width="540" /></td></tr></table><p> + </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Yocto Project Download Page</a></em></span> + This page on the Yocto Project website allows you to download any Yocto Project + release or Board Support Package (BSP) in tarball form. + The tarballs are similar to those found in the + <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a> area.</p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/yp-download.png" align="middle" width="540" /></td></tr></table><p> + </p></li></ul></div><p> + </p></div><div class="section" title="3.4. Yocto Project Terms"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="yocto-project-terms"></a>3.4. Yocto Project Terms</h2></div></div></div><p> + Following is a list of terms and definitions users new to the Yocto Project development + environment might find helpful. + While some of these terms are universal, the list includes them just in case: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Append Files:</em></span> Files that append build information to + a recipe file. + Append files are known as BitBake append files and <code class="filename">.bbappend</code> files. + The OpenEmbedded build system expects every append file to have a corresponding and + underlying recipe (<code class="filename">.bb</code>) file. + Furthermore, the append file and the underlying recipe must have the same root filename. + The filenames can differ only in the file type suffix used (e.g. + <code class="filename">formfactor_0.0.bb</code> and <code class="filename">formfactor_0.0.bbappend</code>). + </p><p>Information in append files overrides the information in the similarly-named recipe file. + For examples of <code class="filename">.bbappend</code> file in use, see the + "<a class="link" href="#using-bbappend-files" title="4.1.4. Using .bbappend Files">Using .bbappend Files</a>" and + "<a class="link" href="#changing-recipes-kernel" title="A.5.2.4. Changing recipes-kernel">Changing <code class="filename">recipes-kernel</code></a>" + sections.</p></li><li class="listitem"><p><span class="emphasis"><em>BitBake:</em></span> The task executor and scheduler used by + the OpenEmbedded build system to build images. + For more information on BitBake, see the <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top"> + BitBake documentation</a>.</p></li><li class="listitem"><p><a id="build-directory"></a><span class="emphasis"><em>Build Directory:</em></span> + This term refers to the area used by the OpenEmbedded build system for builds. + The area is created when you <code class="filename">source</code> the setup + environment script that is found in the source directory + (i.e. <code class="filename">oe-init-build-env</code>). + The <a class="link" href="#var-TOPDIR" target="_top"><code class="filename">TOPDIR</code></a> + variable points to the build directory.</p><p>You have a lot of flexibility when creating the build directory. + Following are some examples that show how to create the directory: + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Create the build directory in your current working directory + and name it <code class="filename">build</code>. + This is the default behavior. + </p><pre class="literallayout"> + $ source oe-init-build-env + </pre></li><li class="listitem"><p>Provide a directory path and specifically name the build + directory. + This next example creates a build directory named <code class="filename">YP-8.0</code> + in your home directory within the directory <code class="filename">mybuilds</code>. + If <code class="filename">mybuilds</code> does not exist, the directory is created for you: + </p><pre class="literallayout"> + $ source poky-1.2+snapshot-8.0/oe-init-build-env $HOME/mybuilds/YP-8.0 + </pre></li><li class="listitem"><p>Provide an existing directory to use as the build directory. + This example uses the existing <code class="filename">mybuilds</code> directory + as the build directory. + </p><pre class="literallayout"> + $ source poky-1.2+snapshot-8.0/oe-init-build-env $HOME/mybuilds/ + </pre></li></ul></div><p> + </p></li><li class="listitem"><p><span class="emphasis"><em>Build System:</em></span> In the context of the Yocto Project + this term refers to the OpenEmbedded build system used by the project. + This build system is based on the project known as "Poky." + For some historical information about Poky, see the + <a class="link" href="#poky">poky</a> term further along in this section. + </p></li><li class="listitem"><p><span class="emphasis"><em>Classes:</em></span> Files that provide for logic encapsulation + and inheritance allowing commonly used patterns to be defined once and easily used + in multiple recipes. + Class files end with the <code class="filename">.bbclass</code> filename extension. + </p></li><li class="listitem"><p><span class="emphasis"><em>Configuration File:</em></span> Configuration information in various + <code class="filename">.conf</code> files provides global definitions of variables. + The <code class="filename">conf/local.conf</code> configuration file in the + <a class="link" href="#build-directory">build directory</a> + contains user-defined variables that affect each build. + The <code class="filename">meta-yocto/conf/distro/poky.conf</code> configuration file + defines Yocto ‘distro’ configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the + <a class="link" href="#source-directory">source directory</a>, define + variables for specific hardware and are only used when building for that target + (e.g. the <code class="filename">machine/beagleboard.conf</code> configuration file defines + variables for the Texas Instruments ARM Cortex-A8 development board). + Configuration files end with a <code class="filename">.conf</code> filename extension. + </p></li><li class="listitem"><p><span class="emphasis"><em>Cross-Development Toolchain:</em></span> + A collection of software development + tools and utilities that allow you to develop software for targeted architectures. + This toolchain contains cross-compilers, linkers, and debuggers that are specific to + an architecture. + You can use the OpenEmbedded build system to build cross-development toolchains in tarball + form that, when + unpacked, contain the development tools you need to cross-compile and test your software. + The Yocto Project ships with images that contain toolchains for supported architectures + as well. + Sometimes this toolchain is referred to as the meta-toolchain.</p></li><li class="listitem"><p><span class="emphasis"><em>Image:</em></span> An image is the result produced when + BitBake processes a given collection of recipes and related metadata. + Images are the binary output that run on specific hardware and for specific + use cases. + For a list of the supported image types that the Yocto Project provides, see the + "<a class="link" href="#ref-images" target="_top">Images</a>" + chapter in the Yocto Project Reference Manual.</p></li><li class="listitem"><p><a id="layer"></a><span class="emphasis"><em>Layer:</em></span> A collection of recipes representing the core, + a BSP, or an application stack. + For a discussion on BSP Layers, see the + "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" + section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</p></li><li class="listitem"><p><a id="metadata"></a><span class="emphasis"><em>Metadata:</em></span> The files that BitBake parses when + building an image. + Metadata includes recipes, classes, and configuration files.</p></li><li class="listitem"><p><span class="emphasis"><em>OE-Core:</em></span> A core set of metadata originating + with OpenEmbedded (OE) that is shared between OE and the Yocto Project. + This metadata is found in the <code class="filename">meta</code> directory of the source + directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Package:</em></span> The packaged output from a baked recipe. + A package is generally the compiled binaries produced from the recipe's sources. + You ‘bake’ something by running it through BitBake.</p></li><li class="listitem"><p><a id="poky"></a><span class="emphasis"><em>Poky:</em></span> The term "poky" can mean several things. + In its most general sence, it is an open-source project that was initially developed + by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded + build system becoming a build system for embedded images. + After Intel Corporation aquired OpenedHand, the project poky became the basis for + the Yocto Project's build system. + Within the Yocto Project source repositories, poky exists as a separate Git repository + that can be cloned to yield a local copy on the host system. + Thus, "poky" can refer to the local copy of the source directory used to develop within + the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>Recipe:</em></span> A set of instructions for building packages. + A recipe describes where you get source code and which patches to apply. + Recipes describe dependencies for libraries or for other recipes, and they + also contain configuration and compilation options. + Recipes contain the logical unit of execution, the software/images to build, and + use the <code class="filename">.bb</code> file extension.</p></li><li class="listitem"><p><a id="source-directory"></a><span class="emphasis"><em>Source Directory:</em></span> + This term refers to the directory structure created as a result of either downloading + and unpacking a Yocto Project release tarball or creating a local copy of + <code class="filename">poky</code> Git repository <code class="filename">git://git.yoctoproject.org/poky</code>. + Sometimes you might here the term "poky directory" used to refer to this + directory structure.</p><p>The source directory contains BitBake, Documentation, metadata and + other files that all support the Yocto Project. + Consequently, you must have the source directory in place on your development + system in order to do any development using the Yocto Project.</p><p>For tarball expansion, the name of the top-level directory of the source directory + is derived from the Yocto Project release tarball. + For example, downloading and unpacking <code class="filename">poky-1.2+snapshot-8.0.tar.bz2</code> + results in a source directory whose top-level folder is named + <code class="filename">poky-1.2+snapshot-8.0</code>. + If you create a local copy of the Git repository, then you can name the repository + anything you like. + Throughout much of the documentation, <code class="filename">poky</code> is used as the name of + the top-level folder of the local copy of the poky Git repository. + So, for example, cloning the <code class="filename">poky</code> Git repository results in a + local Git repository whose top-level folder is also named <code class="filename">poky</code>.</p><p>It is important to understand the differences between the source directory created + by unpacking a released tarball as compared to cloning + <code class="filename">git://git.yoctoproject.org/poky</code>. + When you unpack a tarball, you have an exact copy of the files based on the time of + release - a fixed release point. + Any changes you make to your local files in the source directory are on top of the release. + On the other hand, when you clone the <code class="filename">poky</code> Git repository, you have an + active development repository. + In this case, any local changes you make to the source directory can be later applied + to active development branches of the upstream <code class="filename">poky</code> Git + repository.</p><p>Finally, if you want to track a set of local changes while starting from the same point + as a release tarball, you can create a local Git branch that + reflects the exact copy of the files at the time of their release. + You do this using Git tags that are part of the repository.</p><p>For more information on concepts around Git repositories, branches, and tags, + see the + "<a class="link" href="#repositories-tags-and-branches" title="3.6.1. Repositories, Tags, and Branches">Repositories, Tags, and Branches</a>" + section.</p></li><li class="listitem"><p><span class="emphasis"><em>Tasks:</em></span> Arbitrary groups of software Recipes. + You simply use Tasks to hold recipes that, when built, usually accomplish a single task. + For example, a task could contain the recipes for a company’s proprietary or value-add software. + Or, the task could contain the recipes that enable graphics. + A task is really just another recipe. + Because task files are recipes, they end with the <code class="filename">.bb</code> filename + extension.</p></li><li class="listitem"><p><span class="emphasis"><em>Upstream:</em></span> A reference to source code or repositories + that are not local to the development system but located in a master area that is controlled + by the maintainer of the source code. + For example, in order for a developer to work on a particular piece of code, they need to + first get a copy of it from an "upstream" source.</p></li></ul></div><p> + </p></div><div class="section" title="3.5. Licensing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licensing"></a>3.5. Licensing</h2></div></div></div><p> + Because open source projects are open to the public, they have different licensing structures in place. + License evolution for both Open Source and Free Software has an interesting history. + If you are interested in this history, you can find basic information here: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://en.wikipedia.org/wiki/Open-source_license" target="_top">Open source license history</a> + </p></li><li class="listitem"><p><a class="ulink" href="http://en.wikipedia.org/wiki/Free_software_license" target="_top">Free software license + history</a></p></li></ul></div><p> + </p><p> + In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology + (MIT) License. + MIT licensing permits the reuse of software within proprietary software as long as the + license is distributed with that software. + MIT is also compatible with the GNU General Public License (GPL). + Patches to the Yocto Project follow the upstream licensing scheme. + You can find information on the MIT license at + <a class="ulink" href="http://www.opensource.org/licenses/mit-license.php" target="_top">here</a>. + You can find information on the GNU GPL <a class="ulink" href="http://www.opensource.org/licenses/LGPL-3.0" target="_top"> + here</a>. + </p><p> + When you build an image using Yocto Project, the build process uses a known list of licenses to + ensure compliance. + You can find this list in the Yocto Project files directory at + <code class="filename">meta/files/common-licenses</code>. + Once the build completes, the list of all licenses found and used during that build are + kept in the + <a class="link" href="#build-directory">build directory</a> at + <code class="filename">tmp/deploy/images/licenses</code>. + </p><p> + If a module requires a license that is not in the base list, the build process + generates a warning during the build. + These tools make it easier for a developer to be certain of the licenses with which + their shipped products must comply. + However, even with these tools it is still up to the developer to resolve potential licensing issues. + </p><p> + The base list of licenses used by the build process is a combination of the Software Package + Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects. + <a class="ulink" href="http://spdx.org" target="_top">SPDX Group</a> is a working group of the Linux Foundation + that maintains a specification + for a standard format for communicating the components, licenses, and copyrights + associated with a software package. + <a class="ulink" href="http://opensource.org" target="_top">OSI</a> is a corporation dedicated to the Open Source + Definition and the effort for reviewing and approving licenses that are OSD-conformant. + </p><p> + You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses + <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/files/common-licenses" target="_top">here</a>. + This wiki page discusses the license infrastructure used by the Yocto Project. + </p></div><div class="section" title="3.6. Git"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="git"></a>3.6. Git</h2></div></div></div><p> + The Yocto Project uses Git, which is a free, open source distributed version control system. + Git supports distributed development, non-linear development, and can handle large projects. + It is best that you have some fundamental understanding of how Git tracks projects and + how to work with Git if you are going to use Yocto Project for development. + This section provides a quick overview of how Git works and provides you with a summary + of some essential Git commands. + </p><p> + For more information on Git, see + <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. + If you need to download Git, go to <a class="ulink" href="http://git-scm.com/download" target="_top">http://git-scm.com/download</a>. + </p><div class="section" title="3.6.1. Repositories, Tags, and Branches"><div class="titlepage"><div><div><h3 class="title"><a id="repositories-tags-and-branches"></a>3.6.1. Repositories, Tags, and Branches</h3></div></div></div><p> + As mentioned earlier in section + "<a class="link" href="#yocto-project-repositories" title="3.3. Yocto Project Source Repositories">Yocto Project Source Repositories</a>", + the Yocto Project maintains source repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. + If you look at this web-interface of the repositories, each item is a separate + Git repository. + </p><p> + Git repositories use branching techniques that track content change (not files) + within a project (e.g. a new feature or updated documentation). + Creating a tree-like structure based on project divergence allows for excellent historical + information over the life of a project. + This methodology also allows for an environment in which you can do lots of + local experimentation on a project as you develop changes or new features. + </p><p> + A Git repository represents all development efforts for a given project. + For example, the Git repository <code class="filename">poky</code> contains all changes + and developments for Poky over the course of its entire life. + That means that all changes that make up all releases are captured. + The repository maintains a complete history of changes. + </p><p> + You can create a local copy of any repository by "cloning" it with the Git + <code class="filename">clone</code> command. + When you clone a Git repository, you end up with an identical copy of the + repository on your development system. + Once you have a local copy of a repository, you can take steps to develop locally. + For examples on how to clone Git repositories, see the section + "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Set Up</a>" earlier in this manual. + </p><p> + It is important to understand that Git tracks content change and not files. + Git uses "branches" to organize different development efforts. + For example, the <code class="filename">poky</code> repository has + <code class="filename">laverne</code>, <code class="filename">bernard</code>, + <code class="filename">edison</code>, <code class="filename">denzil</code> and + <code class="filename">master</code> branches among + others. + You can see all the branches by going to + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and + clicking on the + <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/heads" target="_top">[...]</a></code> + link beneath the "Branch" heading. + </p><p> + Each of these branches represents a specific area of development. + The <code class="filename">master</code> branch represents the current or most recent + development. + All other branches represent off-shoots of the <code class="filename">master</code> + branch. + </p><p> + When you create a local copy of a Git repository, the copy has the same set + of branches as the original. + This means you can use Git to create a local working area (also called a branch) + that tracks a specific development branch from the source Git repository. + in other words, you can define your local Git environment to work on any development + branch in the repository. + To help illustrate, here is a set of commands that creates a local copy of the + <code class="filename">poky</code> Git repository and then creates and checks out a local + Git branch that tracks the Yocto Project 1.3 Release (1.2+snapshot) development: + </p><pre class="literallayout"> + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b 1.2+snapshot origin/1.2+snapshot + </pre><p> + In this example, the name of the top-level directory of your local Yocto Project + Files Git repository is <code class="filename">poky</code>, + and the name of the local working area (or local branch) you have created and checked + out is <code class="filename">1.2+snapshot</code>. + The files in your repository now reflect the same files that are in the + <code class="filename">1.2+snapshot</code> development branch of the Yocto Project's + <code class="filename">poky</code> repository. + It is important to understand that when you create and checkout a + local working branch based on a branch name, + your local environment matches the "tip" of that development branch + at the time you created your local branch, which could be + different than the files at the time of a similarly named release. + In other words, creating and checking out a local branch based on the + <code class="filename">1.2+snapshot</code> branch name is not the same as creating and + checking out a local branch based on the <code class="filename">1.2+snapshot-1.3</code> + release. + Keep reading to see how you create a local snapshot of a Yocto Project Release. + </p><p> + Git uses "tags" to mark specific changes in a repository. + Typically, a tag is used to mark a special point such as the final change + before a project is released. + You can see the tags used with the <code class="filename">poky</code> Git repository + by going to <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and + clicking on the + <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/tags" target="_top">[...]</a></code> + link beneath the "Tag" heading. + </p><p> + Some key tags are <code class="filename">laverne-4.0</code>, <code class="filename">bernard-5.0</code>, + and <code class="filename">1.2+snapshot-8.0</code>. + These tags represent Yocto Project releases. + </p><p> + When you create a local copy of the Git repository, you also have access to all the + tags. + Similar to branches, you can create and checkout a local working Git branch based + on a tag name. + When you do this, you get a snapshot of the Git repository that reflects + the state of the files when the change was made associated with that tag. + The most common use is to checkout a working branch that matches a specific + Yocto Project release. + Here is an example: + </p><pre class="literallayout"> + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b my-1.2+snapshot-8.0 1.2+snapshot-8.0 + </pre><p> + In this example, the name of the top-level directory of your local Yocto Project + Files Git repository is <code class="filename">poky</code>. + And, the name of the local branch you have created and checked out is + <code class="filename">my-1.2+snapshot-8.0</code>. + The files in your repository now exactly match the Yocto Project 1.3 + Release tag (<code class="filename">1.2+snapshot-8.0</code>). + It is important to understand that when you create and checkout a local + working branch based on a tag, your environment matches a specific point + in time and not a development branch. + </p></div><div class="section" title="3.6.2. Basic Commands"><div class="titlepage"><div><div><h3 class="title"><a id="basic-commands"></a>3.6.2. Basic Commands</h3></div></div></div><p> + Git has an extensive set of commands that lets you manage changes and perform + collaboration over the life of a project. + Conveniently though, you can manage with a small set of basic operations and workflows + once you understand the basic philosophy behind Git. + You do not have to be an expert in Git to be functional. + A good place to look for instruction on a minimal set of Git commands is + <a class="ulink" href="http://git-scm.com/documentation" target="_top">here</a>. + If you need to download Git, you can do so + <a class="ulink" href="http://git-scm.com/download" target="_top">here</a>. + </p><p> + If you don’t know much about Git, we suggest you educate + yourself by visiting the links previously mentioned. + </p><p> + The following list briefly describes some basic Git operations as a way to get started. + As with any set of commands, this list (in most cases) simply shows the base command and + omits the many arguments they support. + See the Git documentation for complete descriptions and strategies on how to use these commands: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">git init</code>:</em></span> Initializes an empty Git repository. + You cannot use Git commands unless you have a <code class="filename">.git</code> repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git clone</code>:</em></span> Creates a clone of a repository. + During collaboration, this command allows you to create a local repository that is on + equal footing with a fellow developer’s repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git add</code>:</em></span> Adds updated file contents + to the index that + Git uses to track changes. + You must add all files that have changed before you can commit them.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git commit</code>:</em></span> Creates a “commit” that documents + the changes you made. + Commits are used for historical purposes, for determining if a maintainer of a project + will allow the change, and for ultimately pushing the change from your local Git repository + into the project’s upstream (or master) repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git status</code>:</em></span> Reports any modified files that + possibly need to be added and committed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout <branch-name></code>:</em></span> Changes + your working branch. + This command is analogous to “cd”.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout –b <working-branch></code>:</em></span> Creates + a working branch on your local machine where you can isolate work. + It is a good idea to use local branches when adding specific features or changes. + This way if you don’t like what you have done you can easily get rid of the work.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch</code>:</em></span> Reports existing branches and + tells you which branch in which you are currently working.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch -D <branch-name></code>:</em></span> + Deletes an existing branch. + You need to be in a branch other than the one you are deleting + in order to delete <branch-name>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git pull</code>:</em></span> Retrieves information + from an upstream Git + repository and places it in your local Git repository. + You use this command to make sure you are synchronized with the repository + from which you are basing changes (.e.g. the master repository).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git push</code>:</em></span> Sends all your local changes you + have committed to an upstream Git repository (e.g. a contribution repository). + The maintainer of the project draws from these repositories when adding your changes to the + project’s master repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git merge</code>:</em></span> Combines or adds changes from one + local branch of your repository with another branch. + When you create a local Git repository, the default branch is named “master”. + A typical workflow is to create a temporary branch for isolated work, make and commit your + changes, switch to your local master branch, merge the changes from the temporary branch into the + local master branch, and then delete the temporary branch.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git cherry-pick</code>:</em></span> Choose and apply specific + commits from one branch into another branch. + There are times when you might not be able to merge all the changes in one branch with + another but need to pick out certain ones.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gitk</code>:</em></span> Provides a GUI view of the branches + and changes in your local Git repository. + This command is a good way to graphically see where things have diverged in your + local repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git log</code>:</em></span> Reports a history of your changes to the + repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git diff</code>:</em></span> Displays line-by-line differences + between your local working files and the same files in the upstream Git repository that your + branch currently tracks.</p></li></ul></div><p> + </p></div></div><div class="section" title="3.7. Workflows"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="workflows"></a>3.7. Workflows</h2></div></div></div><p> + This section provides some overview on workflows using Git. + In particular, the information covers basic practices that describe roles and actions in a + collaborative development environment. + Again, if you are familiar with this type of development environment, you might want to just + skip this section. + </p><p> + The Yocto Project files are maintained using Git in a "master" branch whose Git history + tracks every change and whose structure provides branches for all diverging functionality. + Although there is no need to use Git, many open source projects do so. + For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" + branch of the Git repository. + The "master" branch is the “upstream” repository where the final builds of the project occur. + The maintainer is responsible for allowing changes in from other developers and for + organizing the underlying branch structure to reflect release strategies and so forth. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>You can see who is the maintainer for Yocto Project files by examining the + <code class="filename">distro_tracking_fields.inc</code> file in the Yocto Project + <code class="filename">meta/conf/distro/include</code> directory.</div><p> + </p><p> + The project also has contribution repositories known as “contrib” areas. + These areas temporarily hold changes to the project that have been submitted or committed + by the Yocto Project development team and by community members that contribute to the project. + The maintainer determines if the changes are qualified to be moved from the "contrib" areas + into the "master" branch of the Git repository. + </p><p> + Developers (including contributing community members) create and maintain cloned repositories + of the upstream "master" branch. + These repositories are local to their development platforms and are used to develop changes. + When a developer is satisfied with a particular feature or change, they “push” the changes + to the appropriate "contrib" repository. + </p><p> + Developers are responsible for keeping their local repository up-to-date with "master". + They are also responsible for straightening out any conflicts that might arise within files + that are being worked on simultaneously by more than one person. + All this work is done locally on the developer’s machine before anything is pushed to a + "contrib" area and examined at the maintainer’s level. + </p><p> + A somewhat formal method exists by which developers commit changes and push them into the + "contrib" area and subsequently request that the maintainer include them into "master" + This process is called “submitting a patch” or “submitting a change.” + </p><p> + To summarize the environment: we have a single point of entry for changes into the project’s + "master" branch of the Git repository, which is controlled by the project’s maintainer. + And, we have a set of developers who independently develop, test, and submit changes + to "contrib" areas for the maintainer to examine. + The maintainer then chooses which changes are going to become a permanent part of the project. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 270px"><td align="left"><img src="figures/git-workflow.png" align="left" height="270" /></td></tr></table><p> + </p><p> + While each development environment is unique, there are some best practices or methods + that help development run smoothly. + The following list describes some of these practices. + For more information about Git workflows, see the workflow topics in the + <a class="ulink" href="http://book.git-scm.com" target="_top">Git Community Book</a>. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Make Small Changes:</em></span> It is best to keep the changes you commit + small as compared to bundling many disparate changes into a single commit. + This practice not only keeps things manageable but also allows the maintainer + to more easily include or refuse changes.</p><p>It is also good practice to leave the repository in a state that allows you to + still successfully build your project. In other words, do not commit half of a feature, + then add the other half in a separate, later commit. + Each commit should take you from one buildable project state to another + buildable state.</p></li><li class="listitem"><p><span class="emphasis"><em>Use Branches Liberally:</em></span> It is very easy to create, use, and + delete local branches in your working Git repository. + You can name these branches anything you like. + It is helpful to give them names associated with the particular feature or change + on which you are working. + Once you are done with a feature or change, simply discard the branch.</p></li><li class="listitem"><p><span class="emphasis"><em>Merge Changes:</em></span> The <code class="filename">git merge</code> + command allows you to take the + changes from one branch and fold them into another branch. + This process is especially helpful when more than a single developer might be working + on different parts of the same feature. + Merging changes also automatically identifies any collisions or “conflicts” + that might happen as a result of the same lines of code being altered by two different + developers.</p></li><li class="listitem"><p><span class="emphasis"><em>Manage Branches:</em></span> Because branches are easy to use, you should + use a system where branches indicate varying levels of code readiness. + For example, you can have a “work” branch to develop in, a “test” branch where the code or + change is tested, a “stage” branch where changes are ready to be committed, and so forth. + As your project develops, you can merge code across the branches to reflect ever-increasing + stable states of the development.</p></li><li class="listitem"><p><span class="emphasis"><em>Use Push and Pull:</em></span> The push-pull workflow is based on the + concept of developers “pushing” local commits to a remote repository, which is + usually a contribution repository. + This workflow is also based on developers “pulling” known states of the project down into their + local development repositories. + The workflow easily allows you to pull changes submitted by other developers from the + upstream repository into your work area ensuring that you have the most recent software + on which to develop. + The Yocto Project has two scripts named <code class="filename">create-pull-request</code> and + <code class="filename">send-pull-request</code> that ship with the release to facilitate this + workflow. + You can find these scripts in the local Yocto Project files Git repository in + the <code class="filename">scripts</code> directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Patch Workflow:</em></span> This workflow allows you to notify the + maintainer through an email that you have a change (or patch) you would like considered + for the "master" branch of the Git repository. + To send this type of change you format the patch and then send the email using the Git commands + <code class="filename">git format-patch</code> and <code class="filename">git send-email</code>. + You can find information on how to submit later in this chapter.</p></li></ul></div><p> + </p></div><div class="section" title="3.8. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="tracking-bugs"></a>3.8. Tracking Bugs</h2></div></div></div><p> + The Yocto Project uses its own implementation of + <a class="ulink" href="http://www.bugzilla.org/about/" target="_top">Bugzilla</a> to track bugs. + Implementations of Bugzilla work well for group development because they track bugs and code + changes, can be used to communicate changes and problems with developers, can be used to + submit and review patches, and can be used to manage quality assurance. + The home page for the Yocto Project implementation of Bugzilla is + <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>. + </p><p> + Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself + such as when discovering an issue with some component of the build system that acts contrary + to the documentation or your expectations. + Following is the general procedure for submitting a new bug using the Yocto Project + Bugzilla. + You can find more information on defect management, bug tracking, and feature request + processes all accomplished through the Yocto Project Bugzilla on the wiki page + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Bugzilla_Configuration_and_Bug_Tracking" target="_top">here</a>. + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Always use the Yocto Project implementation of Bugzilla to submit + a bug.</p></li><li class="listitem"><p>When submitting a new bug, be sure to choose the appropriate + Classification, Product, and Component for which the issue was found. + Defects for Yocto Project fall into one of four classifications: Yocto Projects, + Infrastructure, Poky, and Yocto Metadata Layers. + Each of these Classifications break down into multiple Products and, in some + cases, multiple Components.</p></li><li class="listitem"><p>Use the bug form to choose the correct Hardware and Architecture + for which the bug applies.</p></li><li class="listitem"><p>Indicate the Yocto Project version you were using when the issue + occurred.</p></li><li class="listitem"><p>Be sure to indicate the Severity of the bug. + Severity communicates how the bug impacted your work.</p></li><li class="listitem"><p>Provide a brief summary of the issue. + Try to limit your summary to just a line or two and be sure to capture the + essence of the issue.</p></li><li class="listitem"><p>Provide a detailed description of the issue. + You should provide as much detail as you can about the context, behavior, output, + and so forth that surround the issue. + You can even attach supporting files for output or log by using the "Add an attachment" + button.</p></li><li class="listitem"><p>Submit the bug by clicking the "Submit Bug" button.</p></li></ol></div><p> + </p></div><div class="section" title="3.9. How to Submit a Change"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="how-to-submit-a-change"></a>3.9. How to Submit a Change</h2></div></div></div><p> + Contributions to the Yocto Project and OpenEmbedded are very welcome. + Because the system is extremely configurable and flexible, we recognize that developers + will want to extend, configure or optimize it for their specific uses. + You should send patches to the appropriate mailing list so that they + can be reviewed and merged by the appropriate maintainer. + For a list of the Yocto Project and related mailing lists, see the + "<a class="link" href="#resources-mailinglist" target="_top">Mailing lists</a>" section in + the Yocto Project Reference Manual. + </p><p> + The following is some guidance on which mailing list to use for what type of change: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>For changes to the core metadata, send your patch to the + <a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">openembedded-core</a> mailing list. + For example, a change to anything under the <code class="filename">meta</code> or + <code class="filename">scripts</code> directories + should be sent to this mailing list.</p></li><li class="listitem"><p>For changes to BitBake (anything under the <code class="filename">bitbake</code> + directory), send your patch to the + <a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">bitbake-devel</a> mailing list.</p></li><li class="listitem"><p>For changes to <code class="filename">meta-yocto</code>, send your patch to the + <a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">poky</a> mailing list.</p></li><li class="listitem"><p>For changes to other layers hosted on yoctoproject.org (unless the + layer's documentation specifies otherwise), tools, and Yocto Project + documentation, use the + <a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">yocto</a> mailing list.</p></li><li class="listitem"><p>For additional recipes that do not fit into the core metadata, + you should determine which layer the recipe should go into and submit the + change in the manner recommended by the documentation (e.g. README) supplied + with the layer. If in doubt, please ask on the + <a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">yocto</a> or + <a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">openembedded-devel</a> + mailing lists.</p></li></ul></div><p> + </p><p> + When you send a patch, be sure to include a "Signed-off-by:" + line in the same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 + as follows: + </p><pre class="literallayout"> + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + </pre><p> + </p><p> + In a collaborative environment, it is necessary to have some sort of standard + or method through which you submit changes. + Otherwise, things could get quite chaotic. + One general practice to follow is to make small, controlled changes. + Keeping changes small and isolated aids review, makes merging/rebasing easier + and keeps the change history clean when anyone needs to refer to it in future. + </p><p> + When you make a commit, you must follow certain standards established by the + OpenEmbedded and Yocto Project development teams. + For each commit, you must provide a single-line summary of the change and you + should almost always provide a more detailed description of what you did (i.e. + the body of the commit message). + The only exceptions for not providing a detailed description would be if your + change is a simple, self-explanatory change that needs no description. + Here are the guidelines for composing a commit message: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Provide a single-line, short summary of the change. + This summary is typically viewable in the "shortlist" of changes. + Thus, providing something short and descriptive that gives the reader + a summary of the change is useful when viewing a list of many commits. + This should be prefixed by the recipe name (if changing a recipe), or + else the short form path to the file being changed. + </p></li><li class="listitem"><p>For the body of the commit message, provide detailed information + that describes what you changed, why you made the change, and the approach + you used. It may also be helpful if you mention how you tested the change. + Provide as much detail as you can in the body of the commit message. + </p></li><li class="listitem"><p>If the change addresses a specific bug or issue that is + associated with a bug-tracking ID, include a reference to that ID in + your detailed description. + For example, the Yocto Project uses a specific convention for bug + references - any commit that addresses a specific bug should include the + bug ID in the description (typically at the beginning) as follows: + </p><pre class="literallayout"> + [YOCTO #<bug-id>] + + <detailed description of change> + </pre></li></ul></div><p> + </p><p> + You can find more guidance on creating well-formed commit messages at this OpenEmbedded + wiki page: + <a class="ulink" href="http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines" target="_top">http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines</a>. + </p><p> + Following are general instructions for both pushing changes upstream and for submitting + changes as patches. + </p><div class="section" title="3.9.1. Using Scripts to Push a Change Upstream and Request a Pull"><div class="titlepage"><div><div><h3 class="title"><a id="pushing-a-change-upstream"></a>3.9.1. Using Scripts to Push a Change Upstream and Request a Pull</h3></div></div></div><p> + The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Make your changes in your local Git repository.</p></li><li class="listitem"><p>Stage your changes by using the <code class="filename">git add</code> + command on each file you changed.</p></li><li class="listitem"><p>Commit the change by using the <code class="filename">git commit</code> + command and push it to the "contrib" repository. + Be sure to provide a commit message that follows the project’s commit message standards + as described earlier.</p></li><li class="listitem"><p>Notify the maintainer that you have pushed a change by making a pull + request. + The Yocto Project provides two scripts that conveniently let you generate and send + pull requests to the Yocto Project. + These scripts are <code class="filename">create-pull-request</code> and + <code class="filename">send-pull-request</code>. + You can find these scripts in the <code class="filename">scripts</code> directory of the + Yocto Project file structure.</p><p>Using these scripts correctly formats the requests without introducing any + whitespace or HTML formatting. + The maintainer that receives your patches needs to be able to save and apply them + directly from your emails. + Using these scripts is the preferred method for sending patches.</p><p>For help on using these scripts, simply provide the + <code class="filename">-h</code> argument as follows: + </p><pre class="literallayout"> + $ ~/poky/scripts/create-pull-request -h + $ ~/poky/scripts/send-pull-request -h + </pre></li></ul></div><p> + </p><p> + You can find general Git information on how to push a change upstream in the + <a class="ulink" href="http://book.git-scm.com/3_distributed_workflows.html" target="_top">Git Community Book</a>. + </p></div><div class="section" title="3.9.2. Using Email to Submit a Patch"><div class="titlepage"><div><div><h3 class="title"><a id="submitting-a-patch"></a>3.9.2. Using Email to Submit a Patch</h3></div></div></div><p> + You can submit patches without using the <code class="filename">create-pull-request</code> and + <code class="filename">send-pull-request</code> scripts described in the previous section. + Keep in mind, the preferred method is to use the scripts, however. + </p><p> + Depending on the components changed, you need to submit the email to a specific + mailing list. + For some guidance on which mailing list to use, see the list in the + "<a class="link" href="#how-to-submit-a-change" title="3.9. How to Submit a Change">How to Submit a Change</a>" section + earlier in this manual. + For a description of the available mailing lists, see + "<a class="link" href="#resources-mailinglist" target="_top">Mailing Lists</a>" + section in the Yocto Project Reference Manual. + </p><p> + Here is the general procedure on how to submit a patch through email without using the + scripts: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Make your changes in your local Git repository.</p></li><li class="listitem"><p>Stage your changes by using the <code class="filename">git add</code> + command on each file you changed.</p></li><li class="listitem"><p>Commit the change by using the + <code class="filename">git commit --signoff</code> command. + Using the <code class="filename">--signoff</code> option identifies you as the person + making the change and also satisfies the Developer's Certificate of + Origin (DCO) shown earlier.</p><p>When you form a commit you must follow certain standards established by the + Yocto Project development team. + See the earlier section + "<a class="link" href="#how-to-submit-a-change" title="3.9. How to Submit a Change">How to Submit a Change</a>" + for Yocto Project commit message standards.</p></li><li class="listitem"><p>Format the commit into an email message. + To format commits, use the <code class="filename">git format-patch</code> command. + When you provide the command, you must include a revision list or a number of patches + as part of the command. + For example, these two commands each take the most recent single commit and + format it as an email message in the current directory: + </p><pre class="literallayout"> + $ git format-patch -1 + $ git format-patch HEAD~ + </pre><p>After the command is run, the current directory contains a + numbered <code class="filename">.patch</code> file for the commit.</p><p>If you provide several commits as part of the command, + the <code class="filename">git format-patch</code> command produces a numbered + series of files in the current directory – one for each commit. + If you have more than one patch, you should also use the + <code class="filename">--cover</code> option with the command, which generates a + cover letter as the first "patch" in the series. + You can then edit the cover letter to provide a description for + the series of patches. + For information on the <code class="filename">git format-patch</code> command, + see <code class="filename">GIT_FORMAT_PATCH(1)</code> displayed using the + <code class="filename">man git-format-patch</code> command.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If you are or will be a frequent contributor to the Yocto Project + or to OpenEmbedded, you might consider requesting a contrib area and the + necessary associated rights.</div></li><li class="listitem"><p>Import the files into your mail client by using the + <code class="filename">git send-email</code> command. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>In order to use <code class="filename">git send-email</code>, you must have the + the proper Git packages installed. + For Ubuntu and Fedora the package is <code class="filename">git-email</code>.</div><p>The <code class="filename">git send-email</code> command sends email by using a local + or remote Mail Transport Agent (MTA) such as + <code class="filename">msmtp</code>, <code class="filename">sendmail</code>, or through a direct + <code class="filename">smtp</code> configuration in your Git <code class="filename">config</code> + file. + If you are submitting patches through email only, it is very important + that you submit them without any whitespace or HTML formatting that + either you or your mailer introduces. + The maintainer that receives your patches needs to be able to save and + apply them directly from your emails. + A good way to verify that what you are sending will be applicable by the + maintainer is to do a dry run and send them to yourself and then + save and apply them as the maintainer would.</p><p>The <code class="filename">git send-email</code> command is the preferred method + for sending your patches since there is no risk of compromising whitespace + in the body of the message, which can occur when you use your own mail client. + The command also has several options that let you + specify recipients and perform further editing of the email message. + For information on how to use the <code class="filename">git send-email</code> command, + use the <code class="filename">man git-send-email</code> command.</p></li></ul></div><p> + </p></div></div></div> + + <div class="chapter" title="Chapter 4. Common Tasks"><div class="titlepage"><div><div><h2 class="title"><a id="extendpoky"></a>Chapter 4. Common Tasks</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#understanding-and-creating-layers">4.1. Understanding and Creating Layers</a></span></dt><dd><dl><dt><span class="section"><a href="#yocto-project-layers">4.1.1. Layers</a></span></dt><dt><span class="section"><a href="#creating-your-own-layer">4.1.2. Creating Your Own Layer</a></span></dt><dt><span class="section"><a href="#enabling-your-layer">4.1.3. Enabling Your Layer</a></span></dt><dt><span class="section"><a href="#using-bbappend-files">4.1.4. Using .bbappend Files</a></span></dt><dt><span class="section"><a href="#prioritizing-your-layer">4.1.5. Prioritizing Your Layer</a></span></dt><dt><span class="section"><a href="#managing-layers">4.1.6. Managing Layers</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">4.2. Customizing Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">4.2.1. Customizing Images Using Custom .bb Files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">4.2.2. Customizing Images Using Custom Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">4.2.3. Customizing Images Using Custom <code class="filename">IMAGE_FEATURES</code> and + <code class="filename">EXTRA_IMAGE_FEATURES</code></a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">4.2.4. Customizing Images Using <code class="filename">local.conf</code></a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-addpkg">4.3. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">4.3.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">4.3.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">4.3.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#splitting-an-application-into-multiple-packages">4.3.4. Splitting an Application into Multiple Packages</a></span></dt><dt><span class="section"><a href="#including-static-library-files">4.3.5. Including Static Library Files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">4.3.6. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">4.4. Adding a New Machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">4.4.1. Adding the Machine Configuration File</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">4.4.2. Adding a Kernel for the Machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">4.4.3. Adding a Formfactor Configuration File</a></span></dt></dl></dd><dt><span class="section"><a href="#building-multiple-architecture-libraries-into-one-image">4.5. Combining Multiple Versions of Library Files into One Image</a></span></dt><dd><dl><dt><span class="section"><a href="#preparing-to-use-multilib">4.5.1. Preparing to use Multilib</a></span></dt><dt><span class="section"><a href="#using-multilib">4.5.2. Using Multilib</a></span></dt><dt><span class="section"><a href="#additional-implementation-details">4.5.3. Additional Implementation Details</a></span></dt></dl></dd><dt><span class="section"><a href="#configuring-the-kernel">4.6. Configuring the Kernel</a></span></dt><dd><dl><dt><span class="section"><a href="#using-menuconfig">4.6.1. Using <code class="filename">menuconfig</code></a></span></dt><dt><span class="section"><a href="#creating-config-fragments">4.6.2. Creating Configuration Fragments</a></span></dt><dt><span class="section"><a href="#fine-tuning-the-kernel-configuration-file">4.6.3. Fine-tuning the Kernel Configuration File</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes-updatingimages">4.7. Updating Existing Images</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.8. Incrementing a Package Revision Number</a></span></dt><dt><span class="section"><a href="#usingpoky-configuring-DISTRO_PN_ALIAS">4.9. Handling a Package Name Alias</a></span></dt><dt><span class="section"><a href="#building-software-from-an-external-source">4.10. Building Software from an External Source</a></span></dt><dt><span class="section"><a href="#excluding-recipes-from-the-build">4.11. Excluding Recipes From the Build</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">4.12. Using an External SCM</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug">4.13. Debugging With the GNU Project Debugger (GDB) Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">4.13.1. Launching Gdbserver on the Target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">4.13.2. Launching GDB on the Host Computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">4.14. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">4.14.1. Profiling on the Target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">4.14.2. Using OProfileUI</a></span></dt></dl></dd></dl></div><p> + This chapter describes standard tasks such as adding new + software packages, extending or customizing images, and porting work to + new hardware (adding a new machine). + The chapter also describes how to combine multiple + versions of library files into a single image, how to handle a package name alias, and + gives advice about how to make changes to the Yocto Project to achieve the best results. + </p><div class="section" title="4.1. Understanding and Creating Layers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="understanding-and-creating-layers"></a>4.1. Understanding and Creating Layers</h2></div></div></div><p> + The OpenEmbedded build system supports organizing <a class="link" href="#metadata">metadata</a> + into multiple layers. + Layers allow you to isolate different types of customizations from each other. + You might find it tempting to keep everything in one layer when working on a single project. + However, the more modular you organize your metadata, the easier it is to cope with future changes. + </p><p> + To illustrate how layers are used to keep things modular, consider machine customizations. + These types of customizations typically reside in a BSP Layer. + Furthermore, the machine customizations should be isolated from recipes and metadata that support + a new GUI environment, for example. + This situation gives you a couple a layers: one for the machine configurations, and one for the + GUI environment. + It is important to understand, however, that the BSP layer can still make machine-specific + additions to recipes within the GUI environment layer without polluting the GUI layer itself + with those machine-specific changes. + You can accomplish this through a recipe that is a BitBake append + (<code class="filename">.bbappend</code>) file, which is described later in this section. + </p><p> + </p><div class="section" title="4.1.1. Layers"><div class="titlepage"><div><div><h3 class="title"><a id="yocto-project-layers"></a>4.1.1. Layers</h3></div></div></div><p> + The source directory contains several layers right out of the box. + You can easily identify a layer in the source directory by its folder name. + Folders that are layers begin with the string <code class="filename">meta</code>. + For example, when you set up the <a class="link" href="#source-directory">source directory</a> + structure, you will see several layers: <code class="filename">meta</code>, <code class="filename">meta-demoapps</code>, + <code class="filename">meta-skeleton</code>, and <code class="filename">meta-yocto</code>. + Each of these folders is a layer. + </p><p> + Furthermore, if you set up a local copy of the <code class="filename">meta-intel</code> Git repository + and then explore that folder, you will discover many BSP layers within the + <code class="filename">meta-intel</code> layer. + For more information on BSP layers, see the + "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + </p></div><div class="section" title="4.1.2. Creating Your Own Layer"><div class="titlepage"><div><div><h3 class="title"><a id="creating-your-own-layer"></a>4.1.2. Creating Your Own Layer</h3></div></div></div><p> + It is very easy to create your own layer to use with the OpenEmbedded build system. + Follow these general steps to create your layer: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Check Existing Layers:</em></span> Before creating a new layer, + you should be sure someone has not already created a layer containing the metadata + you need. + You can see the + <a class="ulink" href="http://www.openembedded.org/wiki/LayerIndex" target="_top"><code class="filename">LayerIndex</code></a> + for a list of layers from the OpenEmbedded community that can be used in the + Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>Create a Directory:</em></span> Create the directory + for your layer. + Traditionally, prepend the name of the folder with the string + <code class="filename">meta</code>. + For example: + </p><pre class="literallayout"> + meta-mylayer + meta-GUI_xyz + meta-mymachine + </pre></li><li class="listitem"><p><span class="emphasis"><em>Create a Layer Configuration File:</em></span> Inside your new + layer folder, you need to create a <code class="filename">conf/layer.conf</code> file. + It is easiest to take an existing layer configuration file and copy that to your + layer's <code class="filename">conf</code> directory and then modify the file as needed.</p><p>The <code class="filename">meta-yocto/conf/layer.conf</code> file demonstrates the + required syntax: + </p><pre class="literallayout"> + # We have a conf and classes directory, add to BBPATH + BBPATH := "${LAYERDIR}:${BBPATH}" + + # We have recipes-* directories, add to BBFILES + BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "yocto" + BBFILE_PATTERN_yocto := "^${LAYERDIR}/" + BBFILE_PRIORITY_yocto = "5" + </pre><p>In the previous example, the recipes for the layers are added to + <code class="filename"><a class="link" href="#var-BBFILES" target="_top">BBFILES</a></code>. + The + <code class="filename"><a class="link" href="#var-BBFILE_COLLECTIONS" target="_top">BBFILE_COLLECTIONS</a></code> + variable is then appended with the layer name. + The + <code class="filename"><a class="link" href="#var-BBFILE_PATTERN" target="_top">BBFILE_PATTERN</a></code> + variable is set to a regular expression and is used to match files + from <code class="filename">BBFILES</code> into a particular layer. + In this case, immediate expansion of + <code class="filename"><a class="link" href="#var-LAYERDIR" target="_top">LAYERDIR</a></code> + sets <code class="filename">BBFILE_PATTERN</code> to the layer's path. + The + <code class="filename"><a class="link" href="#var-BBFILE_PRIORITY" target="_top">BBFILE_PRIORITY</a></code> + variable then assigns a priority to the layer. + Applying priorities is useful in situations where the same package might appear in multiple + layers and allows you to choose what layer should take precedence.</p><p>Note the use of the + <code class="filename"><a class="link" href="#var-LAYERDIR" target="_top">LAYERDIR</a></code> + variable with the immediate expansion operator. + The <code class="filename">LAYERDIR</code> variable expands to the directory of the current layer and + requires the immediate expansion operator so that BitBake does not wait to expand the variable + when it's parsing a different directory.</p><p>Through the use of the <code class="filename">BBPATH</code> variable, + BitBake locates <code class="filename">.bbclass</code> files, configuration + files, and files that are included with <code class="filename">include</code> + and <code class="filename">require</code> statements. + For these cases, BitBake uses the first file with the matching name found in + <code class="filename">BBPATH</code>. + This is similar to the way the <code class="filename">PATH</code> variable is used for binaries. + We recommend, therefore, that you use unique <code class="filename">.bbclass</code> + and configuration file names in your custom layer.</p></li><li class="listitem"><p><span class="emphasis"><em>Add Content:</em></span> Depending on the type of layer, + add the content. + If the layer adds support for a machine, add the machine configuration in + a <code class="filename">conf/machine/</code> file within the layer. + If the layer adds distro policy, add the distro configuration in a + <code class="filename">conf/distro/</code> file with the layer. + If the layer introduces new recipes, put the recipes you need in + <code class="filename">recipes-*</code> subdirectories within the layer.</p></li></ol></div><p> + </p><p> + To create layers that are easier to maintain, you should consider the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Avoid "overlaying" entire recipes from other layers in your + configuration. + In other words, don't copy an entire recipe into your layer and then modify it. + Use <code class="filename">.bbappend</code> files to override the parts of the + recipe you need to modify.</p></li><li class="listitem"><p>Avoid duplicating include files. + Use <code class="filename">.bbappend</code> files for each recipe that uses an include + file. + Or, if you are introducing a new recipe that requires the included file, use the + path relative to the original layer directory to refer to the file. + For example, use <code class="filename">require recipes-core/somepackage/somefile.inc</code> + instead of <code class="filename">require somefile.inc</code>. + If you're finding you have to overlay the include file, it could indicate a + deficiency in the include file in the layer to which it originally belongs. + If this is the case, you need to address that deficiency instead of overlaying + the include file. + For example, consider how Qt 4 database support plugins are configured. + The source directory does not have + MySQL or PostgreSQL, however OpenEmbedded's + layer <code class="filename">meta-oe</code> does. + Consequently, <code class="filename">meta-oe</code> uses <code class="filename">.bbappend</code> + files to modify the <code class="filename">QT_SQL_DRIVER_FLAGS</code> variable to enable + the appropriate plugins. + This variable was added to the <code class="filename">qt4.inc</code> include file in + the source directory specifically to allow the <code class="filename">meta-oe</code> layer + to be able to control which plugins are built.</p></li></ul></div><p> + </p><p> + We also recommend the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Store custom layers in a Git repository that uses the + <code class="filename">meta-<layer_name></code> format.</p></li><li class="listitem"><p>Clone the repository alongside other <code class="filename">meta</code> + directories in the + <a class="link" href="#source-directory">source directory</a>.</p></li></ul></div><p> + Following these recommendations keeps your source directory and + its configuration entirely inside the Yocto Project's core base. + </p></div><div class="section" title="4.1.3. Enabling Your Layer"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-your-layer"></a>4.1.3. Enabling Your Layer</h3></div></div></div><p> + Before the OpenEmbedded build system can use your new layer, you need to enable it. + To enable your layer, simply add your layer's path to the + <code class="filename"><a class="link" href="#var-BBLAYERS" target="_top">BBLAYERS</a></code> + variable in your <code class="filename">conf/bblayers.conf</code> file, which is found in the + <a class="link" href="#build-directory">build directory</a>. + The following example shows how to enable a layer named <code class="filename">meta-mylayer</code>: + </p><pre class="literallayout"> + LCONF_VERSION = "1" + + BBFILES ?= "" + BBLAYERS = " \ + /path/to/poky/meta \ + /path/to/poky/meta-yocto \ + /path/to/poky/meta-mylayer \ + " + </pre><p> + </p><p> + BitBake parses each <code class="filename">conf/layer.conf</code> file as specified in the + <code class="filename">BBLAYERS</code> variable within the <code class="filename">conf/bblayers.conf</code> + file. + During the processing of each <code class="filename">conf/layer.conf</code> file, BitBake adds the + recipes, classes and configurations contained within the particular layer to the source + directory. + </p></div><div class="section" title="4.1.4. Using .bbappend Files"><div class="titlepage"><div><div><h3 class="title"><a id="using-bbappend-files"></a>4.1.4. Using .bbappend Files</h3></div></div></div><p> + Recipes used to append metadata to other recipes are called BitBake append files. + BitBake append files use the <code class="filename">.bbappend</code> file type suffix, while + underlying recipes to which metadata is being appended use the + <code class="filename">.bb</code> file type suffix. + </p><p> + A <code class="filename">.bbappend</code> file allows your layer to make additions or + changes to the content of another layer's recipe without having to copy the other + recipe into your layer. + Your <code class="filename">.bbappend</code> file resides in your layer, while the underlying + <code class="filename">.bb</code> recipe file to which you are appending metadata + resides in a different layer. + </p><p> + Append files files must have the same name as the underlying recipe. + For example, the append file <code class="filename">someapp_1.3.bbappend</code> must + apply to <code class="filename">someapp_1.3.bb</code>. + This means the original recipe and append file names are version number specific. + If the underlying recipe is renamed to update to a newer version, the + corresponding <code class="filename">.bbappend</code> file must be renamed as well. + During the build process, BitBake displays an error on starting if it detects a + <code class="filename">.bbappend</code> file that does not have an underlying recipe + with a matching name. + </p><p> + Being able to append information to an existing recipe not only avoids duplication, + but also automatically applies recipe changes in a different layer to your layer. + If you were copying recipes, you would have to manually merge changes as they occur. + </p><p> + As an example, consider the main formfactor recipe and a corresponding formfactor + append file both from the + <a class="link" href="#source-directory">source directory</a>. + Here is the main formfactor recipe, which is named <code class="filename">formfactor_0.0.bb</code> and + located in the meta layer at <code class="filename">meta/recipes-bsp/formfactor</code>: + </p><pre class="literallayout"> + DESCRIPTION = "Device formfactor information" + SECTION = "base" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \ + file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + PR = "r20" + + SRC_URI = "file://config file://machconfig" + S = "${WORKDIR}" + + PACKAGE_ARCH = "${MACHINE_ARCH}" + INHIBIT_DEFAULT_DEPS = "1" + + do_install() { + # Only install file if it has a contents + install -d ${D}${sysconfdir}/formfactor/ + install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ + if [ -s "${S}/machconfig" ]; then + install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ + fi + } + </pre><p> + Here is the append file, which is named <code class="filename">formfactor_0.0.bbappend</code> and is from the + Crown Bay BSP Layer named <code class="filename">meta-intel/meta-crownbay</code>. + The file is in <code class="filename">recipes-bsp/formfactor</code>: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + PRINC = "1" + </pre><p> + This example adds or overrides files in + <a class="link" href="#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> + within a <code class="filename">.bbappend</code> by extending the path BitBake uses to search for files. + The most reliable way to do this is by prepending the + <code class="filename">FILESEXTRAPATHS</code> variable. + For example, if you have your files in a directory that is named the same as your package + (<a class="link" href="#var-PN" target="_top"><code class="filename">PN</code></a>), + you can add this directory by adding the following to your <code class="filename">.bbappend</code> file: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </pre><p> + Using the immediate expansion assignment operator <code class="filename">:=</code> is important because + of the reference to <code class="filename">THISDIR</code>. + The trailing colon character is important as it ensures that items in the list remain + colon-separated. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>BitBake automatically defines the <code class="filename">THISDIR</code> variable. + You should never set this variable yourself. + Using <code class="filename">_prepend</code> ensures your path will be searched prior to other + paths in the final list. + </div><p> + </p><p> + For another example on how to use a <code class="filename">.bbappend</code> file, see the + "<a class="link" href="#changing-recipes-kernel" title="A.5.2.4. Changing recipes-kernel">Changing <code class="filename">recipes-kernel</code></a>" + section. + </p></div><div class="section" title="4.1.5. Prioritizing Your Layer"><div class="titlepage"><div><div><h3 class="title"><a id="prioritizing-your-layer"></a>4.1.5. Prioritizing Your Layer</h3></div></div></div><p> + Each layer is assigned a priority value. + Priority values control which layer takes precedence if there are recipe files with + the same name in multiple layers. + For these cases, the recipe file from the layer with a higher priority number taking precedence. + Priority values also affect the order in which multiple <code class="filename">.bbappend</code> files + for the same recipe are applied. + You can either specify the priority manually, or allow the build system to calculate it + based on the layer's dependencies. + </p><p> + To specify the layer's priority manually, use the + <a class="link" href="#var-BBFILE_PRIORITY" target="_top"><code class="filename">BBFILE_PRIORITY</code></a> + variable. + For example: + </p><pre class="literallayout"> + BBFILE_PRIORITY := "1" + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is possible for a recipe with a lower version number + <a class="link" href="#var-PV" target="_top"><code class="filename">PV</code></a> + in a layer that has a higher priority to take precedence.</p><p>Also, the layer priority does not currently affect the precedence order of + <code class="filename">.conf</code> or <code class="filename">.bbclass</code> files. + Future versions of BitBake might address this.</p></div></div><div class="section" title="4.1.6. Managing Layers"><div class="titlepage"><div><div><h3 class="title"><a id="managing-layers"></a>4.1.6. Managing Layers</h3></div></div></div><p> + You can use the BitBake layer management tool to provide a view into the structure of + recipes across a multi-layer project. + Being able to generate output that reports on configured layers with their paths and + priorities and on <code class="filename">.bbappend</code> files and their applicable recipes + can help to reveal potential problems. + </p><p> + Use the following form when running the layer management tool. + </p><pre class="literallayout"> + $ bitbake-layers <command> [arguments] + </pre><p> + The following list describes the available commands: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><span class="emphasis"><em>help:</em></span></code> + Displays general help or help on a specified command.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-layers:</em></span></code> + Show the current configured layers.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-recipes:</em></span></code> + Lists available recipes and the layers that provide them. + </p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-overlayed:</em></span></code> + Lists overlayed recipes. + A recipe is overlayed when a recipe with the same name exists in another layer + that has a higher layer priority. + </p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-appends:</em></span></code> + Lists <code class="filename">.bbappend</code> files and the recipe files to which + they apply.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>flatten:</em></span></code> + Flattens the layer configuration into a separate output directory. + Flattening your layer configuration builds a "flattened" directory that contains + the contents of all layers, with any overlayed recipes removed and any + <code class="filename">.bbappend</code> files appended to the corresponding recipes. + You might have to perform some manual cleanup of the flattened layer as follows: + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Non-recipe files (such as patches) are overwritten. + The flatten command shows a warning for these files.</p></li><li class="listitem"><p>Anything beyond the normal layer setup has been added to + the <code class="filename">layer.conf</code> file. + Only the lowest priority layer's <code class="filename">layer.conf</code> is used. + </p></li><li class="listitem"><p>Overridden and appended items from <code class="filename">.bbappend</code> + files need to be cleaned up. + The contents of each <code class="filename">.bbappend</code> end up in the + flattened recipe. + However, if there are appended or changed variable values, you need to tidy + these up yourself. + Consider the following example. + Here, the <code class="filename">bitbake-layers</code> command adds the line + <code class="filename">#### bbappended ...</code> so that you know where the following + lines originate: + </p><pre class="literallayout"> + ... + DESCRIPTION = "A useful utility" + ... + EXTRA_OECONF = "--enable-something" + ... + + #### bbappended from meta-anotherlayer #### + + DESCRIPTION = "Customized utility" + EXTRA_OECONF += "--enable-somethingelse" + </pre><p> + Ideally, you would tidy up these utilities as follows: + </p><pre class="literallayout"> + ... + DESCRIPTION = "Customized utility" + ... + EXTRA_OECONF = "--enable-something --enable-somethingelse" + ... + </pre></li></ul></div></li></ul></div><p> + </p></div></div><div class="section" title="4.2. Customizing Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-extend-customimage"></a>4.2. Customizing Images</h2></div></div></div><p> + You can customize images to satisfy particular requirements. + This section describes several methods and provides guidelines for each. + </p><div class="section" title="4.2.1. Customizing Images Using Custom .bb Files"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-custombb"></a>4.2.1. Customizing Images Using Custom .bb Files</h3></div></div></div><p> + One way to get additional software into an image is to create a custom image. + The following example shows the form for the two lines you need: + </p><pre class="literallayout"> + IMAGE_INSTALL = "task-core-x11-base package1 package2" + + inherit core-image + </pre><p> + </p><p> + By creating a custom image, a developer has total control + over the contents of the image. + It is important to use the correct names of packages in the + <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code> + variable. + You must use the OpenEmbedded notation and not the Debian notation for the names + (e.g. <code class="filename">eglibc-dev</code> instead of <code class="filename">libc6-dev</code>). + </p><p> + The other method for creating a custom image is to base it on an existing image. + For example, if you want to create an image based on <code class="filename">core-image-sato</code> + but add the additional package <code class="filename">strace</code> to the image, + copy the <code class="filename">meta/recipes-sato/images/core-image-sato.bb</code> to a + new <code class="filename">.bb</code> and add the following line to the end of the copy: + </p><pre class="literallayout"> + IMAGE_INSTALL += "strace" + </pre><p> + </p></div><div class="section" title="4.2.2. Customizing Images Using Custom Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-customtasks"></a>4.2.2. Customizing Images Using Custom Tasks</h3></div></div></div><p> + For complex custom images, the best approach is to create a custom task package + that is used to build the image or images. + A good example of a tasks package is + <code class="filename">meta/recipes-core/tasks/task-core-boot.bb</code> + The + <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a></code> + variable lists the task packages to build along with the complementary + <code class="filename">-dbg</code> and <code class="filename">-dev</code> packages. + For each package added, you can use + <code class="filename"><a class="link" href="#var-RDEPENDS" target="_top">RDEPENDS</a></code> + and + <code class="filename"><a class="link" href="#var-RRECOMMENDS" target="_top">RRECOMMENDS</a></code> + entries to provide a list of packages the parent task package should contain. + Following is an example: + </p><pre class="literallayout"> + DESCRIPTION = "My Custom Tasks" + + PACKAGES = "\ + task-custom-apps \ + task-custom-apps-dbg \ + task-custom-apps-dev \ + task-custom-tools \ + task-custom-tools-dbg \ + task-custom-tools-dev \ + " + + RDEPENDS_task-custom-apps = "\ + dropbear \ + portmap \ + psplash" + + RDEPENDS_task-custom-tools = "\ + oprofile \ + oprofileui-server \ + lttng-control \ + lttng-viewer" + + RRECOMMENDS_task-custom-tools = "\ + kernel-module-oprofile" + </pre><p> + </p><p> + In the previous example, two task packages are created with their dependencies and their + recommended package dependencies listed: <code class="filename">task-custom-apps</code>, and + <code class="filename">task-custom-tools</code>. + To build an image using these task packages, you need to add + <code class="filename">task-custom-apps</code> and/or + <code class="filename">task-custom-tools</code> to + <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code>. + For other forms of image dependencies see the other areas of this section. + </p></div><div class="section" title="4.2.3. Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-imagefeatures"></a>4.2.3. Customizing Images Using Custom <code class="filename">IMAGE_FEATURES</code> and + <code class="filename">EXTRA_IMAGE_FEATURES</code></h3></div></div></div><p> + Ultimately users might want to add extra image features to the set by using the + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" target="_top">IMAGE_FEATURES</a></code> + variable. + To create these features, the best reference is + <code class="filename">meta/classes/core-image.bbclass</code>, which shows how to achieve this. + In summary, the file looks at the contents of the + <code class="filename">IMAGE_FEATURES</code> + variable and then maps that into a set of tasks or packages. + Based on this information the + <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top"> IMAGE_INSTALL</a></code> + variable is generated automatically. + Users can add extra features by extending the class or creating a custom class for use + with specialized image <code class="filename">.bb</code> files. + You can also add more features by configuring the + <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" target="_top">EXTRA_IMAGE_FEATURES</a></code> + variable in the <code class="filename">local.conf</code> file found in the source directory + located in the build directory. + </p><p> + The Yocto Project ships with two SSH servers you can use in your images: + Dropbear and OpenSSH. + Dropbear is a minimal SSH server appropriate for resource-constrained environments, + while OpenSSH is a well-known standard SSH server implementation. + By default, the <code class="filename">core-image-sato</code> image is configured to use Dropbear. + The <code class="filename">core-image-basic</code> and <code class="filename">core-image-lsb</code> + images both include OpenSSH. + The <code class="filename">core-image-minimal</code> image does not contain an SSH server. + To change these defaults, edit the <code class="filename">IMAGE_FEATURES</code> variable + so that it sets the image you are working with to include + <code class="filename">ssh-server-dropbear</code> or <code class="filename">ssh-server-openssh</code>. + </p></div><div class="section" title="4.2.4. Customizing Images Using local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-customimage-localconf"></a>4.2.4. Customizing Images Using <code class="filename">local.conf</code></h3></div></div></div><p> + It is possible to customize image contents by using variables from your + local configuration in your <code class="filename">conf/local.conf</code> file. + Because it is limited to local use, this method generally only allows you to + add packages and is not as flexible as creating your own customized image. + When you add packages using local variables this way, you need to realize that + these variable changes affect all images at the same time and might not be + what you require. + </p><p> + The simplest way to add extra packages to all images is by using the + <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code> + variable with the <code class="filename">_append</code> operator: + </p><pre class="literallayout"> + IMAGE_INSTALL_append = " strace" + </pre><p> + Use of the syntax is important. + Specifically, the space between the quote and the package name, which is + <code class="filename">strace</code> in this example. + This space is required since the <code class="filename">_append</code> + operator does not add the space. + </p><p> + Furthermore, you must use <code class="filename">_append</code> instead of the <code class="filename">+=</code> + operator if you want to avoid ordering issues. + The reason for this is because doing so unconditionally appends to the variable and + avoids ordering problems due to the variable being set in image recipes and + <code class="filename">.bbclass</code> files with operators like <code class="filename">?=</code>. + Using <code class="filename">_append</code> ensures the operation takes affect. + </p><p> + As shown in its simplest use, <code class="filename">IMAGE_INSTALL_append</code> affects + all images. + It is possible to extend the syntax so that the variable applies to a specific image only. + Here is an example: + </p><pre class="literallayout"> + IMAGE_INSTALL_append_pn-core-image-minimal = " strace" + </pre><p> + This example adds <code class="filename">strace</code> to <code class="filename">core-image-minimal</code> + only. + </p><p> + You can add packages using a similar approach through the + <code class="filename"><a class="link" href="#var-CORE_IMAGE_EXTRA_INSTALL" target="_top">CORE_IMAGE_EXTRA_INSTALL</a></code> + variable. + If you use this variable, only <code class="filename">core-image-*</code> images are affected. + </p></div></div><div class="section" title="4.3. Adding a Package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-extend-addpkg"></a>4.3. Adding a Package</h2></div></div></div><p> + To add a package you need to write a recipe for it. + Writing a recipe means creating a <code class="filename">.bb</code> file that sets some + variables. + For information on variables that are useful for recipes and for information about recipe naming + issues, see the + "<a class="link" href="#ref-varlocality-recipe-required" target="_top">Required</a>" + section of the Yocto Project Reference Manual. + </p><p> + Before writing a recipe from scratch, it is often useful to check + whether someone else has written one already. + OpenEmbedded is a good place to look as it has a wider scope and range of packages. + Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes + you find there should work for you. + </p><p> + For new packages, the simplest way to add a recipe is to base it on a similar + pre-existing recipe. + The sections that follow provide some examples that show how to add standard + types of packages. + </p><div class="section" title="4.3.1. Single .c File Package (Hello World!)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-singlec"></a>4.3.1. Single .c File Package (Hello World!)</h3></div></div></div><p> + Building an application from a single file that is stored locally (e.g. under + <code class="filename">files/</code>) requires a recipe that has the file listed in + the + <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> + variable. + Additionally, you need to manually write the <code class="filename">do_compile</code> and + <code class="filename">do_install</code> tasks. + The <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> + variable defines the + directory containing the source code, which is set to + <code class="filename"><a class="link" href="#var-WORKDIR" target="_top"> + WORKDIR</a></code> in this case - the directory BitBake uses for the build. + </p><pre class="literallayout"> + DESCRIPTION = "Simple helloworld application" + SECTION = "examples" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" + PR = "r0" + + SRC_URI = "file://helloworld.c" + + S = "${WORKDIR}" + + do_compile() { + ${CC} helloworld.c -o helloworld + } + + do_install() { + install -d ${D}${bindir} + install -m 0755 helloworld ${D}${bindir} + } + </pre><p> + </p><p> + By default, the <code class="filename">helloworld</code>, <code class="filename">helloworld-dbg</code>, + and <code class="filename">helloworld-dev</code> packages are built. + For information on how to customize the packaging process, see the + "<a class="link" href="#splitting-an-application-into-multiple-packages" title="4.3.4. Splitting an Application into Multiple Packages">Splitting an Application + into Multiple Packages</a>" section. + </p></div><div class="section" title="4.3.2. Autotooled Package"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-autotools"></a>4.3.2. Autotooled Package</h3></div></div></div><p> + Applications that use Autotools such as <code class="filename">autoconf</code> and + <code class="filename">automake</code> require a recipe that has a source archive listed in + <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> and + also inherits Autotools, which instructs BitBake to use the + <code class="filename">autotools.bbclass</code> file, which contains the definitions of all the steps + needed to build an Autotool-based application. + The result of the build is automatically packaged. + And, if the application uses NLS for localization, packages with local information are + generated (one package per language). + Following is one example: (<code class="filename">hello_2.3.bb</code>) + </p><pre class="literallayout"> + DESCRIPTION = "GNU Helloworld application" + SECTION = "examples" + LICENSE = "GPLv2+" + LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe" + PR = "r0" + + SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" + + inherit autotools gettext + </pre><p> + </p><p> + The variable + <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" target="_top">LIC_FILES_CHKSUM</a></code> + is used to track source license changes as described in the + "<a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" target="_top">Track License Changes</a>" section. + You can quickly create Autotool-based recipes in a manner similar to the previous example. + </p></div><div class="section" title="4.3.3. Makefile-Based Package"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-makefile"></a>4.3.3. Makefile-Based Package</h3></div></div></div><p> + Applications that use GNU <code class="filename">make</code> also require a recipe that has + the source archive listed in + <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>. + You do not need to add a <code class="filename">do_compile</code> step since by default BitBake + starts the <code class="filename">make</code> command to compile the application. + If you need additional <code class="filename">make</code> options you should store them in the + <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" target="_top">EXTRA_OEMAKE</a></code> + variable. + BitBake passes these options into the <code class="filename">make</code> GNU invocation. + Note that a <code class="filename">do_install</code> task is still required. + Otherwise BitBake runs an empty <code class="filename">do_install</code> task by default. + </p><p> + Some applications might require extra parameters to be passed to the compiler. + For example, the application might need an additional header path. + You can accomplish this by adding to the + <code class="filename"><a class="link" href="#var-CFLAGS" target="_top">CFLAGS</a></code> variable. + The following example shows this: + </p><pre class="literallayout"> + CFLAGS_prepend = "-I ${S}/include " + </pre><p> + </p><p> + In the following example, <code class="filename">mtd-utils</code> is a makefile-based package: + </p><pre class="literallayout"> + DESCRIPTION = "Tools for managing memory technology devices." + SECTION = "base" + DEPENDS = "zlib lzo e2fsprogs util-linux" + HOMEPAGE = "http://www.linux-mtd.infradead.org/" + LICENSE = "GPLv2+" + LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ + file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" + + SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \ + file://add-exclusion-to-mkfs-jffs2-git-2.patch" + + S = "${WORKDIR}/git/" + + PR = "r1" + + EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \ + 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" + + do_install () { + oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \ + INCLUDEDIR=${includedir} + install -d ${D}${includedir}/mtd/ + for f in ${S}/include/mtd/*.h; do + install -m 0644 $f ${D}${includedir}/mtd/ + done + } + + PARALLEL_MAKE = "" + + BBCLASSEXTEND = "native" + </pre><p> + </p><p> + If your sources are available as a tarball instead of a Git repository, you + will need to provide the URL to the tarball as well as an + <code class="filename">md5</code> or <code class="filename">sha256</code> sum of + the download. + Here is an example: + </p><pre class="literallayout"> + SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2" + SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b" + </pre><p> + You can generate the <code class="filename">md5</code> or <code class="filename">sha256</code> sums + by using the <code class="filename">md5sum</code> or <code class="filename">sha256sum</code> commands + with the target file as the only argument. + Here is an example: + </p><pre class="literallayout"> + $ md5sum mtd-utils-1.4.9.tar.bz2 + 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2 + </pre><p> + </p></div><div class="section" title="4.3.4. Splitting an Application into Multiple Packages"><div class="titlepage"><div><div><h3 class="title"><a id="splitting-an-application-into-multiple-packages"></a>4.3.4. Splitting an Application into Multiple Packages</h3></div></div></div><p> + You can use the variables + <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a></code> and + <code class="filename"><a class="link" href="#var-FILES" target="_top">FILES</a></code> + to split an application into multiple packages. + </p><p> + Following is an example that uses the <code class="filename">libXpm</code> recipe. + By default, this recipe generates a single package that contains the library along + with a few binaries. + You can modify the recipe to split the binaries into separate packages: + </p><pre class="literallayout"> + require xorg-lib-common.inc + + DESCRIPTION = "X11 Pixmap library" + LICENSE = "X-BSD" + LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" + DEPENDS += "libxext libsm libxt" + PR = "r3" + PE = "1" + + XORG_PN = "libXpm" + + PACKAGES =+ "sxpm cxpm" + FILES_cxpm = "${bindir}/cxpm" + FILES_sxpm = "${bindir}/sxpm" + </pre><p> + </p><p> + In the previous example, we want to ship the <code class="filename">sxpm</code> + and <code class="filename">cxpm</code> binaries in separate packages. + Since <code class="filename">bindir</code> would be packaged into the main + <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> + package by default, we prepend the + <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a> + </code> variable so additional package names are added to the start of list. + This results in the extra + <code class="filename"><a class="link" href="#var-FILES" target="_top">FILES</a>_*</code> + variables then containing information that define which files and + directories go into which packages. + Files included by earlier packages are skipped by latter packages. + Thus, the main + <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> package + does not include the above listed files. + </p></div><div class="section" title="4.3.5. Including Static Library Files"><div class="titlepage"><div><div><h3 class="title"><a id="including-static-library-files"></a>4.3.5. Including Static Library Files</h3></div></div></div><p> + If you are building a library and the library offers static linking, you can control + which static library files (<code class="filename">*.a</code> files) get included in the + built library. + </p><p> + The <code class="filename">PACKAGES</code> and <code class="filename">FILES_*</code> variables in the + <code class="filename">meta/conf/bitbake.conf</code> configuration file define how files installed + by the <code class="filename">do_install</code> task are packaged. + By default, the <code class="filename">PACKAGES</code> variable contains + <code class="filename">${PN}-staticdev</code>, which includes all static library files. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Previously released versions of the Yocto Project defined the static library files + through <code class="filename">${PN}-dev</code>. + </div><p> + Following, is part of the BitBake configuration file. + You can see where the static library files are defined: + </p><pre class="literallayout"> + PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale" + PACKAGES_DYNAMIC = "${PN}-locale-*" + FILES = "" + + FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ + ${sysconfdir} ${sharedstatedir} ${localstatedir} \ + ${base_bindir}/* ${base_sbindir}/* \ + ${base_libdir}/*${SOLIBS} \ + ${datadir}/${BPN} ${libdir}/${BPN}/* \ + ${datadir}/pixmaps ${datadir}/applications \ + ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ + ${libdir}/bonobo/servers" + + FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ + ${datadir}/gnome/help" + SECTION_${PN}-doc = "doc" + + FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \ + ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ + ${datadir}/aclocal ${base_libdir}/*.o" + SECTION_${PN}-dev = "devel" + ALLOW_EMPTY_${PN}-dev = "1" + RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" + + FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a" + SECTION_${PN}-staticdev = "devel" + RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" + </pre><p> + </p></div><div class="section" title="4.3.6. Post Install Scripts"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-extend-addpkg-postinstalls"></a>4.3.6. Post Install Scripts</h3></div></div></div><p> + To add a post-installation script to a package, add a <code class="filename">pkg_postinst_PACKAGENAME() + </code> function to the <code class="filename">.bb</code> file and use + <code class="filename">PACKAGENAME</code> as the name of the package you want to attach to the + <code class="filename">postinst</code> script. + Normally + <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> + can be used, which automatically expands to <code class="filename">PACKAGENAME</code>. + A post-installation function has the following structure: + </p><pre class="literallayout"> + pkg_postinst_PACKAGENAME () { + #!/bin/sh -e + # Commands to carry out + } + </pre><p> + </p><p> + The script defined in the post-installation function is called when the + root filesystem is created. + If the script succeeds, the package is marked as installed. + If the script fails, the package is marked as unpacked and the script is + executed when the image boots again. + </p><p> + Sometimes it is necessary for the execution of a post-installation + script to be delayed until the first boot. + For example, the script might need to be executed on the device itself. + To delay script execution until boot time, use the following structure in the + post-installation script: + </p><pre class="literallayout"> + pkg_postinst_PACKAGENAME () { + #!/bin/sh -e + if [ x"$D" = "x" ]; then + # Actions to carry out on the device go here + else + exit 1 + fi + } + </pre><p> + </p><p> + The previous example delays execution until the image boots again because the + <code class="filename"><a class="link" href="#var-D" target="_top">D</a></code> + variable points + to the directory containing the image when the root filesystem is created at build time but + is unset when executed on the first boot. + </p></div></div><div class="section" title="4.4. Adding a New Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-newmachine"></a>4.4. Adding a New Machine</h2></div></div></div><p> + Adding a new machine to the Yocto Project is a straightforward process. + This section provides information that gives you an idea of the changes you must make. + The information covers adding machines similar to those the Yocto Project already supports. + Although well within the capabilities of the Yocto Project, adding a totally new architecture + might require + changes to <code class="filename">gcc/eglibc</code> and to the site information, which is + beyond the scope of this manual. + </p><p> + For a complete example that shows how to add a new machine, + see the + "<a class="link" href="#dev-manual-bsp-appendix" target="_top">BSP Development Example</a>" + in Appendix A. + </p><div class="section" title="4.4.1. Adding the Machine Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-newmachine-conffile"></a>4.4.1. Adding the Machine Configuration File</h3></div></div></div><p> + To add a machine configuration you need to add a <code class="filename">.conf</code> file + with details of the device being added to the <code class="filename">conf/machine/</code> file. + The name of the file determines the name the OpenEmbedded build system + uses to reference the new machine. + </p><p> + The most important variables to set in this file are as follows: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" target="_top"> + TARGET_ARCH</a></code> (e.g. "arm")</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" target="_top"> + PREFERRED_PROVIDER</a></code>_virtual/kernel (see below)</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" target="_top"> + MACHINE_FEATURES</a></code> (e.g. "apm screen wifi")</p></li></ul></div><p> + </p><p> + You might also need these variables: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" target="_top"> + SERIAL_CONSOLE</a></code> (e.g. "115200 ttyS0")</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-KERNEL_IMAGETYPE" target="_top"> + KERNEL_IMAGETYPE</a></code> (e.g. "zImage")</p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" target="_top"> + IMAGE_FSTYPES</a></code> (e.g. "tar.gz jffs2")</p></li></ul></div><p> + </p><p> + You can find full details on these variables in the reference section. + You can leverage many existing machine <code class="filename">.conf</code> files from + <code class="filename">meta/conf/machine/</code>. + </p></div><div class="section" title="4.4.2. Adding a Kernel for the Machine"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-newmachine-kernel"></a>4.4.2. Adding a Kernel for the Machine</h3></div></div></div><p> + The OpenEmbedded build system needs to be able to build a kernel for the machine. + You need to either create a new kernel recipe for this machine, or extend an + existing recipe. + You can find several kernel examples in the + source directory at <code class="filename">meta/recipes-kernel/linux</code> + that you can use as references. + </p><p> + If you are creating a new recipe, normal recipe-writing rules apply for setting + up a + <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>. + Thus, you need to specify any necessary patches and set + <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> to point at the source code. + You need to create a <code class="filename">configure</code> task that configures the + unpacked kernel with a defconfig. + You can do this by using a <code class="filename">make defconfig</code> command or, + more commonly, by copying in a suitable <code class="filename">defconfig</code> file and and then running + <code class="filename">make oldconfig</code>. + By making use of <code class="filename">inherit kernel</code> and potentially some of the + <code class="filename">linux-*.inc</code> files, most other functionality is + centralized and the the defaults of the class normally work well. + </p><p> + If you are extending an existing kernel, it is usually a matter of adding a + suitable defconfig file. + The file needs to be added into a location similar to defconfig files + used for other machines in a given kernel. + A possible way to do this is by listing the file in the + <code class="filename">SRC_URI</code> and adding the machine to the expression in + <code class="filename"><a class="link" href="#var-COMPATIBLE_MACHINE" target="_top">COMPATIBLE_MACHINE</a></code>: + </p><pre class="literallayout"> + COMPATIBLE_MACHINE = '(qemux86|qemumips)' + </pre><p> + </p></div><div class="section" title="4.4.3. Adding a Formfactor Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-newmachine-formfactor"></a>4.4.3. Adding a Formfactor Configuration File</h3></div></div></div><p> + A formfactor configuration file provides information about the + target hardware for which the image is being built and information that + the build system cannot obtain from other sources such as the kernel. + Some examples of information contained in a formfactor configuration file include + framebuffer orientation, whether or not the system has a keyboard, + the positioning of the keyboard in relation to the screen, and + the screen resolution. + </p><p> + The build system uses reasonable defaults in most cases, but if customization is + necessary you need to create a <code class="filename">machconfig</code> file + in the <code class="filename">meta/recipes-bsp/formfactor/files</code> + directory. + This directory contains directories for specific machines such as + <code class="filename">qemuarm</code> and <code class="filename">qemux86</code>. + For information about the settings available and the defaults, see the + <code class="filename">meta/recipes-bsp/formfactor/files/config</code> file found in the + same area. + Following is an example for qemuarm: + </p><pre class="literallayout"> + HAVE_TOUCHSCREEN=1 + HAVE_KEYBOARD=1 + + 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 + </pre><p> + </p></div></div><div class="section" title="4.5. Combining Multiple Versions of Library Files into One Image"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-multiple-architecture-libraries-into-one-image"></a>4.5. Combining Multiple Versions of Library Files into One Image</h2></div></div></div><p> + The build system offers the ability to build libraries with different + target optimizations or architecture formats and combine these together + into one system image. + You can link different binaries in the image + against the different libraries as needed for specific use cases. + This feature is called "Multilib." + </p><p> + An example would be where you have most of a system compiled in 32-bit + mode using 32-bit libraries, but you have something large, like a database + engine, that needs to be a 64-bit application and use 64-bit libraries. + Multilib allows you to get the best of both 32-bit and 64-bit libraries. + </p><p> + While the Multilib feature is most commonly used for 32 and 64-bit differences, + the approach the build system uses facilitates different target optimizations. + You could compile some binaries to use one set of libraries and other binaries + to use other different sets of libraries. + The libraries could differ in architecture, compiler options, or other + optimizations. + </p><p> + This section overviews the Multilib process only. + For more details on how to implement Multilib, see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Multilib" target="_top">Multilib</a> wiki + page. + </p><div class="section" title="4.5.1. Preparing to use Multilib"><div class="titlepage"><div><div><h3 class="title"><a id="preparing-to-use-multilib"></a>4.5.1. Preparing to use Multilib</h3></div></div></div><p> + User-specific requirements drive the Multilib feature, + Consequently, there is no one "out-of-the-box" configuration that likely + exists to meet your needs. + </p><p> + In order to enable Multilib, you first need to ensure your recipe is + extended to support multiple libraries. + Many standard recipes are already extended and support multiple libraries. + You can check in the <code class="filename">meta/conf/multilib.conf</code> + configuration file in the source directory to see how this is + done using the <code class="filename">BBCLASSEXTEND</code> variable. + Eventually, all recipes will be covered and this list will be unneeded. + </p><p> + For the most part, the Multilib class extension works automatically to + extend the package name from <code class="filename">${PN}</code> to + <code class="filename">${MLPREFIX}${PN}</code>, where <code class="filename">MLPREFIX</code> + is the particular multilib (e.g. "lib32-" or "lib64-"). + Standard variables such as <code class="filename">DEPENDS</code>, + <code class="filename">RDEPENDS</code>, <code class="filename">RPROVIDES</code>, + <code class="filename">RRECOMMENDS</code>, <code class="filename">PACKAGES</code>, and + <code class="filename">PACKAGES_DYNAMIC</code> are automatically extended by the system. + If you are extending any manual code in the recipe, you can use the + <code class="filename">${MLPREFIX}</code> variable to ensure those names are extended + correctly. + This automatic extension code resides in <code class="filename">multilib.bbclass</code>. + </p></div><div class="section" title="4.5.2. Using Multilib"><div class="titlepage"><div><div><h3 class="title"><a id="using-multilib"></a>4.5.2. Using Multilib</h3></div></div></div><p> + After you have set up the recipes, you need to define the actual + combination of multiple libraries you want to build. + You accomplish this through your <code class="filename">local.conf</code> + configuration file in the + <a class="link" href="#build-directory">build directory</a>. + An example configuration would be as follows: + </p><pre class="literallayout"> + MACHINE = "qemux86-64" + require conf/multilib.conf + MULTILIBS = "multilib:lib32" + DEFAULTTUNE_virtclass-multilib-lib32 = "x86" + IMAGE_INSTALL = "lib32-connman" + </pre><p> + This example enables an + additional library named <code class="filename">lib32</code> alongside the + normal target packages. + When combining these "lib32" alternatives, the example uses "x86" for tuning. + For information on this particular tuning, see + <code class="filename">meta/conf/machine/include/ia32/arch-ia32.inc</code>. + </p><p> + The example then includes <code class="filename">lib32-connman</code> + in all the images, which illustrates one method of including a + multiple library dependency. + You can use a normal image build to include this dependency, + for example: + </p><pre class="literallayout"> + $ bitbake core-image-sato + </pre><p> + You can also build Multilib packages specifically with a command like this: + </p><pre class="literallayout"> + $ bitbake lib32-connman + </pre><p> + </p></div><div class="section" title="4.5.3. Additional Implementation Details"><div class="titlepage"><div><div><h3 class="title"><a id="additional-implementation-details"></a>4.5.3. Additional Implementation Details</h3></div></div></div><p> + Different packaging systems have different levels of native Multilib + support. + For the RPM Package Management System, the following implementation details + exist: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A unique architecture is defined for the Multilib packages, + along with creating a unique deploy folder under + <code class="filename">tmp/deploy/rpm</code> in the + <a class="link" href="#build-directory">build directory</a>. + For example, consider <code class="filename">lib32</code> in a + <code class="filename">qemux86-64</code> image. + The possible architectures in the system are "all", "qemux86_64", + "lib32_qemux86_64", and "lib32_x86".</p></li><li class="listitem"><p>The <code class="filename">${MLPREFIX}</code> variable is stripped from + <code class="filename">${PN}</code> during RPM packaging. + The naming for a normal RPM package and a Multilib RPM package in a + <code class="filename">qemux86-64</code> system resolves to something similar to + <code class="filename">bash-4.1-r2.x86_64.rpm</code> and + <code class="filename">bash-4.1.r2.lib32_x86.rpm</code>, respectively. + </p></li><li class="listitem"><p>When installing a Multilib image, the RPM backend first + installs the base image and then installs the Multilib libraries. + </p></li><li class="listitem"><p>The build system relies on RPM to resolve the identical files in the + two (or more) Multilib packages.</p></li></ul></div><p> + </p><p> + For the IPK Package Management System, the following implementation details exist: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">${MLPREFIX}</code> is not stripped from + <code class="filename">${PN}</code> during IPK packaging. + The naming for a normal RPM package and a Multilib IPK package in a + <code class="filename">qemux86-64</code> system resolves to something like + <code class="filename">bash_4.1-r2.x86_64.ipk</code> and + <code class="filename">lib32-bash_4.1-rw_x86.ipk</code>, respectively. + </p></li><li class="listitem"><p>The IPK deploy folder is not modified with + <code class="filename">${MLPREFIX}</code> because packages with and without + the Multilib feature can exist in the same folder due to the + <code class="filename">${PN}</code> differences.</p></li><li class="listitem"><p>IPK defines a sanity check for Multilib installation + using certain rules for file comparison, overridden, etc. + </p></li></ul></div><p> + </p></div></div><div class="section" title="4.6. Configuring the Kernel"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="configuring-the-kernel"></a>4.6. Configuring the Kernel</h2></div></div></div><p> + Configuring the Yocto Project kernel consists of making sure the <code class="filename">.config</code> + file has all the right information in it for the image you are building. + You can use the <code class="filename">menuconfig</code> tool and configuration fragments to + make sure your <code class="filename">.config</code> file is just how you need it. + This section describes how to use <code class="filename">menuconfig</code>, create and use + configuration fragments, and how to interactively tweak your <code class="filename">.config</code> + file to create the leanest kernel configuration file possible. + </p><p> + For concepts on kernel configuration, see the + "<a class="link" href="#kernel-configuration" target="_top">Kernel Configuration</a>" + section in the Yocto Project Kernel Architecture and Use Manual. + </p><div class="section" title="4.6.1. Using menuconfig"><div class="titlepage"><div><div><h3 class="title"><a id="using-menuconfig"></a>4.6.1. Using <code class="filename">menuconfig</code></h3></div></div></div><p> + The easiest way to define kernel configurations is to set them through the + <code class="filename">menuconfig</code> tool. + For general information on <code class="filename">menuconfig</code>, see + <a class="ulink" href="http://en.wikipedia.org/wiki/Menuconfig" target="_top">http://en.wikipedia.org/wiki/Menuconfig</a>. + </p><p> + To use the <code class="filename">menuconfig</code> tool in the Yocto Project development + environment, you must build the tool using BitBake. + The following commands build and invoke <code class="filename">menuconfig</code> assuming the + source directory top-level folder is <code class="filename">~/poky</code>: + </p><pre class="literallayout"> + $ cd ~/poky + $ source oe-init-build-env + $ bitbake linux-yocto -c menuconfig + </pre><p> + Once <code class="filename">menuconfig</code> comes up, its standard interface allows you to + examine and configure all the kernel configuration parameters. + Once you have made your changes, simply exit the tool and save your changes to + create an updated version of the <code class="filename">.config</code> configuration file. + </p><p> + For an example that shows how to change a specific kernel option + using <code class="filename">menuconfig</code>, see the + "<a class="link" href="#changing-the-config-smp-configuration-using-menuconfig" title="B.2.3. Changing the CONFIG_SMP Configuration Using menuconfig">Changing + the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></a>" + section. + </p></div><div class="section" title="4.6.2. Creating Configuration Fragments"><div class="titlepage"><div><div><h3 class="title"><a id="creating-config-fragments"></a>4.6.2. Creating Configuration Fragments</h3></div></div></div><p> + Configuration fragments are simply kernel options that appear in a file + placed where the OpenEmbedded build system can find and apply them. + Syntactically, the configuration statement is identical to what would appear + in the <code class="filename">.config</code> file, which is in the + <a class="link" href="#build-directory">build directory</a> in + <code class="filename">tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></code>. + </p><p> + It is simple to create a configuration fragment. + For example, issuing the following from the shell creates a configuration fragment + file named <code class="filename">my_smp.cfg</code> that enables multi-processor support + within the kernel: + </p><pre class="literallayout"> + $ echo "CONFIG_SMP=y" >> my_smp.cfg + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + All configuration files must use the <code class="filename">.cfg</code> extension in order + for the OpenEmbedded build system to recognize them as a configuration fragment. + </div><p> + </p><p> + Where do you put your configuration files? + You can place these configuration files in the same area pointed to by + <code class="filename">SRC_URI</code>. + The OpenEmbedded build system will pick up the configuration and add it to the + kernel's configuration. + For example, suppose you had a set of configuration options in a file called + <code class="filename">myconfig.cfg</code>. + If you put that file inside a directory named <code class="filename">/linux-yocto</code> + that resides in the same directory as the kernel's append file and then add + a <code class="filename">SRC_URI</code> statement such as the following to the kernel's append file, + those configuration options will be picked up and applied when the kernel is built. + </p><pre class="literallayout"> + SRC_URI += "file://myconfig.cfg" + </pre><p> + </p><p> + As mentioned earlier, you can group related configurations into multiple files and + name them all in the <code class="filename">SRC_URI</code> statement as well. + For example, you could group separate configurations specifically for Ethernet and graphics + into their own files and add those by using a <code class="filename">SRC_URI</code> statement like the + following in your append file: + </p><pre class="literallayout"> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </pre><p> + </p></div><div class="section" title="4.6.3. Fine-tuning the Kernel Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="fine-tuning-the-kernel-configuration-file"></a>4.6.3. Fine-tuning the Kernel Configuration File</h3></div></div></div><p> + You can make sure the <code class="filename">.config</code> is as lean or efficient as + possible by reading the output of the kernel configuration fragment audit, + noting any issues, making changes to correct the issues, and then repeating. + </p><p> + As part of the kernel build process, the + <code class="filename">kernel_configcheck</code> task runs. + This task validates the kernel configuration by checking the final + <code class="filename">.config</code> file against the input files. + During the check, the task produces warning messages for the following + issues: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Requested options that did not make the final + <code class="filename">.config</code> file.</p></li><li class="listitem"><p>Configuration items that appear twice in the same + configuration fragment.</p></li><li class="listitem"><p>Configuration items tagged as 'required' were overridden. + </p></li><li class="listitem"><p>A board overrides a non-board specific option.</p></li><li class="listitem"><p>Listed options not valid for the kernel being processed. + In other words, the option does not appear anywhere.</p></li></ul></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The <code class="filename">kernel_configcheck</code> task can also optionally report + if an option is overridden during processing. + </div><p> + </p><p> + For each output warning, a message points to the file + that contains a list of the options and a pointer to the config + fragment that defines them. + Collectively, the files are the key to streamlining the configuration. + </p><p> + To streamline the configuration, do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start with a full configuration that you know + works - it builds and boots successfully. + This configuration file will be your baseline.</p></li><li class="listitem"><p>Separately run the <code class="filename">configme</code> and + <code class="filename">kernel_configcheck</code> tasks.</p></li><li class="listitem"><p>Take the resulting list of files from the + <code class="filename">kernel_configcheck</code> task warnings and do the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Drop values that are redefined in the fragment but do not + change the final <code class="filename">.config</code> file.</p></li><li class="listitem"><p>Analyze and potentially drop values from the + <code class="filename">.config</code> file that override required + configurations.</p></li><li class="listitem"><p>Analyze and potentially remove non-board specific options. + </p></li><li class="listitem"><p>Remove repeated and invalid options.</p></li></ul></div></li><li class="listitem"><p>After you have worked through the output of the kernel configuration + audit, you can re-run the <code class="filename">configme</code> + and <code class="filename">kernel_configcheck</code> tasks to see the results of your + changes. + If you have more issues, you can deal with them as described in the + previous step.</p></li></ol></div><p> + </p><p> + Iteratively working through steps two through four eventually yields + a minimal, streamlined configuration file. + Once you have the best <code class="filename">.config</code>, you can build the Linux + Yocto kernel. + </p></div></div><div class="section" title="4.7. Updating Existing Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-changes-updatingimages"></a>4.7. Updating Existing Images</h2></div></div></div><p> + Often, rather than re-flashing a new image, you might wish to install updated + packages into an existing running system. + You can do this by first sharing the <code class="filename">tmp/deploy/ipk/</code> directory + through a web server and then by changing <code class="filename">/etc/opkg/base-feeds.conf</code> + to point at the shared server. + Following is an example: + </p><pre class="literallayout"> + $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all + $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a + $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard + </pre><p> + </p></div><div class="section" title="4.8. Incrementing a Package Revision Number"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-changes-prbump"></a>4.8. Incrementing a Package Revision Number</h2></div></div></div><p> + If a committed change results in changing the package output, + then the value of the + <code class="filename"><a class="link" href="#var-PR" target="_top">PR</a></code> + variable needs to be increased + (or "bumped") as part of that commit. + This means that for new recipes you must be sure to add the <code class="filename">PR</code> + variable and set its initial value equal to "r0". + Failing to define <code class="filename">PR</code> makes it easy to miss when you bump a package. + Note that you can only use integer values following the "r" in the + <code class="filename">PR</code> variable. + </p><p> + If you are sharing a common <code class="filename">.inc</code> file with multiple recipes, + you can also use the + <code class="filename"><a class="link" href="#var-INC_PR" target="_top">INC_PR</a></code> + variable to ensure that + the recipes sharing the <code class="filename">.inc</code> file are rebuilt when the + <code class="filename">.inc</code> file itself is changed. + The <code class="filename">.inc</code> file must set <code class="filename">INC_PR</code> + (initially to "r0"), and all recipes referring to it should set <code class="filename">PR</code> + to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. + If the <code class="filename">.inc</code> file is changed then its + <code class="filename">INC_PR</code> should be incremented. + </p><p> + When upgrading the version of a package, assuming the + <code class="filename"><a class="link" href="#var-PV" target="_top">PV</a></code> + changes, the <code class="filename">PR</code> variable should be reset to "r0" + (or "$(INC_PR).0" if you are using <code class="filename">INC_PR</code>). + </p><p> + Usually, version increases occur only to packages. + However, if for some reason <code class="filename">PV</code> changes but does not + increase, you can increase the + <code class="filename"><a class="link" href="#var-PE" target="_top">PE</a></code> + variable (Package Epoch). + The <code class="filename">PE</code> variable defaults to "0". + </p><p> + Version numbering strives to follow the + <a class="ulink" href="http://www.debian.org/doc/debian-policy/ch-controlfields.html" target="_top"> + Debian Version Field Policy Guidelines</a>. + These guidelines define how versions are compared and what "increasing" a version means. + </p><p> + There are two reasons for following the previously mentioned guidelines. + First, to ensure that when a developer updates and rebuilds, they get all the changes to + the repository and do not have to remember to rebuild any sections. + Second, to ensure that target users are able to upgrade their + devices using package manager commands such as <code class="filename">opkg upgrade</code> + (or similar commands for dpkg/apt or rpm-based systems). + </p><p> + The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. + </p></div><div class="section" title="4.9. Handling a Package Name Alias"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-configuring-DISTRO_PN_ALIAS"></a>4.9. Handling a Package Name Alias</h2></div></div></div><p> + Sometimes a package name you are using might exist under an alias or as a similarly named + package in a different distribution. + The OpenEmbedded build system implements a <code class="filename">distro_check</code> + task that automatically connects to major distributions + and checks for these situations. + If the package exists under a different name in a different distribution, you get a + <code class="filename">distro_check</code> mismatch. + You can resolve this problem by defining a per-distro recipe name alias using the + <code class="filename"><a class="link" href="#var-DISTRO_PN_ALIAS" target="_top">DISTRO_PN_ALIAS</a></code> + variable. + </p><p> + Following is an example that shows how you specify the <code class="filename">DISTRO_PN_ALIAS</code> + variable: + </p><pre class="literallayout"> + DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ + distro2=package_name_alias2 \ + distro3=package_name_alias3 \ + ..." + </pre><p> + </p><p> + If you have more than one distribution alias, separate them with a space. + Note that the build system currently automatically checks the + Fedora, OpenSuSE, Debian, Ubuntu, + and Mandriva distributions for source package recipes without having to specify them + using the <code class="filename">DISTRO_PN_ALIAS</code> variable. + For example, the following command generates a report that lists the Linux distributions + that include the sources for each of the recipes. + </p><pre class="literallayout"> + $ bitbake world -f -c distro_check + </pre><p> + The results are stored in the <code class="filename">build/tmp/log/distro_check-${DATETIME}.results</code> + file found in the source directory. + </p></div><div class="section" title="4.10. Building Software from an External Source"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-software-from-an-external-source"></a>4.10. Building Software from an External Source</h2></div></div></div><p> + By default, the OpenEmbedded build system does its work from within the + <a class="link" href="#build-directory">build directory</a>. + The build process involves fetching the source files, unpacking them, and then patching them + if necessary before the build takes place. + </p><p> + Situations exist where you might want to build software from source files that are external to + and thus outside of the <a class="link" href="#source-directory">source directory</a>. + For example, suppose you have a project that includes a new BSP with a heavily customized + kernel, a very minimal image, and some new user-space recipes. + And, you want to minimize the exposure to the build system to the + development team so that they can focus on their project and maintain everyone's workflow + as much as possible. + In this case, you want a kernel source directory on the development machine where the + development occurs. + You want the recipe's + <a class="link" href="#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a> + variable to point to the external directory and use it as is, not copy it. + </p><p> + To build from software that comes from an external source, all you need to do is + change your recipe so that it inherits the + <a class="link" href="#ref-classes-externalsrc" target="_top"><code class="filename">externalsrc.bbclass</code></a> + class and then sets the + <a class="link" href="#var-S" target="_top"><code class="filename">S</code></a> + variable to point to your external source code. + Here are the statements to put in your recipe: + </p><pre class="literallayout"> + inherit externalsrc + S = "/some/path/to/your/package/source" + </pre><p> + </p><p> + It is important to know that the <code class="filename">externalsrc.bbclass</code> assumes that the + source directory <code class="filename">S</code> and the build directory + <a class="link" href="#var-B" target="_top"><code class="filename">B</code></a> + are different even though by default these directories are the same. + This assumption is important because it supports building different variants of the recipe + by using the + <a class="link" href="#var-BBCLASSEXTEND" target="_top"><code class="filename">BBCLASSEXTEND</code></a> + variable. + You could allow the build directory to be the same as the source directory but you would + not be able to build more than one variant of the recipe. + Consequently, if you are building multiple variants of the recipe, you need to establish a + build directory that is different than the source directory. + </p></div><div class="section" title="4.11. Excluding Recipes From the Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="excluding-recipes-from-the-build"></a>4.11. Excluding Recipes From the Build</h2></div></div></div><p> + You might find that there are groups of recipes you want to filter + out of the build process. + For example, recipes you know you will never use or want should not + be part of the build. + Removing these recipes from parsing speeds up parts of the build. + </p><p> + It is possible to filter or mask out <code class="filename">.bb</code> and + <code class="filename">.bbappend</code> files. + You can do this by providing an expression with the + <code class="filename"><a class="link" href="#var-BBMASK" target="_top">BBMASK</a></code> + variable. + Here is an example: + </p><pre class="literallayout"> + BBMASK = ".*/meta-mymachine/recipes-maybe/" + </pre><p> + Here, all <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files + in the directory that match the expression are ignored during the build + process. + </p></div><div class="section" title="4.12. Using an External SCM"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-appdev-srcrev"></a>4.12. Using an External SCM</h2></div></div></div><p> + If you're working on a recipe that pulls from an external Source Code Manager (SCM), it + is possible to have the OpenEmbedded build system notice new changes added to the + SCM and then build the package that depends on them using the latest version. + This only works for SCMs from which it is possible to get a sensible revision number for changes. + Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories. + </p><p> + To enable this behavior, simply add the following to the <code class="filename">local.conf</code> + configuration file found in the + <a class="link" href="#build-directory" target="_top">build directory</a>: + </p><pre class="literallayout"> + SRCREV_pn-<PN> = "${AUTOREV}" + </pre><p> + where <code class="filename">PN</code> + is the name of the package for which you want to enable automatic source + revision updating. + </p></div><div class="section" title="4.13. Debugging With the GNU Project Debugger (GDB) Remotely"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-gdb-remotedebug"></a>4.13. Debugging With the GNU Project Debugger (GDB) Remotely</h2></div></div></div><p> + GDB allows you to examine running programs, which in turn help you to understand and fix problems. + It also allows you to perform post-mortem style analysis of program crashes. + GDB is available as a package within the Yocto Project and by default is + installed in sdk images. + See the "<a class="link" href="#ref-images" target="_top">Images</a>" chapter + in the Yocto Project Reference Manual for a description of these images. + You can find information on GDB at <a class="ulink" href="http://sourceware.org/gdb/" target="_top">http://sourceware.org/gdb/</a>. + </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + For best results, install <code class="filename">-dbg</code> packages for the applications + you are going to debug. + Doing so makes available extra debug symbols that give you more meaningful output. + </div><p> + Sometimes, due to memory or disk space constraints, it is not possible + to use GDB directly on the remote target to debug applications. + These constraints arise because GDB needs to load the debugging information and the + binaries of the process being debugged. + Additionally, GDB needs to perform many computations to locate information such as function + names, variable names and values, stack traces and so forth - even before starting the + debugging process. + These extra computations place more load on the target system and can alter the + characteristics of the program being debugged. + </p><p> + To help get past the previously mentioned constraints, you can use Gdbserver. + Gdbserver runs on the remote target and does not load any debugging information + from the debugged process. + Instead, a GDB instance processes the debugging information that is run on a + remote computer - the host GDB. + The host GDB then sends control commands to Gdbserver to make it stop or start the debugged + program, as well as read or write memory regions of that debugged program. + All the debugging information loaded and processed as well + as all the heavy debugging is done by the host GDB. + Offloading these processes gives the Gdbserver running on the target a chance to remain + small and fast. + </p><p> + Because the host GDB is responsible for loading the debugging information and + for doing the necessary processing to make actual debugging happen, the + user has to make sure the host can access the unstripped binaries complete + with their debugging information and also be sure the target is compiled with no optimizations. + The host GDB must also have local access to all the libraries used by the + debugged program. + Because Gdbserver does not need any local debugging information, the binaries on + the remote target can remain stripped. + However, the binaries must also be compiled without optimization + so they match the host's binaries. + </p><p> + To remain consistent with GDB documentation and terminology, the binary being debugged + on the remote target machine is referred to as the "inferior" binary. + For documentation on GDB see the + <a class="ulink" href="http://sourceware.org/gdb/documentation/" target="_top">GDB site</a>. + </p><div class="section" title="4.13.1. Launching Gdbserver on the Target"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-gdb-remotedebug-launch-gdbserver"></a>4.13.1. Launching Gdbserver on the Target</h3></div></div></div><p> + First, make sure Gdbserver is installed on the target. + If it is not, install the package <code class="filename">gdbserver</code>, which needs the + <code class="filename">libthread-db1</code> package. + </p><p> + As an example, to launch Gdbserver on the target and make it ready to "debug" a + program located at <code class="filename">/path/to/inferior</code>, connect + to the target and launch: + </p><pre class="literallayout"> + $ gdbserver localhost:2345 /path/to/inferior + </pre><p> + Gdbserver should now be listening on port 2345 for debugging + commands coming from a remote GDB process that is running on the host computer. + Communication between Gdbserver and the host GDB are done using TCP. + To use other communication protocols, please refer to the + <a class="ulink" href="http://www.gnu.org/software/gdb/" target="_top">Gdbserver documentation</a>. + </p></div><div class="section" title="4.13.2. Launching GDB on the Host Computer"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-gdb-remotedebug-launch-gdb"></a>4.13.2. Launching GDB on the Host Computer</h3></div></div></div><p> + Running GDB on the host computer takes a number of stages. + This section describes those stages. + </p><div class="section" title="4.13.2.1. Building the Cross-GDB Package"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-buildcross"></a>4.13.2.1. Building the Cross-GDB Package</h4></div></div></div><p> + A suitable GDB cross-binary is required that runs on your host computer but + also knows about the the ABI of the remote target. + You can get this binary from the meta-toolchain. + Here is an example: + </p><pre class="literallayout"> + /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb + </pre><p> + where <code class="filename">arm</code> is the target architecture and + <code class="filename">linux-gnueabi</code> the target ABI. + </p><p> + Alternatively, you can use BitBake to build the <code class="filename">gdb-cross</code> binary. + Here is an example: + </p><pre class="literallayout"> + $ bitbake gdb-cross + </pre><p> + Once the binary is built, you can find it here: + </p><pre class="literallayout"> + tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb + </pre><p> + </p></div><div class="section" title="4.13.2.2. Making the Inferior Binaries Available"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-inferiorbins"></a>4.13.2.2. Making the Inferior Binaries Available</h4></div></div></div><p> + The inferior binary (complete with all debugging symbols) as well as any + libraries (and their debugging symbols) on which the inferior binary depends + need to be available. + There are a number of ways you can make these available. + </p><p> + Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain + image installed on the device. + In the case of <code class="filename">core-image-sato</code>, + <code class="filename">core-image-sato-sdk</code> would contain suitable symbols. + Because the sdk images already have the debugging symbols installed, it is just a + question of expanding the archive to some location and then informing GDB. + </p><p> + Alternatively, the OpenEmbedded build system can build a custom directory of files + for a specific + debugging purpose by reusing its <code class="filename">tmp/rootfs</code> directory. + This directory contains the contents of the last built image. + This process assumes two things: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The image running on the target was the last image to + be built.</p></li><li class="listitem"><p>The package (<code class="filename">foo</code> in the following + example) that contains the inferior binary to be debugged has been built + without optimization and has debugging information available.</p></li></ul></div><p> + </p><p> + The following steps show how to build the custom directory of files: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install the package (<code class="filename">foo</code> in this case) to + <code class="filename">tmp/rootfs</code>: + </p><pre class="literallayout"> + $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ + tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf -o \ + tmp/rootfs/ update + </pre></li><li class="listitem"><p>Install the debugging information: + </p><pre class="literallayout"> + $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ + tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \ + -o tmp/rootfs install foo + + $ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ + tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \ + -o tmp/rootfs install foo-dbg + </pre></li></ol></div><p> + </p></div><div class="section" title="4.13.2.3. Launch the Host GDB"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-launchhost"></a>4.13.2.3. Launch the Host GDB</h4></div></div></div><p> + To launch the host GDB, you run the <code class="filename">cross-gdb</code> binary and provide + the inferior binary as part of the command line. + For example, the following command form continues with the example used in + the previous section. + This command form loads the <code class="filename">foo</code> binary + as well as the debugging information: + </p><pre class="literallayout"> + $ <target-abi>-gdb rootfs/usr/bin/foo + </pre><p> + Once the GDB prompt appears, you must instruct GDB to load all the libraries + of the inferior binary from <code class="filename">tmp/rootfs</code> as follows: + </p><pre class="literallayout"> + $ set solib-absolute-prefix /path/to/tmp/rootfs + </pre><p> + The pathname <code class="filename">/path/to/tmp/rootfs</code> must either be + the absolute path to <code class="filename">tmp/rootfs</code> or the location at which + binaries with debugging information reside. + </p><p> + At this point you can have GDB connect to the Gdbserver that is running + on the remote target by using the following command form: + </p><pre class="literallayout"> + $ target remote remote-target-ip-address:2345 + </pre><p> + The <code class="filename">remote-target-ip-address</code> is the IP address of the + remote target where the Gdbserver is running. + Port 2345 is the port on which the GDBSERVER is running. + </p></div><div class="section" title="4.13.2.4. Using the Debugger"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-gdb-remotedebug-launch-gdb-using"></a>4.13.2.4. Using the Debugger</h4></div></div></div><p> + You can now proceed with debugging as normal - as if you were debugging + on the local machine. + For example, to instruct GDB to break in the "main" function and then + continue with execution of the inferior binary use the following commands + from within GDB: + </p><pre class="literallayout"> + (gdb) break main + (gdb) continue + </pre><p> + </p><p> + For more information about using GDB, see the project's online documentation at + <a class="ulink" href="http://sourceware.org/gdb/download/onlinedocs/" target="_top">http://sourceware.org/gdb/download/onlinedocs/</a>. + </p></div></div></div><div class="section" title="4.14. Profiling with OProfile"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-oprofile"></a>4.14. Profiling with OProfile</h2></div></div></div><p> + <a class="ulink" href="http://oprofile.sourceforge.net/" target="_top">OProfile</a> is a + statistical profiler well suited for finding performance + bottlenecks in both userspace software and in the kernel. + This profiler provides answers to questions like "Which functions does my application spend + the most time in when doing X?" + Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling + applications on target hardware straightforward. + </p><p> + To use OProfile, you need an image that has OProfile installed. + The easiest way to do this is with <code class="filename">tools-profile</code> in the + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" target="_top">IMAGE_FEATURES</a></code> variable. + You also need debugging symbols to be available on the system where the analysis + takes place. + You can gain access to the symbols by using <code class="filename">dbg-pkgs</code> in the + <code class="filename">IMAGE_FEATURES</code> variable or by + installing the appropriate <code class="filename">-dbg</code> packages. + </p><p> + For successful call graph analysis, the binaries must preserve the frame + pointer register and should also be compiled with the + <code class="filename">-fno-omit-framepointer</code> flag. + You can achieve this by setting the + <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" target="_top">SELECTED_OPTIMIZATION</a></code> + variable to + <code class="filename">-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</code>. + You can also achieve it by setting the + <code class="filename"><a class="link" href="#var-DEBUG_BUILD" target="_top">DEBUG_BUILD</a></code> + variable to "1" in the <code class="filename">local.conf</code> configuration file. + If you use the <code class="filename">DEBUG_BUILD</code> variable you will also add extra debug information + that can make the debug packages large. + </p><div class="section" title="4.14.1. Profiling on the Target"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-oprofile-target"></a>4.14.1. Profiling on the Target</h3></div></div></div><p> + Using OProfile you can perform all the profiling work on the target device. + A simple OProfile session might look like the following: + </p><p> + </p><pre class="literallayout"> + # opcontrol --reset + # opcontrol --start --separate=lib --no-vmlinux -c 5 + . + . + [do whatever is being profiled] + . + . + # opcontrol --stop + $ opreport -cl + </pre><p> + </p><p> + In this example, the <code class="filename">reset</code> command clears any previously profiled data. + The next command starts OProfile. + The options used when starting the profiler separate dynamic library data + within applications, disable kernel profiling, and enable callgraphing up to + five levels deep. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + To profile the kernel, you would specify the + <code class="filename">--vmlinux=/path/to/vmlinux</code> option. + The <code class="filename">vmlinux</code> file is usually in the source directory in the + <code class="filename">/boot/</code> directory and must match the running kernel. + </div><p> + </p><p> + After you perform your profiling tasks, the next command stops the profiler. + After that, you can view results with the <code class="filename">opreport</code> command with options + to see the separate library symbols and callgraph information. + </p><p> + Callgraphing logs information about time spent in functions and about a function's + calling function (parent) and called functions (children). + The higher the callgraphing depth, the more accurate the results. + However, higher depths also increase the logging overhead. + Consequently, you should take care when setting the callgraphing depth. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + On ARM, binaries need to have the frame pointer enabled for callgraphing to work. + To accomplish this use the <code class="filename">-fno-omit-framepointer</code> option + with <code class="filename">gcc</code>. + </div><p> + </p><p> + For more information on using OProfile, see the OProfile + online documentation at + <a class="ulink" href="http://oprofile.sourceforge.net/docs/" target="_top">http://oprofile.sourceforge.net/docs/</a>. + </p></div><div class="section" title="4.14.2. Using OProfileUI"><div class="titlepage"><div><div><h3 class="title"><a id="platdev-oprofile-oprofileui"></a>4.14.2. Using OProfileUI</h3></div></div></div><p> + A graphical user interface for OProfile is also available. + You can download and build this interface from the Yocto Project at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/oprofileui/" target="_top">http://git.yoctoproject.org/cgit.cgi/oprofileui/</a>. + If the "tools-profile" image feature is selected, all necessary binaries + are installed onto the target device for OProfileUI interaction. + </p><p> + Even though the source directory usually includes all needed patches on the target device, you + might find you need other OProfile patches for recent OProfileUI features. + If so, see the <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/oprofileui/tree/README" target="_top"> + OProfileUI README</a> for the most recent information. + </p><div class="section" title="4.14.2.1. Online Mode"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-oprofile-oprofileui-online"></a>4.14.2.1. Online Mode</h4></div></div></div><p> + Using OProfile in online mode assumes a working network connection with the target + hardware. + With this connection, you just need to run "oprofile-server" on the device. + By default, OProfile listens on port 4224. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + You can change the port using the <code class="filename">--port</code> command-line + option. + </div><p> + </p><p> + The client program is called <code class="filename">oprofile-viewer</code> and its UI is relatively + straightforward. + You access key functionality through the buttons on the toolbar, which + are duplicated in the menus. + Here are the buttons: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Connect:</em></span> Connects to the remote host. + You can also supply the IP address or hostname.</p></li><li class="listitem"><p><span class="emphasis"><em>Disconnect:</em></span> Disconnects from the target. + </p></li><li class="listitem"><p><span class="emphasis"><em>Start:</em></span> Starts profiling on the device. + </p></li><li class="listitem"><p><span class="emphasis"><em>Stop:</em></span> Stops profiling on the device and + downloads the data to the local host. + Stopping the profiler generates the profile and displays it in the viewer. + </p></li><li class="listitem"><p><span class="emphasis"><em>Download:</em></span> Downloads the data from the + target and generates the profile, which appears in the viewer.</p></li><li class="listitem"><p><span class="emphasis"><em>Reset:</em></span> Resets the sample data on the device. + Resetting the data removes sample information collected from previous + sampling runs. + Be sure you reset the data if you do not want to include old sample information. + </p></li><li class="listitem"><p><span class="emphasis"><em>Save:</em></span> Saves the data downloaded from the + target to another directory for later examination.</p></li><li class="listitem"><p><span class="emphasis"><em>Open:</em></span> Loads previously saved data. + </p></li></ul></div><p> + </p><p> + The client downloads the complete 'profile archive' from + the target to the host for processing. + This archive is a directory that contains the sample data, the object files, + and the debug information for the object files. + The archive is then converted using the <code class="filename">oparchconv</code> script, which is + included in this distribution. + The script uses <code class="filename">opimport</code> to convert the archive from + the target to something that can be processed on the host. + </p><p> + Downloaded archives reside in the build directory in + <code class="filename">/tmp</code> and are cleared up when they are no longer in use. + </p><p> + If you wish to perform kernel profiling, you need to be sure + a <code class="filename">vmlinux</code> file that matches the running kernel is available. + In the source directory, that file is usually located in + <code class="filename">/boot/vmlinux-KERNELVERSION</code>, where + <code class="filename">KERNEL-version</code> is the version of the kernel. + The OpenEmbedded build system generates separate <code class="filename">vmlinux</code> + packages for each kernel it builds. + Thus, it should just be a question of making sure a matching package is + installed (e.g. <code class="filename">opkg install kernel-vmlinux</code>. + The files are automatically installed into development and profiling images + alongside OProfile. + A configuration option exists within the OProfileUI settings page that you can use to + enter the location of the <code class="filename">vmlinux</code> file. + </p><p> + Waiting for debug symbols to transfer from the device can be slow, and it + is not always necessary to actually have them on the device for OProfile use. + All that is needed is a copy of the filesystem with the debug symbols present + on the viewer system. + The "<a class="link" href="#platdev-gdb-remotedebug-launch-gdb" title="4.13.2. Launching GDB on the Host Computer">Launching GDB on the Host Computer</a>" + section covers how to create such a directory with + the source directory and how to use the OProfileUI Settings dialog to specify the location. + If you specify the directory, it will be used when the file checksums + match those on the system you are profiling. + </p></div><div class="section" title="4.14.2.2. Offline Mode"><div class="titlepage"><div><div><h4 class="title"><a id="platdev-oprofile-oprofileui-offline"></a>4.14.2.2. Offline Mode</h4></div></div></div><p> + If network access to the target is unavailable, you can generate + an archive for processing in <code class="filename">oprofile-viewer</code> as follows: + </p><pre class="literallayout"> + # opcontrol --reset + # opcontrol --start --separate=lib --no-vmlinux -c 5 + . + . + [do whatever is being profiled] + . + . + # opcontrol --stop + # oparchive -o my_archive + </pre><p> + </p><p> + In the above example, <code class="filename">my_archive</code> is the name of the + archive directory where you would like the profile archive to be kept. + After the directory is created, you can copy it to another host and load it + using <code class="filename">oprofile-viewer</code> open functionality. + If necessary, the archive is converted. + </p></div></div></div></div> + + <div class="chapter" title="Chapter 5. Common Development Models"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-model"></a>Chapter 5. Common Development Models</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#system-development-model">5.1. System Development Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#developing-a-board-support-package-bsp">5.1.1. Developing a Board Support Package (BSP)</a></span></dt><dt><span class="section"><a href="#modifying-the-kernel">5.1.2. Modifying the Kernel</a></span></dt></dl></dd><dt><span class="section"><a href="#application-development-workflow">5.2. Application Development Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#workflow-using-the-adt-and-eclipse">5.2.1. Workflow Using the ADT and <span class="trademark">Eclipse</span>™</a></span></dt><dt><span class="section"><a href="#adt-eclipse">5.2.2. Working Within Eclipse</a></span></dt><dt><span class="section"><a href="#workflow-using-stand-alone-cross-development-toolchains">5.2.3. Workflow Using Stand-alone Cross-development Toolchains</a></span></dt></dl></dd><dt><span class="section"><a href="#modifying-temporary-source-code">5.3. Modifying Temporary Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#finding-the-temporary-source-code">5.3.1. Finding the Temporary Source Code</a></span></dt><dt><span class="section"><a href="#using-a-quilt-workflow">5.3.2. Using a Quilt Workflow</a></span></dt><dt><span class="section"><a href="#using-a-git-workflow">5.3.3. Using a Git Workflow</a></span></dt></dl></dd><dt><span class="section"><a href="#image-development-using-hob">5.4. Image Development Using Hob</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">5.5. Using a Development Shell</a></span></dt></dl></div><p> + Many development models exist for which you can use the Yocto Project. + This chapter overviews the following methods: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>System Development:</em></span> + System Development covers Board Support Package (BSP) development and kernel + modification or configuration. + If you want to examine specific examples of the system development models, + see the "<a class="link" href="#dev-manual-bsp-appendix" title="Appendix A. BSP Development Example">BSP Development Example</a>" + appendix and the + "<a class="link" href="#dev-manual-kernel-appendix" title="Appendix B. Kernel Modification Example">Kernel Modification Example</a>" appendix. + </p></li><li class="listitem"><p><span class="emphasis"><em>User Application Development:</em></span> + User Application Development covers development of applications that you intend + to run on some target hardware. + For a user-space application development example that uses the + <span class="trademark">Eclipse</span>™ IDE, + see the + Yocto Project Application Developer's Guide. + </p></li><li class="listitem"><p><span class="emphasis"><em>Temporary Source Code Modification:</em></span> + Direct modification of temporary source code is a convenient development model + to quickly iterate and develop towards a solution. + Once the solution has been implemented, you should of course take steps to + get the changes upstream and applied in the affected recipes.</p></li><li class="listitem"><p><span class="emphasis"><em>Image Development using Hob:</em></span> + You can use the <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> to build + custom operating system images within the build environment. + Hob provides an efficient interface to the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em>Using a Development Shell:</em></span> + You can use a <code class="filename">devshell</code> to efficiently debug commands or simply + edit packages. + Working inside a development shell is a quick way to set up the OpenEmbedded build + environment to work on parts of a project.</p></li></ul></div><p> +</p><div class="section" title="5.1. System Development Workflow"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="system-development-model"></a>5.1. System Development Workflow</h2></div></div></div><p> + System development involves modification or creation of an image that you want to run on + a specific hardware target. + Usually, when you want to create an image that runs on embedded hardware, the image does + not require the same number of features that a full-fledged Linux distribution provides. + Thus, you can create a much smaller image that is designed to use only the hardware + features for your particular hardware. + </p><p> + To help you understand how system development works in the Yocto Project, this section + covers two types of image development: BSP creation and kernel modification or + configuration. + </p><div class="section" title="5.1.1. Developing a Board Support Package (BSP)"><div class="titlepage"><div><div><h3 class="title"><a id="developing-a-board-support-package-bsp"></a>5.1.1. Developing a Board Support Package (BSP)</h3></div></div></div><p> + A BSP is a packageof recipes that, when applied, during a build results in + an image that you can run on a particular board. + Thus, the package, when compiled into the new image, supports the operation of the board. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + For a brief list of terms used when describing the development process in the Yocto Project, + see the "<a class="link" href="#yocto-project-terms" title="3.4. Yocto Project Terms">Yocto Project Terms</a>" section. + </div><p> + The remainder of this section presents the basic steps used to create a BSP + based on an existing BSP that ships with the Yocto Project. + You can reference the "<a class="link" href="#dev-manual-bsp-appendix" title="Appendix A. BSP Development Example">BSP Development Example</a>" + appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start. + </p><p> + The following illustration and list summarize the BSP creation general workflow. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/bsp-dev-flow.png" align="middle" width="540" /></td></tr></table><p> + </p><p> + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Set up your host development system to support + development using the Yocto Project</em></span>: See the + "<a class="link" href="#the-linux-distro" target="_top">The Linux Distributions</a>" + and the + "<a class="link" href="#packages" target="_top">The Packages</a>" sections both + in the Yocto Project Quick Start for requirements.</p></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of the project files on your + system</em></span>: You need this <a class="link" href="#source-directory">source + directory</a> available on your host system. + Having these files on your system gives you access to the build + process and to the tools you need. + For information on how to set up the source directory, see the + "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Setup</a>" section.</p></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of the base BSP files</em></span>: Having + the BSP files on your system gives you access to the build + process and to the tools you need for creating a BSP. + For information on how to get these files, see the + "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Setup</a>" section.</p></li><li class="listitem"><p><span class="emphasis"><em>Choose a BSP that is supported by the Yocto Project + as your base BSP</em></span>: + The Yocto Project ships with several BSPs that support various hardware. + It is best to base your new BSP on an existing BSP rather than create all the + recipes and configuration files from scratch. + While it is possible to create everything from scratch, basing your new BSP + on something that is close is much easier. + Or, at a minimum, leveraging off an existing BSP + gives you some structure with which to start.</p><p>At this point you need to understand your target hardware well enough to determine which + existing BSP it most closely matches. + Things to consider are your hardware’s on-board features, such as CPU type and graphics support. + You should look at the README files for supported BSPs to get an idea of which one + you could use. + A generic <span class="trademark">Intel</span>® + <span class="trademark">Atom</span>™-based BSP to consider is the + Crown Bay that does not support the <span class="trademark">Intel</span>® + Embedded Media Graphics Driver (EMGD). + The remainder of this example uses that base BSP.</p><p>To see the supported BSPs, go to the + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Download</a> page on the Yocto Project + website and click on “BSP Downloads.”</p></li><li class="listitem"><p><span class="emphasis"><em>Create your own BSP layer</em></span>: Layers are ideal for + isolating and storing work for a given piece of hardware. + A layer is really just a location or area in which you place the recipes for your BSP. + In fact, a BSP is, in itself, a special type of layer. + </p><p> + Another example that illustrates a layer is an application. + Suppose you are creating an application that has library or other dependencies in + order for it to compile and run. + The layer, in this case, would be where all the recipes that define those dependencies + are kept. + The key point for a layer is that it is an isolated area that contains + all the relevant information for the project that the OpenEmbedded build + system knows about. + For more information on layers, see the + "<a class="link" href="#understanding-and-creating-layers" title="4.1. Understanding and Creating Layers">Understanding and Creating Layers</a>" + section. + For more information on BSP layers, see the + "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>" section in the + Yocto Project Board Support Package (BSP) Developer's Guide.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Four BSPs exist that are part of the + Yocto Project release: <code class="filename">atom-pc</code>, <code class="filename">beagleboard</code>, + <code class="filename">mpc8315e</code>, and <code class="filename">routerstationpro</code>. + The recipes and configurations for these four BSPs are located and dispersed + within the <a class="link" href="#source-directory">source directory</a>. + On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, + N450, Cedar Trail, Fish River, Fish River Island II, Romley, sys940x, tlk, + and Sugar Bay exist in their own separate layers within the larger + <code class="filename">meta-intel</code> layer.</div><p>When you set up a layer for a new BSP, you should follow a standard layout. + This layout is described in the section + "<a class="link" href="#bsp-filelayout" target="_top">Example Filesystem Layout</a>" + section of the Board Support Package (BSP) Development Guide. + In the standard layout, you will notice a suggested structure for recipes and + configuration information. + You can see the standard layout for the Crown Bay BSP in this example by examining the + directory structure of the <code class="filename">meta-crownbay</code> layer inside the + source directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Make configuration changes to your new BSP + layer</em></span>: The standard BSP layer structure organizes the files you need + to edit in <code class="filename">conf</code> and several <code class="filename">recipes-*</code> + directories within the BSP layer. + Configuration changes identify where your new layer is on the local system + and identify which kernel you are going to use. + </p></li><li class="listitem"><p><span class="emphasis"><em>Make recipe changes to your new BSP layer</em></span>: Recipe + changes include altering recipes (<code class="filename">.bb</code> files), removing + recipes you don't use, and adding new recipes that you need to support your hardware. + </p></li><li class="listitem"><p><span class="emphasis"><em>Prepare for the build</em></span>: Once you have made all the + changes to your BSP layer, there remains a few things + you need to do for the OpenEmbedded build system in order for it to create your image. + You need to get the build environment ready by sourcing an environment setup script + and you need to be sure two key configuration files are configured appropriately.</p><p>The entire process for building an image is overviewed in the section + "<a class="link" href="#building-image" target="_top">Building an Image</a>" section + of the Yocto Project Quick Start. + You might want to reference this information.</p></li><li class="listitem"><p><span class="emphasis"><em>Build the image</em></span>: The OpenEmbedded build system + uses the BitBake tool to build images based on the type of image you want to create. + You can find more information on BitBake + <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">here</a>.</p><p>The build process supports several types of images to satisfy different needs. + See the + "<a class="link" href="#ref-images" target="_top">Images</a>" chapter + in the Yocto Project Reference Manual for information on + supported images.</p></li></ol></div><p> + </p><p> + You can view a video presentation on "Building Custom Embedded Images with Yocto" + at <a class="ulink" href="http://free-electrons.com/blog/elc-2011-videos" target="_top">Free Electrons</a>. + You can also find supplemental information in + <a class="ulink" href="http://www.yoctoproject.org/docs/1.3/bsp-guide/bsp-guide.html" target="_top"> + The Board Support Package (BSP) Development Guide</a>. + Finally, there is wiki page write up of the example also located + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another" target="_top"> + here</a> that you might find helpful. + </p></div><div class="section" title="5.1.2. Modifying the Kernel"><div class="titlepage"><div><div><h3 class="title"><a id="modifying-the-kernel"></a>5.1.2. <a id="kernel-spot"></a>Modifying the Kernel</h3></div></div></div><p> + Kernel modification involves changing the Yocto Project kernel, which could involve changing + configuration options as well as adding new kernel recipes. + Configuration changes can be added in the form of configuration fragments, while recipe + modification comes through the kernel's <code class="filename">recipes-kernel</code> area + in a kernel layer you create. + </p><p> + The remainder of this section presents a high-level overview of the Yocto Project + kernel architecture and the steps to modify the kernel. + For a complete discussion of the kernel, see the + Yocto Project Kernel Architecture and Use Manual. + You can reference the appendix + "<a class="link" href="#dev-manual-kernel-appendix" title="Appendix B. Kernel Modification Example">Kernel Modification Example</a>" + for a detailed example that changes the configuration of a kernel. + </p><div class="section" title="5.1.2.1. Kernel Overview"><div class="titlepage"><div><div><h4 class="title"><a id="kernel-overview"></a>5.1.2.1. Kernel Overview</h4></div></div></div><p> + Traditionally, when one thinks of a patched kernel, they think of a base kernel + source tree and a fixed structure that contains kernel patches. + The Yocto Project, however, employs mechanisms, that in a sense, result in a kernel source + generator. + By the end of this section, this analogy will become clearer. + </p><p> + You can find a web interface to the Yocto Project kernel source repositories at + <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>. + If you look at the interface, you will see to the left a grouping of + Git repositories titled "Yocto Linux Kernel." + Within this group, you will find several kernels supported by + the Yocto Project: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-2.6.34</code></em></span> - The + stable Yocto Project kernel that is based on the Linux 2.6.34 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-2.6.37</code></em></span> - The + stable Yocto Project kernel that is based on the Linux 2.6.37 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-3.0</code></em></span> - The stable + Yocto Project kernel that is based on the Linux 3.0 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-3.0-1.1.x</code></em></span> - The + stable Yocto Project kernel to use with the Yocto Project Release 1.1.x. This kernel + is based on the Linux 3.0 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-3.2</code></em></span> - The + stable Yocto Project kernel to use with the Yocto Project Release 1.2. This kernel + is based on the Linux 3.2 released kernel.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">linux-yocto-dev</code></em></span> - A development + kernel based on the latest upstream release candidate available.</p></li></ul></div><p> + </p><p> + The kernels are maintained using the Git revision control system + that structures them using the familiar "tree", "branch", and "leaf" scheme. + Branches represent diversions from general code to more specific code, while leaves + represent the end-points for a complete and unique kernel whose source files + when gathered from the root of the tree to the leaf accumulate to create the files + necessary for a specific piece of hardware and its features. + The following figure displays this concept: + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 540px"><td align="center"><img src="figures/kernel-overview-1.png" align="middle" /></td></tr></table><p> + </p><p> + + </p><p> + Within the figure, the "Kernel.org Branch Point" represents the point in the tree + where a supported base kernel is modified from the Linux kernel. + For example, this could be the branch point for the <code class="filename">linux-yocto-3.0</code> + kernel. + Thus, everything further to the right in the structure is based on the + <code class="filename">linux-yocto-3.0</code> kernel. + Branch points to right in the figure represent where the + <code class="filename">linux-yocto-3.0</code> kernel is modified for specific hardware + or types of kernels, such as real-time kernels. + Each leaf thus represents the end-point for a kernel designed to run on a specific + targeted device. + </p><p> + + </p><p> + The overall result is a Git-maintained repository from which all the supported + kernel types can be derived for all the supported devices. + A big advantage to this scheme is the sharing of common features by keeping them in + "larger" branches within the tree. + This practice eliminates redundant storage of similar features shared among kernels. + </p><p> + + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Keep in mind the figure does not take into account all the supported Yocto + Project kernel types, but rather shows a single generic kernel just for conceptual purposes. + Also keep in mind that this structure represents the Yocto Project source repositories + that are either pulled from during the build or established on the host development system + prior to the build by either cloning a particular kernel's Git repository or by + downloading and unpacking a tarball. + </div><p> + + </p><p> + Storage of all the available kernel source code is one thing, while representing the + code on your host development system is another. + Conceptually, you can think of the kernel source repositories as all the + source files necessary for all the supported kernels. + As a developer, you are just interested in the source files for the kernel on + on which you are working. + And, furthermore, you need them available on your host system. + </p><p> + + </p><p> + You make kernel source code available on your host development system by using + Git to create a bare clone of the Yocto Project kernel Git repository + in which you are interested. + Then, you use Git again to clone a copy of that bare clone. + This copy represents the directory structure on your host system that is particular + to the kernel you want. + These are the files you actually modify to change the kernel. + See the <a class="link" href="#local-kernel-files">Yocto Project Kernel</a> item earlier + in this manual for an example of how to set up the kernel source directory + structure on your host system. + </p><p> + + </p><p> + This next figure illustrates how the kernel source files might be arranged on + your host system. + </p><p> + + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/kernel-overview-3-denzil.png" align="middle" /></td></tr></table><p> + </p><p> + + </p><p> + In the previous figure, the file structure on the left represents the bare clone + set up to track the Yocto Project kernel Git repository. + The structure on the right represents the copy of the bare clone. + When you make modifcations to the kernel source code, this is the area in which + you work. + Once you make corrections, you must use Git to push the committed changes to the + bare clone. + The example in <a class="xref" href="#modifying-the-kernel-source-code" title="B.1. Modifying the Kernel Source Code">Section B.1, “Modifying the Kernel Source Code”</a> provides a detailed example. + </p><p> + + </p><p> + What happens during the build? + When you build the kernel on your development system all files needed for the build + are taken from the source repositories pointed to by the + <code class="filename">SRC_URI</code> variable and gathered in a temporary work area + where they are subsequently used to create the unique kernel. + Thus, in a sense, the process constructs a local source tree specific to your + kernel to generate the new kernel image - a source generator if you will. + </p><p> + The following figure shows the temporary file structure + created on your host system when the build occurs. + This build directory contains all the source files used during the build. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 450px"><td align="center"><img src="figures/kernel-overview-2.png" align="middle" /></td></tr></table><p> + </p><p> + Again, for a complete discussion of the Yocto Project kernel's architecture and its + branching strategy, see the + Yocto Project Kernel Architecture and Use Manual. + You can also reference the + "<a class="link" href="#modifying-the-kernel-source-code" title="B.1. Modifying the Kernel Source Code">Modifying the Kernel Source Code</a>" + section for a detailed example that modifies the kernel. + </p></div><div class="section" title="5.1.2.2. Kernel Modification Workflow"><div class="titlepage"><div><div><h4 class="title"><a id="kernel-modification-workflow"></a>5.1.2.2. Kernel Modification Workflow</h4></div></div></div><p> + This illustration and the following list summarizes the kernel modification general workflow. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 675px"><td align="center"><img src="figures/kernel-dev-flow.png" align="middle" width="540" /></td></tr></table><p> + </p><p> + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Set up your host development system to support + development using the Yocto Project</em></span>: See + "<a class="link" href="#the-linux-distro" target="_top">The Linux Distributions</a>" and + "<a class="link" href="#packages" target="_top">The Packages</a>" sections both + in the Yocto Project Quick Start for requirements.</p></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of project files on your + system</em></span>: Having the <a class="link" href="#source-directory">source + directory</a> on your system gives you access to the build process and tools + you need. + For information on how to get these files, see the bulleted item + "<a class="link" href="#local-yp-release">Yocto Project Release</a>" earlier in this manual. + </p></li><li class="listitem"><p><span class="emphasis"><em>Set up a local copy of the <code class="filename">poky-extras</code> Git + repository</em></span>: This local repository is the area for your configuration + fragments, new kernel recipes, and the kernel <code class="filename">.bbappend</code> + file used during the build. + It is good practice to set this repository up inside your local + source directory. + For information on how to get these files, see the bulleted item + "<a class="link" href="#poky-extras-repo">The <code class="filename">poky-extras</code> Git Repository</a>" + earlier in this manual. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>While it is certainly possible to modify the kernel without involving + a local Git repository, the suggested workflow for kernel modification + using the Yocto Project does use a Git repository.</div></li><li class="listitem"><p><span class="emphasis"><em>Establish a local copy of the Yocto Project kernel files on your + system</em></span>: In order to make modifications to the kernel you need two things: + a bare clone of the Yocto Project kernel you are modifying and + a copy of that bare clone. + The bare clone is required by the build process and is the area to which you + push your kernel source changes (pulling does not work with bare clones). + The copy of the bare clone is a local Git repository that contains all the kernel's + source files. + You make your changes to the files in this copy of the bare clone. + For information on how to set these two items up, see the bulleted item + "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" + earlier in this manual.</p></li><li class="listitem"><p><span class="emphasis"><em>Make changes to the kernel source code if + applicable</em></span>: Modifying the kernel does not always mean directly + changing source files. + However, if you have to do this, you make the changes in the local + Git repository you set up to hold the source files (i.e. the copy of the + bare clone). + Once the changes are made, you need to use Git commands to commit the changes + and then push them to the bare clone.</p></li><li class="listitem"><p><span class="emphasis"><em>Make kernel configuration changes + if applicable</em></span>: + If your situation calls for changing the kernel's configuration, you can + use <code class="filename">menuconfig</code> + to enable and disable kernel configurations. + Using <code class="filename">menuconfig</code> allows you to interactively develop and test the + configuration changes you are making to the kernel. + When saved, changes using <code class="filename">menuconfig</code> update the kernel's + <code class="filename">.config</code>. + Try to resist the temptation of directly editing the <code class="filename">.config</code> + file found in the + <a class="link" href="#build-directory">build directory</a> at + <code class="filename">tmp/sysroots/<machine-name>/kernel</code>. + Doing so, can produce unexpected results when the OpenEmbedded build system + regenerates the configuration file.</p><p>Once you are satisfied with the configuration changes made using + <code class="filename">menuconfig</code>, you can directly examine the + <code class="filename">.config</code> file against a saved original and gather those + changes into a config fragment to be referenced from within the kernel's + <code class="filename">.bbappend</code> file.</p></li><li class="listitem"><p><span class="emphasis"><em>Add or extend kernel recipes if applicable</em></span>: + The standard + layer structure organizes recipe files inside the + <code class="filename">meta-kernel-dev</code> layer that is within the local + <code class="filename">poky-extras</code> Git repository. + If you need to add new kernel recipes, you add them within this layer. + Also within this area, you will find the <code class="filename">.bbappend</code> + file that appends information to the kernel's recipe file used during the + build. + </p></li><li class="listitem"><p><span class="emphasis"><em>Prepare for the build</em></span>: Once you have made all the + changes to your kernel (configurations, source code changes, recipe additions, + or recipe changes), there remains a few things + you need to do in order for the build system to create your image. + If you have not done so, you need to get the build environment ready by sourcing + the environment setup script described earlier. + You also need to be sure two key configuration files + (<code class="filename">local.conf</code> and <code class="filename">bblayers.conf</code>) + are configured appropriately.</p><p>The entire process for building an image is overviewed in the + "<a class="link" href="#building-image" target="_top">Building an Image</a>" + section of the Yocto Project Quick Start. + You might want to reference this information. + Also, you should look at the detailed examples found in the appendices at + at the end of this manual.</p></li><li class="listitem"><p><span class="emphasis"><em>Build the image</em></span>: The OpenEmbedded + build system uses the BitBake + tool to build images based on the type of image you want to create. + You can find more information on BitBake + <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">here</a>.</p><p>The build process supports several types of images to satisfy different needs. + See the "<a class="link" href="#ref-images" target="_top">Images</a>" chapter in + the Yocto Project Reference Manual for information on supported images.</p></li><li class="listitem"><p><span class="emphasis"><em>Make your configuration changes available + in the kernel layer</em></span>: Up to this point, all the configuration changes to the + kernel have been done and tested iteratively. + Once they are tested and ready to go, you can move them into the kernel layer, + which allows you to distribute the layer.</p></li><li class="listitem"><p><span class="emphasis"><em>If applicable, share your in-tree changes</em></span>: + If the changes you made + are suited for all Yocto Project kernel users, you might want to send them on + for inclusion into the upstream kernel's Git repository. + If the changes are accepted, the Yocto Project Maintainer pulls them into + the master branch of the kernel tree. + Doing so makes them available to everyone using the kernel.</p></li></ol></div><p> + </p></div></div></div><div class="section" title="5.2. Application Development Workflow"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="application-development-workflow"></a>5.2. Application Development Workflow</h2></div></div></div><p> + Application development involves creating an application that you want + to run on your target hardware, which is running a kernel image created using the + OpenEmbedded build system. + The Yocto Project provides an Application Development Toolkit (ADT) and + stand-alone cross-development toolchains that + facilitate quick development and integration of your application into its run-time environment. + Using the ADT and toolchains, you can compile and link your application. + You can then deploy your application to the actual hardware or to the QEMU emulator for testing. + If you are familiar with the popular Eclipse IDE, you can use an Eclipse Yocto Plug-in to + allow you to develop, deploy, and test your application all from within Eclipse. + </p><p> + While we strongly suggest using the ADT to develop your application, this option might not + be best for you. + If this is the case, you can still use pieces of the Yocto Project for your development process. + However, because the process can vary greatly, this manual does not provide detail on the process. + </p><div class="section" title="5.2.1. Workflow Using the ADT and Eclipse™"><div class="titlepage"><div><div><h3 class="title"><a id="workflow-using-the-adt-and-eclipse"></a>5.2.1. Workflow Using the ADT and <span class="trademark">Eclipse</span>™</h3></div></div></div><p> + To help you understand how application development works using the ADT, this section + provides an overview of the general development process and a detailed example of the process + as it is used from within the Eclipse IDE. + </p><p> + The following illustration and list summarize the application development general workflow. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 720px"><td align="center"><img src="figures/app-dev-flow.png" align="middle" /></td></tr></table><p> + </p><p> + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Prepare the Host System for the Yocto Project</em></span>: + See + "<a class="link" href="#the-linux-distro" target="_top">The Linux Distributions</a>" and + "<a class="link" href="#packages" target="_top">The Packages</a>" sections both + in the Yocto Project Quick Start for requirements.</p></li><li class="listitem"><p><span class="emphasis"><em>Secure the Yocto Project Kernel Target Image</em></span>: + You must have a target kernel image that has been built using the OpenEmbeded + build system.</p><p>Depending on whether the Yocto Project has a pre-built image that matches your target + architecture and where you are going to run the image while you develop your application + (QEMU or real hardware), the area from which you get the image differs. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Download the image from + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top"> + <code class="filename">machines</code></a> if your target architecture is supported + and you are going to develop and test your application on actual hardware. + </p></li><li class="listitem"><p>Download the image from the + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top"> + <code class="filename">machines/qemu</code></a> if your target architecture is supported + and you are going to develop and test your application using the QEMU + emulator.</p></li><li class="listitem"><p>Build your image if you cannot find a pre-built image that matches + your target architecture. + If your target architecture is similar to a supported architecture, you can + modify the kernel image before you build it. + See the + "<a class="link" href="#kernel-modification-workflow" title="5.1.2.2. Kernel Modification Workflow">Kernel Modification Workflow</a>" + section earlier in this manual for information on how to create a modified + Yocto Project kernel.</p></li></ul></div><p>For information on pre-built kernel image naming schemes for images + that can run on the QEMU emulator, see the + "<a class="link" href="#downloading-the-pre-built-linux-kernel" target="_top">Downloading the Pre-Built Linux Kernel</a>" + section in the Yocto Project Quick Start.</p></li><li class="listitem"><p><span class="emphasis"><em>Install the ADT</em></span>: + The ADT provides a target-specific cross-development toolchain, the root filesystem, + the QEMU emulator, and other tools that can help you develop your application. + While it is possible to get these pieces separately, the ADT Installer provides an + easy method. + You can get these pieces by running an ADT installer script, which is configurable. + For information on how to install the ADT, see the + "<a class="link" href="#using-the-adt-installer" target="_top">Using the ADT Installer</a>" + section + in the Yocto Project Application Developer's Guide.</p></li><li class="listitem"><p><span class="emphasis"><em>If Applicable, Secure the Target Root Filesystem</em></span>: + If you choose not to install the ADT using the ADT Installer, + you need to find and download the + appropriate root filesystems. + You can find these tarballs in the same areas used for the kernel images. + Depending on the type of image you are running, the root filesystem you need differs. + For example, if you are developing an application that runs on an image that + supports Sato, you need to get root filesystem that supports Sato. + </p></li><li class="listitem"><p><span class="emphasis"><em>Create and Build your Application</em></span>: + At this point, you need to have source files for your application. + Once you have the files, you can use the Eclipse IDE to import them and build the + project. + If you are not using Eclipse, you need to use the cross-development tools you have + installed to create the image.</p></li><li class="listitem"><p><span class="emphasis"><em>Deploy the Image with the Application</em></span>: + If you are using the Eclipse IDE, you can deploy your image to the hardware or to + QEMU through the project's preferences. + If you are not using the Eclipse IDE, then you need to deploy the application using + other methods to the hardware. + Or, if you are using QEMU, you need to use that tool and load your image in for testing. + </p></li><li class="listitem"><p><span class="emphasis"><em>Test and Debug the Application</em></span>: + Once your application is deployed, you need to test it. + Within the Eclipse IDE, you can use the debubbing environment along with the + set of user-space tools installed along with the ADT to debug your application. + Of course, the same user-space tools are available separately if you choose + not to use the Eclipse IDE.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2. Working Within Eclipse"><div class="titlepage"><div><div><h3 class="title"><a id="adt-eclipse"></a>5.2.2. Working Within Eclipse</h3></div></div></div><p> + The Eclipse IDE is a popular development environment and it fully supports + development using the Yocto Project. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project supports both the Juno and Indigo versions + of the Eclipse IDE. + Thus, the following information provides setup information for both versions. + </div><p> + </p><p> + When you install and configure the Eclipse Yocto Project Plug-in into + the Eclipse IDE, you maximize your Yocto Project experience. + Installing and configuring the Plug-in results in an environment that + has extensions specifically designed to let you more easily develop software. + These extensions allow for cross-compilation, deployment, and execution of + your output into a QEMU emulation session. + You can also perform cross-debugging and profiling. + The environment also supports a suite of tools that allows you to perform + remote profiling, tracing, collection of power data, collection of + latency data, and collection of performance data. + </p><p> + This section describes how to install and configure the Eclipse IDE + Yocto Plug-in and how to use it to develop your application. + </p><div class="section" title="5.2.2.1. Setting Up the Eclipse IDE"><div class="titlepage"><div><div><h4 class="title"><a id="setting-up-the-eclipse-ide"></a>5.2.2.1. Setting Up the Eclipse IDE</h4></div></div></div><p> + To develop within the Eclipse IDE, you need to do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install the optimal version of the Eclipse IDE.</p></li><li class="listitem"><p>Configure the Eclipse IDE.</p></li><li class="listitem"><p>Install the Eclipse Yocto Plug-in.</p></li><li class="listitem"><p>Configure the Eclipse Yocto Plug-in.</p></li></ol></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Do not install Eclipse from your distribution's package repository. + Be sure to install Eclipse from the official Eclipse download site as directed + in the next section. + </div><p> + </p><div class="section" title="5.2.2.1.1. Installing the Eclipse IDE"><div class="titlepage"><div><div><h5 class="title"><a id="installing-eclipse-ide"></a>5.2.2.1.1. Installing the Eclipse IDE</h5></div></div></div><p> + It is recommended that you have the Juno 4.2 version of the + Eclipse IDE installed on your development system. + However, if you currently have the Indigo 3.7.2 version installed and you do + not want to upgrade the IDE, you can configure Indigo to work with the + Yocto Project. + See the + "<a class="link" href="#configuring-the-eclipse-ide-indigo" title="5.2.2.1.3. Configuring the Eclipse IDE (Indigo)">Configuring the Eclipse IDE (Indigo)</a>" + section. + </p><p> + If you don’t have the Juno 4.2 Eclipse IDE installed, you can find the tarball at + <a class="ulink" href="http://www.eclipse.org/downloads" target="_top">http://www.eclipse.org/downloads</a>. + From that site, choose the Eclipse Classic version particular to your development + host. + This version contains the Eclipse Platform, the Java Development + Tools (JDT), and the Plug-in Development Environment. + </p><p> + Once you have downloaded the tarball, extract it into a clean + directory. + For example, the following commands unpack and install the Eclipse IDE + tarball found in the <code class="filename">Downloads</code> area + into a clean directory using the default name <code class="filename">eclipse</code>: + </p><pre class="literallayout"> + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-SDK-4.2-linux-gtk-x86_64.tar.gz + </pre><p> + </p><p> + If you have the Indigo 3.7.2 Eclipse IDE already installed and you want to use that + version, one issue exists that you need to be aware of regarding the Java + Virtual machine’s garbage collection (GC) process. + The GC process does not clean up the permanent generation + space (PermGen). + This space stores metadata descriptions of classes. + The default value is set too small and it could trigger an + out-of-memory error such as the following: + </p><pre class="literallayout"> + Java.lang.OutOfMemoryError: PermGen space + </pre><p> + </p><p> + This error causes the application to hang. + </p><p> + To fix this issue, you can use the <code class="filename">--vmargs</code> + option when you start the Indigo 3.7.2 Eclipse IDE + to increase the size of the permanent generation space: + </p><pre class="literallayout"> + eclipse --vmargs --XX:PermSize=256M + </pre><p> + </p></div><div class="section" title="5.2.2.1.2. Configuring the Eclipse IDE (Juno)"><div class="titlepage"><div><div><h5 class="title"><a id="configuring-the-eclipse-ide-juno"></a>5.2.2.1.2. Configuring the Eclipse IDE (Juno)</h5></div></div></div><p> + This section presents the steps needed to configure the Juno 4.2 Eclipse IDE. + If you are using Indigo 3.7.2, see the + "<a class="link" href="#configuring-the-eclipse-ide-indigo" title="5.2.2.1.3. Configuring the Eclipse IDE (Indigo)">Configuring the Eclipse IDE (Indigo)</a>". + </p><p> + Before installing and configuring the Eclipse Yocto Plug-in, you need to configure + the Juno 4.2 Eclipse IDE. + Follow these general steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start the Eclipse IDE.</p></li><li class="listitem"><p>Make sure you are in your Workbench and select + "Install New Software" from the "Help" pull-down menu. + </p></li><li class="listitem"><p>Select <code class="filename">Juno - http://download.eclipse.org/releases/juno</code> + from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Expand the box next to "Linux Tools" and select the + "LTTng - Linux Tracing Toolkit" boxes.</p></li><li class="listitem"><p>Expand the box next to "Mobile and Device Development" and select the + following boxes: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">C/C++ Remote Launch</code></p></li><li class="listitem"><p><code class="filename">Remote System Explorer End-user Runtime</code></p></li><li class="listitem"><p><code class="filename">Remote System Explorer User Actions</code></p></li><li class="listitem"><p><code class="filename">Target Management Terminal</code></p></li><li class="listitem"><p><code class="filename">TCF Remote System Explorer add-in</code></p></li><li class="listitem"><p><code class="filename">TCF Target Explorer</code></p></li></ul></div></li><li class="listitem"><p>Expand the box next to <code class="filename">Programming Languages</code> + and select the <code class="filename">Autotools Support for CDT</code> + and <code class="filename">C/C++ Development Tools</code> boxes.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.1.3. Configuring the Eclipse IDE (Indigo)"><div class="titlepage"><div><div><h5 class="title"><a id="configuring-the-eclipse-ide-indigo"></a>5.2.2.1.3. Configuring the Eclipse IDE (Indigo)</h5></div></div></div><p> + This section presents the steps needed to configure the Indigo 3.7.2 Eclipse IDE. + If you are using Juno 4.2, see the + "<a class="link" href="#configuring-the-eclipse-ide-juno" title="5.2.2.1.2. Configuring the Eclipse IDE (Juno)">Configuring the Eclipse IDE (Juno)</a>". + </p><p> + Before installing and configuring the Eclipse Yocto Plug-in, you need to configure + the Indigo 3.7.2 Eclipse IDE. + Follow these general steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start the Eclipse IDE.</p></li><li class="listitem"><p>Make sure you are in your Workbench and select + "Install New Software" from the "Help" pull-down menu. + </p></li><li class="listitem"><p>Select <code class="filename">indigo - http://download.eclipse.org/releases/indigo</code> + from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Expand the box next to <code class="filename">Programming Languages</code> + and select the <code class="filename">Autotools Support for CDT (incubation)</code> + and <code class="filename">C/C++ Development Tools</code> boxes.</p></li><li class="listitem"><p>Expand the box next to "Linux Tools" and select the + "LTTng - Linux Tracing Toolkit(incubation)" boxes.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li><li class="listitem"><p>After the Eclipse IDE restarts and from the Workbench, select + "Install New Software" from the "Help" pull-down menu.</p></li><li class="listitem"><p>Click the + "Available Software Sites" link.</p></li><li class="listitem"><p>Check the box next to + <code class="filename">http://download.eclipse.org/tm/updates/3.3</code> + and click "OK".</p></li><li class="listitem"><p>Select <code class="filename">http://download.eclipse.org/tm/updates/3.3</code> + from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Check the box next to <code class="filename">TM and RSE Main Features</code>. + </p></li><li class="listitem"><p>Expand the box next to <code class="filename">TM and RSE Optional Add-ons</code> + and select every item except <code class="filename">RSE Unit Tests</code> and + <code class="filename">RSE WinCE Services (incubation)</code>.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li><li class="listitem"><p>If necessary, select + "Install New Software" from the "Help" pull-down menu so you can click the + "Available Software Sites" link again.</p></li><li class="listitem"><p>After clicking "Available Software Sites", check the box next to + <code class="filename">http://download.eclipse.org/tools/cdt/releases/indigo</code> + and click "OK".</p></li><li class="listitem"><p>Select <code class="filename">http://download.eclipse.orgtools/cdt/releases/indigo</code> + from the "Work with:" pull-down menu.</p></li><li class="listitem"><p>Check the box next to <code class="filename">CDT Main Features</code>. + </p></li><li class="listitem"><p>Expand the box next to <code class="filename">CDT Optional Features</code> + and select <code class="filename">C/C++ Remote Launch</code> and + <code class="filename">Target Communication Framework (incubation)</code>.</p></li><li class="listitem"><p>Complete the installation and restart the Eclipse IDE.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.1.4. Installing or Accessing the Eclipse Yocto Plug-in"><div class="titlepage"><div><div><h5 class="title"><a id="installing-the-eclipse-yocto-plug-in"></a>5.2.2.1.4. Installing or Accessing the Eclipse Yocto Plug-in</h5></div></div></div><p> + You can install the Eclipse Yocto Plug-in into the Eclipse IDE + one of two ways: use the Yocto Project's Eclipse Update site to install the pre-built plug-in, + or build and install the plug-in from the latest source code. + If you don't want to permanently install the plug-in but just want to try it out + within the Eclipse environment, you can import the plug-in project from the + Yocto Project source repositories. + </p><div class="section" title="5.2.2.1.4.1. Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site"><div class="titlepage"><div><div><h6 class="title"><a id="new-software"></a>5.2.2.1.4.1. Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</h6></div></div></div><p> + To install the Eclipse Yocto Plug-in from the update site, + follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Start up the Eclipse IDE.</p></li><li class="listitem"><p>In Eclipse, select "Install New Software" from the "Help" menu.</p></li><li class="listitem"><p>Click "Add..." in the "Work with:" area.</p></li><li class="listitem"><p>Enter + <code class="filename">http://downloads.yoctoproject.org/releases/eclipse-plugin/1.3</code> + in the URL field and provide a meaningful name in the "Name" field.</p></li><li class="listitem"><p>Click "OK" to have the entry added to the "Work with:" + drop-down list.</p></li><li class="listitem"><p>Select the entry for the plug-in from the "Work with:" drop-down + list.</p></li><li class="listitem"><p>Check the box next to <code class="filename">Development tools and SDKs for Yocto Linux</code>. + </p></li><li class="listitem"><p>Complete the remaining software installation steps and + then restart the Eclipse IDE to finish the installation of the plug-in. + </p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.1.4.2. Installing the Plug-in Using the Latest Source Code"><div class="titlepage"><div><div><h6 class="title"><a id="zip-file-method"></a>5.2.2.1.4.2. Installing the Plug-in Using the Latest Source Code</h6></div></div></div><p> + To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Open a shell and create a Git repository with: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse + </pre><p> + For this example, the repository is named + <code class="filename">~/yocto-eclipse</code>.</p></li><li class="listitem"><p>Locate the <code class="filename">build.sh</code> script in the + Git repository you created in the previous step. + The script is located in the <code class="filename">scripts</code>.</p></li><li class="listitem"><p>Be sure to set and export the <code class="filename">ECLIPSE_HOME</code> environment + variable to the top-level directory in which you installed the Indigo + version of Eclipse. + For example, if your Eclipse directory is <code class="filename">$HOME/eclipse</code>, + use the following: + </p><pre class="literallayout"> + $ export ECLIPSE_HOME=$HOME/eclipse + </pre></li><li class="listitem"><p>Run the <code class="filename">build.sh</code> script and provide the + name of the Git branch along with the Yocto Project release you are + using. + Here is an example that uses the <code class="filename">master</code> Git repository + and the <code class="filename">1.1M4</code> release: + </p><pre class="literallayout"> + $ scripts/build.sh master 1.1M4 + </pre><p> + After running the script, the file + <code class="filename">org.yocto.sdk-<release>-<date>-archive.zip</code> + is in the current directory.</p></li><li class="listitem"><p>If necessary, start the Eclipse IDE and be sure you are in the + Workbench.</p></li><li class="listitem"><p>Select "Install New Software" from the "Help" pull-down menu. + </p></li><li class="listitem"><p>Click "Add".</p></li><li class="listitem"><p>Provide anything you want in the "Name" field.</p></li><li class="listitem"><p>Click "Archive" and browse to the ZIP file you built + in step four. + This ZIP file should not be "unzipped", and must be the + <code class="filename">*archive.zip</code> file created by running the + <code class="filename">build.sh</code> script.</p></li><li class="listitem"><p>Check the box next to the new entry in the installation window and complete + the installation.</p></li><li class="listitem"><p>Restart the Eclipse IDE if necessary.</p></li></ol></div><p> + </p><p> + At this point you should be able to configure the Eclipse Yocto Plug-in as described in the + "<a class="link" href="#configuring-the-eclipse-yocto-plug-in" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in">Configuring the Eclipse Yocto Plug-in</a>" + section.</p></div><div class="section" title="5.2.2.1.4.3. Importing the Plug-in Project into the Eclipse Environment"><div class="titlepage"><div><div><h6 class="title"><a id="yocto-project-source"></a>5.2.2.1.4.3. Importing the Plug-in Project into the Eclipse Environment</h6></div></div></div><p> + Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories + is useful when you want to try out the latest plug-in from the tip of plug-in's + development tree. + It is important to understand when you import the plug-in you are not installing + it into the Eclipse application. + Rather, you are importing the project and just using it. + To import the plug-in project, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Open a shell and create a Git repository with: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse + </pre><p> + For this example, the repository is named + <code class="filename">~/yocto-eclipse</code>.</p></li><li class="listitem"><p>In Eclipse, select "Import" from the "File" menu.</p></li><li class="listitem"><p>Expand the "General" box and select "existing projects into workspace" + and then click "Next".</p></li><li class="listitem"><p>Select the root directory and browse to + <code class="filename">~/yocto-eclipse/plugins</code>.</p></li><li class="listitem"><p>Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and + "org.yocto.sdk.remotetools". + Select and import all of them.</p></li></ol></div><p> + </p><p> + The left navigation pane in the Eclipse application shows the default projects. + Right-click on one of these projects and run it as an Eclipse application. + This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. + </p></div></div><div class="section" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in"><div class="titlepage"><div><div><h5 class="title"><a id="configuring-the-eclipse-yocto-plug-in"></a>5.2.2.1.5. Configuring the Eclipse Yocto Plug-in</h5></div></div></div><p> + Configuring the Eclipse Yocto Plug-in involves setting the Cross + Compiler options and the Target options. + The configurations you choose become the default settings for all projects. + You do have opportunities to change them later when + you configure the project (see the following section). + </p><p> + To start, you need to do the following from within the Eclipse IDE: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Choose <code class="filename">Windows -> Preferences</code> to display + the <code class="filename">Preferences</code> Dialog</p></li><li class="listitem"><p>Click <code class="filename">Yocto Project ADT</code></p></li></ul></div><p> + </p><div class="section" title="5.2.2.1.5.1. Configuring the Cross-Compiler Options"><div class="titlepage"><div><div><h6 class="title"><a id="configuring-the-cross-compiler-options"></a>5.2.2.1.5.1. Configuring the Cross-Compiler Options</h6></div></div></div><p> + To configure the Cross Compiler Options, you must select the type of toolchain, + point to the toolchain, specify the sysroot location, and select the target architecture. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Selecting the Toolchain Type:</em></span> + Choose between <code class="filename">Standalone pre-built toolchain</code> + and <code class="filename">Build system derived toolchain</code> for Cross + Compiler Options. + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em> + <code class="filename">Standalone Pre-built Toolchain:</code></em></span> + Select this mode when you are using a stand-alone cross-toolchain. + For example, suppose you are an application developer and do not + need to build a target image. + Instead, you just want to use an architecture-specific toolchain on an + existing kernel and target root filesystem. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <code class="filename">Build System Derived Toolchain:</code></em></span> + Select this mode if the cross-toolchain has been installed and built + as part of the build directory. + When you select <code class="filename">Build system derived toolchain</code>, + you are using the toolchain bundled + inside the build directory. + </p></li></ul></div><p> + </p></li><li class="listitem"><p><span class="emphasis"><em>Point to the Toolchain:</em></span> + If you are using a stand-alone pre-built toolchain, you should be pointing to the + <code class="filename">/opt/poky/1.3</code> directory. + This is the location for toolchains installed by the ADT Installer or by hand. + Sections "<a class="link" href="#configuring-and-running-the-adt-installer-script" target="_top">Configuring + and Running the ADT Installer Script</a>" and + "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" + in the Yocto Project Application Developer's Guide + describe two ways to install a stand-alone cross-toolchain in the + <code class="filename">/opt/poky</code> directory. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>It is possible to install a stand-alone cross-toolchain in a directory + other than <code class="filename">/opt/poky</code>. + However, doing so is discouraged.</div><p>If you are using a system-derived toolchain, the path you provide + for the <code class="filename">Toolchain Root Location</code> + field is the build directory. + See the "<a class="link" href="#using-the-toolchain-from-within-the-build-tree" target="_top">Using + BitBake and the build directory</a>" section in the Yocto Project Application + Developer's Guide for information on how to install the toolchain into the build +directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Specify the Sysroot Location:</em></span> + This location is where the root filesystem for the + target hardware is created on the development system by the ADT Installer. + The QEMU user-space tools, the + NFS boot process, and the cross-toolchain all use the sysroot location. + </p></li><li class="listitem"><p><span class="emphasis"><em>Select the Target Architecture:</em></span> + The target architecture is the type of hardware you are + going to use or emulate. + Use the pull-down <code class="filename">Target Architecture</code> menu to make + your selection. + The pull-down menu should have the supported architectures. + If the architecture you need is not listed in the menu, you + will need to build the image. + See the "<a class="link" href="#building-image" target="_top">Building an Image</a>" section + of the Yocto Project Quick Start for more information.</p></li></ul></div><p> + </p></div><div class="section" title="5.2.2.1.5.2. Configuring the Target Options"><div class="titlepage"><div><div><h6 class="title"><a id="configuring-the-target-options"></a>5.2.2.1.5.2. Configuring the Target Options</h6></div></div></div><p> + You can choose to emulate hardware using the QEMU emulator, or you + can choose to run your image on actual hardware. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">QEMU:</code></em></span> Select this option if + you will be using the QEMU emulator. + If you are using the emulator, you also need to locate the kernel + and specify any custom options.</p><p>If you selected <code class="filename">Build system derived toolchain</code>, + the target kernel you built will be located in the + build directory in <code class="filename">tmp/deploy/images</code> directory. + If you selected <code class="filename">Standalone pre-built toolchain</code>, the + pre-built image you downloaded is located + in the directory you specified when you downloaded the image.</p><p>Most custom options are for advanced QEMU users to further + customize their QEMU instance. + These options are specified between paired angled brackets. + Some options must be specified outside the brackets. + In particular, the options <code class="filename">serial</code>, + <code class="filename">nographic</code>, and <code class="filename">kvm</code> must all + be outside the brackets. + Use the <code class="filename">man qemu</code> command to get help on all the options + and their use. + The following is an example: + </p><pre class="literallayout"> + serial ‘<-m 256 -full-screen>’ + </pre><p> + Regardless of the mode, Sysroot is already defined as part of the + Cross Compiler Options configuration in the + <code class="filename">Sysroot Location:</code> field.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">External HW:</code></em></span> Select this option + if you will be using actual hardware.</p></li></ul></div><p> + </p><p> + Click the <code class="filename">OK</code> button to save your plug-in configurations. + </p></div></div></div><div class="section" title="5.2.2.2. Creating the Project"><div class="titlepage"><div><div><h4 class="title"><a id="creating-the-project"></a>5.2.2.2. Creating the Project</h4></div></div></div><p> + You can create two types of projects: Autotools-based, or Makefile-based. + This section describes how to create Autotools-based projects from within + the Eclipse IDE. + For information on creating Makefile-based projects in a terminal window, see the section + "<a class="link" href="#using-the-command-line" target="_top">Using the Command Line</a>" + in the Yocto Project Application Developer's Guide. + </p><p> + To create a project based on a Yocto template and then display the source code, + follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">File -> New -> Project</code>.</p></li><li class="listitem"><p>Double click <code class="filename">CC++</code>.</p></li><li class="listitem"><p>Double click <code class="filename">C Project</code> to create the project.</p></li><li class="listitem"><p>Expand <code class="filename">Yocto Project ADT Project</code>.</p></li><li class="listitem"><p>Select <code class="filename">Hello World ANSI C Autotools Project</code>. + This is an Autotools-based project based on a Yocto template.</p></li><li class="listitem"><p>Put a name in the <code class="filename">Project name:</code> field. + Do not use hyphens as part of the name.</p></li><li class="listitem"><p>Click <code class="filename">Next</code>.</p></li><li class="listitem"><p>Add information in the <code class="filename">Author</code> and + <code class="filename">Copyright notice</code> fields.</p></li><li class="listitem"><p>Be sure the <code class="filename">License</code> field is correct.</p></li><li class="listitem"><p>Click <code class="filename">Finish</code>.</p></li><li class="listitem"><p>If the "open perspective" prompt appears, click "Yes" so that you + in the C/C++ perspective.</p></li><li class="listitem"><p>The left-hand navigation pane shows your project. + You can display your source by double clicking the project's source file. + </p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.3. Configuring the Cross-Toolchains"><div class="titlepage"><div><div><h4 class="title"><a id="configuring-the-cross-toolchains"></a>5.2.2.3. Configuring the Cross-Toolchains</h4></div></div></div><p> + The earlier section, "<a class="link" href="#configuring-the-eclipse-yocto-plug-in" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in">Configuring + the Eclipse Yocto Plug-in</a>", sets up the default project + configurations. + You can override these settings for a given project by following these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">Project -> Change Yocto Project Settings</code>: + This selection brings up the <code class="filename">Yocot Project Settings</code> Dialog + and allows you to make changes specific to an individual project. + </p><p>By default, the Cross Compiler Options and Target Options for a project + are inherited from settings you provide using the <code class="filename">Preferences</code> + Dialog as described earlier + in the "<a class="link" href="#configuring-the-eclipse-yocto-plug-in" title="5.2.2.1.5. Configuring the Eclipse Yocto Plug-in">Configuring the Eclipse + Yocto Plug-in</a>" section. + The <code class="filename">Yocto Project Settings</code> + Dialog allows you to override those default settings + for a given project.</p></li><li class="listitem"><p>Make your configurations for the project and click "OK".</p></li><li class="listitem"><p>Select <code class="filename">Project -> Reconfigure Project</code>: + This selection reconfigures the project by running + <code class="filename">autogen.sh</code> in the workspace for your project. + The script also runs <code class="filename">libtoolize</code>, <code class="filename">aclocal</code>, + <code class="filename">autoconf</code>, <code class="filename">autoheader</code>, + <code class="filename">automake --a</code>, and + <code class="filename">./configure</code>. + Click on the <code class="filename">Console</code> tab beneath your source code to + see the results of reconfiguring your project.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.4. Building the Project"><div class="titlepage"><div><div><h4 class="title"><a id="building-the-project"></a>5.2.2.4. Building the Project</h4></div></div></div><p> + To build the project, select <code class="filename">Project -> Build Project</code>. + The console should update and you can note the cross-compiler you are using. + </p></div><div class="section" title="5.2.2.5. Starting QEMU in User Space NFS Mode"><div class="titlepage"><div><div><h4 class="title"><a id="starting-qemu-in-user-space-nfs-mode"></a>5.2.2.5. Starting QEMU in User Space NFS Mode</h4></div></div></div><p> + To start the QEMU emulator from within Eclipse, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Expose the <code class="filename">Run -> External Tools</code> menu. + Your image should appear as a selectable menu item. + </p></li><li class="listitem"><p>Select your image from the menu to launch the + emulator in a new window.</p></li><li class="listitem"><p>If needed, enter your host root password in the shell window at the prompt. + This sets up a <code class="filename">Tap 0</code> connection needed for running in user-space + NFS mode.</p></li><li class="listitem"><p>Wait for QEMU to launch.</p></li><li class="listitem"><p>Once QEMU launches, you can begin operating within that + environment. + For example, you could determine the IP Address + for the user-space NFS by using the <code class="filename">ifconfig</code> command. + </p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.6. Deploying and Debugging the Application"><div class="titlepage"><div><div><h4 class="title"><a id="deploying-and-debugging-the-application"></a>5.2.2.6. Deploying and Debugging the Application</h4></div></div></div><p> + Once the QEMU emulator is running the image, using the Eclipse IDE + you can deploy your application and use the emulator to perform debugging. + Follow these steps to deploy the application. + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">Run -> Debug Configurations...</code></p></li><li class="listitem"><p>In the left area, expand <code class="filename">C/C++Remote Application</code>.</p></li><li class="listitem"><p>Locate your project and select it to bring up a new + tabbed view in the <code class="filename">Debug Configurations</code> Dialog.</p></li><li class="listitem"><p>Enter the absolute path into which you want to deploy + the application. + Use the <code class="filename">Remote Absolute File Path for C/C++Application:</code> field. + For example, enter <code class="filename">/usr/bin/<programname></code>.</p></li><li class="listitem"><p>Click on the <code class="filename">Debugger</code> tab to see the cross-tool debugger + you are using.</p></li><li class="listitem"><p>Click on the <code class="filename">Main</code> tab.</p></li><li class="listitem"><p>Create a new connection to the QEMU instance + by clicking on <code class="filename">new</code>.</p></li><li class="listitem"><p>Select <code class="filename">TCF</code>, which means Target Communication + Framework.</p></li><li class="listitem"><p>Click <code class="filename">Next</code>.</p></li><li class="listitem"><p>Clear out the <code class="filename">host name</code> field and enter the IP Address + determined earlier.</p></li><li class="listitem"><p>Click <code class="filename">Finish</code> to close the + <code class="filename">New Connections</code> Dialog.</p></li><li class="listitem"><p>Use the drop-down menu now in the <code class="filename">Connection</code> field and pick + the IP Address you entered.</p></li><li class="listitem"><p>Click <code class="filename">Debug</code> to bring up a login screen + and login.</p></li><li class="listitem"><p>Accept the debug perspective.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.7. Running User-Space Tools"><div class="titlepage"><div><div><h4 class="title"><a id="running-user-space-tools"></a>5.2.2.7. Running User-Space Tools</h4></div></div></div><p> + As mentioned earlier in the manual, several tools exist that enhance + your development experience. + These tools are aids in developing and debugging applications and images. + You can run these user-space tools from within the Eclipse IDE through the + <code class="filename">YoctoTools</code> menu. + </p><p> + Once you pick a tool, you need to configure it for the remote target. + Every tool needs to have the connection configured. + You must select an existing TCF-based RSE connection to the remote target. + If one does not exist, click <code class="filename">New</code> to create one. + </p><p> + Here are some specifics about the remote tools: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">OProfile</code>:</em></span> Selecting this tool causes + the <code class="filename">oprofile-server</code> on the remote target to launch on + the local host machine. + The <code class="filename">oprofile-viewer</code> must be installed on the local host machine and the + <code class="filename">oprofile-server</code> must be installed on the remote target, + respectively, in order to use. + You must compile and install the <code class="filename">oprofile-viewer</code> from the source code + on your local host machine. + Furthermore, in order to convert the target's sample format data into a form that the + host can use, you must have <code class="filename">oprofile</code> version 0.9.4 or + greater installed on the host.</p><p>You can locate both the viewer and server from + <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/oprofileui/" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/oprofileui/</a>. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The <code class="filename">oprofile-server</code> is installed by default on + the <code class="filename">core-image-sato-sdk</code> image.</div></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">Lttng-ust</code>:</em></span> Selecting this tool runs + <code class="filename">usttrace</code> on the remote target, transfers the output data back + to the local host machine, and uses the <code class="filename">lttng</code> Eclipse plug-in to + graphically display the output. + For information on how to use <code class="filename">lttng</code> to trace an application, see + <a class="ulink" href="http://lttng.org/files/ust/manual/ust.html" target="_top">http://lttng.org/files/ust/manual/ust.html</a>.</p><p>For <code class="filename">Application</code>, you must supply the absolute path name of the + application to be traced by user mode <code class="filename">lttng</code>. + For example, typing <code class="filename">/path/to/foo</code> triggers + <code class="filename">usttrace /path/to/foo</code> on the remote target to trace the + program <code class="filename">/path/to/foo</code>.</p><p><code class="filename">Argument</code> is passed to <code class="filename">usttrace</code> + running on the remote target.</p><p>Before you use the <code class="filename">lttng-ust</code> tool, you need to setup + the <code class="filename">lttng</code> Eclipse plug-in and create a <code class="filename">lttng</code> + project. + Do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Follow these + <a class="ulink" href="http://wiki.eclipse.org/Linux_Tools_Project/LTTng#Downloading_and_installing_the_LTTng_parser_library" target="_top">instructions</a> + to download and install the <code class="filename">lttng</code> parser library. + </p></li><li class="listitem"><p>Select <code class="filename">Window -> Open Perspective -> Other</code> + and then select <code class="filename">LTTng</code>.</p></li><li class="listitem"><p>Click <code class="filename">OK</code> to change the Eclipse perspective + into the <code class="filename">LTTng</code> perspective.</p></li><li class="listitem"><p>Create a new <code class="filename">LTTng</code> project by selecting + <code class="filename">File -> New -> Project</code>.</p></li><li class="listitem"><p>Choose <code class="filename">LTTng -> LTTng Project</code>.</p></li><li class="listitem"><p>Click <code class="filename">YoctoTools -> lttng-ust</code> to start user mode + <code class="filename">lttng</code> on the remote target.</p></li></ol></div><p>After the output data has been transferred from the remote target back to the local + host machine, new traces will be imported into the selected <code class="filename">LTTng</code> project. + Then you can go to the <code class="filename">LTTng</code> project, right click the imported + trace, and set the trace type as the <code class="filename">LTTng</code> kernel trace. + Finally, right click the imported trace and select <code class="filename">Open</code> + to display the data graphically.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">PowerTOP</code>:</em></span> Selecting this tool runs + <code class="filename">powertop</code> on the remote target machine and displays the results in a + new view called <code class="filename">powertop</code>.</p><p><code class="filename">Time to gather data(sec):</code> is the time passed in seconds before data + is gathered from the remote target for analysis.</p><p><code class="filename">show pids in wakeups list:</code> corresponds to the + <code class="filename">-p</code> argument + passed to <code class="filename">powertop</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">LatencyTOP and Perf</code>:</em></span> + <code class="filename">latencytop</code> identifies system latency, while + <code class="filename">perf</code> monitors the system's + performance counter registers. + Selecting either of these tools causes an RSE terminal view to appear + from which you can run the tools. + Both tools refresh the entire screen to display results while they run.</p></li></ul></div><p> + </p></div><div class="section" title="5.2.2.8. Customizing an Image Using a BitBake Commander Project and Hob"><div class="titlepage"><div><div><h4 class="title"><a id="customizing-an-image-using-a-bitbake-commander-project-and-hob"></a>5.2.2.8. Customizing an Image Using a BitBake Commander Project and Hob</h4></div></div></div><p> + Within Eclipse, you can create a Yocto BitBake Commander project, + edit the metadata, and then use the + <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> to build a customized + image all within one IDE. + </p><div class="section" title="5.2.2.8.1. Creating the Yocto BitBake Commander Project"><div class="titlepage"><div><div><h5 class="title"><a id="creating-the-yocto-bitbake-commander-project"></a>5.2.2.8.1. Creating the Yocto BitBake Commander Project</h5></div></div></div><p> + To create a Yocto BitBake Commander project, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select <code class="filename">Window -> Open Perspective -> Other</code> + and then choose <code class="filename">Bitbake Commander</code>.</p></li><li class="listitem"><p>Click <code class="filename">OK</code> to change the Eclipse perspective into the + Bitbake Commander perspective.</p></li><li class="listitem"><p>Select <code class="filename">File -> New -> Project</code> to create a new Yocto + Bitbake Commander project.</p></li><li class="listitem"><p>Choose <code class="filename">Yocto Project Bitbake Commander -> New Yocto Project</code> + and click <code class="filename">Next</code>.</p></li><li class="listitem"><p>Enter the Project Name and choose the Project Location. + The Yocto project's metadata files will be put under the directory + <code class="filename"><project_location>/<project_name></code>. + If that directory does not exist, you need to check + the "Clone from Yocto Git Repository" box, which would execute a + <code class="filename">git clone</code> command to get the project's metadata files. + </p></li><li class="listitem"><p>Select <code class="filename">Finish</code> to create the project.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.8.2. Editing the Metadata Files"><div class="titlepage"><div><div><h5 class="title"><a id="editing-the-metadata-files"></a>5.2.2.8.2. Editing the Metadata Files</h5></div></div></div><p> + After you create the Yocto Bitbake Commander project, you can modify the metadata files + by opening them in the project. + When editing recipe files (<code class="filename">.bb</code> files), you can view BitBake + variable values and information by hovering the mouse pointer over the variable name and + waiting a few seconds. + </p><p> + To edit the metadata, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select your Yocto Bitbake Commander project.</p></li><li class="listitem"><p>Select <code class="filename">File -> New -> Yocto BitBake Commander -> BitBake Recipe</code> + to open a new recipe wizard.</p></li><li class="listitem"><p>Point to your source by filling in the "SRC_URL" field. + For example, you can add a recipe to your + <a class="link" href="#source-directory" target="_top">source directory</a> + by defining "SRC_URL" as follows: + </p><pre class="literallayout"> + ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz + </pre></li><li class="listitem"><p>Click "Populate" to calculate the archive md5, sha256, + license checksum values and to auto-generate the recipe filename.</p></li><li class="listitem"><p>Fill in the "Description" field.</p></li><li class="listitem"><p>Be sure values for all required fields exist.</p></li><li class="listitem"><p>Click <code class="filename">Finish</code>.</p></li></ol></div><p> + </p></div><div class="section" title="5.2.2.8.3. Building and Customizing the Image"><div class="titlepage"><div><div><h5 class="title"><a id="buiding-and-customizing-the-image"></a>5.2.2.8.3. Building and Customizing the Image</h5></div></div></div><p> + To build and customize the image in Eclipse, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Select your Yocto Bitbake Commander project.</p></li><li class="listitem"><p>Select <code class="filename">Project -> Launch HOB</code>.</p></li><li class="listitem"><p>Enter the build directory where you want to put your final images.</p></li><li class="listitem"><p>Click <code class="filename">OK</code> to launch Hob.</p></li><li class="listitem"><p>Use Hob to customize and build your own images. + For information on Hob, see the + <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob Project Page</a> on the + Yocto Project website.</p></li></ol></div><p> + </p></div></div></div><div class="section" title="5.2.3. Workflow Using Stand-alone Cross-development Toolchains"><div class="titlepage"><div><div><h3 class="title"><a id="workflow-using-stand-alone-cross-development-toolchains"></a>5.2.3. Workflow Using Stand-alone Cross-development Toolchains</h3></div></div></div><p> + If you want to develop an application without prior installation of the ADT, you + still can employ the cross-development toolchain, the QEMU emulator, and a number of supported + target image files. + You just need to follow these general steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Install the cross-development toolchain for your target hardware:</em></span> + For information on how to install the toolchain, see the + "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" + section + in the Yocto Project Application Developer's Guide.</p></li><li class="listitem"><p><span class="emphasis"><em>Download the Target Image:</em></span> The Yocto Project supports + several target architectures and has many pre-built kernel images and root filesystem + images.</p><p>If you are going to develop your application on hardware, go to the + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top"><code class="filename">machines</code></a> + download area and choose a target machine area + from which to download the kernel image and root filesystem. + This download area could have several files in it that support development using + actual hardware. + For example, the area might contain <code class="filename">.hddimg</code> files that combine the + kernel image with the filesystem, boot loaders, etc. + Be sure to get the files you need for your particular development process.</p><p>If you are going to develop your application and then run and test it using the QEMU + emulator, go to the + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/qemu" target="_top"><code class="filename">machines/qemu</code></a> + download area. + From this area, go down into the directory for your target architecture + (e.g. <code class="filename">qemux86_64</code> for an + <span class="trademark">Intel</span>®-based 64-bit architecture). + Download kernel, root filesystem, and any other files you need for your process. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>In order to use the root filesystem in QEMU, you need to extract it. + See the + "<a class="link" href="#extracting-the-root-filesystem" target="_top">Extracting the Root Filesystem</a>" + section for information on how to extract the root filesystem.</div></li><li class="listitem"><p><span class="emphasis"><em>Develop and Test your Application:</em></span> At this point, + you have the tools to develop your application. + If you need to separately install and use the QEMU emulator, you can go to + <a class="ulink" href="http://www.qemu.org" target="_top">QEMU Home Page</a> to download and learn about the + emulator.</p></li></ol></div><p> + </p></div></div><div class="section" title="5.3. Modifying Temporary Source Code"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="modifying-temporary-source-code"></a>5.3. Modifying Temporary Source Code</h2></div></div></div><p> + You might + find it helpful during development to modify the temporary source code used by recipes + to build packages. + For example, suppose you are developing a patch and you need to experiment a bit + to figure out your solution. + After you have initially built the package, you can iteratively tweak the + source code, which is located in the + <a class="link" href="#build-directory">build directory</a>, and then + you can force a re-compile and quickly test your altered code. + Once you settle on a solution, you can then preserve your changes in the form of + patches. + You can accomplish these steps all within either a + <a class="ulink" href="http://savannah.nongnu.org/projects/quilt" target="_top">Quilt</a> or + <a class="link" href="#git" title="3.6. Git">Git</a> workflow. + </p><div class="section" title="5.3.1. Finding the Temporary Source Code"><div class="titlepage"><div><div><h3 class="title"><a id="finding-the-temporary-source-code"></a>5.3.1. Finding the Temporary Source Code</h3></div></div></div><p> + During a build, the unpacked temporary source code used by recipes + to build packages is available in the build directory as + defined by the + <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> variable. + Below is the default value for the <code class="filename">S</code> variable as defined in the + <code class="filename">meta/conf/bitbake.conf</code> configuration file in the + <a class="link" href="#source-directory">source directory</a>: + </p><pre class="literallayout"> + S = ${WORKDIR}/${BP} + </pre><p> + You should be aware that many recipes override the <code class="filename">S</code> variable. + For example, recipes that fetch their source from Git usually set + <code class="filename">S</code> to <code class="filename">${WORKDIR}/git</code>. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><code class="filename">BP</code> represents the "Base Package", which is the base package + name and the package version: + <pre class="literallayout"> + BP = ${BPN}-${PV} + </pre></div><p> + </p><p> + The path to the work directory for the recipe + (<a class="link" href="#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>) depends + on the package name and the architecture of the target device. + For example, here is the work directory for packages whose targets are not device-dependent: + </p><pre class="literallayout"> + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + </pre><p> + Let's look at an example without variables. + Assuming a top-level source directory named <code class="filename">poky</code> + and a default build directory of <code class="filename">poky/build</code>, + the following is the work directory for the <code class="filename">acl</code> package: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 + </pre><p> + </p><p> + If your package is dependent on the target device, the work directory varies slightly: + </p><pre class="literallayout"> + ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + </pre><p> + Again, assuming top-level source directory named <code class="filename">poky</code> + and a default build directory of <code class="filename">poky/build</code>, the + following is the work directory for the <code class="filename">acl</code> package that is being + built for a MIPS-based device: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + To better understand how the OpenEmbedded build system resolves directories during the + build process, see the glossary entries for the + <a class="link" href="#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>, + <a class="link" href="#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a>, + <a class="link" href="#var-TOPDIR" target="_top"><code class="filename">TOPDIR</code></a>, + <a class="link" href="#var-PACKAGE_ARCH" target="_top"><code class="filename">PACKAGE_ARCH</code></a>, + <a class="link" href="#var-TARGET_OS" target="_top"><code class="filename">TARGET_OS</code></a>, + <a class="link" href="#var-PN" target="_top"><code class="filename">PN</code></a>, + <a class="link" href="#var-PV" target="_top"><code class="filename">PV</code></a>, + and + <a class="link" href="#var-PR" target="_top"><code class="filename">PR</code></a> + variables in the Yocto Project Reference Manual. + </div><p> + Now that you know where to locate the directory that has the temporary source code, you can use a + Quilt or Git workflow to make your edits, test the changes, and preserve the + changes in the form of patches. + </p></div><div class="section" title="5.3.2. Using a Quilt Workflow"><div class="titlepage"><div><div><h3 class="title"><a id="using-a-quilt-workflow"></a>5.3.2. Using a Quilt Workflow</h3></div></div></div><p> + <a class="ulink" href="http://savannah.nongnu.org/projects/quilt" target="_top">Quilt</a> + is a powerful tool that allows you to capture source code changes without having + a clean source tree. + This section outlines the typical workflow you can use to modify temporary source code, + test changes, and then preserve the changes in the form of a patch all using Quilt. + </p><p> + Follow these general steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Find the Source Code:</em></span> + The temporary source code used by the OpenEmbedded build system is kept in the + build directory. + See the + "<a class="link" href="#finding-the-temporary-source-code" title="5.3.1. Finding the Temporary Source Code">Finding the Temporary Source Code</a>" + section to learn how to locate the directory that has the temporary source code for a + particular package.</p></li><li class="listitem"><p><span class="emphasis"><em>Change Your Working Directory:</em></span> + You need to be in the directory that has the temporary source code. + That directory is defined by the + <a class="link" href="#var-S" target="_top">S</a> + variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Create a New Patch:</em></span> + Before modifying source code, you need to create a new patch. + To create a new patch file, use <code class="filename">quilt new</code> as below: + </p><pre class="literallayout"> + $ quilt new my_changes.patch + </pre></li><li class="listitem"><p><span class="emphasis"><em>Notify Quilt and Add Files:</em></span> + After creating the patch, you need to notify Quilt about the files you will + be changing. + Add the files you will be modifying into the patch you just created: + </p><pre class="literallayout"> + $ quilt add file1.c file2.c file3.c + </pre></li><li class="listitem"><p><span class="emphasis"><em>Edit the Files:</em></span> + Make the changes to the temporary source code.</p></li><li class="listitem"><p><span class="emphasis"><em>Test Your Changes:</em></span> + Once you have modified the source code, the easiest way to test your changes + is by calling the <code class="filename">compile</code> task as shown in the following example: + </p><pre class="literallayout"> + $ bitbake -c compile -f <name_of_package> + </pre><p> + The <code class="filename">-f</code> or <code class="filename">--force</code> + option forces re-execution of the specified task. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>All the modifications you make to the temporary source code + disappear once you <code class="filename">-c clean</code> or + <code class="filename">-c cleanall</code> with BitBake for the package. + Modifications will also disappear if you use the <code class="filename">rm_work</code> + feature as described in the + "<a class="link" href="#building-image" target="_top">Building an Image</a>" + section of the Yocto Project Quick Start. + </div></li><li class="listitem"><p><span class="emphasis"><em>Generate the Patch:</em></span> + Once your changes work as expected, you need to use Quilt to generate the final patch that + contains all your modifications. + </p><pre class="literallayout"> + $ quilt refresh + </pre><p> + At this point the <code class="filename">my_changes.patch</code> file has all your edits made + to the <code class="filename">file1.c</code>, <code class="filename">file2.c</code>, and + <code class="filename">file3.c</code> files.</p><p>You can find the resulting patch file in the <code class="filename">patches/</code> + subdirectory of the source (<code class="filename">S</code>) directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Copy the Patch File:</em></span> + For simplicity, copy the patch file into a directory named <code class="filename">files</code>, + which you can create in the same directory as the recipe. + Placing the patch here guarantees that the OpenEmbedded build system will find + the patch. + Next, add the patch into the + <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> + of the recipe. + Here is an example: + </p><pre class="literallayout"> + SRC_URI += "file://my_changes.patch" + </pre></li><li class="listitem"><p><span class="emphasis"><em>Increment the Package Revision Number:</em></span> + Finally, don't forget to 'bump' the + <code class="filename"><a class="link" href="#var-PR" target="_top">PR</a></code> + value in the same recipe since the resulting packages have changed.</p></li></ol></div><p> + </p></div><div class="section" title="5.3.3. Using a Git Workflow"><div class="titlepage"><div><div><h3 class="title"><a id="using-a-git-workflow"></a>5.3.3. Using a Git Workflow</h3></div></div></div><p> + Git is an even more powerful tool that allows you to capture source code changes without having + a clean source tree. + This section outlines the typical workflow you can use to modify temporary source code, + test changes, and then preserve the changes in the form of a patch all using Git. + For general information on Git as it is used in the Yocto Project, see the + "<a class="link" href="#git" title="3.6. Git">Git</a>" section. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + This workflow uses Git only for its ability to manage local changes to the source code + and produce patches independent of any version control system used with the Yocto Project. + </div><p> + Follow these general steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Find the Source Code:</em></span> + The temporary source code used by the OpenEmbedded build system is kept in the + build directory. + See the + "<a class="link" href="#finding-the-temporary-source-code" title="5.3.1. Finding the Temporary Source Code">Finding the Temporary Source Code</a>" + section to learn how to locate the directory that has the temporary source code for a + particular package.</p></li><li class="listitem"><p><span class="emphasis"><em>Change Your Working Directory:</em></span> + You need to be in the directory that has the temporary source code. + That directory is defined by the + <a class="link" href="#var-S" target="_top">S</a> + variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Initialize a Git Repository:</em></span> + Use the <code class="filename">git init</code> command to initialize a new local repository + that is based on the work directory: + </p><pre class="literallayout"> + $ git init + </pre></li><li class="listitem"><p><span class="emphasis"><em>Stage all the files:</em></span> + Use the <code class="filename">git add *</code> command to stage all the files in the source + code directory so that they can be committed: + </p><pre class="literallayout"> + $ git add * + </pre></li><li class="listitem"><p><span class="emphasis"><em>Commit the Source Files:</em></span> + Use the <code class="filename">git commit</code> command to initially commit all the files in + the work directory: + </p><pre class="literallayout"> + $ git commit + </pre><p> + At this point, your Git repository is aware of all the source code files. + Any edits you now make to files will be tracked by Git.</p></li><li class="listitem"><p><span class="emphasis"><em>Edit the Files:</em></span> + Make the changes to the temporary source code.</p></li><li class="listitem"><p><span class="emphasis"><em>Test Your Changes:</em></span> + Once you have modified the source code, the easiest way to test your changes + is by calling the <code class="filename">compile</code> task as shown in the following example: + </p><pre class="literallayout"> + $ bitbake -c compile -f <name_of_package> + </pre><p> + The <code class="filename">-f</code> or <code class="filename">--force</code> + option forces re-execution of the specified task. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>All the modifications you make to the temporary source code + disappear once you <code class="filename">-c clean</code> or + <code class="filename">-c cleanall</code> with BitBake for the package. + Modifications will also disappear if you use the <code class="filename">rm_work</code> + feature as described in the + "<a class="link" href="#building-image" target="_top">Building an Image</a>" + section of the Yocto Project Quick Start. + </div></li><li class="listitem"><p><span class="emphasis"><em>See the List of Files You Changed:</em></span> + Use the <code class="filename">git status</code> command to see what files you have actually edited. + The ability to have Git track the files you have changed is an advantage that this + workflow has over the Quilt workflow. + Here is the Git command to list your changed files: + </p><pre class="literallayout"> + $ git status + </pre></li><li class="listitem"><p><span class="emphasis"><em>Stage the Modified Files:</em></span> + Use the <code class="filename">git add</code> command to stage the changed files so they + can be committed as follows: + </p><pre class="literallayout"> + $ git add file1.c file2.c file3.c + </pre></li><li class="listitem"><p><span class="emphasis"><em>Commit the Staged Files and View Your Changes:</em></span> + Use the <code class="filename">git commit</code> command to commit the changes to the + local repository. + Once you have committed the files, you can use the <code class="filename">git log</code> + command to see your changes: + </p><pre class="literallayout"> + $ git commit + $ git log + </pre></li><li class="listitem"><p><span class="emphasis"><em>Generate the Patch:</em></span> + Once the changes are committed, use the <code class="filename">git format-patch</code> + command to generate a patch file: + </p><pre class="literallayout"> + $ git format-patch HEAD~1 + </pre><p> + The <code class="filename">HEAD~1</code> part of the command causes Git to generate the + patch file for the most recent commit.</p><p>At this point, the patch file has all your edits made + to the <code class="filename">file1.c</code>, <code class="filename">file2.c</code>, and + <code class="filename">file3.c</code> files. + You can find the resulting patch file in the current directory. + The patch file ends with <code class="filename">.patch</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Copy the Patch File:</em></span> + For simplicity, copy the patch file into a directory named <code class="filename">files</code>, + which you can create in the same directory as the recipe. + Placing the patch here guarantees that the OpenEmbedded build system will find + the patch. + Next, add the patch into the + <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> + of the recipe. + Here is an example: + </p><pre class="literallayout"> + SRC_URI += "file://my_changes.patch" + </pre></li><li class="listitem"><p><span class="emphasis"><em>Increment the Package Revision Number:</em></span> + Finally, don't forget to 'bump' the + <code class="filename"><a class="link" href="#var-PR" target="_top">PR</a></code> + value in the same recipe since the resulting packages have changed.</p></li></ol></div><p> + </p></div></div><div class="section" title="5.4. Image Development Using Hob"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="image-development-using-hob"></a>5.4. Image Development Using Hob</h2></div></div></div><p> + The <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> is a graphical user interface for the + OpenEmbedded build system, which is based on BitBake. + You can use the Hob to build custom operating system images within the Yocto Project build environment. + Hob simply provides a friendly interface over the build system used during system development. + In other words, building images with the Hob lets you take care of common build tasks more easily. + </p><p> + For a better understanding of Hob, see the project page at + <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">http://www.yoctoproject.org/projects/hob</a> on the Yocto Project website. + The page has a short introductory training video on Hob. + The following lists some features of Hob: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can setup and run Hob using these commands: + </p><pre class="literallayout"> + $ source oe-init-build-env + $ hob + </pre></li><li class="listitem"><p>You can set the + <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> + for which you are building the image.</p></li><li class="listitem"><p>You can modify various policy settings such as the package format used to build with, + the parrallelism BitBake uses, whether or not to build an external toolchain, and which host + to build against.</p></li><li class="listitem"><p>You can manage + <a class="link" href="#understanding-and-creating-layers" title="4.1. Understanding and Creating Layers">layers</a>.</p></li><li class="listitem"><p>You can select a base image and then add extra packages for your custom build. + </p></li><li class="listitem"><p>You can launch and monitor the build from within Hob.</p></li></ul></div><p> + </p></div><div class="section" title="5.5. Using a Development Shell"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="platdev-appdev-devshell"></a>5.5. Using a Development Shell</h2></div></div></div><p> + When debugging certain commands or even when just editing packages, + <code class="filename">devshell</code> can be a useful tool. + When you invoke <code class="filename">devshell</code>, source files are + extracted into your working directory and patches are applied. + Then, a new terminal is opened and you are placed in the working directory. + In the new terminal, all the OpenEmbedded build-related environment variables are + still defined so you can use commands such as <code class="filename">configure</code> and + <code class="filename">make</code>. + The commands execute just as if the OpenEmbedded build system were executing them. + Consequently, working this way can be helpful when debugging a build or preparing + software to be used with the OpenEmbedded build system. + </p><p> + Following is an example that uses <code class="filename">devshell</code> on a target named + <code class="filename">matchbox-desktop</code>: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop -c devshell + </pre><p> + </p><p> + This command opens a terminal with a shell prompt within the OpenEmbedded build environment. + The default shell is xterm. + The following occurs: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">PATH</code> variable includes the + cross-toolchain.</p></li><li class="listitem"><p>The <code class="filename">pkgconfig</code> variables find the correct + <code class="filename">.pc</code> files.</p></li><li class="listitem"><p>The <code class="filename">configure</code> command finds the + Yocto Project site files as well as any other necessary files.</p></li></ul></div><p> + Within this environment, you can run <code class="filename">configure</code> + or <code class="filename">compile</code> commands as if they were being run by + the OpenEmbedded build system itself. + As noted earlier, the working directory also automatically changes to the + source directory (<a class="link" href="#var-S" target="_top"><code class="filename">S</code></a>). + </p><p> + When you are finished, you just exit the shell or close the terminal window. + </p><p> + Because an external shell is launched rather than opening directly into the + original terminal window, it allows easier interaction with BitBake's multiple + threads as well as accomodates a future client/server split. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + It is worth remembering that when using <code class="filename">devshell</code> + you need to use the full compiler name such as <code class="filename">arm-poky-linux-gnueabi-gcc</code> + instead of just using <code class="filename">gcc</code>. + The same applies to other applications such as <code class="filename">binutils</code>, + <code class="filename">libtool</code> and so forth. + BitBake sets up environment variables such as <code class="filename">CC</code> + to assist applications, such as <code class="filename">make</code> to find the correct tools. + </p><p> + It is also worth noting that <code class="filename">devshell</code> still works over + X11 forwarding and similar situations + </p></div></div></div> + + <div class="appendix" title="Appendix A. BSP Development Example"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-bsp-appendix"></a>Appendix A. BSP Development Example</h2></div></div></div><p> + This appendix provides a complete BSP development example. + The example assumes the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>No previous preparation or use of the Yocto Project.</p></li><li class="listitem"><p>Use of the Crown Bay Board Support Package (BSP) as a "base" BSP from + which to work. + The example begins with the Crown Bay BSP as the starting point + but ends by building a new 'atom-pc' BSP, which was based on the Crown Bay BSP. + </p></li><li class="listitem"><p>Shell commands assume <code class="filename">bash</code></p></li><li class="listitem"><p>Example was developed on an Intel-based Core i7 platform running + Ubuntu 10.04 LTS released in April of 2010.</p></li></ul></div><p> +</p><div class="section" title="A.1. Getting Local Source Files and BSP Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="getting-local-yocto-project-files-and-bsp-files"></a>A.1. Getting Local Source Files and BSP Files</h2></div></div></div><p> + You need to have the <a class="link" href="#source-directory">source directory</a> + available on your host system. + You can set up this directory through tarball extraction or by cloning the + <code class="filename">poky</code> Git repository. + The following paragraphs describe both methods. + For additional information, see the bulleted item + "<a class="link" href="#local-yp-release">Yocto Project Release</a>". + </p><p> + As mentioned, one way to set up the source directory is to use Git to clone the + <code class="filename">poky</code> repository. + These commands create a local copy of the Git repository. + By default, the top-level directory of the repository is named <code class="filename">poky</code>: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/poky + $ cd poky + </pre><p> + Alternatively, you can start with the downloaded Poky "1.2+snapshot" tarball. + These commands unpack the tarball into a source directory structure. + By default, the top-level directory of the source directory is named + <code class="filename">poky-1.2+snapshot-8.0</code>: + </p><pre class="literallayout"> + $ tar xfj poky-1.2+snapshot-8.0.tar.bz2 + $ cd poky-1.2+snapshot-8.0 + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you're using the tarball method, you can ignore all the following steps that + ask you to carry out Git operations. + You already have the results of those operations + in the form of the 1.2+snapshot release tarballs. + Consequently, there is nothing left to do other than extract those tarballs into the + proper locations.</p><p>Once you expand the released tarball, you have a snapshot of the Git repository + that represents a specific release. + Fundamentally, this is different than having a local copy of the Poky Git repository. + Given the tarball method, changes you make are building on top of a release. + With the Git repository method you have the ability to track development + and keep changes in revision control. + See the + "<a class="link" href="#repositories-tags-and-branches" title="3.6.1. Repositories, Tags, and Branches">Repositories, Tags, and Branches</a>" section + for more discussion around these differences.</p></div><p> + </p><p> + With the local <code class="filename">poky</code> Git repository set up, + you have all the development branches available to you from which you can work. + Next, you need to be sure that your local repository reflects the exact + release in which you are interested. + From inside the repository you can see the development branches that represent + areas of development that have diverged from the main (master) branch + at some point, such as a branch to track a maintenance release's development. + You can also see the tag names used to mark snapshots of stable releases or + points in the repository. + Use the following commands to list out the branches and the tags in the repository, + respectively. + </p><pre class="literallayout"> + $ git branch -a + $ git tag -l + </pre><p> + For this example, we are going to use the Yocto Project 1.3 Release, which is code + named "1.2+snapshot". + To make sure we have a local area (branch in Git terms) on our machine that + reflects the 1.3 release, we can use the following commands: + </p><pre class="literallayout"> + $ cd ~/poky + $ git fetch --tags + $ git checkout 1.2+snapshot-8.0 -b 1.2+snapshot + Switched to a new branch '1.2+snapshot' + </pre><p> + The <code class="filename">git fetch --tags</code> is somewhat redundant since you just set + up the repository and should have all the tags. + The <code class="filename">fetch</code> command makes sure all the tags are available in your + local repository. + The Git <code class="filename">checkout</code> command with the <code class="filename">-b</code> option + creates a local branch for you named <code class="filename">1.2+snapshot</code>. + Your local branch begins in the same state as the Yocto Project 1.3 released tarball + marked with the <code class="filename">1.2+snapshot-8.0</code> tag in the source repositories. + </p></div><div class="section" title="A.2. Choosing a Base BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="choosing-a-base-bsp-app"></a>A.2. Choosing a Base BSP</h2></div></div></div><p> + For this example, the base BSP is the <span class="trademark">Intel</span>® + <span class="trademark">Atom</span>™ Processor E660 with Intel Platform + Controller Hub EG20T Development Kit, which is otherwise referred to as "Crown Bay." + The BSP layer is <code class="filename">meta-crownbay</code>. + The base BSP is simply the BSP + we will be using as a starting point, so don't worry if you don't actually have Crown Bay + hardware. + The remainder of the example transforms the base BSP into a BSP that should be + able to boot on generic atom-pc (netbook) hardware. + </p><p> + For information on how to choose a base BSP, see + "<a class="link" href="#developing-a-board-support-package-bsp" title="5.1.1. Developing a Board Support Package (BSP)">Developing a Board Support Package (BSP)</a>". + </p></div><div class="section" title="A.3. Getting Your Base BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="getting-your-base-bsp-app"></a>A.3. Getting Your Base BSP</h2></div></div></div><p> + You need to have the base BSP layer on your development system. + Similar to the local <a class="link" href="#source-directory">source directory</a>, + you can get the BSP + layer in a couple of different ways: + download the BSP tarball and extract it, or set up a local Git repository that + has the BSP layers. + You should use the same method that you used to set up the source directory earlier. + See "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Setup</a>" for information on how to get + the BSP files. + </p><p> + This example assumes the BSP layer will be located within a directory named + <code class="filename">meta-intel</code> contained within the <code class="filename">poky</code> + parent directory. + The following steps will automatically create the + <code class="filename">meta-intel</code> directory and the contained + <code class="filename">meta-crownbay</code> starting point in both the Git and the tarball cases. + </p><p> + If you're using the Git method, you could do the following to create + the starting layout after you have made sure you are in the <code class="filename">poky</code> + directory created in the previous steps: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/meta-intel.git + $ cd meta-intel + </pre><p> + Alternatively, you can start with the downloaded Crown Bay tarball. + You can download the 1.2+snapshot version of the BSP tarball from the + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Download</a> page of the + Yocto Project website. + Here is the specific link for the tarball needed for this example: + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/crownbay-noemgd/crownbay-noemgd-1.2+snapshot-8.0.tar.bz2" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines/crownbay-noemgd/crownbay-noemgd-1.2+snapshot-8.0.tar.bz2</a>. + Again, be sure that you are already in the <code class="filename">poky</code> directory + as described previously before installing the tarball: + </p><pre class="literallayout"> + $ tar xfj crownbay-noemgd-1.2+snapshot-8.0.tar.bz2 + $ cd meta-intel + </pre><p> + </p><p> + The <code class="filename">meta-intel</code> directory contains all the metadata + that supports BSP creation. + If you're using the Git method, the following + step will switch to the 1.2+snapshot metadata. + If you're using the tarball method, you already have the correct metadata and can + skip to the next step. + Because <code class="filename">meta-intel</code> is its own Git repository, you will want + to be sure you are in the appropriate branch for your work. + For this example we are going to use the <code class="filename">1.2+snapshot</code> branch. + </p><pre class="literallayout"> + $ git checkout -b 1.2+snapshot origin/1.2+snapshot + Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. + Switched to a new branch '1.2+snapshot' + </pre><p> + </p></div><div class="section" title="A.4. Making a Copy of the Base BSP to Create Your New BSP Layer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app"></a>A.4. Making a Copy of the Base BSP to Create Your New BSP Layer</h2></div></div></div><p> + Now that you have set up the source directory and included the base BSP files, you need to + create a new layer for your BSP. + To create your BSP layer, you simply copy the <code class="filename">meta-crownbay</code> + layer to a new layer. + </p><p> + For this example, the new layer will be named <code class="filename">meta-mymachine</code>. + The name should follow the BSP layer naming convention, which is + <code class="filename">meta-<name></code>. + The following assumes your working directory is <code class="filename">meta-intel</code> + inside your source directory. + To start your new layer, just copy the new layer alongside the existing + BSP layers in the <code class="filename">meta-intel</code> directory: + </p><pre class="literallayout"> + $ cp -a meta-crownbay/ meta-mymachine + </pre><p> + </p></div><div class="section" title="A.5. Making Changes to Your BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="making-changes-to-your-bsp-app"></a>A.5. Making Changes to Your BSP</h2></div></div></div><p> + Right now you have two identical BSP layers with different names: + <code class="filename">meta-crownbay</code> and <code class="filename">meta-mymachine</code>. + You need to change your configurations so that they work for your new BSP and + your particular hardware. + The following sections look at each of these areas of the BSP. + </p><div class="section" title="A.5.1. Changing the BSP Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-bsp-configuration"></a>A.5.1. Changing the BSP Configuration</h3></div></div></div><p> + We will look first at the configurations, which are all done in the layer’s + <code class="filename">conf</code> directory. + </p><p> + First, since in this example the new BSP will not support EMGD, we will get rid of the + <code class="filename">crownbay.conf</code> file and then rename the + <code class="filename">crownbay-noemgd.conf</code> file to <code class="filename">mymachine.conf</code>. + Much of what we do in the configuration directory is designed to help the OpenEmbedded + build system work with the new layer and to be able to find and use the right software. + The following two commands result in a single machine configuration file named + <code class="filename">mymachine.conf</code>. + </p><pre class="literallayout"> + $ rm meta-mymachine/conf/machine/crownbay.conf + $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \ + meta-mymachine/conf/machine/mymachine.conf + </pre><p> + </p><p> + Next, we need to make changes to the <code class="filename">mymachine.conf</code> itself. + The only changes we want to make for this example are to the comment lines. + Changing comments, of course, is never strictly necessary, but it's alway good form to make + them reflect reality as much as possible. + + Here, simply substitute the Crown Bay name with an appropriate name for the BSP + (<code class="filename">mymachine</code> in this case) and change the description to + something that describes your hardware. + </p><p> + Note that inside the <code class="filename">mymachine.conf</code> is the + <code class="filename">PREFERRED_VERSION_linux-yocto</code> statement. + This statement identifies the kernel that the BSP is going to use. + In this case, the BSP is using <code class="filename">linux-yocto</code>, which is the + current Yocto Project kernel based on the Linux 3.2 release. + </p><p> + The next configuration file in the new BSP layer we need to edit is + <code class="filename">meta-mymachine/conf/layer.conf</code>. + This file identifies build information needed for the new layer. + You can see the + "<a class="link" href="#bsp-filelayout-layer" target="_top">Layer Configuration File</a>" section + in The Board Support Packages (BSP) Development Guide for more information on this configuration file. + Basically, we are changing the existing statements to work with our BSP. + </p><p> + The file contains these statements that reference the Crown Bay BSP: + </p><pre class="literallayout"> + BBFILE_COLLECTIONS += "crownbay" + BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" + BBFILE_PRIORITY_crownbay = "6" + + LAYERDEPENDS_crownbay = "intel" + </pre><p> + </p><p> + Simply substitute the machine string name <code class="filename">crownbay</code> + with the new machine name <code class="filename">mymachine</code> to get the following: + </p><pre class="literallayout"> + BBFILE_COLLECTIONS += "mymachine" + BBFILE_PATTERN_mymachine := "^${LAYERDIR}/" + BBFILE_PRIORITY_mymachine = "6" + + LAYERDEPENDS_mymachine = "intel" + </pre><p> + </p></div><div class="section" title="A.5.2. Changing the Recipes in Your BSP"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-recipes-in-your-bsp"></a>A.5.2. Changing the Recipes in Your BSP</h3></div></div></div><p> + Now we will take a look at the recipes in your new layer. + The standard BSP structure has areas for BSP, graphics, core, and kernel recipes. + When you create a BSP, you use these areas for appropriate recipes and append files. + Recipes take the form of <code class="filename">.bb</code> files, while append files take + the form of <code class="filename">.bbappend</code> files. + If you want to leverage the existing recipes the OpenEmbedded build system uses + but change those recipes, you can use <code class="filename">.bbappend</code> files. + All new recipes and append files for your layer must go in the layer’s + <code class="filename">recipes-bsp</code>, <code class="filename">recipes-kernel</code>, + <code class="filename">recipes-core</code>, and + <code class="filename">recipes-graphics</code> directories. + </p><div class="section" title="A.5.2.1. Changing recipes-bsp"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-bsp"></a>A.5.2.1. Changing <code class="filename">recipes-bsp</code></h4></div></div></div><p> + First, let's look at <code class="filename">recipes-bsp</code>. + For this example we are not adding any new BSP recipes. + And, we only need to remove the formfactor we do not want and change the name of + the remaining one that doesn't support EMGD. + These commands take care of the <code class="filename">recipes-bsp</code> recipes: + </p><pre class="literallayout"> + $ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay + $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \ + meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine + </pre><p> + </p></div><div class="section" title="A.5.2.2. Changing recipes-graphics"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-graphics"></a>A.5.2.2. Changing <code class="filename">recipes-graphics</code></h4></div></div></div><p> + Now let's look at <code class="filename">recipes-graphics</code>. + For this example we want to remove anything that supports EMGD and + be sure to rename remaining directories appropriately. + The following commands clean up the <code class="filename">recipes-graphics</code> directory: + </p><pre class="literallayout"> + $ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay + $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \ + meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine + </pre><p> + </p><p> + At this point the <code class="filename">recipes-graphics</code> directory just has files that + support Video Electronics Standards Association (VESA) graphics modes and not EMGD. + </p></div><div class="section" title="A.5.2.3. Changing recipes-core"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-core"></a>A.5.2.3. Changing <code class="filename">recipes-core</code></h4></div></div></div><p> + Now let's look at changes in <code class="filename">recipes-core</code>. + The file <code class="filename">task-core-tools.bbappend</code> in + <code class="filename">recipes-core/tasks</code> appends the similarly named recipe + located in the <a class="link" href="#source-directory">source directory</a> at + <code class="filename">meta/recipes-core/tasks</code>. + The append file in our layer right now is Crown Bay-specific and supports + EMGD and non-EMGD. + Here are the contents of the file: + </p><pre class="literallayout"> + RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap" + RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap" + </pre><p> + </p><p> + The <code class="filename">RRECOMMENDS</code> statements list packages that + extend usability. + The first <code class="filename">RRECOMMENDS</code> statement can be removed, while the + second one can be changed to reflect <code class="filename">meta-mymachine</code>: + </p><pre class="literallayout"> + RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap" + </pre><p> + </p></div><div class="section" title="A.5.2.4. Changing recipes-kernel"><div class="titlepage"><div><div><h4 class="title"><a id="changing-recipes-kernel"></a>A.5.2.4. Changing <code class="filename">recipes-kernel</code></h4></div></div></div><p> + Finally, let's look at <code class="filename">recipes-kernel</code> changes. + Recall that the BSP uses the <code class="filename">linux-yocto</code> kernel as determined + earlier in the <code class="filename">mymachine.conf</code>. + The recipe for that kernel is not located in the + BSP layer but rather in the source directory at + <code class="filename">meta/recipes-kernel/linux</code> and is + named <code class="filename">linux-yocto_3.2.bb</code>. + The <code class="filename">SRCREV_machine</code> and <code class="filename">SRCREV_meta</code> + statements point to the exact commits used by the Yocto Project development team + in their source repositories that identify the right kernel for our hardware. + In other words, the <code class="filename">SRCREV</code> values are simply Git commit + IDs that identify which commit on each + of the kernel branches (machine and meta) will be checked out and used to build + the kernel. + </p><p> + However, in the <code class="filename">meta-mymachine</code> layer in + <code class="filename">recipes-kernel/linux</code> resides a <code class="filename">.bbappend</code> + file named <code class="filename">linux-yocto_3.2.bbappend</code> that + appends information to the recipe of the same name in <code class="filename">meta/recipes-kernel/linux</code>. + Thus, the <code class="filename">SRCREV</code> statements in the append file override + the more general statements found in <code class="filename">meta</code>. + </p><p> + The <code class="filename">SRCREV</code> statements in the append file currently identify + the kernel that supports the Crown Bay BSP with and without EMGD support. + Here are the statements: + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The commit ID strings used in this manual might not match the actual commit + ID strings found in the <code class="filename">linux-yocto_3.2.bbappend</code> file. + For the example, this difference does not matter.</div><p> + </p><pre class="literallayout"> + SRCREV_machine_pn-linux-yocto_crownbay ?= \ + "211fc7f4d10ec2b82b424286aabbaff9254b7cbd" + SRCREV_meta_pn-linux-yocto_crownbay ?= \ + "514847185c78c07f52e02750fbe0a03ca3a31d8f" + + SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \ + "211fc7f4d10ec2b82b424286aabbaff9254b7cbd" + SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \ + "514847185c78c07f52e02750fbe0a03ca3a31d8f" + </pre><p> + </p><p> + You will notice that there are two pairs of <code class="filename">SRCREV</code> statements. + The top pair identifies the kernel that supports + EMGD, which we don’t care about in this example. + The bottom pair identifies the kernel that we will use: + <code class="filename">linux-yocto</code>. + At this point though, the unique commit strings all are still associated with + Crown Bay and not <code class="filename">meta-mymachine</code>. + </p><p> + To fix this situation in <code class="filename">linux-yocto_3.2.bbappend</code>, + we delete the two <code class="filename">SRCREV</code> statements that support + EMGD (the top pair). + We also change the remaining pair to specify <code class="filename">mymachine</code> + and insert the commit identifiers to identify the kernel in which we + are interested, which will be based on the <code class="filename">atom-pc-standard</code> + kernel. + In this case, because we're working with the 1.2+snapshot branch of everything, we + need to use the <code class="filename">SRCREV</code> values for the atom-pc branch + that are associated with the 1.2+snapshot release. + To find those values, we need to find the <code class="filename">SRCREV</code> + values that 1.2+snapshot uses for the atom-pc branch, which we find in the + <code class="filename">poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.2.bbappend</code> + file. + </p><p> + The machine <code class="filename">SRCREV</code> we want is in the + <code class="filename">SRCREV_machine_atom-pc</code> variable. + The meta <code class="filename">SRCREV</code> isn't specified in this file, so it must be + specified in the base kernel recipe in the + <code class="filename">poky/meta/recipes-kernel/linux/linux-yocto_3.2.bb</code> + file, in the <code class="filename">SRCREV_meta</code> variable found there. + Here are the final <code class="filename">SRCREV</code> statements: + </p><pre class="literallayout"> + SRCREV_machine_pn-linux-yocto_mymachine ?= \ + "f29531a41df15d74be5ad47d958e4117ca9e489e" + SRCREV_meta_pn-linux-yocto_mymachine ?= \ + "b14a08f5c7b469a5077c10942f4e1aec171faa9d" + </pre><p> + </p><p> + In this example, we're using the <code class="filename">SRCREV</code> values we + found already captured in the 1.2+snapshot release because we're creating a BSP based on + 1.2+snapshot. + If, instead, we had based our BSP on the master branches, we would want to use + the most recent <code class="filename">SRCREV</code> values taken directly from the kernel repo. + We will not be doing that for this example. + However, if you do base a future BSP on master and + if you are familiar with Git repositories, you probably won’t have trouble locating the + exact commit strings in the Yocto Project source repositories you need to change + the <code class="filename">SRCREV</code> statements. + You can find all the <code class="filename">machine</code> and <code class="filename">meta</code> + branch points (commits) for the <code class="filename">linux-yocto-3.2</code> kernel at + <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.2" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.2</a>. + </p><p> + If you need a little more assistance after going to the link then do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Expand the list of branches by clicking <code class="filename">[…]</code></p></li><li class="listitem"><p>Click on the <code class="filename">standard/default/common-pc/atom-pc</code> + branch</p></li><li class="listitem"><p>Click on the commit column header to view the top commit</p></li><li class="listitem"><p>Copy the commit string for use in the + <code class="filename">linux-yocto_3.2.bbappend</code> file</p></li></ol></div><p> + </p><p> + For the <code class="filename">SRCREV</code> statement that points to the <code class="filename">meta</code> + branch use the same procedure except expand the <code class="filename">meta</code> + branch in step 2 above. + </p><p> + Also in the <code class="filename">linux-yocto_3.2.bbappend</code> file are + <a class="link" href="#var-COMPATIBLE_MACHINE" target="_top"><code class="filename">COMPATIBLE_MACHINE</code></a>, + <a class="link" href="#var-KMACHINE" target="_top"><code class="filename">KMACHINE</code></a>, + and + <a class="link" href="#var-KBRANCH" target="_top"><code class="filename">KBRANCH</code></a> statements. + Two sets of these exist: one set supports EMGD and one set does not. + Because we are not interested in supporting EMGD those three can be deleted. + The remaining three must be changed so that <code class="filename">mymachine</code> replaces + <code class="filename">crownbay-noemgd</code> and <code class="filename">crownbay</code>. + Because we are using the <code class="filename">atom-pc</code> branch for this new BSP, we can also find + the exact branch we need for the <code class="filename">KMACHINE</code> + and <code class="filename">KBRANCH</code> variables in our new BSP from the value + we find in the + <code class="filename">poky/meta-yocto/recipes-kernel/linux/linux-yocto_3.2.bbappend</code> + file we looked at in a previous step. + In this case, the values we want are in the <code class="filename">KMACHINE_atom-pc</code> variable + and the <code class="filename">KBRANCH_atom-pc</code> variables in that file. + Here is the final <code class="filename">linux-yocto_3.2.bbappend</code> file after all + the edits: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + COMPATIBLE_MACHINE_mymachine = "mymachine" + KMACHINE_mymachine = "atom-pc" + KBRANCH_mymachine = "standard/default/common-pc/atom-pc" + + SRCREV_machine_pn-linux-yocto_mymachine ?= \ + "f29531a41df15d74be5ad47d958e4117ca9e489e" + SRCREV_meta_pn-linux-yocto_mymachine ?= \ + "b14a08f5c7b469a5077c10942f4e1aec171faa9d" + </pre><p> + </p></div></div><div class="section" title="A.5.3. BSP Recipe Change Summary"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-recipe-change-summary"></a>A.5.3. BSP Recipe Change Summary</h3></div></div></div><p> + In summary, the edits to the layer’s recipe files result in removal of any files and + statements that do not support your targeted hardware in addition to the inclusion + of any new recipes you might need. + In this example, it was simply a matter of ridding the new layer + <code class="filename">meta-mymachine</code> of any code that supported the EMGD features + and making sure we were identifying the kernel that supports our example, which + is the <code class="filename">atom-pc-standard</code> kernel. + We did not introduce any new recipes to the layer. + </p><p> + Finally, it is also important to update the layer’s <code class="filename">README</code> + file so that the information in it reflects your BSP. + </p></div></div><div class="section" title="A.6. Preparing for the Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="preparing-for-the-build-app"></a>A.6. Preparing for the Build</h2></div></div></div><p> + To get ready to build your image that uses the new layer you need to do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Get the environment ready for the build by sourcing the environment + script. + The environment script is in the top-level of the source directory. + The script has the string + <code class="filename">init-build-env</code> in the file’s name. + For this example, the following command gets the build environment ready: + </p><pre class="literallayout"> + $ source oe-init-build-env yocto-build + </pre><p> + When you source the script, a build directory is created in the current + working directory. + In our example we were in the <code class="filename">poky</code> directory. + Thus, entering the previous command created the <code class="filename">yocto-build</code> directory. + If you do not provide a name for the build directory it defaults to + <code class="filename">build</code>. + The <code class="filename">yocto-build</code> directory contains a + <code class="filename">conf</code> directory that has + two configuration files you will need to check: <code class="filename">bblayers.conf</code> + and <code class="filename">local.conf</code>.</p></li><li class="listitem"><p>Check and edit the resulting <code class="filename">local.conf</code> file. + This file minimally identifies the machine for which to build the image by + configuring the <code class="filename">MACHINE</code> variable. + For this example you must set the variable to mymachine as follows: + </p><pre class="literallayout"> + MACHINE ??= “mymachine” + </pre><p> + You should also be sure any other variables in which you are interested are set. + Some variables to consider are <code class="filename">BB_NUMBER_THREADS</code> + and <code class="filename">PARALLEL_MAKE</code>, both of which can greatly reduce your build time + if your development system supports multiple cores. + For development systems that support multiple cores, a good rule of thumb is to set + both the <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code> + variables to twice the number of cores your system supports.</p></li><li class="listitem"><p>Update the <code class="filename">bblayers.conf</code> file so that it includes + both the path to your new BSP layer and the path to the + <code class="filename">meta-intel</code> layer. + In this example, you need to include both these paths as part of the + <code class="filename">BBLAYERS</code> variable: + </p><pre class="literallayout"> + $HOME/poky/meta-intel + $HOME/poky/meta-intel/meta-mymachine + </pre></li></ol></div><p> + </p><p> + The + <a class="link" href="#ref-variables-glos" target="_top">Variables Glossary</a> chapter in the + Yocto Project Reference Manual has more information on configuration variables. + </p></div><div class="section" title="A.7. Building and Booting the Image"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-the-image-app"></a>A.7. Building and Booting the Image</h2></div></div></div><p> + To build the image for our <code class="filename">meta-mymachine</code> BSP enter the following command + from the same shell from which you ran the setup script. + You should run the <code class="filename">bitbake</code> command without any intervening shell commands. + For example, moving your working directory around could cause problems. + Here is the command for this example: + </p><pre class="literallayout"> + $ bitbake -k core-image-sato + </pre><p> + </p><p> + This command specifies an image that has Sato support and that can be run from a USB device or + from a CD without having to first install anything. + The build process takes significant time and includes thousands of tasks, which are reported + at the console. + If the build results in any type of error you should check for misspellings in the + files you changed or problems with your host development environment such as missing packages. + </p><p> + Finally, once you have an image, you can try booting it from a device + (e.g. a USB device). + To prepare a bootable USB device, insert a USB flash drive into your build system and + copy the <code class="filename">.hddimg</code> file, located in the + <code class="filename">poky/build/tmp/deploy/images</code> + directory after a successful build to the flash drive. + Assuming the USB flash drive takes device <code class="filename">/dev/sdf</code>, + use <code class="filename">dd</code> to copy the live image to it. + For example: + </p><pre class="literallayout"> + # dd if=core-image-sato-mymachine-20111101223904.hddimg of=/dev/sdf + # sync + # eject /dev/sdf + </pre><p> + You should now have a bootable USB flash device. + </p><p> + Insert the device + into a bootable USB socket on the target, and power it on. + The system should boot to the Sato graphical desktop. + <sup>[<a id="id1497755" href="#ftn.id1497755" class="footnote">2</a>]</sup> + </p><p> + For reference, the sato image produced by the previous steps for 1.2+snapshot + should look like the following in terms of size. + If your sato image is much different from this, + you probably made a mistake in one of the above steps: + </p><pre class="literallayout"> + 260538368 2012-04-27 01:44 core-image-sato-mymachine-20120427025051.hddimg + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>The previous instructions are also present in the README that was copied + from meta-crownbay, which should also be updated to reflect the specifics of your + new BSP. + That file and the <code class="filename">README.hardware</code> file in the top-level + <code class="filename">poky</code> directory + also provides some suggestions for things to try if booting fails and produces + strange error messages.</div><p> + </p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id1497755" href="#id1497755" class="para">2</a>] </sup>Because + this new image is not in any way tailored to the system you're + booting it on, which is assumed to be some sort of atom-pc (netbook) system for this + example, it might not be completely functional though it should at least boot to a text + prompt. + Specifically, it might fail to boot into graphics without some tweaking. + If this ends up being the case, a possible next step would be to replace the + <code class="filename">mymachine.conf</code> + contents with the contents of <code class="filename">atom-pc.conf</code> and replace + <code class="filename">xorg.conf</code> with <code class="filename">atom-pc xorg.conf</code> + in <code class="filename">meta-yocto</code> and see if it fares any better. + In any case, following the previous steps will give you a buildable image that + will probably boot on most systems. + Getting things working like you want + them to for your hardware will normally require some amount of experimentation with + configuration settings.</p></div></div></div> + + <div class="appendix" title="Appendix B. Kernel Modification Example"><div class="titlepage"><div><div><h2 class="title"><a id="dev-manual-kernel-appendix"></a>Appendix B. Kernel Modification Example</h2></div></div></div><p> + Kernel modification involves changing or adding configurations to an existing kernel, + changing or adding recipes to the kernel that are needed to support specific hardware features, + or even altering the source code itself. + This appendix presents simple examples that modify the kernel source code, + change the kernel configuration, and add a kernel source recipe. + </p><div class="section" title="B.1. Modifying the Kernel Source Code"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="modifying-the-kernel-source-code"></a>B.1. Modifying the Kernel Source Code</h2></div></div></div><p> + This example adds some simple QEMU emulator console output at boot time by + adding <code class="filename">printk</code> statements to the kernel's + <code class="filename">calibrate.c</code> source code file. + Booting the modified image causes the added messages to appear on the emulator's + console. + </p><div class="section" title="B.1.1. Understanding the Files You Need"><div class="titlepage"><div><div><h3 class="title"><a id="understanding-the-files-you-need"></a>B.1.1. Understanding the Files You Need</h3></div></div></div><p> + Before you modify the kernel, you need to know what Git repositories and file + structures you need. + Briefly, you need the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A local + <a class="link" href="#source-directory">source directory</a> for the + poky Git repository</p></li><li class="listitem"><p>Local copies of the + <a class="link" href="#poky-extras-repo"><code class="filename">poky-extras</code></a> + Git repository placed within the source directory.</p></li><li class="listitem"><p>A bare clone of the + <a class="link" href="#local-kernel-files">Yocto Project Kernel</a> upstream Git + repository to which you want to push your modifications. + </p></li><li class="listitem"><p>A copy of that bare clone in which you make your source + modifications</p></li></ul></div><p> + </p><p> + The following figure summarizes these four areas. + Within each rectangular that represents a data structure, a + host development directory pathname appears at the + lower left-hand corner of the box. + These pathnames are the locations used in this example. + The figure also provides key statements and commands used during the kernel + modification process: + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 450px"><td align="center"><img src="figures/kernel-example-repos-denzil.png" align="middle" /></td></tr></table><p> + </p><p> + Here is a brief description of the four areas: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Local Source Directory:</em></span> + This area contains all the metadata that supports building images + using the OpenEmbedded build system. + In this example, the source directory also + contains the build directory, which contains the configuration directory + that lets you control the build. + Also in this example, the source directory contains local copies of the + <code class="filename">poky-extras</code> Git repository.</p><p>See the bulleted item + "<a class="link" href="#local-yp-release">Yocto Project Release</a>" + for information on how to get these files on your local system.</p></li><li class="listitem"><p><span class="emphasis"><em>Local copies of the<code class="filename">poky-extras</code> + Git Repository:</em></span> + This area contains the <code class="filename">meta-kernel-dev</code> layer, + which is where you make changes that append the kernel build recipes. + You edit <code class="filename">.bbappend</code> files to locate your + local kernel source files and to identify the kernel being built. + This Git repository is a gathering place for extensions to the Yocto Project + (or really any) kernel recipes that faciliate the creation and development + of kernel features, BSPs or configurations.</p><p>See the bulleted item + "<a class="link" href="#poky-extras-repo">The + <code class="filename">poky-extras</code> Git Repository</a>" + for information on how to get these files.</p></li><li class="listitem"><p><span class="emphasis"><em>Bare Clone of the Yocto Project kernel:</em></span> + This bare Git repository tracks the upstream Git repository of the Linux + Yocto kernel source code you are changing. + When you modify the kernel you must work through a bare clone. + All source code changes you make to the kernel must be committed and + pushed to the bare clone using Git commands. + As mentioned, the <code class="filename">.bbappend</code> file in the + <code class="filename">poky-extras</code> repository points to the bare clone + so that the build process can locate the locally changed source files.</p><p>See the bulleted item + "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" + for information on how to set up the bare clone. + </p></li><li class="listitem"><p><span class="emphasis"><em>Copy of the Yocto Project Kernel Bare Clone:</em></span> + This Git repository contains the actual source files that you modify. + Any changes you make to files in this location need to ultimately be pushed + to the bare clone using the <code class="filename">git push</code> command.</p><p>See the bulleted item + "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" + for information on how to set up the bare clone. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Typically, Git workflows follow a scheme where changes made to a local area + are pulled into a Git repository. + However, because the <code class="filename">git pull</code> command does not work + with bare clones, this workflow pushes changes to the + repository even though you could use other more complicated methods to + get changes into the bare clone.</div><p> + </p></li></ul></div><p> + </p></div><div class="section" title="B.1.2. Setting Up the Local Source Directory"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-the-local-yocto-project-files-git-repository"></a>B.1.2. Setting Up the Local Source Directory</h3></div></div></div><p> + You can set up the source directory through tarball extraction or by + cloning the <code class="filename">poky</code> Git repository. + This example uses <code class="filename">poky</code> as the root directory of the + local source directory. + See the bulleted item + "<a class="link" href="#local-yp-release">Yocto Project Release</a>" + for information on how to get these files. + </p><p> + Once you have source directory set up, + you have many development branches from which you can work. + From inside the local repository you can see the branch names and the tag names used + in the upstream Git repository by using either of the following commands: + </p><pre class="literallayout"> + $ cd poky + $ git branch -a + $ git tag -l + </pre><p> + This example uses the Yocto Project 1.3 Release code named "1.2+snapshot", + which maps to the <code class="filename">1.2+snapshot</code> branch in the repository. + The following commands create and checkout the local <code class="filename">1.2+snapshot</code> + branch: + </p><pre class="literallayout"> + $ git checkout -b 1.2+snapshot origin/1.2+snapshot + Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. + Switched to a new branch '1.2+snapshot' + </pre><p> + </p></div><div class="section" title="B.1.3. Setting Up the Local poky-extras Git Repository"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-the-poky-extras-git-repository"></a>B.1.3. Setting Up the Local poky-extras Git Repository</h3></div></div></div><p> + This example creates a local copy of the <code class="filename">poky-extras</code> Git + repository inside the <code class="filename">poky</code> source directory. + See the bulleted item "<a class="link" href="#poky-extras-repo">The + <code class="filename">poky-extras</code> Git Repository</a>" + for information on how to set up a local copy of the + <code class="filename">poky-extras</code> repository. + </p><p> + Because this example uses the Yocto Project 1.3 Release code + named "1.2+snapshot", which maps to the <code class="filename">1.2+snapshot</code> + branch in the repository, you need to be sure you are using that + branch for <code class="filename">poky-extra</code>. + The following commands create and checkout the local + branch you are using for the <code class="filename">1.2+snapshot</code> + branch: + </p><pre class="literallayout"> + $ git checkout -b 1.2+snapshot origin/1.2+snapshot + Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. + Switched to a new branch '1.2+snapshot' + </pre><p> + </p></div><div class="section" title="B.1.4. Setting Up the Bare Clone and its Copy"><div class="titlepage"><div><div><h3 class="title"><a id="setting-up-the-bare-clone-and-its-copy"></a>B.1.4. Setting Up the Bare Clone and its Copy</h3></div></div></div><p> + This example modifies the <code class="filename">linux-yocto-3.2</code> kernel. + Thus, you need to create a bare clone of that kernel and then make a copy of the + bare clone. + See the bulleted item + "<a class="link" href="#local-kernel-files">Yocto Project Kernel</a>" + for information on how to do that. + </p><p> + The bare clone exists for the kernel build tools and simply as the receiving end + of <code class="filename">git push</code> + commands after you make edits and commits inside the copy of the clone. + The copy (<code class="filename">my-linux-yocto-3.2-work</code> in this example) has to have + a local branch created and checked out for your work. + This example uses <code class="filename">common-pc-base</code> as the local branch. + The following commands create and checkout the branch: + </p><pre class="literallayout"> + $ cd ~/my-linux-yocto-3.2-work + $ git checkout -b common-pc-base origin/standard/default/common-pc/base + Checking out files: 100% (532/532), done. + Branch common-pc-base set up to track remote branch + standard/default/common-pc/base from origin. + Switched to a new branch 'common-pc-base' + </pre><p> + </p></div><div class="section" title="B.1.5. Building and Booting the Default QEMU Kernel Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-and-booting-the-default-qemu-kernel-image"></a>B.1.5. Building and Booting the Default QEMU Kernel Image</h3></div></div></div><p> + Before we make changes to the kernel source files, this example first builds the + default image and then boots it inside the QEMU emulator. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Because a full build can take hours, you should check two variables in the + <code class="filename">build</code> directory that is created after you source the + <code class="filename">oe-init-build-env</code> script. + You can find these variables + <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code> + in the <code class="filename">build/conf</code> directory in the + <code class="filename">local.conf</code> configuration file. + By default, these variables are commented out. + If your host development system supports multi-core and multi-thread capabilities, + you can uncomment these statements and set the variables to significantly shorten + the full build time. + As a guideline, set both <code class="filename">BB_NUMBER_THREADS</code> and + <code class="filename">PARALLEL_MAKE</code> to twice the number + of cores your machine supports. + </div><p> + The following two commands <code class="filename">source</code> the build environment setup script + and build the default <code class="filename">qemux86</code> image. + If necessary, the script creates the build directory: + </p><pre class="literallayout"> + $ cd ~/poky + $ source oe-init-build-env + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + meta-toolchain-sdk + adt-installer + meta-ide-support + + You can also run generated qemu images with a command like 'runqemu qemux86' + </pre><p> + </p><p> + The following <code class="filename">bitbake</code> command starts the build: + </p><pre class="literallayout"> + $ bitbake -k core-image-minimal + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Be sure to check the settings in the <code class="filename">local.conf</code> + before starting the build.</div><p> + </p><p> + After the build completes, you can start the QEMU emulator using the resulting image + <code class="filename">qemux86</code> as follows: + </p><pre class="literallayout"> + $ runqemu qemux86 + </pre><p> + </p><p> + As the image boots in the emulator, console message and status output appears + across the terminal window. + Because the output scrolls by quickly, it is difficult to read. + To examine the output, you log into the system using the + login <code class="filename">root</code> with no password. + Once you are logged in, issue the following command to scroll through the + console output: + </p><pre class="literallayout"> + # dmesg | less + </pre><p> + </p><p> + Take note of the output as you will want to look for your inserted print command output + later in the example. + </p></div><div class="section" title="B.1.6. Changing the Source Code and Pushing it to the Bare Clone"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-source-code-and-pushing-it-to-the-bare-clone"></a>B.1.6. Changing the Source Code and Pushing it to the Bare Clone</h3></div></div></div><p> + The file you change in this example is named <code class="filename">calibrate.c</code> + and is located in the <code class="filename">my-linux-yocto-3.2-work</code> Git repository + (the copy of the bare clone) in <code class="filename">init</code>. + This example simply inserts several <code class="filename">printk</code> statements + at the beginning of the <code class="filename">calibrate_delay</code> function. + </p><p> + Here is the unaltered code at the start of this function: + </p><pre class="literallayout"> + void __cpuinit calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + </pre><p> + </p><p> + Here is the altered code showing five new <code class="filename">printk</code> statements + near the top of the function: + </p><pre class="literallayout"> + void __cpuinit calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + </pre><p> + </p><p> + After making and saving your changes, you need to stage them for the push. + The following Git commands are one method of staging and committing your changes: + </p><pre class="literallayout"> + $ git add calibrate.c + $ git commit --signoff + </pre><p> + </p><p> + Once the source code has been modified, you need to use Git to push the changes to + the bare clone. + If you do not push the changes, then the OpenEmbedded build system will not pick + up the changed source files. + </p><p> + The following command pushes the changes to the bare clone: + </p><pre class="literallayout"> + $ git push origin common-pc-base:standard/default/common-pc/base + </pre><p> + </p></div><div class="section" title="B.1.7. Changing Build Parameters for Your Build"><div class="titlepage"><div><div><h3 class="title"><a id="changing-build-parameters-for-your-build"></a>B.1.7. Changing Build Parameters for Your Build</h3></div></div></div><p> + At this point, the source has been changed and pushed. + The example now defines some variables used by the OpenEmbedded build system + to locate your kernel source. + You essentially need to identify where to find the kernel recipe and the changed source code. + You also need to be sure some basic configurations are in place that identify the + type of machine you are building and to help speed up the build should your host support + multiple-core and thread capabilities. + </p><p> + Do the following to make sure the build parameters are set up for the example. + Once you set up these build parameters, they do not have to change unless you + change the target architecture of the machine you are building or you move + the bare clone, copy of the clone, or the <code class="filename">poky-extras</code> repository: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Build for the Correct Target Architecture:</em></span> The + <code class="filename">local.conf</code> file in the build directory defines the build's + target architecture. + By default, <code class="filename">MACHINE</code> is set to + <code class="filename">qemux86</code>, which specifies a 32-bit + <span class="trademark">Intel</span>® Architecture + target machine suitable for the QEMU emulator. + In this example, <code class="filename">MACHINE</code> is correctly configured. + </p></li><li class="listitem"><p><span class="emphasis"><em>Optimize Build Time:</em></span> Also in the + <code class="filename">local.conf</code> file are two variables that can speed your + build time if your host supports multi-core and multi-thread capabilities: + <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code>. + If the host system has multiple cores then you can optimize build time + by setting both these variables to twice the number of + cores.</p></li><li class="listitem"><p><span class="emphasis"><em>Identify Your <code class="filename">meta-kernel-dev</code> + Layer:</em></span> The <code class="filename">BBLAYERS</code> variable in the + <code class="filename">bblayers.conf</code> file found in the + <code class="filename">poky/build/conf</code> directory needs to have the path to your local + <code class="filename">meta-kernel-dev</code> layer. + By default, the <code class="filename">BBLAYERS</code> variable contains paths to + <code class="filename">meta</code> and <code class="filename">meta-yocto</code> in the + <code class="filename">poky</code> Git repository. + Add the path to your <code class="filename">meta-kernel-dev</code> location. + Be sure to substitute your user information in the statement. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/poky-extras/meta-kernel-dev \ + " + </pre></li><li class="listitem"><p><span class="emphasis"><em>Identify Your Source Files:</em></span> In the + <code class="filename">linux-yocto_3.2.bbappend</code> file located in the + <code class="filename">poky-extras/meta-kernel-dev/recipes-kernel/linux</code> + directory, you need to identify the location of the + local source code, which in this example is the bare clone named + <code class="filename">linux-yocto-3.2.git</code>. + To do this, set the <code class="filename">KSRC_linux_yocto</code> variable to point to your + local <code class="filename">linux-yocto-3.2.git</code> Git repository by adding the + following statement. + Be sure to substitute your user information in the statement: + </p><pre class="literallayout"> + KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git" + </pre></li></ul></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Before attempting to build the modified kernel, there is one more set of changes you + need to make in the <code class="filename">meta-kernel-dev</code> layer. + Because all the kernel <code class="filename">.bbappend</code> files are parsed during the + build process regardless of whether you are using them or not, you should either + comment out the <code class="filename">COMPATIBLE_MACHINE</code> statements in all + unused <code class="filename">.bbappend</code> files, or simply remove (or rename) all the files + except the one your are using for the build + (i.e. <code class="filename">linux-yocto_3.2.bbappend</code> in this example).</p><p>If you do not make one of these two adjustments, your machine will be compatible + with all the kernel recipes in the <code class="filename">meta-kernel-dev</code> layer. + When your machine is comapatible with all the kernel recipes, the build attempts + to build all kernels in the layer. + You could end up with build errors blocking your work.</p></div></div><div class="section" title="B.1.8. Building and Booting the Modified QEMU Kernel Image"><div class="titlepage"><div><div><h3 class="title"><a id="building-and-booting-the-modified-qemu-kernel-image"></a>B.1.8. Building and Booting the Modified QEMU Kernel Image</h3></div></div></div><p> + Next, you need to build the modified image. + Do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Your environment should be set up since you previously sourced + the <code class="filename">oe-init-build-env</code> script. + If it isn't, source the script again from <code class="filename">poky</code>. + </p><pre class="literallayout"> + $ cd ~/poky + $ source oe-init-build-env + </pre><p> + </p></li><li class="listitem"><p>Be sure old images are cleaned out by running the + <code class="filename">cleanall</code> BitBake task as follows from your build directory: + </p><pre class="literallayout"> + $ bitbake -c cleanall linux-yocto + </pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Never remove any files by hand from the <code class="filename">tmp/deploy</code> + directory insided the build directory. + Always use the BitBake <code class="filename">cleanall</code> task to clear + out previous builds.</div></li><li class="listitem"><p>Next, build the kernel image using this command: + </p><pre class="literallayout"> + $ bitbake -k core-image-minimal + </pre></li><li class="listitem"><p>Finally, boot the modified image in the QEMU emulator + using this command: + </p><pre class="literallayout"> + $ runqemu qemux86 + </pre></li></ol></div><p> + </p><p> + Log into the machine using <code class="filename">root</code> with no password and then + use the following shell command to scroll through the console's boot output. + </p><pre class="literallayout"> + # dmesg | less + </pre><p> + </p><p> + You should see the results of your <code class="filename">printk</code> statements + as part of the output. + </p></div></div><div class="section" title="B.2. Changing the Kernel Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="changing-the-kernel-configuration"></a>B.2. Changing the Kernel Configuration</h2></div></div></div><p> + This example changes the default behavior, which is "on", of the Symmetric + Multi-processing Support (<code class="filename">CONFIG_SMP</code>) to "off". + It is a simple example that demonstrates how to reconfigure the kernel. + </p><div class="section" title="B.2.1. Getting Set Up to Run this Example"><div class="titlepage"><div><div><h3 class="title"><a id="getting-set-up-to-run-this-example"></a>B.2.1. Getting Set Up to Run this Example</h3></div></div></div><p> + If you took the time to work through the example that modifies the kernel source code + in "<a class="link" href="#modifying-the-kernel-source-code" title="B.1. Modifying the Kernel Source Code">Modifying the Kernel Source + Code</a>" you should already have the source directory set up on your + host machine. + If this is the case, go to the next section, which is titled + "<a class="link" href="#examining-the-default-config-smp-behavior" title="B.2.2. Examining the Default CONFIG_SMP Behavior">Examining the Default + <code class="filename">CONFIG_SMP</code> Behavior</a>", and continue with the + example. + </p><p> + If you don't have the source directory established on your system, + you can get them through tarball extraction or by + cloning the <code class="filename">poky</code> Git repository. + This example uses <code class="filename">poky</code> as the root directory of the + <a class="link" href="#source-directory">source directory</a>. + See the bulleted item + "<a class="link" href="#local-yp-release">Yocto Project Release</a>" + for information on how to get these files. + </p><p> + Once you have the local copy of the repository set up, + you have many development branches from which you can work. + From inside the repository you can see the branch names and the tag names used + in the upstream Git repository using either of the following commands: + </p><pre class="literallayout"> + $ cd poky + $ git branch -a + $ git tag -l + </pre><p> + This example uses the Yocto Project 1.3 Release code named "1.2+snapshot", + which maps to the <code class="filename">1.2+snapshot</code> branch in the repository. + The following commands create and checkout the local <code class="filename">1.2+snapshot</code> + branch: + </p><pre class="literallayout"> + $ git checkout -b 1.2+snapshot origin/1.2+snapshot + Branch 1.2+snapshot set up to track remote branch 1.2+snapshot from origin. + Switched to a new branch '1.2+snapshot' + </pre><p> + </p><p> + Next, you need to build the default <code class="filename">qemux86</code> image that you + can boot using QEMU. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Because a full build can take hours, you should check two variables in the + <code class="filename">build</code> directory that is created after you source the + <code class="filename">oe-init-build-env</code> script. + You can find these variables + <code class="filename">BB_NUMBER_THREADS</code> and <code class="filename">PARALLEL_MAKE</code> + in the <code class="filename">build/conf</code> directory in the + <code class="filename">local.conf</code> configuration file. + By default, these variables are commented out. + If your host development system supports multi-core and multi-thread capabilities, + you can uncomment these statements and set the variables to significantly shorten + the full build time. + As a guideline, set both the <code class="filename">BB_NUMBER_THREADS</code> and the + <code class="filename">PARALLEL_MAKE</code> variables to twice the number + of cores your machine supports. + </div><p> + The following two commands <code class="filename">source</code> the build environment setup script + and build the default <code class="filename">qemux86</code> image. + If necessary, the script creates the build directory: + </p><pre class="literallayout"> + $ cd ~/poky + $ source oe-init-build-env + + ### Shell environment set up for builds. ### + + You can now run 'bitbake <target>' + + Common targets are: + core-image-minimal + core-image-sato + meta-toolchain + meta-toolchain-sdk + adt-installer + meta-ide-support + + You can also run generated qemu images with a command like 'runqemu qemux86' + </pre><p> + </p><p> + The following <code class="filename">bitbake</code> command starts the build: + </p><pre class="literallayout"> + $ bitbake -k core-image-minimal + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Be sure to check the settings in the <code class="filename">local.conf</code> + before starting the build.</div><p> + </p></div><div class="section" title="B.2.2. Examining the Default CONFIG_SMP Behavior"><div class="titlepage"><div><div><h3 class="title"><a id="examining-the-default-config-smp-behavior"></a>B.2.2. Examining the Default <code class="filename">CONFIG_SMP</code> Behavior</h3></div></div></div><p> + By default, <code class="filename">CONFIG_SMP</code> supports multiple processor machines. + To see this default setting from within the QEMU emulator, boot your image using + the emulator as follows: + </p><pre class="literallayout"> + $ runqemu qemux86 qemuparams="-smp 4" + </pre><p> + </p><p> + Login to the machine using <code class="filename">root</code> with no password. + After logging in, enter the following command to see how many processors are + being supported in the emulator. + The emulator reports support for the number of processors you specified using + the <code class="filename">-smp</code> option, four in this case: + </p><pre class="literallayout"> + # cat /proc/cpuinfo | grep processor + processor : 0 + processor : 1 + processor : 2 + processor : 3 + # + </pre><p> + To check the setting for <code class="filename">CONFIG_SMP</code>, you can use the + following command: + </p><pre class="literallayout"> + zcat /proc/config.gz | grep CONFIG_SMP + </pre><p> + The console returns the following showing that multi-processor machine support + is set: + </p><pre class="literallayout"> + CONFIG_SMP=y + </pre><p> + Logout of the emulator using the <code class="filename">exit</code> command and + then close it down. + </p></div><div class="section" title="B.2.3. Changing the CONFIG_SMP Configuration Using menuconfig"><div class="titlepage"><div><div><h3 class="title"><a id="changing-the-config-smp-configuration-using-menuconfig"></a>B.2.3. Changing the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></h3></div></div></div><p> + The <code class="filename">menuconfig</code> tool provides an interactive method with which + to set kernel configurations. + You need to run <code class="filename">menuconfig</code> inside the Yocto BitBake environment. + Thus, the environment must be set up using the <code class="filename">oe-init-build-env</code> + script found in the build directory. + If you have not sourced this script do so with the following commands: + </p><pre class="literallayout"> + $ cd ~/poky + $ source oe-init-build-env + </pre><p> + </p><p> + After setting up the environment to run <code class="filename">menuconfig</code>, you are ready + to use the tool to interactively change the kernel configuration. + In this example, we are basing our changes on the <code class="filename">linux-yocto-3.2</code> + kernel. + The OpenEmbedded build system recognizes this kernel as + <code class="filename">linux-yocto</code>. + Thus, the following commands from the shell in which you previously sourced the + environment initialization script cleans the shared state cache and the + <a class="link" href="#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a> + directory and then builds and launches <code class="filename">menuconfig</code>: + </p><pre class="literallayout"> + $ bitbake linux-yocto -c menuconfig + </pre><p> + </p><p> + Once <code class="filename">menuconfig</code> launches, navigate through the user interface + to find the <code class="filename">CONFIG_SMP</code> configuration setting. + You can find it at <code class="filename">Processor Type and Features</code>. + The configuration selection is + <code class="filename">Symmetric Multi-processing Support</code>. + After using the arrow keys to highlight this selection, press "n" to turn it off. + Then, exit out and save your selections. + </p><p> + Once you save the selection, the <code class="filename">.config</code> configuration file + is updated. + This is the file that the build system uses to configure the Yocto Project kernel + when it is built. + You can find and examine this file in the build directory. + This example uses the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.11+git1+84f... + ...656ed30-r1/linux-qemux86-standard-build + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The previous example directory is artificially split and many of the characters + in the actual filename are omitted in order to make it more readable. + Also, depending on the kernel you are using, the exact pathname might differ + slightly. + </div><p> + </p><p> + Within the <code class="filename">.config</code> file, you can see the following setting: + </p><pre class="literallayout"> + # CONFIG_SMP is not set + </pre><p> + </p><p> + A good method to isolate changed configurations is to use a combination of the + <code class="filename">menuconfig</code> tool and simple shell commands. + Before changing configurations with <code class="filename">menuconfig</code>, copy the + existing <code class="filename">.config</code> and rename it to something else, + use <code class="filename">menuconfig</code> to make + as many changes an you want and save them, then compare the renamed configuration + file against the newly created file. + You can use the resulting differences as your base to create configuration fragments + to permanently save in your kernel layer. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Be sure to make a copy of the <code class="filename">.config</code> and don't just + rename it. + The build system needs an existing <code class="filename">.config</code> + from which to work. + </div><p> + </p></div><div class="section" title="B.2.4. Recompiling the Kernel and Testing the New Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="recompiling-the-kernel-and-testing-the-new-configuration"></a>B.2.4. Recompiling the Kernel and Testing the New Configuration</h3></div></div></div><p> + At this point, you are ready to recompile your kernel image with + the new setting in effect using the BitBake command below: + </p><pre class="literallayout"> + $ bitbake linux-yocto + </pre><p> + </p><p> + Now run the QEMU emulator and pass it the same multi-processor option as before: + </p><pre class="literallayout"> + $ runqemu qemux86 qemuparams="-smp 4" + </pre><p> + </p><p> + Login to the machine using <code class="filename">root</code> with no password + and test for the number of processors the kernel supports: + </p><pre class="literallayout"> + # cat /proc/cpuinfo | grep processor + processor : 0 + # + </pre><p> + </p><p> + From the output, you can see that the kernel no longer supports multi-processor systems. + The output indicates support for a single processor. You can verify the + <code class="filename">CONFIG_SMP</code> setting by using this command: + </p><pre class="literallayout"> + zcat /proc/config.gz | grep CONFIG_SMP + </pre><p> + The console returns the following output: + </p><pre class="literallayout"> + # CONFIG_SMP is not set + </pre><p> + You have successfully reconfigured the kernel. + </p></div></div><div class="section" title="B.3. Adding Kernel Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adding-kernel-recipes"></a>B.3. Adding Kernel Recipes</h2></div></div></div><p> + A future release of this manual will present an example that adds kernel recipes, which provide + new functionality to the kernel. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="180"><tr style="height: 270px"><td align="center"><img src="figures/wip.png" align="middle" width="180" /></td></tr></table><p> + </p></div></div> + +</div> + +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/adt-title.png" align="left" width="100%" /></td></tr></table> + + <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="adt-manual"></a></h1></div><div><div class="authorgroup"> + <div class="author"><h3 class="author"><span class="firstname">Jessica</span> <span class="surname">Zhang</span></h3><div class="affiliation"> + <span class="orgname">Intel Corporation<br /></span> + </div><code class="email"><<a class="email" href="mailto:jessica.zhang@intel.com">jessica.zhang@intel.com</a>></code></div> + </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1499739"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. + </p> + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + Yocto Project Application Developer's Guide on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + + </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> + <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> + <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> + <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> + <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + </table></div></div></div><hr /></div> + + + <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="adt-intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#adt-intro-section">1.1. The Application Development Toolkit (ADT)</a></span></dt><dd><dl><dt><span class="section"><a href="#the-cross-toolchain">1.1.1. The Cross-Toolchain</a></span></dt><dt><span class="section"><a href="#sysroot">1.1.2. Sysroot</a></span></dt><dt><span class="section"><a href="#eclipse-overview">1.1.3. Eclipse Yocto Plug-in</a></span></dt><dt><span class="section"><a href="#the-qemu-emulator">1.1.4. The QEMU Emulator</a></span></dt><dt><span class="section"><a href="#user-space-tools">1.1.5. User-Space Tools</a></span></dt></dl></dd></dl></div><p> + Welcome to the Yocto Project Application Developer's Guide. + This manual provides information that lets you begin developing applications + using the Yocto Project. +</p><p> + The Yocto Project provides an application development environment based on + an Application Development Toolkit (ADT) and the availability of stand-alone + cross-development toolchains and other tools. + This manual describes the ADT and how you can configure and install it, + how to access and use the cross-development toolchains, how to + customize the development packages installation, + how to use command line development for both Autotools-based and Makefile-based projects, + and an introduction to the Eclipse Yocto Plug-in. +</p><div class="section" title="1.1. The Application Development Toolkit (ADT)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adt-intro-section"></a>1.1. The Application Development Toolkit (ADT)</h2></div></div></div><p> + Part of the Yocto Project development solution is an Application Development + Toolkit (ADT). + The ADT provides you with a custom-built, cross-development + platform suited for developing a user-targeted product application. + </p><p> + Fundamentally, the ADT consists of the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>An architecture-specific cross-toolchain and matching + sysroot both built by the OpenEmbedded build system, which uses Poky. + The toolchain and sysroot are based on a metadata configuration and extensions, + which allows you to cross-develop on the host machine for the target hardware. + </p></li><li class="listitem"><p>The Eclipse IDE Yocto Plug-in.</p></li><li class="listitem"><p>The Quick EMUlator (QEMU), which lets you simulate target hardware. + </p></li><li class="listitem"><p>Various user-space tools that greatly enhance your application + development experience.</p></li></ul></div><p> + </p><div class="section" title="1.1.1. The Cross-Toolchain"><div class="titlepage"><div><div><h3 class="title"><a id="the-cross-toolchain"></a>1.1.1. The Cross-Toolchain</h3></div></div></div><p> + The cross-toolchain consists of a cross-compiler, cross-linker, and cross-debugger + that are used to develop user-space applications for targeted hardware. + This toolchain is created either by running the ADT Installer script or + through a build directory that is based on your metadata + configuration or extension for your targeted device. + The cross-toolchain works with a matching target sysroot. + </p></div><div class="section" title="1.1.2. Sysroot"><div class="titlepage"><div><div><h3 class="title"><a id="sysroot"></a>1.1.2. Sysroot</h3></div></div></div><p> + The matching target sysroot contains needed headers and libraries for generating + binaries that run on the target architecture. + The sysroot is based on the target root filesystem image that is built by + the OpenEmbedded build system Poky and uses the same metadata configuration + used to build the cross-toolchain. + </p></div><div class="section" title="1.1.3. Eclipse Yocto Plug-in"><div class="titlepage"><div><div><h3 class="title"><a id="eclipse-overview"></a>1.1.3. Eclipse Yocto Plug-in</h3></div></div></div><p> + The Eclipse IDE is a popular development environment and it fully supports + development using the Yocto Project. + When you install and configure the Eclipse Yocto Project Plug-in into + the Eclipse IDE, you maximize your Yocto Project experience. + Installing and configuring the Plug-in results in an environment that + has extensions specifically designed to let you more easily develop software. + These extensions allow for cross-compilation, deployment, and execution of + your output into a QEMU emulation session. + You can also perform cross-debugging and profiling. + The environment also supports a suite of tools that allows you to perform + remote profiling, tracing, collection of power data, collection of + latency data, and collection of performance data. + </p><p> + For information about the application development workflow that uses the Eclipse + IDE and for a detailed example of how to install and configure the Eclipse + Yocto Project Plug-in, see the + "<a class="link" href="#adt-eclipse" target="_top">Working Within Eclipse</a>" section + of the Yocto Project Development Manual. + </p></div><div class="section" title="1.1.4. The QEMU Emulator"><div class="titlepage"><div><div><h3 class="title"><a id="the-qemu-emulator"></a>1.1.4. The QEMU Emulator</h3></div></div></div><p> + The QEMU emulator allows you to simulate your hardware while running your + application or image. + QEMU is made available a number of ways: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>If you use the ADT Installer script to install ADT, you can + specify whether or not to install QEMU.</p></li><li class="listitem"><p>If you have downloaded a Yocto Project release and unpacked + it to create a source directory and you have sourced + the environment setup script, QEMU is installed and automatically + available.</p></li><li class="listitem"><p>If you have installed the cross-toolchain + tarball and you have sourcing the toolchain's setup environment script, QEMU + is also installed and automatically available.</p></li></ul></div><p> + </p></div><div class="section" title="1.1.5. User-Space Tools"><div class="titlepage"><div><div><h3 class="title"><a id="user-space-tools"></a>1.1.5. User-Space Tools</h3></div></div></div><p> + User-space tools are included as part of the distribution. + You will find these tools helpful during development. + The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust. + These tools are common development tools for the Linux platform. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>LatencyTOP:</em></span> LatencyTOP focuses on latency + that causes skips in audio, + stutters in your desktop experience, or situations that overload your server + even when you have plenty of CPU power left. + You can find out more about LatencyTOP at + <a class="ulink" href="http://www.latencytop.org/" target="_top">http://www.latencytop.org/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>PowerTOP:</em></span> Helps you determine what + software is using the most power. + You can find out more about PowerTOP at + <a class="ulink" href="http://www.linuxpowertop.org/" target="_top">http://www.linuxpowertop.org/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>OProfile:</em></span> A system-wide profiler for Linux + systems that is capable of profiling all running code at low overhead. + You can find out more about OProfile at + <a class="ulink" href="http://oprofile.sourceforge.net/about/" target="_top">http://oprofile.sourceforge.net/about/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Perf:</em></span> Performance counters for Linux used + to keep track of certain types of hardware and software events. + For more information on these types of counters see + <a class="ulink" href="https://perf.wiki.kernel.org/" target="_top">https://perf.wiki.kernel.org/</a> and click + on “Perf tools.”</p></li><li class="listitem"><p><span class="emphasis"><em>SystemTap:</em></span> A free software infrastructure + that simplifies information gathering about a running Linux system. + This information helps you diagnose performance or functional problems. + SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in. + See <a class="ulink" href="http://sourceware.org/systemtap" target="_top">http://sourceware.org/systemtap</a> for more information + on SystemTap.</p></li><li class="listitem"><p><span class="emphasis"><em>Lttng-ust:</em></span> A User-space Tracer designed to + provide detailed information on user-space activity. + See <a class="ulink" href="http://lttng.org/ust" target="_top">http://lttng.org/ust</a> for more information on Lttng-ust. + </p></li></ul></div><p> + </p></div></div></div> + + <div class="chapter" title="Chapter 2. Preparing for Application Development"><div class="titlepage"><div><div><h2 class="title"><a id="adt-prepare"></a>Chapter 2. Preparing for Application Development</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#installing-the-adt">2.1. Installing the ADT and Toolchains</a></span></dt><dd><dl><dt><span class="section"><a href="#using-the-adt-installer">2.1.1. Using the ADT Installer</a></span></dt><dt><span class="section"><a href="#using-an-existing-toolchain-tarball">2.1.2. Using a Cross-Toolchain Tarball</a></span></dt><dt><span class="section"><a href="#using-the-toolchain-from-within-the-build-tree">2.1.3. Using BitBake and the Build Directory</a></span></dt></dl></dd><dt><span class="section"><a href="#setting-up-the-cross-development-environment">2.2. Setting Up the Cross-Development Environment</a></span></dt><dt><span class="section"><a href="#securing-kernel-and-filesystem-images">2.3. Securing Kernel and Filesystem Images</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-the-images">2.3.1. Getting the Images</a></span></dt><dt><span class="section"><a href="#extracting-the-root-filesystem">2.3.2. Extracting the Root Filesystem</a></span></dt></dl></dd></dl></div><p> + In order to develop applications, you need set up your host development system. + Several ways exist that allow you to install cross-development tools, QEMU, the + Eclipse Yocto Plug-in, and other tools. + This chapter describes how to prepare for application development. +</p><div class="section" title="2.1. Installing the ADT and Toolchains"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-the-adt"></a>2.1. Installing the ADT and Toolchains</h2></div></div></div><p> + The following list describes installation methods that set up varying degrees of tool + availabiltiy on your system. + Regardless of the installation method you choose, + you must <code class="filename">source</code> the cross-toolchain + environment setup script before you use a toolchain. + See the "<a class="link" href="#setting-up-the-cross-development-environment" title="2.2. Setting Up the Cross-Development Environment">Setting Up the + Cross-Development Environment</a>" section for more information. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Avoid mixing installation methods when installing toolchains for different architectures. + For example, avoid using the ADT Installer to install some toolchains and then hand-installing + cross-development toolchains from downloaded tarballs to install toolchains + for different architectures. + Mixing installation methods can result in situations where the ADT Installer becomes + unreliable and might not install the toolchain.</p><p>If you must mix installation methods, you might avoid problems by deleting + <code class="filename">/var/lib/opkg</code>, thus purging the <code class="filename">opkg</code> package + metadata</p></div><p> + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Use the ADT Installer Script:</em></span> + This method is the recommended way to install the ADT because it + automates much of the process for you. + For example, you can configure the installation to install the QEMU emulator + and the user-space NFS, specify which root filesystem profiles to download, + and define the target sysroot location.</p></li><li class="listitem"><p><span class="emphasis"><em>Use an Existing Toolchain Tarball:</em></span> + Using this method, you select and download an architecture-specific + toolchain tarball and then hand-install the toolchain. + If you use this method, you just get the cross-toolchain and QEMU - you do not + get any of the other mentioned benefits had you run the ADT Installer script.</p></li><li class="listitem"><p><span class="emphasis"><em>Use the Toolchain from within the Build Directory:</em></span> + If you already have a + <a class="link" href="#build-directory" target="_top">build directory</a>, + you can build the cross-toolchain within the directory. + However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you + do not get any of the other benefits without taking separate steps.</p></li></ul></div><p> + </p><div class="section" title="2.1.1. Using the ADT Installer"><div class="titlepage"><div><div><h3 class="title"><a id="using-the-adt-installer"></a>2.1.1. Using the ADT Installer</h3></div></div></div><p> + To run the ADT Installer, you need to first get the ADT Installer tarball and then run the ADT + Installer Script. + </p><div class="section" title="2.1.1.1. Getting the ADT Installer Tarball"><div class="titlepage"><div><div><h4 class="title"><a id="getting-the-adt-installer-tarball"></a>2.1.1.1. Getting the ADT Installer Tarball</h4></div></div></div><p> + The ADT Installer is contained in the ADT Installer tarball. + You can download the tarball into any directory from the + <a class="ulink" href="http://downloads.yoctoproject.org/releases" target="_top">Index of Releases</a>, specifically + at + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/adt_installer" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/adt_installer</a>. + Or, you can use BitBake to generate the tarball inside the existing + <a class="link" href="#build-directory" target="_top">build directory</a>. + </p><p> + If you use BitBake to generate the ADT Installer tarball, you must + <code class="filename">source</code> the environment setup script + (<code class="filename">oe-init-build-env</code>) located + in the source directory before running the <code class="filename">bitbake</code> + command that creates the tarball. + </p><p> + The following example commands download the Poky tarball, set up the + <a class="link" href="#source-directory" target="_top">source directory</a>, + set up the environment while also creating the default build directory, + and run the <code class="filename">bitbake</code> command that results in the tarball + <code class="filename">~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</code>: + </p><pre class="literallayout"> + $ cd ~ + $ mkdir yocto-project + $ cd yocto-project + $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-1.2+snapshot-8.0.tar.bz2 + $ tar xjf poky-1.2+snapshot-8.0.tar.bz2 + $ source poky-1.2+snapshot-8.0/oe-init-build-env + $ bitbake adt-installer + </pre><p> + </p></div><div class="section" title="2.1.1.2. Configuring and Running the ADT Installer Script"><div class="titlepage"><div><div><h4 class="title"><a id="configuring-and-running-the-adt-installer-script"></a>2.1.1.2. Configuring and Running the ADT Installer Script</h4></div></div></div><p> + Before running the ADT Installer script, you need to unpack the tarball. + You can unpack the tarball in any directory you wish. + For example, this command copies the ADT Installer tarball from where + it was built into the home directory and then unpacks the tarball into + a top-level directory named <code class="filename">adt-installer</code>: + </p><pre class="literallayout"> + $ cd ~ + $ cp ~/poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME + $ tar -xjf adt_installer.tar.bz2 + </pre><p> + Unpacking it creates the directory <code class="filename">adt-installer</code>, + which contains the ADT Installer script (<code class="filename">adt_installer</code>) + and its configuration file (<code class="filename">adt_installer.conf</code>). + </p><p> + Before you run the script, however, you should examine the ADT Installer configuration + file and be sure you are going to get what you want. + Your configurations determine which kernel and filesystem image are downloaded. + </p><p> + The following list describes the configurations you can define for the ADT Installer. + For configuration values and restrictions, see the comments in + the <code class="filename">adt-installer.conf</code> file: + + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">YOCTOADT_REPO</code>: This area + includes the IPKG-based packages and the root filesystem upon which + the installation is based. + If you want to set up your own IPKG repository pointed to by + <code class="filename">YOCTOADT_REPO</code>, you need to be sure that the + directory structure follows the same layout as the reference directory + set up at <a class="ulink" href="http://adtrepo.yoctoproject.org" target="_top">http://adtrepo.yoctoproject.org</a>. + Also, your repository needs to be accessible through HTTP.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_TARGETS</code>: The machine + target architectures for which you want to set up cross-development + environments.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_QEMU</code>: Indicates whether + or not to install the emulator QEMU.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_NFS_UTIL</code>: Indicates whether + or not to install user-mode NFS. + If you plan to use the Eclipse IDE Yocto plug-in against QEMU, + you should install NFS. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>To boot QEMU images using our userspace NFS server, you need + to be running <code class="filename">portmap</code> or <code class="filename">rpcbind</code>. + If you are running <code class="filename">rpcbind</code>, you will also need to add the + <code class="filename">-i</code> option when <code class="filename">rpcbind</code> starts up. + Please make sure you understand the security implications of doing this. + You might also have to modify your firewall settings to allow + NFS booting to work.</div></li><li class="listitem"><p><code class="filename">YOCTOADT_ROOTFS_<arch></code>: The root + filesystem images you want to download from the + <code class="filename">YOCTOADT_IPKG_REPO</code> repository.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_TARGET_SYSROOT_IMAGE_<arch></code>: The + particular root filesystem used to extract and create the target sysroot. + The value of this variable must have been specified with + <code class="filename">YOCTOADT_ROOTFS_<arch></code>. + For example, if you downloaded both <code class="filename">minimal</code> and + <code class="filename">sato-sdk</code> images by setting + <code class="filename">YOCTOADT_ROOTFS_<arch></code> + to "minimal sato-sdk", then <code class="filename">YOCTOADT_ROOTFS_<arch></code> + must be set to either <code class="filename">minimal</code> or + <code class="filename">sato-sdk</code>.</p></li><li class="listitem"><p><code class="filename">YOCTOADT_TARGET_SYSROOT_LOC_<arch></code>: The + location on the development host where the target sysroot is created. + </p></li></ul></div><p> + </p><p> + After you have configured the <code class="filename">adt_installer.conf</code> file, + run the installer using the following command. + Be sure that you are not trying to use cross-compilation tools. + When you run the installer, the environment must use a + host <code class="filename">gcc</code>: + </p><pre class="literallayout"> + $ ./adt_installer + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The ADT Installer requires the <code class="filename">libtool</code> package to complete. + If you install the recommended packages as described in + "<a class="link" href="#packages" target="_top">The Packages</a>" + section of the Yocto Project Quick Start, then you will have libtool installed. + </div><p> + Once the installer begins to run, you are asked whether you want to run in + interactive or silent mode. + If you want to closely monitor the installation, choose “I” for interactive + mode rather than “S” for silent mode. + Follow the prompts from the script to complete the installation. + </p><p> + Once the installation completes, the ADT, which includes the cross-toolchain, is installed. + You will notice environment setup files for the cross-toolchain in + <code class="filename">/opt/poky/1.3</code>, + and image tarballs in the <code class="filename">adt-installer</code> + directory according to your installer configurations, and the target sysroot located + according to the <code class="filename">YOCTOADT_TARGET_SYSROOT_LOC_<arch></code> variable + also in your configuration file. + </p></div></div><div class="section" title="2.1.2. Using a Cross-Toolchain Tarball"><div class="titlepage"><div><div><h3 class="title"><a id="using-an-existing-toolchain-tarball"></a>2.1.2. Using a Cross-Toolchain Tarball</h3></div></div></div><p> + If you want to simply install the cross-toolchain by hand, you can do so by using an existing + cross-toolchain tarball. + If you use this method to install the cross-toolchain and you still need to install the target + sysroot, you will have to install sysroot separately. + </p><p> + Follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Go to + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/toolchain/</a> + and find the folder that matches your host development system + (i.e. <code class="filename">i686</code> for 32-bit machines or + <code class="filename">x86-64</code> for 64-bit machines).</p></li><li class="listitem"><p>Go into that folder and download the toolchain tarball whose name + includes the appropriate target architecture. + For example, if your host development system is an Intel-based 64-bit system and + you are going to use your cross-toolchain for an Intel-based 32-bit target, go into the + <code class="filename">x86_64</code> folder and download the following tarball: + </p><pre class="literallayout"> + poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2 + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>As an alternative to steps one and two, you can build the toolchain tarball + if you have a <a class="link" href="#build-directory" target="_top">build directory</a>. + If you need GMAE, you should use the <code class="filename">bitbake meta-toolchain-gmae</code> + command. + The resulting tarball will support such development. + However, if you are not concerned with GMAE, + you can generate the tarball using <code class="filename">bitbake meta-toolchain</code>.</p><p>Use the appropriate <code class="filename">bitbake</code> command only after you have + sourced the <code class="filename">oe-build-init-env</code> script located in the source + directory. + When the <code class="filename">bitbake</code> command completes, the tarball will + be in <code class="filename">tmp/deploy/sdk</code> in the build directory. + </p></div></li><li class="listitem"><p>Make sure you are in the root directory with root privileges and then expand + the tarball. + The tarball expands into <code class="filename">/opt/poky/1.3</code>. + Once the tarball is expanded, the cross-toolchain is installed. + You will notice environment setup files for the cross-toolchain in the directory. + </p></li></ol></div><p> + </p></div><div class="section" title="2.1.3. Using BitBake and the Build Directory"><div class="titlepage"><div><div><h3 class="title"><a id="using-the-toolchain-from-within-the-build-tree"></a>2.1.3. Using BitBake and the Build Directory</h3></div></div></div><p> + A final way of making the cross-toolchain available is to use BitBake + to generate the toolchain within an existing + <a class="link" href="#build-directory" target="_top">build directory</a>. + This method does not install the toolchain into the + <code class="filename">/opt</code> directory. + As with the previous method, if you need to install the target sysroot, you must + do that separately as well. + </p><p> + Follow these steps to generate the toolchain into the build directory: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Source the environment setup script + <code class="filename">oe-init-build-env</code> located in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + </p></li><li class="listitem"><p>At this point, you should be sure that the + <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> variable + in the <code class="filename">local.conf</code> file found in the + <code class="filename">conf</code> directory of the build directory + is set for the target architecture. + Comments within the <code class="filename">local.conf</code> file list the values you + can use for the <code class="filename">MACHINE</code> variable. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>You can populate the build directory with the cross-toolchains for more + than a single architecture. + You just need to edit the <code class="filename">MACHINE</code> variable in the + <code class="filename">local.conf</code> file and re-run the BitBake + command.</div></li><li class="listitem"><p>Run <code class="filename">bitbake meta-ide-support</code> to complete the + cross-toolchain generation. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If you change out of your working directory after you + <code class="filename">source</code> the environment setup script and before you run + the <code class="filename">bitbake</code> command, the command might not work. + Be sure to run the <code class="filename">bitbake</code> command immediately + after checking or editing the <code class="filename">local.conf</code> but without + changing out of your working directory.</div><p> + Once the <code class="filename">bitbake</code> command finishes, + the cross-toolchain is generated and populated within the build directory. + You will notice environment setup files for the cross-toolchain in the + build directory in the <code class="filename">tmp</code> directory. + Setup script filenames contain the strings <code class="filename">environment-setup</code>. + </p></li></ol></div><p> + </p></div></div><div class="section" title="2.2. Setting Up the Cross-Development Environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="setting-up-the-cross-development-environment"></a>2.2. Setting Up the Cross-Development Environment</h2></div></div></div><p> + Before you can develop using the cross-toolchain, you need to set up the + cross-development environment by sourcing the toolchain's environment setup script. + If you used the ADT Installer or hand-installed cross-toolchain, + then you can find this script in the <code class="filename">/opt/poky/1.3</code> + directory. + If you installed the toolchain in the + <a class="link" href="#build-directory" target="_top">build directory</a>, + you can find the environment setup + script for the toolchain in the build directory's <code class="filename">tmp</code> directory. + </p><p> + Be sure to run the environment setup script that matches the architecture for + which you are developing. + Environment setup scripts begin with the string “<code class="filename">environment-setup</code>” + and include as part of their name the architecture. + For example, the toolchain environment setup script for a 64-bit IA-based architecture would + be the following: + </p><pre class="literallayout"> + /opt/poky/1.3/environment-setup-x86_64-poky-linux + </pre><p> + </p></div><div class="section" title="2.3. Securing Kernel and Filesystem Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="securing-kernel-and-filesystem-images"></a>2.3. Securing Kernel and Filesystem Images</h2></div></div></div><p> + You will need to have a kernel and filesystem image to boot using your + hardware or the QEMU emulator. + Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem + as the target sysroot, you need to extract the root filesystem. + </p><div class="section" title="2.3.1. Getting the Images"><div class="titlepage"><div><div><h3 class="title"><a id="getting-the-images"></a>2.3.1. Getting the Images</h3></div></div></div><p> + To get the kernel and filesystem images, you either have to build them or download + pre-built versions. + You can find examples for both these situations in the + "<a class="link" href="#test-run" target="_top">A Quick Test Run</a>" section of + the Yocto Project Quick Start. + </p><p> + The Yocto Project ships basic kernel and filesystem images for several + architectures (<code class="filename">x86</code>, <code class="filename">x86-64</code>, + <code class="filename">mips</code>, <code class="filename">powerpc</code>, and <code class="filename">arm</code>) + that you can use unaltered in the QEMU emulator. + These kernel images reside in the release + area - <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines" target="_top">http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/machines</a> + and are ideal for experimentation using Yocto Project. + For information on the image types you can build using the OpenEmbedded build system, + see the + "<a class="link" href="#ref-images" target="_top">Images</a>" chapter in + the Yocto Project Reference Manual. + </p><p> + If you plan on remotely deploying and debugging your application from within the + Eclipse IDE, you must have an image that contains the Yocto Target Communication + Framework (TCF) agent (<code class="filename">tcf-agent</code>). + By default, the Yocto Project provides only one type pre-built image that contains the + <code class="filename">tcf-agent</code>. + And, those images are SDK (e.g.<code class="filename">core-image-sato-sdk</code>). + </p><p> + If you want to use a different image type that contains the <code class="filename">tcf-agent</code>, + you can do so one of two ways: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Modify the <code class="filename">conf/local.conf</code> configuration in + the <a class="link" href="#build-directory" target="_top">build directory</a> + and then rebuild the image. + With this method, you need to modify the + <a class="link" href="#var-EXTRA_IMAGE_FEATURES" target="_top"><code class="filename">EXTRA_IMAGE_FEATURES</code></a> + variable to have the value of "tools-debug" before rebuilding the image. + Once the image is rebuilt, the <code class="filename">tcf-agent</code> will be included + in the image and is launched automatically after the boot.</p></li><li class="listitem"><p>Manually build the <code class="filename">tcf-agent</code>. + To build the agent, follow these steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Be sure the ADT is installed as described in the + "<a class="link" href="#installing-the-adt" title="2.1. Installing the ADT and Toolchains">Installing the ADT and Toolchains</a>" section. + </p></li><li class="listitem"><p>Set up the cross-development environment as described in the + "<a class="link" href="#setting-up-the-cross-development-environment" title="2.2. Setting Up the Cross-Development Environment">Setting + Up the Cross-Development Environment</a>" section.</p></li><li class="listitem"><p>Get the <code class="filename">tcf-agent</code> source code using + the following commands: + </p><pre class="literallayout"> + $ git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git + $ cd agent + </pre></li><li class="listitem"><p>Modify the <code class="filename">Makefile.inc</code> file + for the cross-compilation environment by setting the + <code class="filename">OPSYS</code> and + <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> + variables according to your target.</p></li><li class="listitem"><p>Use the cross-development tools to build the + <code class="filename">tcf-agent</code>. + Before you "Make" the file, be sure your cross-tools are set up first. + See the "<a class="link" href="#makefile-based-projects" title="4.2. Makefile-Based Projects">Makefile-Based Projects</a>" + section for information on how to make sure the cross-tools are set up + correctly.</p><p>If the build is successful, the <code class="filename">tcf-agent</code> output will + be <code class="filename">obj/$(OPSYS)/$(MACHINE)/Debug/agent</code>.</p></li><li class="listitem"><p>Deploy the agent into the image's root filesystem.</p></li></ol></div><p> + </p></li></ul></div><p> + </p></div><div class="section" title="2.3.2. Extracting the Root Filesystem"><div class="titlepage"><div><div><h3 class="title"><a id="extracting-the-root-filesystem"></a>2.3.2. Extracting the Root Filesystem</h3></div></div></div><p> + You must extract the root filesystem if you want to boot the image using NFS + or you want to use the root filesystem as the target sysroot. + For example, the Eclipse IDE environment with the Eclipse Yocto Plug-in installed allows you + to use QEMU to boot under NFS. + Another example is if you want to develop your target application using the + root filesystem as the target sysroot. + </p><p> + To extract the root filesystem, first <code class="filename">source</code> + the cross-development environment setup script and then + use the <code class="filename">runqemu-extract-sdk</code> command on the + filesystem image. + For example, the following commands set up the environment and then extract + the root filesystem from a previously built filesystem image tarball named + <code class="filename">core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2</code>. + The example extracts the root filesystem into the <code class="filename">$HOME/qemux86-sato</code> + directory: + </p><pre class="literallayout"> + $ source $HOME/poky/build/tmp/environment-setup-i586-poky-linux + $ runqemu-extract-sdk \ + tmp/deploy/images/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ + $HOME/qemux86-sato + </pre><p> + In this case, you could now point to the target sysroot at + <code class="filename">$HOME/qemux86-sato</code>. + </p></div></div></div> + + <div class="chapter" title="Chapter 3. Optionally Customizing the Development Packages Installation"><div class="titlepage"><div><div><h2 class="title"><a id="adt-package"></a>Chapter 3. Optionally Customizing the Development Packages Installation</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#package-management-systems">3.1. Package Management Systems</a></span></dt><dt><span class="section"><a href="#configuring-the-pms">3.2. Configuring the PMS</a></span></dt></dl></div><p> + Because the Yocto Project is suited for embedded Linux development, it is + likely that you will need to customize your development packages installation. + For example, if you are developing a minimal image, then you might not need + certain packages (e.g. graphics support packages). + Thus, you would like to be able to remove those packages from your target sysroot. + </p><div class="section" title="3.1. Package Management Systems"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="package-management-systems"></a>3.1. Package Management Systems</h2></div></div></div><p> + The OpenEmbedded build system supports the generation of sysroot files using + three different Package Management Systems (PMS): + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>OPKG:</em></span> A less well known PMS whose use + originated in the OpenEmbedded and OpenWrt embedded Linux projects. + This PMS works with files packaged in an <code class="filename">.ipk</code> format. + See <a class="ulink" href="http://en.wikipedia.org/wiki/Opkg" target="_top">http://en.wikipedia.org/wiki/Opkg</a> for more + information about OPKG.</p></li><li class="listitem"><p><span class="emphasis"><em>RPM:</em></span> A more widely known PMS intended for GNU/Linux + distributions. + This PMS works with files packaged in an <code class="filename">.rms</code> format. + The build system currently installs through this PMS by default. + See <a class="ulink" href="http://en.wikipedia.org/wiki/RPM_Package_Manager" target="_top">http://en.wikipedia.org/wiki/RPM_Package_Manager</a> + for more information about RPM.</p></li><li class="listitem"><p><span class="emphasis"><em>Debian:</em></span> The PMS for Debian-based systems + is built on many PMS tools. + The lower-level PMS tool <code class="filename">dpkg</code> forms the base of the Debian PMS. + For information on dpkg see + <a class="ulink" href="http://en.wikipedia.org/wiki/Dpkg" target="_top">http://en.wikipedia.org/wiki/Dpkg</a>.</p></li></ul></div><p> + </p></div><div class="section" title="3.2. Configuring the PMS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="configuring-the-pms"></a>3.2. Configuring the PMS</h2></div></div></div><p> + Whichever PMS you are using, you need to be sure that the + <a class="link" href="#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a> + variable in the <code class="filename">conf/local.conf</code> + file is set to reflect that system. + The first value you choose for the variable specifies the package file format for the root + filesystem at sysroot. + Additional values specify additional formats for convenience or testing. + See the configuration file for details. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + For build performance information related to the PMS, see + <a class="link" href="#ref-classes-package" target="_top">Packaging - <code class="filename">package*.bbclass</code></a> + in the Yocto Project Reference Manual. + </div><p> + As an example, consider a scenario where you are using OPKG and you want to add + the <code class="filename">libglade</code> package to the target sysroot. + </p><p> + First, you should generate the <code class="filename">ipk</code> file for the + <code class="filename">libglade</code> package and add it + into a working <code class="filename">opkg</code> repository. + Use these commands: + </p><pre class="literallayout"> + $ bitbake libglade + $ bitbake package-index + </pre><p> + </p><p> + Next, source the environment setup script found in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + Follow that by setting up the installation destination to point to your + sysroot as <code class="filename"><sysroot_dir></code>. + Finally, have an OPKG configuration file <code class="filename"><conf_file></code> + that corresponds to the <code class="filename">opkg</code> repository you have just created. + The following command forms should now work: + </p><pre class="literallayout"> + $ opkg-cl –f <conf_file> -o <sysroot_dir> update + $ opkg-cl –f <cconf_file> -o <sysroot_dir> \ + --force-overwrite install libglade + $ opkg-cl –f <cconf_file> -o <sysroot_dir> \ + --force-overwrite install libglade-dbg + $ opkg-cl –f <conf_file> -o <sysroot_dir> \ + --force-overwrite install libglade-dev + </pre><p> + </p></div></div> + + <div class="chapter" title="Chapter 4. Using the Command Line"><div class="titlepage"><div><div><h2 class="title"><a id="using-the-command-line"></a>Chapter 4. Using the Command Line</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#autotools-based-projects">4.1. Autotools-Based Projects</a></span></dt><dt><span class="section"><a href="#makefile-based-projects">4.2. Makefile-Based Projects</a></span></dt></dl></div><p> + Recall that earlier the manual discussed how to use an existing toolchain + tarball that had been installed into <code class="filename">/opt/poky</code>, + which is outside of the build directory + (see the section "<a class="link" href="#using-an-existing-toolchain-tarball" title="2.1.2. Using a Cross-Toolchain Tarball">Using an Existing + Toolchain Tarball)</a>". + And, that sourcing your architecture-specific environment setup script + initializes a suitable cross-toolchain development environment. + During the setup, locations for the compiler, QEMU scripts, QEMU binary, + a special version of <code class="filename">pkgconfig</code> and other useful + utilities are added to the <code class="filename">PATH</code> variable. + Variables to assist <code class="filename">pkgconfig</code> and <code class="filename">autotools</code> + are also defined so that, + for example, <code class="filename">configure.sh</code> can find pre-generated + test results for tests that need target hardware on which to run. + These conditions allow you to easily use the toolchain outside of the + OpenEmbedded build environment on both autotools-based projects and + Makefile-based projects. + </p><div class="section" title="4.1. Autotools-Based Projects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="autotools-based-projects"></a>4.1. Autotools-Based Projects</h2></div></div></div><p> + For an Autotools-based project, you can use the cross-toolchain by just + passing the appropriate host option to <code class="filename">configure.sh</code>. + The host option you use is derived from the name of the environment setup + script in <code class="filename">/opt/poky</code> resulting from unpacking the + cross-toolchain tarball. + For example, the host option for an ARM-based target that uses the GNU EABI + is <code class="filename">armv5te-poky-linux-gnueabi</code>. + Note that the name of the script is + <code class="filename">environment-setup-armv5te-poky-linux-gnueabi</code>. + Thus, the following command works: + </p><pre class="literallayout"> + $ configure --host=armv5te-poky-linux-gnueabi \ + --with-libtool-sysroot=<sysroot-dir> + </pre><p> + </p><p> + This single command updates your project and rebuilds it using the appropriate + cross-toolchain tools. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + If <code class="filename">configure</code> script results in problems recognizing the + <code class="filename">--with-libtool-sysroot=<sysroot-dir></code> option, + regenerate the script to enable the support by doing the following and then + re-running the script: + <pre class="literallayout"> + $ libtoolize --automake + $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ + [-I <dir_containing_your_project-specific_m4_macros>] + $ autoconf + $ autoheader + $ automake -a + </pre></div></div><div class="section" title="4.2. Makefile-Based Projects"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="makefile-based-projects"></a>4.2. Makefile-Based Projects</h2></div></div></div><p> + For a Makefile-based project, you use the cross-toolchain by making sure + the tools are used. + You can do this as follows: + </p><pre class="literallayout"> + CC=arm-poky-linux-gnueabi-gcc + LD=arm-poky-linux-gnueabi-ld + CFLAGS=”${CFLAGS} --sysroot=<sysroot-dir>” + CXXFLAGS=”${CXXFLAGS} --sysroot=<sysroot-dir>” + </pre><p> + </p></div></div> + + + +</div> + +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/bsp-title.png" align="left" width="100%" /></td></tr></table> + + <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="bsp-guide"></a></h1></div><div><div class="authorgroup"> + <div class="author"><h3 class="author"><span class="firstname">Tom</span> <span class="surname">Zanussi</span></h3><div class="affiliation"> + <span class="orgname">Intel Corporation<br /></span> + </div><code class="email"><<a class="email" href="mailto:tom.zanussi@intel.com">tom.zanussi@intel.com</a>></code></div> + <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"> + <span class="orgname">Linux Foundation<br /></span> + </div><code class="email"><<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>></code></div> + </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1501714"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/" target="_top">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. + </p> + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + Yocto Project Board Support Package (BSP) Developer's Guide on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> + <tr><td align="left">Revision 0.9</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">The initial document draft released with the Yocto Project 0.9 Release.</td></tr> + <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> + <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> + <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> + <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + </table></div></div></div><hr /></div> + + + <div class="chapter" title="Chapter 1. Board Support Packages (BSP) - Developer's Guide"><div class="titlepage"><div><div><h2 class="title"><a id="bsp"></a>Chapter 1. Board Support Packages (BSP) - Developer's Guide</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#bsp-layers">1.1. BSP Layers</a></span></dt><dt><span class="section"><a href="#bsp-filelayout">1.2. Example Filesystem Layout</a></span></dt><dd><dl><dt><span class="section"><a href="#bsp-filelayout-license">1.2.1. License Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-readme">1.2.2. README File</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-readme-sources">1.2.3. README.sources File</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-binary">1.2.4. Pre-built User Binaries</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-layer">1.2.5. Layer Configuration File</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-machine">1.2.6. Hardware Configuration Options</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-misc-recipes">1.2.7. Miscellaneous Recipe Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-core-recipes">1.2.8. Core Recipe Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-recipes-graphics">1.2.9. Display Support Files</a></span></dt><dt><span class="section"><a href="#bsp-filelayout-kernel">1.2.10. Linux Kernel Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#requirements-and-recommendations-for-released-bsps">1.3. Requirements and Recommendations for Released BSPs</a></span></dt><dd><dl><dt><span class="section"><a href="#released-bsp-requirements">1.3.1. Released BSP Requirements</a></span></dt><dt><span class="section"><a href="#released-bsp-recommendations">1.3.2. Released BSP Recommendations</a></span></dt></dl></dd><dt><span class="section"><a href="#customizing-a-recipe-for-a-bsp">1.4. Customizing a Recipe for a BSP</a></span></dt><dt><span class="section"><a href="#bsp-licensing-considerations">1.5. BSP Licensing Considerations</a></span></dt><dt><span class="section"><a href="#using-the-yocto-projects-bsp-tools">1.6. Using the Yocto Project's BSP Tools</a></span></dt><dd><dl><dt><span class="section"><a href="#common-features">1.6.1. Common Features</a></span></dt><dt><span class="section"><a href="#creating-a-new-bsp-layer-using-the-yocto-bsp-script">1.6.2. Creating a new BSP Layer Using the yocto-bsp Script</a></span></dt><dt><span class="section"><a href="#managing-kernel-patches-and-config-items-with-yocto-kernel">1.6.3. Managing Kernel Patches and Config Items with yocto-kernel</a></span></dt></dl></dd></dl></div><p> + A Board Support Package (BSP) is a collection of information that + defines how to support a particular hardware device, set of devices, or + hardware platform. + The BSP includes information about the hardware features + present on the device and kernel configuration information along with any + additional hardware drivers required. + The BSP also lists any additional software + components required in addition to a generic Linux software stack for both + essential and optional platform features. + </p><p> + This chapter (or document if you are reading the BSP Developer's Guide) + talks about BSP Layers, defines a structure for components + so that BSPs follow a commonly understood layout, discusses how to customize + a recipe for a BSP, addresses BSP licensing, and provides information that + shows you how to create and manage a + <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layer</a> using two Yocto Project + <a class="link" href="#using-the-yocto-projects-bsp-tools" title="1.6. Using the Yocto Project's BSP Tools">BSP Tools</a>. + </p><div class="section" title="1.1. BSP Layers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bsp-layers"></a>1.1. BSP Layers</h2></div></div></div><p> + The BSP consists of a file structure inside a base directory. + Collectively, you can think of the base directory and the file structure + as a BSP Layer. + BSP Layers use the following naming convention: + </p><pre class="literallayout"> + meta-<bsp_name> + </pre><p> + "bsp_name" is a placeholder for the machine or platform name. + </p><p> + The layer's base directory (<code class="filename">meta-<bsp_name></code>) is the root + of the BSP Layer. + This root is what you add to the + <a class="link" href="#var-BBLAYERS" target="_top"><code class="filename">BBLAYERS</code></a> + variable in the <code class="filename">conf/bblayers.conf</code> file found in the + <a class="link" href="#build-directory" target="_top">build directory</a>. + Adding the root allows the OpenEmbedded build system to recognize the BSP + definition and from it build an image. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS = " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-<bsp_name> \ + " + </pre><p> + </p><p> + Some BSPs require additional layers on + top of the BSP's root layer in order to be functional. + For these cases, you also need to add those layers to the + <code class="filename">BBLAYERS</code> variable in order to build the BSP. + You must also specify in the "Dependencies" section of the BSP's + <code class="filename">README</code> file any requirements for additional + layers and, preferably, any + build instructions that might be contained elsewhere + in the <code class="filename">README</code> file. + </p><p> + Some layers function as a layer to hold other BSP layers. + An example of this type of layer is the <code class="filename">meta-intel</code> layer. + The <code class="filename">meta-intel</code> layer contains over 10 individual BSP layers. + </p><p> + For more detailed information on layers, see the + "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding and Creating Layers</a>" + section of the Yocto Project Development Manual. + You can also see the detailed examples in the appendices of the + Yocto Project Development Manual. + </p></div><div class="section" title="1.2. Example Filesystem Layout"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bsp-filelayout"></a>1.2. Example Filesystem Layout</h2></div></div></div><p> + Providing a common form allows end-users to understand and become familiar + with the layout. + A common format also encourages standardization of software support of hardware. + </p><p> + The proposed form does have elements that are specific to the + OpenEmbedded build system. + It is intended that this information can be + used by other build systems besides the OpenEmbedded build system + and that it will be simple + to extract information and convert it to other formats if required. + The OpenEmbedded build system, through its standard layers mechanism, can directly + accept the format described as a layer. + The BSP captures all + the hardware-specific details in one place in a standard format, which is + useful for any person wishing to use the hardware platform regardless of + the build system they are using. + </p><p> + The BSP specification does not include a build system or other tools - + it is concerned with the hardware-specific components only. + At the end-distribution point, you can ship the BSP combined with a build system + and other tools. + However, it is important to maintain the distinction that these + are separate components that happen to be combined in certain end products. + </p><p> + Before looking at the common form for the file structure inside a BSP Layer, + you should be aware that some requirements do exist in order for a BSP to + be considered compliant with the Yocto Project. + For that list of requirements, see the + "<a class="link" href="#released-bsp-requirements" title="1.3.1. Released BSP Requirements">Released BSP Requirements</a>" + section. + </p><p> + Below is the common form for the file structure inside a BSP Layer. + While you can use this basic form for the standard, realize that the actual structures + for specific BSPs could differ. + + </p><pre class="literallayout"> + meta-<bsp_name>/ + meta-<bsp_name>/<bsp_license_file> + meta-<bsp_name>/README + meta-<bsp_name>/README.sources + meta-<bsp_name>/binary/<bootable_images> + meta-<bsp_name>/conf/layer.conf + meta-<bsp_name>/conf/machine/*.conf + meta-<bsp_name>/recipes-bsp/* + meta-<bsp_name>/recipes-core/* + meta-<bsp_name>/recipes-graphics/* + meta-<bsp_name>/recipes-kernel/linux/linux-yocto_<kernel_rev>.bbappend + </pre><p> + </p><p> + Below is an example of the Crown Bay BSP: + + </p><pre class="literallayout"> + meta-crownbay/COPYING.MIT + meta-crownbay/README + meta-crownbay/README.sources + meta-crownbay/binary/ + meta-crownbay/conf/ + meta-crownbay/conf/layer.conf + meta-crownbay/conf/machine/ + meta-crownbay/conf/machine/crownbay.conf + meta-crownbay/conf/machine/crownbay-noemgd.conf + meta-crownbay/recipes-bsp/ + meta-crownbay/recipes-bsp/formfactor/ + meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend + meta-crownbay/recipes-bsp/formfactor/formfactor/ + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/ + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig + meta-crownbay/recipes-core/ + meta-crownbay/recipes-core/tasks/ + meta-crownbay/recipes-core/tasks/task-core-tools-profile.bbappend + meta-crownbay/recipes-graphics/ + meta-crownbay/recipes-graphics/xorg-xserver/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/ + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf + meta-crownbay/recipes-kernel/ + meta-crownbay/recipes-kernel/linux/ + meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.0.bbappend + meta-crownbay/recipes-kernel/linux/linux-yocto_2.6.37.bbappend + meta-crownbay/recipes-kernel/linux/linux-yocto_3.0.bbappend + </pre><p> + </p><p> + The following sections describe each part of the proposed BSP format. + </p><div class="section" title="1.2.1. License Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-license"></a>1.2.1. License Files</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/<bsp_license_file> + </pre><p> + </p><p> + These optional files satisfy licensing requirements for the BSP. + The type or types of files here can vary depending on the licensing requirements. + For example, in the Crown Bay BSP all licensing requirements are handled with the + <code class="filename">COPYING.MIT</code> file. + </p><p> + Licensing files can be MIT, BSD, GPLv*, and so forth. + These files are recommended for the BSP but are optional and totally up to the BSP developer. + </p></div><div class="section" title="1.2.2. README File"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-readme"></a>1.2.2. README File</h3></div></div></div><p> + You can find this file in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/README + </pre><p> + </p><p> + This file provides information on how to boot the live images that are optionally + included in the <code class="filename">binary/</code> directory. + The <code class="filename">README</code> file also provides special information needed for + building the image. + </p><p> + At a minimum, the <code class="filename">README</code> file must + contain a list of dependencies, such as the names of + any other layers on which the BSP depends and the name of + the BSP maintainer with his or her contact information. + </p></div><div class="section" title="1.2.3. README.sources File"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-readme-sources"></a>1.2.3. README.sources File</h3></div></div></div><p> + You can find this file in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/README.sources + </pre><p> + </p><p> + This file provides information on where to locate the BSP source files. + For example, information provides where to find the sources that comprise + the images shipped with the BSP. + Information is also included to help you find the metadata used to generate the images + that ship with the BSP. + </p></div><div class="section" title="1.2.4. Pre-built User Binaries"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-binary"></a>1.2.4. Pre-built User Binaries</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/binary/<bootable_images> + </pre><p> + </p><p> + This optional area contains useful pre-built kernels and user-space filesystem + images appropriate to the target system. + This directory typically contains graphical (e.g. sato) and minimal live images + when the BSP tarball has been created and made available in the + <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + You can use these kernels and images to get a system running and quickly get started + on development tasks. + </p><p> + The exact types of binaries present are highly hardware-dependent. + However, a README file should be present in the BSP Layer that explains how to use + the kernels and images with the target hardware. + If pre-built binaries are present, source code to meet licensing requirements must also + exist in some form. + </p></div><div class="section" title="1.2.5. Layer Configuration File"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-layer"></a>1.2.5. Layer Configuration File</h3></div></div></div><p> + You can find this file in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/conf/layer.conf + </pre><p> + </p><p> + The <code class="filename">conf/layer.conf</code> file identifies the file structure as a + layer, identifies the + contents of the layer, and contains information about how the build + system should use it. + Generally, a standard boilerplate file such as the following works. + In the following example, you would replace "<code class="filename">bsp</code>" and + "<code class="filename">_bsp</code>" with the actual name + of the BSP (i.e. <code class="filename"><bsp_name></code> from the example template). + </p><p> + </p><pre class="literallayout"> + # We have a conf and classes directory, add to BBPATH + BBPATH := "${BBPATH}:${LAYERDIR}" + + # We have a recipes directory, add to BBFILES + BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*.bb \ + ${LAYERDIR}/recipes-*/*.bbappend" + + BBFILE_COLLECTIONS += "bsp" + BBFILE_PATTERN_bsp := "^${LAYERDIR}/" + BBFILE_PRIORITY_bsp = "6" + </pre><p> + </p><p> + To illustrate the string substitutions, here are the last three statements from the Crown + Bay <code class="filename">conf/layer.conf</code> file: + </p><pre class="literallayout"> + BBFILE_COLLECTIONS += "crownbay" + BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" + BBFILE_PRIORITY_crownbay = "6" + </pre><p> + </p><p> + This file simply makes BitBake aware of the recipes and configuration directories. + The file must exist so that the OpenEmbedded build system can recognize the BSP. + </p></div><div class="section" title="1.2.6. Hardware Configuration Options"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-machine"></a>1.2.6. Hardware Configuration Options</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/conf/machine/*.conf + </pre><p> + </p><p> + The machine files bind together all the information contained elsewhere + in the BSP into a format that the build system can understand. + If the BSP supports multiple machines, multiple machine configuration files + can be present. + These filenames correspond to the values to which users have set the + <a class="link" href="#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a> variable. + </p><p> + These files define things such as the kernel package to use + (<a class="link" href="#var-PREFERRED_PROVIDER" target="_top"><code class="filename">PREFERRED_PROVIDER</code></a> + of virtual/kernel), the hardware drivers to + include in different types of images, any special software components + that are needed, any bootloader information, and also any special image + format requirements. + </p><p> + Each BSP Layer requires at least one machine file. + However, you can supply more than one file. + For example, in the Crown Bay BSP shown earlier in this section, the + <code class="filename">conf/machine</code> directory contains two configuration files: + <code class="filename">crownbay.conf</code> and <code class="filename">crownbay-noemgd.conf</code>. + The <code class="filename">crownbay.conf</code> file is used for the Crown Bay BSP + that supports the <span class="trademark">Intel</span>® Embedded + Media and Graphics Driver (<span class="trademark">Intel</span>® + EMGD), while the <code class="filename">crownbay-noemgd.conf</code> file is used for the + Crown Bay BSP that does not support the <span class="trademark">Intel</span>® + EMGD. + </p><p> + This <code class="filename">crownbay.conf</code> file could also include + a hardware "tuning" file that is commonly used to + define the package architecture and specify + optimization flags, which are carefully chosen to give best + performance on a given processor. + </p><p> + Tuning files are found in the <code class="filename">meta/conf/machine/include</code> + directory within the + <a class="link" href="#source-directory" target="_top">source directory</a>. + Tuning files can also reside in the BSP Layer itself. + For example, the <code class="filename">ia32-base.inc</code> file resides in the + <code class="filename">meta-intel</code> BSP Layer in <code class="filename">conf/machine/include</code>. + </p><p> + To use an include file, you simply include them in the machine configuration file. + For example, the Crown Bay BSP <code class="filename">crownbay.conf</code> has the + following statements: + </p><pre class="literallayout"> + include conf/machine/include/tune-atom.inc + include conf/machine/include/ia32-base.inc + </pre><p> + </p></div><div class="section" title="1.2.7. Miscellaneous Recipe Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-misc-recipes"></a>1.2.7. Miscellaneous Recipe Files</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/recipes-bsp/* + </pre><p> + </p><p> + This optional directory contains miscellaneous recipe files for the BSP. + Most notably would be the formfactor files. + For example, in the Crown Bay BSP there is the + <code class="filename">formfactor_0.0.bbappend</code> file, which is an append file used + to augment the recipe that starts the build. + Furthermore, there are machine-specific settings used during the build that are + defined by the <code class="filename">machconfig</code> files. + In the Crown Bay example, two <code class="filename">machconfig</code> files exist: + one that supports the + <span class="trademark">Intel</span>® Embedded + Media and Graphics Driver (<span class="trademark">Intel</span>® + EMGD) and one that does not: + </p><pre class="literallayout"> + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig + meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + If a BSP does not have a formfactor entry, defaults are established according to + the formfactor configuration file that is installed by the main + formfactor recipe + <code class="filename">meta/recipes-bsp/formfactor/formfactor_0.0.bb</code>, + which is found in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + </p></div></div><div class="section" title="1.2.8. Core Recipe Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-core-recipes"></a>1.2.8. Core Recipe Files</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/recipes-core/* + </pre><p> + </p><p> + This directory contains recipe files that are almost always necessary to build a + useful, working Linux image. + Thus, the term "core" is used to group these recipes. + For example, in the Crown Bay BSP there is the + <code class="filename">task-core-tools-profile.bbappend</code> file, which is an append file used + to recommend that the + <a class="ulink" href="http://sourceware.org/systemtap/wiki" target="_top">SystemTap</a> + package be included as a package when the image is built. + </p></div><div class="section" title="1.2.9. Display Support Files"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-recipes-graphics"></a>1.2.9. Display Support Files</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/recipes-graphics/* + </pre><p> + </p><p> + This optional directory contains recipes for the BSP if it has + special requirements for graphics support. + All files that are needed for the BSP to support a display are kept here. + For example, the Crown Bay BSP contains two versions of the + <code class="filename">xorg.conf</code> file. + The version in <code class="filename">crownbay</code> builds a BSP that supports the + <span class="trademark">Intel</span>® Embedded Media Graphics Driver (EMGD), + while the version in <code class="filename">crownbay-noemgd</code> builds + a BSP that supports Video Electronics Standards Association (VESA) graphics only: + </p><pre class="literallayout"> + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf + meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd/xorg.conf + </pre><p> + </p></div><div class="section" title="1.2.10. Linux Kernel Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-filelayout-kernel"></a>1.2.10. Linux Kernel Configuration</h3></div></div></div><p> + You can find these files in the BSP Layer at: + </p><pre class="literallayout"> + meta-<bsp_name>/recipes-kernel/linux/linux-yocto_*.bbappend + </pre><p> + </p><p> + These files append your specific changes to the main kernel recipe you are using. + </p><p> + For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the + <a class="link" href="#source-directory" target="_top">source directory</a> + at <code class="filename">meta/recipes-kernel/linux</code>. + You can append your specific changes to the kernel recipe by using a + similarly named append file, which is located in the BSP Layer (e.g. + the <code class="filename">meta-<bsp_name>/recipes-kernel/linux</code> directory). + </p><p> + Suppose you are using the <code class="filename">linux-yocto_3.4.bb</code> recipe to build + the kernel. + In other words, you have selected the kernel in your + <code class="filename"><bsp_name>.conf</code> file by adding the following statements: + </p><pre class="literallayout"> + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto = "3.4%" + </pre><p> + You would use the <code class="filename">linux-yocto_3.4.bbappend</code> file to append + specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. + </p><p> + As an example, look at the existing Crown Bay BSP. + The append file used is: + </p><pre class="literallayout"> + meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend + </pre><p> + The following listing shows the file. + Be aware that the actual commit ID strings in this example listing might be different + than the actual strings in the file from the <code class="filename">meta-intel</code> + Git source repository. + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/default/crownbay" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/default/crownbay" + + SRCREV_machine_pn-linux-yocto_crownbay ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" + SRCREV_meta_pn-linux-yocto_crownbay ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" + + SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" + SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" + </pre><p> + This append file contains statements used to support the Crown Bay BSP for both + <span class="trademark">Intel</span>® EMGD and the VESA graphics. + The build process, in this case, recognizes and uses only the statements that + apply to the defined machine name - <code class="filename">crownbay</code> in this case. + So, the applicable statements in the <code class="filename">linux-yocto_3.4.bbappend</code> + file are follows: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/default/crownbay" + + SRCREV_machine_pn-linux-yocto_crownbay ?= "48101e609711fcfe8d5e737a37a5a69f4bd57d9a" + SRCREV_meta_pn-linux-yocto_crownbay ?= "5b4c9dc78b5ae607173cc3ddab9bce1b5f78129b" + </pre><p> + The append file defines <code class="filename">crownbay</code> as the + <a class="link" href="#var-COMPATIBLE_MACHINE" target="_top"><code class="filename">COMPATIBLE_MACHINE</code></a> + and uses the + <a class="link" href="#var-KMACHINE" target="_top"><code class="filename">KMACHINE</code></a> variable to + ensure the machine name used by the OpenEmbedded build system maps to the + machine name used by the Linux Yocto kernel. + The file also uses the optional + <a class="link" href="#var-KBRANCH" target="_top"><code class="filename">KBRANCH</code></a> variable + to ensure the build process uses the <code class="filename">standard/default/crownbay</code> + kernel branch. + Finally, the append file points to the specific top commits in the + <a class="link" href="#source-directory" target="_top">source directory</a> Git + repository and the <code class="filename">meta</code> Git repository branches to identify the + exact kernel needed to build the Crown Bay BSP. + </p><p> + One thing missing in this particular BSP, which you will typically need when + developing a BSP, is the kernel configuration file (<code class="filename">.config</code>) for your BSP. + When developing a BSP, you probably have a kernel configuration file or a set of kernel + configuration files that, when taken together, define the kernel configuration for your BSP. + You can accomplish this definition by putting the configurations in a file or a set of files + inside a directory located at the same level as your kernel's append file and having the same + name as the kernel's main recipe file. + With all these conditions met, simply reference those files in a + <code class="filename">SRC_URI</code> statement in the append file. + </p><p> + For example, suppose you had a some configuration options in a file called + <code class="filename">network_configs.cfg</code>. + You can place that file inside a directory named <code class="filename">/linux-yocto</code> and then add + a <code class="filename">SRC_URI</code> statement such as the following to the append file. + When the OpenEmbedded build system builds the kernel, the configuration options are + picked up and applied. + </p><pre class="literallayout"> + SRC_URI += "file://network_configs.cfg" + </pre><p> + </p><p> + To group related configurations into multiple files, you perform a similar procedure. + Here is an example that groups separate configurations specifically for Ethernet and graphics + into their own files and adds the configurations + by using a <code class="filename">SRC_URI</code> statement like the following in your append file: + </p><pre class="literallayout"> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </pre><p> + </p><p> + The <code class="filename">FILESEXTRAPATHS</code> variable is in boilerplate form in the + previous example in order to make it easy to do that. + This variable must be in your layer or BitBake will not find the patches or + configurations even if you have them in your <code class="filename">SRC_URI</code>. + The <code class="filename">FILESEXTRAPATHS</code> variable enables the build process to + find those configuration files. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + Other methods exist to accomplish grouping and defining configuration options. + For example, if you are working with a local clone of the kernel repository, + you could checkout the kernel's <code class="filename">meta</code> branch, make your changes, + and then push the changes to the local bare clone of the kernel. + The result is that you directly add configuration options to the + <code class="filename">meta</code> branch for your BSP. + The configuration options will likely end up in that location anyway if the BSP gets + added to the Yocto Project. + For an example showing how to change the BSP configuration, see the + "<a class="link" href="#changing-the-bsp-configuration" target="_top">Changing the BSP Configuration</a>" + section in the Yocto Project Development Manual. + For a better understanding of working with a local clone of the kernel repository + and a local bare clone of the kernel, see the + "<a class="link" href="#modifying-the-kernel-source-code" target="_top">Modifying the Kernel + Source Code</a>" section also in the Yocto Project Development Manual. + </p><p> + In general, however, the Yocto Project maintainers take care of moving the + <code class="filename">SRC_URI</code>-specified + configuration options to the kernel's <code class="filename">meta</code> branch. + Not only is it easier for BSP developers to not have to worry about putting those + configurations in the branch, but having the maintainers do it allows them to apply + 'global' knowledge about the kinds of common configuration options multiple BSPs in + the tree are typically using. + This allows for promotion of common configurations into common features. + </p></div></div></div><div class="section" title="1.3. Requirements and Recommendations for Released BSPs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="requirements-and-recommendations-for-released-bsps"></a>1.3. Requirements and Recommendations for Released BSPs</h2></div></div></div><p> + Certain requirements exist for a released BSP to be considered + compliant with the Yocto Project. + Additionally, a single recommendation also exists. + This section describes the requirements and recommendation for + released BSPs. + </p><div class="section" title="1.3.1. Released BSP Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="released-bsp-requirements"></a>1.3.1. Released BSP Requirements</h3></div></div></div><p> + Before looking at BSP requirements, you should consider the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The requirements here assume the BSP layer is a well-formed, "legal" + layer that can be added to the Yocto Project. + For guidelines on creating a layer that meets these base requirements, see the + "<a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layers</a>" and the + "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding + and Creating Layers"</a> in the Yocto Project Development Manual.</p></li><li class="listitem"><p>The requirements in this section apply regardless of how you + ultimately package a BSP. + You should consult the packaging and distribution guidelines for your + specific release process. + For an example of packaging and distribution requirements, see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process" target="_top">Third + Party BSP Release Process</a> wiki page.</p></li><li class="listitem"><p>The requirements for the BSP as it is made available to a developer + are completely independent of the released form of the BSP. + For example, the BSP metadata can be contained within a Git repository + and could have a directory structure completely different from what appears + in the officially released BSP layer.</p></li><li class="listitem"><p>It is not required that specific packages or package + modifications exist in the BSP layer, beyond the requirements for general + compliance with the Yocto Project. + For example, no requirement exists dictating that a specific kernel or + kernel version be used in a given BSP.</p></li></ul></div><p> + </p><p> + Following are the requirements for a released BSP that conforms to the + Yocto Project: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Layer Name:</em></span> + The BSP must have a layer name that follows the Yocto + Project standards. + For information on BSP layer names, see the + "<a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layers</a>" section. + </p></li><li class="listitem"><p><span class="emphasis"><em>File System Layout:</em></span> + When possible, use the same directory names in your + BSP layer as listed in the <code class="filename">recipes.txt</code> file. + In particular, you should place recipes + (<code class="filename">.bb</code> files) and recipe + modifications (<code class="filename">.bbappend</code> files) into + <code class="filename">recipes-*</code> subdirectories by functional area + as outlined in <code class="filename">recipes.txt</code>. + If you cannot find a category in <code class="filename">recipes.txt</code> + to fit a particular recipe, you can make up your own + <code class="filename">recipe-*</code> subdirectory. + You can find <code class="filename">recipes.txt</code> in the + <code class="filename">meta</code> directory of the + <a class="link" href="#source-directory" target="_top">source directory</a>, + or in the OpenEmbedded Core Layer + (<code class="filename">openembedded-core</code>) found at + <a class="ulink" href="http://git.openembedded.org/openembedded-core/tree/meta" target="_top">http://git.openembedded.org/openembedded-core/tree/meta</a>. + </p><p>Within any particular <code class="filename">recipes-*</code> category, the layout + should match what is found in the OpenEmbedded Core + Git repository (<code class="filename">openembedded-core</code>) + or the source directory (<code class="filename">poky</code>). + In other words, make sure you place related files in appropriately + related <code class="filename">recipes-*</code> subdirectories specific to the + recipe's function, or within a subdirectory containing a set of closely-related + recipes. + The recipes themselves should follow the general guidelines + for recipes used in the Yocto Project found in the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide" target="_top">Yocto + Recipe and Patch Style Guide</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>License File:</em></span> + You must include a license file in the + <code class="filename">meta-<bsp_name></code> directory. + This license covers the BSP metadata as a whole. + You must specify which license to use since there is no + default license if one is not specified. + See the + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/meta-intel/tree/meta-fishriver/COPYING.MIT" target="_top"><code class="filename">COPYING.MIT</code></a> + file for the Fish River BSP in the <code class="filename">meta-fishriver</code> BSP layer + as an example.</p></li><li class="listitem"><p><span class="emphasis"><em>README File:</em></span> + You must include a <code class="filename">README</code> file in the + <code class="filename">meta-<bsp_name></code> directory. + See the + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/meta-intel/tree/meta-fishriver/README" target="_top"><code class="filename">README</code></a> + file for the Fish River BSP in the <code class="filename">meta-fishriver</code> BSP layer + as an example.</p><p>At a minimum, the <code class="filename">README</code> file should + contain the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>A brief description about the hardware the BSP + targets.</p></li><li class="listitem"><p>A list of all the dependencies a + on which a BSP layer depends. + These dependencies are typically a list of required layers needed + to build the BSP. + However, the dependencies should also contain information regarding + any other dependencies the BSP might have.</p></li><li class="listitem"><p>Any required special licensing information. + For example, this information includes information on + special variables needed to satisfy a EULA, + or instructions on information needed to build or distribute + binaries built from the BSP metadata.</p></li><li class="listitem"><p>The name and contact information for the + BSP layer maintainer. + This is the person to whom patches and questions should + be sent.</p></li><li class="listitem"><p>Instructions on how to build the BSP using the BSP + layer.</p></li><li class="listitem"><p>Instructions on how to boot the BSP build from + the BSP layer.</p></li><li class="listitem"><p>Instructions on how to boot the binary images + contained in the <code class="filename">/binary</code> directory, + if present.</p></li><li class="listitem"><p>Information on any known bugs or issues that users + should know about when either building or booting the BSP + binaries.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em>README.sources File:</em></span> + You must include a <code class="filename">README.sources</code> in the + <code class="filename">meta-<bsp_name></code> directory. + This file specifies exactly where you can find the sources used to + generate the binary images contained in the + <code class="filename">/binary</code> directory, if present. + See the + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/meta-intel/tree/meta-fishriver/README.sources" target="_top"><code class="filename">README.sources</code></a> + file for the Fish River BSP in the <code class="filename">meta-fishriver</code> BSP layer + as an example.</p></li><li class="listitem"><p><span class="emphasis"><em>Layer Configuration File:</em></span> + You must include a <code class="filename">conf/layer.conf</code> in the + <code class="filename">meta-<bsp_name></code> directory. + This file identifies the <code class="filename">meta-<bsp_name></code> + BSP layer as a layer to the build system.</p></li><li class="listitem"><p><span class="emphasis"><em>Machine Configuration File:</em></span> + You must include a <code class="filename">conf/machine/<bsp_name>.conf</code> + in the <code class="filename">meta-<bsp_name></code> directory. + This configuration file defines a machine target that can be built + using the BSP layer. + Multiple machine configuration files define variations of machine + configurations that are supported by the BSP. + If a BSP supports more multiple machine variations, you need to + adequately describe each variation in the BSP + <code class="filename">README</code> file. + Do not use multiple machine configuration files to describe disparate + hardware. + Multiple machine configuration files should describe very similar targets. + If you do have very different targets, you should create a separate + BSP. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>It is completely possible for a developer to structure the + working repository as a conglomeration of unrelated BSP + files, and to possibly generate specifically targeted 'release' BSPs + from that directory using scripts or some other mechanism. + Such considerations are outside the scope of this document.</div><p> + </p></li></ul></div><p> + </p></div><div class="section" title="1.3.2. Released BSP Recommendations"><div class="titlepage"><div><div><h3 class="title"><a id="released-bsp-recommendations"></a>1.3.2. Released BSP Recommendations</h3></div></div></div><p> + Following are recommendations for a released BSP that conforms to the + Yocto Project: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Bootable Images:</em></span> + BSP releases + can contain one or more bootable images. + Including bootable images allows users to easily try out the BSP + on their own hardware.</p><p>In some cases, it might not be convenient to include a + bootable image. + In this case, you might want to make two versions of the + BSP available: one that contains binary images, and one + that does not. + The version that does not contain bootable images avoids + unnecessary download times for users not interested in the images. + </p><p>If you need to distribute a BSP and include bootable images or build kernel and + filesystems meant to allow users to boot the BSP for evaluation + purposes, you should put the images and artifacts within a + <code class="filename">binary/</code> subdirectory located in the + <code class="filename">meta-<bsp_name></code> directory. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If you do include a bootable image as part of the BSP and the image + was built by software covered by the GPL or other open source licenses, + it is your responsibility to understand + and meet all licensing requirements, which could include distribution + of source files.</div></li><li class="listitem"><p><span class="emphasis"><em>Use a Yocto Linux Kernel:</em></span> + Kernel recipes in the BSP should be based on a Yocto Linux kernel. + Basing your recipes on these kernels reduces the costs for maintaining + the BSP and increases its scalability. + See the <code class="filename">Yocto Linux Kernel</code> category in the + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top"><code class="filename">Yocto Source Repositories</code></a> + for these kernels.</p></li></ul></div><p> + </p></div></div><div class="section" title="1.4. Customizing a Recipe for a BSP"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="customizing-a-recipe-for-a-bsp"></a>1.4. Customizing a Recipe for a BSP</h2></div></div></div><p> + If you plan on customizing a recipe for a particular BSP, you need to do the + following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Include within the BSP layer a <code class="filename">.bbappend</code> + file for the modified recipe.</p></li><li class="listitem"><p>Place the BSP-specific file in the BSP's recipe + <code class="filename">.bbappend</code> file path under a directory named + after the machine.</p></li></ul></div><p> + </p><p> + To better understand this, consider an example that customizes a recipe by adding + a BSP-specific configuration file named <code class="filename">interfaces</code> to the + <code class="filename">netbase_4.47.bb</code> recipe for machine "xyz". + Do the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Edit the <code class="filename">netbase_4.47.bbappend</code> file so that it + contains the following: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + PRINC := "${@int(PRINC) + 2}" + </pre></li><li class="listitem"><p>Create and place the new <code class="filename">interfaces</code> + configuration file in the BSP's layer here: + </p><pre class="literallayout"> + meta-xyz/recipes-core/netbase/files/xyz/interfaces + </pre></li></ol></div><p> + </p></div><div class="section" title="1.5. BSP Licensing Considerations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bsp-licensing-considerations"></a>1.5. BSP Licensing Considerations</h2></div></div></div><p> + In some cases, a BSP contains separately licensed Intellectual Property (IP) + for a component or components. + For these cases, you are required to accept the terms of a commercial or other + type of license that requires some kind of explicit End User License Agreement (EULA). + Once the license is accepted, the OpenEmbedded build system can then build and + include the corresponding component in the final BSP image. + If the BSP is available as a pre-built image, you can download the image after + agreeing to the license or EULA. + </p><p> + You could find that some separately licensed components that are essential + for normal operation of the system might not have an unencumbered (or free) + substitute. + Without these essential components, the system would be non-functional. + Then again, you might find that other licensed components that are simply + 'good-to-have' or purely elective do have an unencumbered, free replacement + component that you can use rather than agreeing to the separately licensed component. + Even for components essential to the system, you might find an unencumbered component + that is not identical but will work as a less-capable version of the + licensed version in the BSP recipe. + </p><p> + For cases where you can substitute a free component and still + maintain the system's functionality, the Yocto Project website's + <a class="ulink" href="http://www.yoctoproject.org/download/all?keys=&download_type=1&download_version=" target="_top">BSP + Download Page</a> makes available de-featured BSPs + that are completely free of any IP encumbrances. + For these cases, you can use the substitution directly and + without any further licensing requirements. + If present, these fully de-featured BSPs are named appropriately + different as compared to the names of the respective + encumbered BSPs. + If available, these substitutions are your + simplest and most preferred options. + Use of these substitutions of course assumes the resulting functionality meets + system requirements. + </p><p> + If however, a non-encumbered version is unavailable or + it provides unsuitable functionality or quality, you can use an encumbered + version. + </p><p> + A couple different methods exist within the OpenEmbedded build system to + satisfy the licensing requirements for an encumbered BSP. + The following list describes them in order of preference: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Use the <code class="filename">LICENSE_FLAGS</code> variable + to define the recipes that have commercial or other types of + specially-licensed packages:</em></span> + For each of those recipes, you can + specify a matching license string in a + <code class="filename">local.conf</code> variable named + <code class="filename">LICENSE_FLAGS_WHITELIST</code>. + Specifying the matching license string signifies that you agree to the license. + Thus, the build system can build the corresponding recipe and include + the component in the image. + See the + "<a class="link" href="#enabling-commercially-licensed-recipes" target="_top">Enabling + Commercially Licensed Recipes</a>" section in the Yocto Project Reference + Manual for details on how to use these variables.</p><p>If you build as you normally would, without + specifying any recipes in the + <code class="filename">LICENSE_FLAGS_WHITELIST</code>, the build stops and + provides you with the list of recipes that you have + tried to include in the image that need entries in + the <code class="filename">LICENSE_FLAGS_WHITELIST</code>. + Once you enter the appropriate license flags into the whitelist, + restart the build to continue where it left off. + During the build, the prompt will not appear again + since you have satisfied the requirement.</p><p>Once the appropriate license flags are on the white list + in the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, you + can build the encumbered image with no change at all + to the normal build process.</p></li><li class="listitem"><p><span class="emphasis"><em>Get a pre-built version of the BSP:</em></span> + You can get this type of BSP by visiting the Yocto Project website's + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">Download</a> + page and clicking on "BSP Downloads". + You can download BSP tarballs that contain proprietary components + after agreeing to the licensing + requirements of each of the individually encumbered + packages as part of the download process. + Obtaining the BSP this way allows you to access an encumbered + image immediately after agreeing to the + click-through license agreements presented by the + website. + Note that if you want to build the image + yourself using the recipes contained within the BSP + tarball, you will still need to create an + appropriate <code class="filename">LICENSE_FLAGS_WHITELIST</code> to match the + encumbered recipes in the BSP.</p></li></ol></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Pre-compiled images are bundled with + a time-limited kernel that runs for a + predetermined amount of time (10 days) before it forces + the system to reboot. + This limitation is meant to discourage direct redistribution + of the image. + You must eventually rebuild the image if you want to remove this restriction. + </div></div><div class="section" title="1.6. Using the Yocto Project's BSP Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-the-yocto-projects-bsp-tools"></a>1.6. Using the Yocto Project's BSP Tools</h2></div></div></div><p> + The Yocto Project includes a couple of tools that enable + you to create a <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP layer</a> + from scratch and do basic configuration and maintenance + of the kernel without ever looking at a metadata file. + These tools are <code class="filename">yocto-bsp</code> and <code class="filename">yocto-kernel</code>, + respectively. + </p><p> + The following sections describe the common location and help features as well + as details for the <code class="filename">yocto-bsp</code> and <code class="filename">yocto-kernel</code> + tools. + </p><div class="section" title="1.6.1. Common Features"><div class="titlepage"><div><div><h3 class="title"><a id="common-features"></a>1.6.1. Common Features</h3></div></div></div><p> + Designed to have a command interface somewhat like + <a class="link" href="#git" target="_top">Git</a>, each + tool is structured as a set of sub-commands under a + top-level command. + The top-level command (<code class="filename">yocto-bsp</code> + or <code class="filename">yocto-kernel</code>) itself does + nothing but invoke or provide help on the sub-commands + it supports. + </p><p> + Both tools reside in the <code class="filename">scripts/</code> subdirectory + of the <a class="link" href="#source-directory" target="_top">source directory</a>. + Consequently, to use the scripts, you must <code class="filename">source</code> the + environment just as you would when invoking a build: + </p><pre class="literallayout"> + $ source oe-init-build-env [build_dir] + </pre><p> + </p><p> + The most immediately useful function is to get help on both tools. + The built-in help system makes it easy to drill down at + any time and view the syntax required for any specific command. + Simply enter the name of the command, or the command along with + <code class="filename">help</code> to display a list of the available sub-commands. + Here is an example: + </p><pre class="literallayout"> + $ yocto-bsp + $ yocto-bsp help + + Usage: + + Create a customized Yocto BSP layer. + + usage: yocto-bsp [--version] [--help] COMMAND [ARGS] + + The most commonly used 'yocto-bsp' commands are: + create Create a new Yocto BSP + list List available values for options and BSP properties + + See 'yocto-bsp help COMMAND' for more information on a specific command. + + + Options: + --version show program's version number and exit + -h, --help show this help message and exit + -D, --debug output debug information + </pre><p> + </p><p> + Similarly, entering just the name of a sub-command shows the detailed usage + for that sub-command: + </p><pre class="literallayout"> + $ yocto-bsp create + + Usage: + + Create a new Yocto BSP + usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] + [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] + + This command creates a Yocto BSP based on the specified parameters. + The new BSP will be a new BSP layer contained by default within + the top-level directory specified as 'meta-bsp-name'. The -o option + can be used to place the BSP layer in a directory with a different + name and location. + + ... + </pre><p> + </p><p> + For any sub-command, you can also use the word 'help' just before the + sub-command to get more extensive documentation: + </p><pre class="literallayout"> + $ yocto-bsp help create + + NAME + yocto-bsp create - Create a new Yocto BSP + + SYNOPSIS + yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] + [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] + + DESCRIPTION + This command creates a Yocto BSP based on the specified + parameters. The new BSP will be a new Yocto BSP layer contained + by default within the top-level directory specified as + 'meta-bsp-name'. The -o option can be used to place the BSP layer + in a directory with a different name and location. + + The value of the 'karch' parameter determines the set of files + that will be generated for the BSP, along with the specific set of + 'properties' that will be used to fill out the BSP-specific + portions of the BSP. + + ... + + NOTE: Once created, you should add your new layer to your + bblayers.conf file in order for it to be subsequently seen and + modified by the yocto-kernel tool. + + NOTE for x86- and x86_64-based BSPs: The generated BSP assumes the + presence of the of the meta-intel layer, so you should also have a + meta-intel layer present and added to your bblayers.conf as well. + </pre><p> + </p><p> + Now that you know where these two commands reside and how to access information + on them, you should find it relatively straightforward to discover the commands + necessary to create a BSP and perform basic kernel maintenance on that BSP using + the tools. + The next sections provide a concrete starting point to expand on a few points that + might not be immediately obvious or that could use further explanation. + </p></div><div class="section" title="1.6.2. Creating a new BSP Layer Using the yocto-bsp Script"><div class="titlepage"><div><div><h3 class="title"><a id="creating-a-new-bsp-layer-using-the-yocto-bsp-script"></a>1.6.2. Creating a new BSP Layer Using the yocto-bsp Script</h3></div></div></div><p> + The <code class="filename">yocto-bsp</code> script creates a new + <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP layer</a> for any architecture supported + by the Yocto Project, as well as QEMU versions of the same. + The default mode of the script's operation is to prompt you for information needed + to generate the BSP layer. + For the current set of BSPs, the script prompts you for various important + parameters such as: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>which kernel to use</p></li><li class="listitem"><p>which branch of that kernel to use (or re-use)</p></li><li class="listitem"><p>whether or not to use X, and if so, which drivers to use</p></li><li class="listitem"><p>whether to turn on SMP</p></li><li class="listitem"><p>whether the BSP has a keyboard</p></li><li class="listitem"><p>whether the BSP has a touchscreen</p></li><li class="listitem"><p>any remaining configurable items associated with the BSP</p></li></ul></div><p> + </p><p> + You use the <code class="filename">yocto-bsp create</code> sub-command to create + a new BSP layer. + This command requires you to specify a particular architecture on which to + base the BSP. + Assuming you have sourced the environment, you can use the + <code class="filename">yocto-bsp list karch</code> sub-command to list the + architectures available for BSP creation as follows: + </p><pre class="literallayout"> + $ yocto-bsp list karch + Architectures available: + arm + powerpc + i386 + mips + x86_64 + qemu + </pre><p> + </p><p> + The remainder of this section presents an example that uses + <code class="filename">myarm</code> as the machine name and <code class="filename">qemu</code> + as the machine architecture. + Of the available architectures, <code class="filename">qemu</code> is the only architecture + that causes the script to prompt you further for an actual architecture. + In every other way, this architecture is representative of how creating a BSP for + a 'real' machine would work. + The reason the example uses this architecture is because it is an emulated architecture + and can easily be followed without requiring actual hardware. + </p><p> + As the <code class="filename">yocto-bsp create</code> command runs, default values for + the prompts appear in brackets. + Pressing enter without supplying anything on the command line or pressing enter + and providing an invalid response causes the script to accept the default value. + </p><p> + Following is the complete example: + </p><pre class="literallayout"> + $ yocto-bsp create myarm qemu + Which qemu architecture would you like to use? [default: x86] + 1) common 32-bit x86 + 2) common 64-bit x86 + 3) common 32-bit ARM + 4) common 32-bit PowerPC + 5) common 32-bit MIPS + 3 + Would you like to use the default (3.2) kernel? (Y/n) + Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [Y/n] + Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.2... + Please choose a machine branch to base this BSP on => [default: standard/default/common-pc] + 1) base + 2) standard/base + 3) standard/default/arm-versatile-926ejs + 4) standard/default/base + 5) standard/default/beagleboard + 6) standard/default/cedartrailbsp (copy).xml + 7) standard/default/common-pc-64/base + 8) standard/default/common-pc-64/jasperforest + 9) standard/default/common-pc-64/romley + 10) standard/default/common-pc-64/sugarbay + 11) standard/default/common-pc/atom-pc + 12) standard/default/common-pc/base + 13) standard/default/crownbay + 14) standard/default/emenlow + 15) standard/default/fishriver + 16) standard/default/fri2 + 17) standard/default/fsl-mpc8315e-rdb + 18) standard/default/mti-malta32-be + 19) standard/default/mti-malta32-le + 20) standard/default/preempt-rt + 21) standard/default/qemu-ppc32 + 22) standard/default/routerstationpro + 23) standard/preempt-rt/base + 24) standard/preempt-rt/qemu-ppc32 + 25) standard/preempt-rt/routerstationpro + 26) standard/tiny + 3 + Do you need SMP support? (Y/n) + Does your BSP have a touchscreen? (y/N) + Does your BSP have a keyboard? (Y/n) + New qemu BSP created in meta-myarm + </pre><p> + Let's take a closer look at the example now: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>For the <code class="filename">qemu</code> architecture, + the script first prompts you for which emulated architecture to use. + In the example, we use the <code class="filename">arm</code> architecture. + </p></li><li class="listitem"><p>The script then prompts you for the kernel. + The default kernel is 3.2 and is acceptable. + So, the example accepts the default. + If you enter 'n', the script prompts you to further enter the kernel + you do want to use (e.g. 3.0, 3.2_preempt-rt, etc.).</p></li><li class="listitem"><p>Next, the script asks whether you would like to have a new + branch created especially for your BSP in the local + <a class="link" href="#local-kernel-files" target="_top">Linux Yocto Kernel</a> + Git repository . + If not, then the script re-uses an existing branch.</p><p>In this example, the default (or 'yes') is accepted. + Thus, a new branch is created for the BSP rather than using a common, shared + branch. + The new branch is the branch committed to for any patches you might later add. + The reason a new branch is the default is that typically + new BSPs do require BSP-specific patches. + The tool thus assumes that most of time a new branch is required. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>In the current implementation, creation or re-use of a branch does + not actually matter. + The reason is because the generated BSPs assume that patches and + configurations live in recipe-space, which is something that can be done + with or without a dedicated branch. + Generated BSPs, however, are different. + This difference becomes significant once the tool's 'publish' functionality + is implemented.</div></li><li class="listitem"><p>Regardless of which choice is made in the previous step, + you are now given the opportunity to select a particular machine branch on + which to base your new BSP-specific machine branch on + (or to re-use if you had elected to not create a new branch). + Because this example is generating an <code class="filename">arm</code> BSP, the example + uses <code class="filename">#3</code> at the prompt, which selects the arm-versatile branch. + </p></li><li class="listitem"><p>The remainder of the prompts are routine. + Defaults are accepted for each.</p></li><li class="listitem"><p>By default, the script creates the new BSP Layer in the + <a class="link" href="#build-directory" target="_top">build directory</a>. + </p></li></ol></div><p> + </p><p> + Once the BSP Layer is created, you must add it to your + <code class="filename">bblayers.conf</code> file. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS = " \ + /usr/local/src/yocto/meta \ + /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-myarm \ + " + </pre><p> + Adding the layer to this file allows the build system to build the BSP and + the <code class="filename">yocto-kernel</code> tool to be able to find the layer and + other metadata it needs on which to operate. + </p></div><div class="section" title="1.6.3. Managing Kernel Patches and Config Items with yocto-kernel"><div class="titlepage"><div><div><h3 class="title"><a id="managing-kernel-patches-and-config-items-with-yocto-kernel"></a>1.6.3. Managing Kernel Patches and Config Items with yocto-kernel</h3></div></div></div><p> + Assuming you have created a <a class="link" href="#bsp-layers" title="1.1. BSP Layers">BSP Layer</a> using + <a class="link" href="#creating-a-new-bsp-layer-using-the-yocto-bsp-script" title="1.6.2. Creating a new BSP Layer Using the yocto-bsp Script"> + <code class="filename">yocto-bsp</code></a> and you added it to your + <a class="link" href="#var-BBLAYERS" target="_top"><code class="filename">BBLAYERS</code></a> + variable in the <code class="filename">bblayers.conf</code> file, you can now use + the <code class="filename">yocto-kernel</code> script to add patches and configuration + items to the BSP's kernel. + </p><p> + The <code class="filename">yocto-kernel</code> script allows you to add, remove, and list patches + and kernel config settings to a BSP's kernel + <code class="filename">.bbappend</code> file. + All you need to do is use the appropriate sub-command. + Recall that the easiest way to see exactly what sub-commands are available + is to use the <code class="filename">yocto-kernel</code> built-in help as follows: + </p><pre class="literallayout"> + $ yocto-kernel + Usage: + + Modify and list Yocto BSP kernel config items and patches. + + usage: yocto-kernel [--version] [--help] COMMAND [ARGS] + + The most commonly used 'yocto-kernel' commands are: + config list List the modifiable set of bare kernel config options for a BSP + config add Add or modify bare kernel config options for a BSP + config rm Remove bare kernel config options from a BSP + patch list List the patches associated with a BSP + patch add Patch the Yocto kernel for a BSP + patch rm Remove patches from a BSP + + See 'yocto-kernel help COMMAND' for more information on a specific command. + </pre><p> + </p><p> + The <code class="filename">yocto-kernel patch add</code> sub-command allows you to add a + patch to a BSP. + The following example adds two patches to the <code class="filename">myarm</code> BSP: + </p><pre class="literallayout"> + $ yocto-kernel patch add myarm ~/test.patch + Added patches: + test.patch + + $ yocto-kernel patch add myarm ~/yocto-testmod.patch + Added patches: + yocto-testmod.patch + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Although the previous example adds patches one at a time, it is possible + to add multiple patches at the same time.</div><p> + </p><p> + You can verify patches have been added by using the + <code class="filename">yocto-kernel patch list</code> sub-command. + Here is an example: + </p><pre class="literallayout"> + $ yocto-kernel patch list myarm + The current set of machine-specific patches for myarm is: + 1) test.patch + 2) yocto-testmod.patch + </pre><p> + </p><p> + You can also use the <code class="filename">yocto-kernel</code> script to + remove a patch using the <code class="filename">yocto-kernel patch rm</code> sub-command. + Here is an example: + </p><pre class="literallayout"> + $ yocto-kernel patch rm myarm + Specify the patches to remove: + 1) test.patch + 2) yocto-testmod.patch + 1 + Removed patches: + test.patch + </pre><p> + </p><p> + Again, using the <code class="filename">yocto-kernel patch list</code> sub-command, + you can verify that the patch was in fact removed: + </p><pre class="literallayout"> + $ yocto-kernel patch list myarm + The current set of machine-specific patches for myarm is: + 1) yocto-testmod.patch + </pre><p> + </p><p> + In a completely similar way, you can use the <code class="filename">yocto-kernel config add</code> + sub-command to add one or more kernel config item settings to a BSP. + The following commands add a couple of config items to the + <code class="filename">myarm</code> BSP: + </p><pre class="literallayout"> + $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y + Added items: + CONFIG_MISC_DEVICES=y + + $ yocto-kernel config add myarm KCONFIG_YOCTO_TESTMOD=y + Added items: + CONFIG_YOCTO_TESTMOD=y + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Although the previous example adds config items one at a time, it is possible + to add multiple config items at the same time.</div><p> + </p><p> + You can list the config items now associated with the BSP. + Doing so shows you the config items you added as well as others associated + with the BSP: + </p><pre class="literallayout"> + $ yocto-kernel config list myarm + The current set of machine-specific kernel config items for myarm is: + 1) CONFIG_MISC_DEVICES=y + 2) CONFIG_YOCTO_TESTMOD=y + </pre><p> + </p><p> + Finally, you can remove one or more config items using the + <code class="filename">yocto-kernel config rm</code> sub-command in a manner + completely analogous to <code class="filename">yocto-kernel patch rm</code>. + </p></div></div></div> + + + +</div> + +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/kernel-title.png" align="left" width="100%" /></td></tr></table> + + <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="kernel-manual"></a></h1></div><div><div class="authorgroup"> + <div class="author"><h3 class="author"><span class="firstname">Bruce</span> <span class="surname">Ashfield</span></h3><div class="affiliation"> + <span class="orgname">Wind River Corporation<br /></span> + </div><code class="email"><<a class="email" href="mailto:bruce.ashfield@windriver.com">bruce.ashfield@windriver.com</a>></code></div> + </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1504523"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. + </p> + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + Yocto Project Kernel Architecture and Use Manual on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> + <tr><td align="left">Revision 0.9</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">The initial document draft released with the Yocto Project 0.9 Release.</td></tr> + <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> + <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> + <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> + <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + </table></div></div></div><hr /></div> + + + <div class="chapter" title="Chapter 1. Yocto Project Kernel Architecture and Use Manual"><div class="titlepage"><div><div><h2 class="title"><a id="kernel-doc-intro"></a>Chapter 1. Yocto Project Kernel Architecture and Use Manual</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#kernel-intro-section">1.1. Introduction</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-intro-section"></a>1.1. Introduction</h2></div></div></div><p> + The Yocto Project presents kernels as a fully patched, history-clean Git + repositories. + Each repository represents selected features, board support, + and configurations extensively tested by the Yocto Project. + Yocto Project kernels allow the end user to leverage community + best practices to seamlessly manage the development, build and debug cycles. + </p><p> + This manual describes Yocto Project kernels by providing information + on history, organization, benefits, and use. + The manual consists of two sections: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Concepts:</em></span> Describes concepts behind a kernel. + You will understand how a kernel is organized and why it is organized in + the way it is. You will understand the benefits of a kernel's organization + and the mechanisms used to work with the kernel and how to apply it in your + design process.</p></li><li class="listitem"><p><span class="emphasis"><em>Using a Kernel:</em></span> Describes best practices + and "how-to" information + that lets you put a kernel to practical use. + Some examples are how to examine changes in a branch and how to + save kernel modifications.</p></li></ul></div><p> + </p><p> + For more information on the Linux kernel, see the following links: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Linux Foundation's guide for kernel development + process - <a class="ulink" href="http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process" target="_top">http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process</a></p></li><li class="listitem"><p>A fairly encompassing guide on Linux kernel development - + <a class="ulink" href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD" target="_top">http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD</a></p></li></ul></div><p> + </p><p> + For more discussion on the Yocto Project kernel, you can see these sections + in the Yocto Project Development Manual: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + "<a class="link" href="#kernel-overview" target="_top">Kernel Overview</a>"</p></li><li class="listitem"><p> + "<a class="link" href="#kernel-modification-workflow" target="_top">Kernel Modification Workflow</a>" + </p></li><li class="listitem"><p> + "<a class="link" href="#dev-manual-kernel-appendix" target="_top">Kernel Modification Example</a>"</p></li></ul></div><p> + </p><p> + For general information on the Yocto Project, visit the website at + <a class="ulink" href="http://www.yoctoproject.org" target="_top">http://www.yoctoproject.org</a>. + </p></div></div> + + <div class="chapter" title="Chapter 2. Yocto Project Kernel Concepts"><div class="titlepage"><div><div><h2 class="title"><a id="kernel-concepts"></a>Chapter 2. Yocto Project Kernel Concepts</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#concepts-org">2.1. Introduction</a></span></dt><dt><span class="section"><a href="#kernel-goals">2.2. Kernel Goals</a></span></dt><dt><span class="section"><a href="#kernel-big-picture">2.3. Yocto Project Kernel Development and Maintenance Overview</a></span></dt><dt><span class="section"><a href="#kernel-architecture">2.4. Kernel Architecture</a></span></dt><dd><dl><dt><span class="section"><a href="#architecture-overview">2.4.1. Overview</a></span></dt><dt><span class="section"><a href="#branching-and-workflow">2.4.2. Branching Strategy and Workflow</a></span></dt><dt><span class="section"><a href="#source-code-manager-git">2.4.3. Source Code Manager - Git</a></span></dt></dl></dd><dt><span class="section"><a href="#kernel-configuration">2.5. Kernel Configuration</a></span></dt><dt><span class="section"><a href="#kernel-tools">2.6. Kernel Tools</a></span></dt></dl></div><div class="section" title="2.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="concepts-org"></a>2.1. Introduction</h2></div></div></div><p> + This chapter provides conceptual information about the kernel: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Kernel Goals</p></li><li class="listitem"><p>Kernel Development and Maintenance Overview</p></li><li class="listitem"><p>Kernel Architecture</p></li><li class="listitem"><p>Kernel Tools</p></li></ul></div><p> + </p></div><div class="section" title="2.2. Kernel Goals"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-goals"></a>2.2. Kernel Goals</h2></div></div></div><p> + The complexity of embedded kernel design has increased dramatically. + Whether it is managing multiple implementations of a particular feature or tuning and + optimizing board specific features, both flexibility and maintainability are key concerns. + The Linux kernels available through the Yocto Project are presented with the embedded + developer's needs in mind and have evolved to assist in these key concerns. + For example, prior methods such as applying hundreds of patches to an extracted + tarball have been replaced with proven techniques that allow easy inspection, + bisection and analysis of changes. + Application of these techniques also creates a platform for performing integration and + collaboration with the thousands of upstream development projects. + </p><p> + With all these considerations in mind, the Yocto Project's kernel and development team + strives to attain these goals: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Allow the end user to leverage community best practices to seamlessly + manage the development, build and debug cycles.</p></li><li class="listitem"><p>Create a platform for performing integration and collaboration with the + thousands of upstream development projects that exist.</p></li><li class="listitem"><p>Provide mechanisms that support many different work flows, front-ends and + management techniques.</p></li><li class="listitem"><p>Deliver the most up-to-date kernel possible while still ensuring that + the baseline kernel is the most stable official release.</p></li><li class="listitem"><p>Include major technological features as part of the Yocto Project's + upward revision strategy.</p></li><li class="listitem"><p>Present a kernel Git repository that, similar to the upstream + <code class="filename">kernel.org</code> tree, + has a clear and continuous history.</p></li><li class="listitem"><p>Deliver a key set of supported kernel types, where each type is tailored + to meet a specific use (e.g. networking, consumer, devices, and so forth).</p></li><li class="listitem"><p>Employ a Git branching strategy that, from a developer's point of view, + results in a linear path from the baseline <code class="filename">kernel.org</code>, + through a select group of features and + ends with their BSP-specific commits.</p></li></ul></div><p> + </p></div><div class="section" title="2.3. Yocto Project Kernel Development and Maintenance Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-big-picture"></a>2.3. Yocto Project Kernel Development and Maintenance Overview</h2></div></div></div><p> + Kernels available through the Yocto Project, like other kernels, are based off the Linux + kernel releases from <a class="ulink" href="http://www.kernel.org" target="_top">http://www.kernel.org</a>. + At the beginning of a major development cycle, the Yocto Project team + chooses its kernel based on factors such as release timing, the anticipated release + timing of final upstream <code class="filename">kernel.org</code> versions, and Yocto Project + feature requirements. + Typically, the kernel chosen is in the + final stages of development by the community. + In other words, the kernel is in the release + candidate or "rc" phase and not yet a final release. + But, by being in the final stages of external development, the team knows that the + <code class="filename">kernel.org</code> final release will clearly be within the early stages of + the Yocto Project development window. + </p><p> + This balance allows the team to deliver the most up-to-date kernel + as possible, while still ensuring that the team has a stable official release for + the baseline Linux kernel version. + </p><p> + The ultimate source for kernels available through the Yocto Project are released kernels + from <code class="filename">kernel.org</code>. + In addition to a foundational kernel from <code class="filename">kernel.org</code>, the + kernels available contain a mix of important new mainline + developments, non-mainline developments (when there is no alternative), + Board Support Package (BSP) developments, + and custom features. + These additions result in a commercially released Yocto Project Linux kernel that caters + to specific embedded designer needs for targeted hardware. + </p><p> + Once a kernel is officially released, the Yocto Project team goes into + their next development cycle, or upward revision (uprev) cycle, while still + continuing maintenance on the released kernel. + It is important to note that the most sustainable and stable way + to include feature development upstream is through a kernel uprev process. + Back-porting hundreds of individual fixes and minor features from various + kernel versions is not sustainable and can easily compromise quality. + </p><p> + During the uprev cycle, the Yocto Project team uses an ongoing analysis of + kernel development, BSP support, and release timing to select the best + possible <code class="filename">kernel.org</code> version. + The team continually monitors community kernel + development to look for significant features of interest. + The team does consider back-porting large features if they have a significant advantage. + User or community demand can also trigger a back-port or creation of new + functionality in the Yocto Project baseline kernel during the uprev cycle. + </p><p> + Generally speaking, every new kernel both adds features and introduces new bugs. + These consequences are the basic properties of upstream kernel development and are + managed by the Yocto Project team's kernel strategy. + It is the Yocto Project team's policy to not back-port minor features to the released kernel. + They only consider back-porting significant technological jumps - and, that is done + after a complete gap analysis. + The reason for this policy is that back-porting any small to medium sized change + from an evolving kernel can easily create mismatches, incompatibilities and very + subtle errors. + </p><p> + These policies result in both a stable and a cutting + edge kernel that mixes forward ports of existing features and significant and critical + new functionality. + Forward porting functionality in the kernels available through the Yocto Project kernel + can be thought of as a "micro uprev." + The many “micro uprevs” produce a kernel version with a mix of + important new mainline, non-mainline, BSP developments and feature integrations. + This kernel gives insight into new features and allows focused + amounts of testing to be done on the kernel, which prevents + surprises when selecting the next major uprev. + The quality of these cutting edge kernels is evolving and the kernels are used in leading edge + feature and BSP development. + </p></div><div class="section" title="2.4. Kernel Architecture"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-architecture"></a>2.4. Kernel Architecture</h2></div></div></div><p> + This section describes the architecture of the kernels available through the + Yocto Project and provides information + on the mechanisms used to achieve that architecture. + </p><div class="section" title="2.4.1. Overview"><div class="titlepage"><div><div><h3 class="title"><a id="architecture-overview"></a>2.4.1. Overview</h3></div></div></div><p> + As mentioned earlier, a key goal of the Yocto Project is to present the + developer with + a kernel that has a clear and continuous history that is visible to the user. + The architecture and mechanisms used achieve that goal in a manner similar to the + upstream <code class="filename">kernel.org</code>. + </p><p> + You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with + added features logically structured on top of the baseline. + The features are tagged and organized by way of a branching strategy implemented by the + source code manager (SCM) Git. + For information on Git as applied to the Yocto Project, see the + "<a class="link" href="#git" target="_top">Git</a>" section in the + Yocto Project Development Manual. + </p><p> + The result is that the user has the ability to see the added features and + the commits that make up those features. + In addition to being able to see added features, the user can also view the history of what + made up the baseline kernel. + </p><p> + The following illustration shows the conceptual Yocto Project kernel. + </p><p> + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/kernel-architecture-overview.png" align="middle" /></td></tr></table><p> + </p><p> + In the illustration, the "Kernel.org Branch Point" + marks the specific spot (or release) from + which the Yocto Project kernel is created. + From this point "up" in the tree, features and differences are organized and tagged. + </p><p> + The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel + type and BSP that is organized further up the tree. + Placing these common features in the + tree this way means features don't have to be duplicated along individual branches of the + structure. + </p><p> + From the Yocto Project Baseline Kernel, branch points represent specific functionality + for individual BSPs as well as real-time kernels. + The illustration represents this through three BSP-specific branches and a real-time + kernel branch. + Each branch represents some unique functionality for the BSP or a real-time kernel. + </p><p> + In this example structure, the real-time kernel branch has common features for all + real-time kernels and contains + more branches for individual BSP-specific real-time kernels. + The illustration shows three branches as an example. + Each branch points the way to specific, unique features for a respective real-time + kernel as they apply to a given BSP. + </p><p> + The resulting tree structure presents a clear path of markers (or branches) to the + developer that, for all practical purposes, is the kernel needed for any given set + of requirements. + </p></div><div class="section" title="2.4.2. Branching Strategy and Workflow"><div class="titlepage"><div><div><h3 class="title"><a id="branching-and-workflow"></a>2.4.2. Branching Strategy and Workflow</h3></div></div></div><p> + The Yocto Project team creates kernel branches at points where functionality is + no longer shared and thus, needs to be isolated. + For example, board-specific incompatibilities would require different functionality + and would require a branch to separate the features. + Likewise, for specific kernel features, the same branching strategy is used. + </p><p> + This branching strategy results in a tree that has features organized to be specific + for particular functionality, single kernel types, or a subset of kernel types. + This strategy also results in not having to store the same feature twice + internally in the tree. + Rather, the kernel team stores the unique differences required to apply the + feature onto the kernel type in question. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The Yocto Project team strives to place features in the tree such that they can be + shared by all boards and kernel types where possible. + However, during development cycles or when large features are merged, + the team cannot always follow this practice. + In those cases, the team uses isolated branches to merge features. + </div><p> + </p><p> + BSP-specific code additions are handled in a similar manner to kernel-specific additions. + Some BSPs only make sense given certain kernel types. + So, for these types, the team creates branches off the end of that kernel type for all + of the BSPs that are supported on that kernel type. + From the perspective of the tools that create the BSP branch, the BSP is really no + different than a feature. + Consequently, the same branching strategy applies to BSPs as it does to features. + So again, rather than store the BSP twice, the team only stores the unique + differences for the BSP across the supported multiple kernels. + </p><p> + While this strategy can result in a tree with a significant number of branches, it is + important to realize that from the developer's point of view, there is a linear + path that travels from the baseline <code class="filename">kernel.org</code>, through a select + group of features and ends with their BSP-specific commits. + In other words, the divisions of the kernel are transparent and are not relevant + to the developer on a day-to-day basis. + From the developer's perspective, this path is the "master" branch. + The developer does not need to be aware of the existence of any other branches at all. + Of course, there is value in the existence of these branches + in the tree, should a person decide to explore them. + For example, a comparison between two BSPs at either the commit level or at the line-by-line + code <code class="filename">diff</code> level is now a trivial operation. + </p><p> + Working with the kernel as a structured tree follows recognized community best practices. + In particular, the kernel as shipped with the product, should be + considered an "upstream source" and viewed as a series of + historical and documented modifications (commits). + These modifications represent the development and stabilization done + by the Yocto Project kernel development team. + </p><p> + Because commits only change at significant release points in the product life cycle, + developers can work on a branch created + from the last relevant commit in the shipped Yocto Project kernel. + As mentioned previously, the structure is transparent to the developer + because the kernel tree is left in this state after cloning and building the kernel. + </p></div><div class="section" title="2.4.3. Source Code Manager - Git"><div class="titlepage"><div><div><h3 class="title"><a id="source-code-manager-git"></a>2.4.3. Source Code Manager - Git</h3></div></div></div><p> + The Source Code Manager (SCM) is Git. + This SCM is the obvious mechanism for meeting the previously mentioned goals. + Not only is it the SCM for <code class="filename">kernel.org</code> but, + Git continues to grow in popularity and supports many different work flows, + front-ends and management techniques. + </p><p> + You can find documentation on Git at <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. + You can also get an introduction to Git as it applies to the Yocto Project in the + "<a class="link" href="#git" target="_top">Git</a>" + section in the Yocto Project Development Manual. + These referenced sections overview Git and describe a minimal set of + commands that allows you to be functional using Git. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + You can use as much, or as little, of what Git has to offer to accomplish what + you need for your project. + You do not have to be a "Git Master" in order to use it with the Yocto Project. + </div><p> + </p></div></div><div class="section" title="2.5. Kernel Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-configuration"></a>2.5. Kernel Configuration</h2></div></div></div><p> + Kernel configuration, along with kernel features, defines how a kernel + image is built for the Yocto Project. + Through configuration settings, you can customize a Yocto Project kernel to be + specific to particular hardware. + For example, you can specify sound support or networking support. + This section describes basic concepts behind Kernel configuration within the + Yocto Project and references you to other areas for specific configuration + applications. + </p><p> + Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any + Linux kernel. + The build process for a Yocto Project kernel uses a <code class="filename">.config</code> file, which + is created through the Linux Kernel Coinfiguration (LKC) tool. + You can directly set various configurations in the + <code class="filename">.config</code> file by using the <code class="filename">menuconfig</code> + tool as built by BitBake. + You can also define configurations in the file by using configuration fragments. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + It is not recommended that you edit the <code class="filename">.config</code> file directly. + </div><p> + Here are some brief descriptions of the ways you can affect the + <code class="filename">.config</code> file: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The <code class="filename">menuconfig</code> Tool:</em></span> + One of many front-ends that allows you to define kernel configurations. + Some others are <code class="filename">make config</code>, + <code class="filename">make nconfig</code>, and <code class="filename">make gconfig</code>. + In the Yocto Project environment, you must use BitBake to build the + <code class="filename">menuconfig</code> tool before you can use it to define + configurations: + </p><pre class="literallayout"> + $ bitbake linux-yocto -c menuconfig + </pre><p> + After the tool is built, you can interact with it normally. + You can see how <code class="filename">menuconfig</code> is used to change a simple + kernel configuration in the + "<a class="link" href="#changing-the-config-smp-configuration-using-menuconfig" target="_top">Changing the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></a>" + section of the Yocto Project Development Manual. + For general information on <code class="filename">menuconfig</code>, see + <a class="ulink" href="http://en.wikipedia.org/wiki/Menuconfig" target="_top">http://en.wikipedia.org/wiki/Menuconfig</a>. + </p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Fragments:</em></span> A file with a + list of kernel options just as they would appear syntactically in the + <code class="filename">.config</code> file. + Configuration fragments are typically logical groupings and are assembled + by the OpenEmbedded build system to produce input used by the LKC + that ultimately generates the <code class="filename">.config</code> file.</p><p>The + <code class="filename"><a class="link" href="#var-KERNEL_FEATURES" target="_top">KERNEL_FEATURES</a></code> + variable can be used to list configuration fragments. + For further discussion on applying configuration fragments, see the + "<a class="link" href="#bsp-filelayout-kernel" target="_top">Linux Kernel Configuration</a>" + section in the Yocto Project Board Support Package (BSP) Guide. + </p></li></ul></div><p> + </p></div><div class="section" title="2.6. Kernel Tools"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="kernel-tools"></a>2.6. Kernel Tools</h2></div></div></div><p> + Since most standard workflows involve moving forward with an existing tree by + continuing to add and alter the underlying baseline, the tools that manage + the Yocto Project's kernel construction are largely hidden from the developer to + present a simplified view of the kernel for ease of use. + </p><p> + Fundamentally, the kernel tools that manage and construct the + Yocto Project kernel accomplish the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Group patches into named, reusable features.</p></li><li class="listitem"><p>Allow top-down control of included features.</p></li><li class="listitem"><p>Bind kernel configurations to kernel patches and features.</p></li><li class="listitem"><p>Present a seamless Git repository that blends Yocto Project value + with the <code class="filename">kernel.org</code> history and development.</p></li></ul></div><p> + </p></div></div> + + <div class="chapter" title="Chapter 3. Working with the Yocto Project Kernel"><div class="titlepage"><div><div><h2 class="title"><a id="kernel-how-to"></a>Chapter 3. Working with the Yocto Project Kernel</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#actions-org">3.1. Introduction</a></span></dt><dt><span class="section"><a href="#tree-construction">3.2. Tree Construction</a></span></dt><dt><span class="section"><a href="#build-strategy">3.3. Build Strategy</a></span></dt><dt><span class="section"><a href="#workflow-examples">3.4. Workflow Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#change-inspection-kernel-changes-commits">3.4.1. Change Inspection: Changes/Commits</a></span></dt><dt><span class="section"><a href="#development-saving-kernel-modifications">3.4.2. Development: Saving Kernel Modifications</a></span></dt><dt><span class="section"><a href="#scm-working-with-the-yocto-project-kernel-in-another-scm">3.4.3. Working with the Yocto Project Kernel in Another SCM</a></span></dt><dt><span class="section"><a href="#bsp-creating">3.4.4. Creating a BSP Based on an Existing Similar BSP</a></span></dt><dt><span class="section"><a href="#tip-dirty-string">3.4.5. "-dirty" String</a></span></dt></dl></dd></dl></div><div class="section" title="3.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="actions-org"></a>3.1. Introduction</h2></div></div></div><p> + This chapter describes how to accomplish tasks involving a kernel's tree structure. + The information is designed to help the developer that wants to modify the Yocto + Project kernel and contribute changes upstream to the Yocto Project. + The information covers the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Tree construction</p></li><li class="listitem"><p>Build strategies</p></li><li class="listitem"><p>Workflow examples</p></li></ul></div><p> + </p></div><div class="section" title="3.2. Tree Construction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="tree-construction"></a>3.2. Tree Construction</h2></div></div></div><p> + This section describes construction of the Yocto Project kernel source repositories + as accomplished by the Yocto Project team to create kernel repositories. + These kernel repositories are found under the heading "Yocto Linux Kernel" at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a> + and can be shipped as part of a Yocto Project release. + The team creates these repositories by + compiling and executing the set of feature descriptions for every BSP/feature + in the product. + Those feature descriptions list all necessary patches, + configuration, branching, tagging and feature divisions found in a kernel. + Thus, the Yocto Project kernel repository (or tree) is built. + </p><p> + The existence of this tree allows you to access and clone a particular + Yocto Project kernel repository and use it to build images based on their configurations + and features. + </p><p> + You can find the files used to describe all the valid features and BSPs + in the Yocto Project kernel in any clone of the Yocto Project kernel source repository + Git tree. + For example, the following command clones the Yocto Project baseline kernel that + branched off of <code class="filename">linux.org</code> version 3.4: + </p><pre class="literallayout"> + $ git clone git://git.yoctoproject.org/linux-yocto-3.4 + </pre><p> + For another example of how to set up a local Git repository of the Yocto Project + kernel files, see the + "<a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a>" bulleted + item in the Yocto Project Development Manual. + </p><p> + Once you have cloned the kernel Git repository on your local machine, you can + switch to the <code class="filename">meta</code> branch within the repository. + Here is an example that assumes the local Git repository for the kernel is in + a top-level directory named <code class="filename">linux-yocto-3.4</code>: + </p><pre class="literallayout"> + $ cd ~/linux-yocto-3.4 + $ git checkout -b meta origin/meta + </pre><p> + Once you have checked out and switched to the <code class="filename">meta</code> branch, + you can see a snapshot of all the kernel configuration and feature descriptions that are + used to build that particular kernel repository. + These descriptions are in the form of <code class="filename">.scc</code> files. + </p><p> + You should realize, however, that browsing your local kernel repository + for feature descriptions and patches is not an effective way to determine what is in a + particular kernel branch. + Instead, you should use Git directly to discover the changes in a branch. + Using Git is an efficient and flexible way to inspect changes to the kernel. + For examples showing how to use Git to inspect kernel commits, see the following sections + in this chapter. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Ground up reconstruction of the complete kernel tree is an action only taken by the + Yocto Project team during an active development cycle. + When you create a clone of the kernel Git repository, you are simply making it + efficiently available for building and development. + </div><p> + </p><p> + The following steps describe what happens when the Yocto Project Team constructs + the Yocto Project kernel source Git repository (or tree) found at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a> given the + introduction of a new top-level kernel feature or BSP. + These are the actions that effectively create the tree + that includes the new feature, patch or BSP: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A top-level kernel feature is passed to the kernel build subsystem. + Normally, this feature is a BSP for a particular kernel type.</p></li><li class="listitem"><p>The file that describes the top-level feature is located by searching + these system directories: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The in-tree kernel-cache directories, which are located + in <code class="filename">meta/cfg/kernel-cache</code></p></li><li class="listitem"><p>Areas pointed to by <code class="filename">SRC_URI</code> statements + found in recipes</p></li></ul></div><p> + For a typical build, the target of the search is a + feature description in an <code class="filename">.scc</code> file + whose name follows this format: + </p><pre class="literallayout"> + <bsp_name>-<kernel_type>.scc + </pre><p> + </p></li><li class="listitem"><p>Once located, the feature description is either compiled into a simple script + of actions, or into an existing equivalent script that is already part of the + shipped kernel.</p></li><li class="listitem"><p>Extra features are appended to the top-level feature description. + These features can come from the + <a class="link" href="#var-KERNEL_FEATURES" target="_top"><code class="filename">KERNEL_FEATURES</code></a> + variable in recipes.</p></li><li class="listitem"><p>Each extra feature is located, compiled and appended to the script + as described in step three.</p></li><li class="listitem"><p>The script is executed to produce a series of <code class="filename">meta-*</code> + directories. + These directories are descriptions of all the branches, tags, patches and configurations that + need to be applied to the base Git repository to completely create the + source (build) branch for the new BSP or feature.</p></li><li class="listitem"><p>The base repository is cloned, and the actions + listed in the <code class="filename">meta-*</code> directories are applied to the + tree.</p></li><li class="listitem"><p>The Git repository is left with the desired branch checked out and any + required branching, patching and tagging has been performed.</p></li></ol></div><p> + </p><p> + The kernel tree is now ready for developer consumption to be locally cloned, + configured, and built into a Yocto Project kernel specific to some target hardware. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The generated <code class="filename">meta-*</code> directories add to the kernel + as shipped with the Yocto Project release. + Any add-ons and configuration data are applied to the end of an existing branch. + The full repository generation that is found in the + official Yocto Project kernel repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a> + is the combination of all supported boards and configurations.</p><p>The technique the Yocto Project team uses is flexible and allows for seamless + blending of an immutable history with additional patches specific to a + deployment. + Any additions to the kernel become an integrated part of the branches.</p></div><p> + </p></div><div class="section" title="3.3. Build Strategy"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="build-strategy"></a>3.3. Build Strategy</h2></div></div></div><p> + Once a local Git repository of the Yocto Project kernel exists on a development system, + you can consider the compilation phase of kernel development - building a kernel image. + Some prerequisites exist that are validated by the build process before compilation + starts: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">SRC_URI</code> points to the kernel Git + repository.</p></li><li class="listitem"><p>A BSP build branch exists. + This branch has the following form: + </p><pre class="literallayout"> + <kernel_type>/<bsp_name> + </pre></li></ul></div><p> + The OpenEmbedded build system makes sure these conditions exist before attempting compilation. + Other means, however, do exist, such as as bootstrapping a BSP, see + the "<a class="link" href="#workflow-examples" title="3.4. Workflow Examples">Workflow Examples</a>". + </p><p> + Before building a kernel, the build process verifies the tree + and configures the kernel by processing all of the + configuration "fragments" specified by feature descriptions in the <code class="filename">.scc</code> + files. + As the features are compiled, associated kernel configuration fragments are noted + and recorded in the <code class="filename">meta-*</code> series of directories in their compilation order. + The fragments are migrated, pre-processed and passed to the Linux Kernel + Configuration subsystem (<code class="filename">lkc</code>) as raw input in the form + of a <code class="filename">.config</code> file. + The <code class="filename">lkc</code> uses its own internal dependency constraints to do the final + processing of that information and generates the final <code class="filename">.config</code> file + that is used during compilation. + </p><p> + Using the board's architecture and other relevant values from the board's template, + kernel compilation is started and a kernel image is produced. + </p><p> + The other thing that you notice once you configure a kernel is that + the build process generates a build tree that is separate from your kernel's local Git + source repository tree. + This build tree has a name that uses the following form, where + <code class="filename">${MACHINE}</code> is the metadata name of the machine (BSP) and "kernel_type" is one + of the Yocto Project supported kernel types (e.g. "standard"): + </p><pre class="literallayout"> + linux-${MACHINE}-<kernel_type>-build + </pre><p> + </p><p> + The existing support in the <code class="filename">kernel.org</code> tree achieves this + default functionality. + </p><p> + This behavior means that all the generated files for a particular machine or BSP are now in + the build tree directory. + The files include the final <code class="filename">.config</code> file, all the <code class="filename">.o</code> + files, the <code class="filename">.a</code> files, and so forth. + Since each machine or BSP has its own separate build directory in its own separate branch + of the Git repository, you can easily switch between different builds. + </p></div><div class="section" title="3.4. Workflow Examples"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="workflow-examples"></a>3.4. Workflow Examples</h2></div></div></div><p> + As previously noted, the Yocto Project kernel has built-in Git integration. + However, these utilities are not the only way to work with the kernel repository. + The Yocto Project has not made changes to Git or to other tools that + would invalidate alternate workflows. + Additionally, the way the kernel repository is constructed results in using + only core Git functionality, thus allowing any number of tools or front ends to use the + resulting tree. + </p><p> + This section contains several workflow examples. + Many of the examples use Git commands. + You can find Git documentation at + <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>. + You can find a simple overview of using Git with the Yocto Project in the + "<a class="link" href="#git" target="_top">Git</a>" + section of the Yocto Project Development Manual. + </p><div class="section" title="3.4.1. Change Inspection: Changes/Commits"><div class="titlepage"><div><div><h3 class="title"><a id="change-inspection-kernel-changes-commits"></a>3.4.1. Change Inspection: Changes/Commits</h3></div></div></div><p> + A common question when working with a kernel is: + "What changes have been applied to this tree?" + </p><p> + In projects that have a collection of directories that + contain patches to the kernel, it is possible to inspect or "grep" the contents + of the directories to get a general feel for the changes. + This sort of patch inspection is not an efficient way to determine what has been + done to the kernel. + The reason it is inefficient is because there are many optional patches that are + selected based on the kernel type and the feature description. + Additionally, patches could exist in directories that are not included in the search. + </p><p> + A more efficient way to determine what has changed in the branch is to use + Git and inspect or search the kernel tree. + This method gives you a full view of not only the source code modifications, + but also provides the reasons for the changes. + </p><div class="section" title="3.4.1.1. What Changed in a Kernel?"><div class="titlepage"><div><div><h4 class="title"><a id="what-changed-in-a-kernel"></a>3.4.1.1. What Changed in a Kernel?</h4></div></div></div><p> + Following are a few examples that show how to use Git commands to examine changes. + Because Git repositories in the Yocto Project do not break existing Git + functionality, and because there exists many permutations of these types of + Git commands, many methods exist by which you can discover changes. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + In the following examples, unless you provide a commit range, + <code class="filename">kernel.org</code> history is blended with Yocto Project + kernel changes. + You can form ranges by using branch names from the kernel tree as the + upper and lower commit markers with the Git commands. + You can see the branch names through the web interface to the + Yocto Project source repositories at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>. + For example, the branch names for the <code class="filename">linux-yocto-3.4</code> + kernel repository can be seen at + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads</a>. + </div><p> + To see a full range of the changes, use the + <code class="filename">git whatchanged</code> command and specify a commit range + for the branch (<code class="filename"><commit>..<commit></code>). + </p><p> + Here is an example that looks at what has changed in the + <code class="filename">emenlow</code> branch of the + <code class="filename">linux-yocto-3.4</code> kernel. + The lower commit range is the commit associated with the + <code class="filename">standard/base</code> branch, while + the upper commit range is the commit associated with the + <code class="filename">standard/emenlow</code> branch. + </p><pre class="literallayout"> + $ git whatchanged origin/standard/base..origin/standard/emenlow + </pre><p> + </p><p> + To see a summary of changes use the <code class="filename">git log</code> command. + Here is an example using the same branches: + </p><pre class="literallayout"> + $ git log --oneline origin/standard/base..origin/standard/emenlow + </pre><p> + The <code class="filename">git log</code> output might be more useful than + the <code class="filename">git whatchanged</code> as you get + a short, one-line summary of each change and not the entire commit. + </p><p> + If you want to see code differences associated with all the changes, use + the <code class="filename">git diff</code> command. + Here is an example: + </p><pre class="literallayout"> + $ git diff origin/standard/base..origin/standard/emenlow + </pre><p> + </p><p> + You can see the commit log messages and the text differences using the + <code class="filename">git show</code> command: + Here is an example: + </p><pre class="literallayout"> + $ git show origin/standard/base..origin/standard/emenlow + </pre><p> + </p><p> + You can create individual patches for each change by using the + <code class="filename">git format-patch</code> command. + Here is an example that that creates patch files for each commit and + places them in your <code class="filename">Documents</code> directory: + </p><pre class="literallayout"> + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + </pre><p> + </p></div><div class="section" title="3.4.1.2. Show a Particular Feature or Branch Change"><div class="titlepage"><div><div><h4 class="title"><a id="show-a-particular-feature-or-branch-change"></a>3.4.1.2. Show a Particular Feature or Branch Change</h4></div></div></div><p> + Developers use tags in the Yocto Project kernel tree to divide changes for significant + features or branches. + Once you know a particular tag, you can use Git commands + to show changes associated with the tag and find the branches that contain + the feature. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Because BSP branch, <code class="filename">kernel.org</code>, and feature tags are all + present, there could be many tags. + </div><p> + The <code class="filename">git show <tag></code> command shows changes that are tagged by + a feature. + Here is an example that shows changes tagged by the <code class="filename">systemtap</code> + feature: + </p><pre class="literallayout"> + $ git show systemtap + </pre><p> + You can use the <code class="filename">git branch --contains <tag></code> command + to show the branches that contain a particular feature. + This command shows the branches that contain the <code class="filename">systemtap</code> + feature: + </p><pre class="literallayout"> + $ git branch --contains systemtap + </pre><p> + </p><p> + You can use many other comparisons to isolate BSP and kernel changes. + For example, you can compare against <code class="filename">kernel.org</code> tags + such as the <code class="filename">v3.4</code> tag. + </p></div></div><div class="section" title="3.4.2. Development: Saving Kernel Modifications"><div class="titlepage"><div><div><h3 class="title"><a id="development-saving-kernel-modifications"></a>3.4.2. Development: Saving Kernel Modifications</h3></div></div></div><p> + Another common operation is to build a BSP supplied by the Yocto Project, make some + changes, rebuild, and then test. + Those local changes often need to be exported, shared or otherwise maintained. + </p><p> + Since the Yocto Project kernel source tree is backed by Git, this activity is + much easier as compared to with previous releases. + Because Git tracks file modifications, additions and deletions, it is easy + to modify the code and later realize that you need to save the changes. + It is also easy to determine what has changed. + This method also provides many tools to commit, undo and export those modifications. + </p><p> + This section and its sub-sections, describe general application of Git's + <code class="filename">push</code> and <code class="filename">pull</code> commands, which are used to + get your changes upstream or source your code from an upstream repository. + The Yocto Project provides scripts that help you work in a collaborative development + environment. + For information on these scripts, see the + "<a class="link" href="#pushing-a-change-upstream" target="_top">Using Scripts to Push a Change + Upstream and Request a Pull</a>" and + "<a class="link" href="#submitting-a-patch" target="_top">Using Email to Submit a Patch</a>" + sections in the Yocto Project Development Manual. + </p><p> + There are many ways to save kernel modifications. + The technique employed + depends on the destination for the patches: + + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bulk storage</p></li><li class="listitem"><p>Internal sharing either through patches or by using Git</p></li><li class="listitem"><p>External submissions</p></li><li class="listitem"><p>Exporting for integration into another Source Code + Manager (SCM)</p></li></ul></div><p> + </p><p> + Because of the following list of issues, the destination of the patches also influences + the method for gathering them: + + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Bisectability</p></li><li class="listitem"><p>Commit headers</p></li><li class="listitem"><p>Division of subsystems for separate submission or review</p></li></ul></div><p> + </p><div class="section" title="3.4.2.1. Bulk Export"><div class="titlepage"><div><div><h4 class="title"><a id="bulk-export"></a>3.4.2.1. Bulk Export</h4></div></div></div><p> + This section describes how you can "bulk" export changes that have not + been separated or divided. + This situation works well when you are simply storing patches outside of the kernel + source repository, either permanently or temporarily, and you are not committing + incremental changes during development. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + This technique is not appropriate for full integration of upstream submission + because changes are not properly divided and do not provide an avenue for per-change + commit messages. + Therefore, this example assumes that changes have not been committed incrementally + during development and that you simply must gather and export them. + </div><p> + </p><pre class="literallayout"> + # bulk export of ALL modifications without separation or division + # of the changes + + $ git add . + $ git commit -s -a -m <msg> + or + $ git commit -s -a # and interact with $EDITOR + </pre><p> + </p><p> + The previous operations capture all the local changes in the project source + tree in a single Git commit. + And, that commit is also stored in the project's source tree. + </p><p> + Once the changes are exported, you can restore them manually using a template + or through integration with the <code class="filename">default_kernel</code>. + </p></div><div class="section" title="3.4.2.2. Incremental/Planned Sharing"><div class="titlepage"><div><div><h4 class="title"><a id="incremental-planned-sharing"></a>3.4.2.2. Incremental/Planned Sharing</h4></div></div></div><p> + This section describes how to save modifications when you are making incremental + commits or practicing planned sharing. + The examples in this section assume that you have incrementally committed + changes to the tree during development and now need to export them. + The sections that follow + describe how you can export your changes internally through either patches or by + using Git commands. + </p><p> + During development, the following commands are of interest. + For full Git documentation, refer to the Git documentation at + <a class="ulink" href="http://github.com" target="_top">http://github.com</a>. + + </p><pre class="literallayout"> + # edit a file + $ vi <path>/file + # stage the change + $ git add <path>/file + # commit the change + $ git commit -s + # remove a file + $ git rm <path>/file + # commit the change + $ git commit -s + + ... etc. + </pre><p> + </p><p> + Distributed development with Git is possible when you use a universally + agreed-upon unique commit identifier (set by the creator of the commit) that maps to a + specific change set with a specific parent. + This identifier is created for you when + you create a commit, and is re-created when you amend, alter or re-apply + a commit. + As an individual in isolation, this is of no interest. + However, if you + intend to share your tree with normal Git <code class="filename">push</code> and + <code class="filename">pull</code> operations for + distributed development, you should consider the ramifications of changing a + commit that you have already shared with others. + </p><p> + Assuming that the changes have not been pushed upstream, or pulled into + another repository, you can update both the commit content and commit messages + associated with development by using the following commands: + + </p><pre class="literallayout"> + $ Git add <path>/file + $ Git commit --amend + $ Git rebase or Git rebase -i + </pre><p> + </p><p> + Again, assuming that the changes have not been pushed upstream, and that + no pending works-in-progress exist (use <code class="filename">git status</code> to check), then + you can revert (undo) commits by using the following commands: + + </p><pre class="literallayout"> + # remove the commit, update working tree and remove all + # traces of the change + $ git reset --hard HEAD^ + # remove the commit, but leave the files changed and staged for re-commit + $ git reset --soft HEAD^ + # remove the commit, leave file change, but not staged for commit + $ git reset --mixed HEAD^ + </pre><p> + </p><p> + You can create branches, "cherry-pick" changes, or perform any number of Git + operations until the commits are in good order for pushing upstream + or for pull requests. + After a <code class="filename">push</code> or <code class="filename">pull</code> command, + commits are normally considered + "permanent" and you should not modify them. + If the commits need to be changed, you can incrementally do so with new commits. + These practices follow standard Git workflow and the <code class="filename">kernel.org</code> best + practices, which is recommended. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + It is recommended to tag or branch before adding changes to a Yocto Project + BSP or before creating a new one. + The reason for this recommendation is because the branch or tag provides a + reference point to facilitate locating and exporting local changes. + </div><p> + </p><div class="section" title="3.4.2.2.1. Exporting Changes Internally by Using Patches"><div class="titlepage"><div><div><h5 class="title"><a id="export-internally-via-patches"></a>3.4.2.2.1. Exporting Changes Internally by Using Patches</h5></div></div></div><p> + This section describes how you can extract committed changes from a working directory + by exporting them as patches. + Once the changes have been extracted, you can use the patches for upstream submission, + place them in a Yocto Project template for automatic kernel patching, + or apply them in many other common uses. + </p><p> + This example shows how to create a directory with sequentially numbered patches. + Once the directory is created, you can apply it to a repository using the + <code class="filename">git am</code> command to reproduce the original commit and all + the related information such as author, date, commit log, and so forth. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The new commit identifiers (ID) will be generated upon re-application. + This action reflects that the commit is now applied to an underlying commit + with a different ID. + </div><p> + </p><pre class="literallayout"> + # <first-commit> can be a tag if one was created before development + # began. It can also be the parent branch if a branch was created + # before development began. + + $ git format-patch -o <dir> <first commit>..<last commit> + </pre><p> + </p><p> + In other words: + </p><pre class="literallayout"> + # Identify commits of interest. + + # If the tree was tagged before development + $ git format-patch -o <save dir> <tag> + + # If no tags are available + $ git format-patch -o <save dir> HEAD^ # last commit + $ git format-patch -o <save dir> HEAD^^ # last 2 commits + $ git whatchanged # identify last commit + $ git format-patch -o <save dir> <commit id> + $ git format-patch -o <save dir> <rev-list> + </pre><p> + </p></div><div class="section" title="3.4.2.2.2. Exporting Changes Internally by Using Git"><div class="titlepage"><div><div><h5 class="title"><a id="export-internally-via-git"></a>3.4.2.2.2. Exporting Changes Internally by Using Git</h5></div></div></div><p> + This section describes how you can export changes from a working directory + by pushing the changes into a master repository or by making a pull request. + Once you have pushed the changes to the master repository, you can then + pull those same changes into a new kernel build at a later time. + </p><p> + Use this command form to push the changes: + </p><pre class="literallayout"> + $ git push ssh://<master_server>/<path_to_repo> + <local_branch>:<remote_branch> + </pre><p> + </p><p> + For example, the following command pushes the changes from your local branch + <code class="filename">yocto/standard/common-pc/base</code> to the remote branch with the same name + in the master repository <code class="filename">//git.mycompany.com/pub/git/kernel-3.4</code>. + </p><pre class="literallayout"> + $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \ + yocto/standard/common-pc/base:yocto/standard/common-pc/base + </pre><p> + </p><p> + A pull request entails using the <code class="filename">git request-pull</code> command to compose + an email to the + maintainer requesting that a branch be pulled into the master repository, see + <a class="ulink" href="http://github.com/guides/pull-requests" target="_top">http://github.com/guides/pull-requests</a> for an example. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Other commands such as <code class="filename">git stash</code> or branching can also be used to save + changes, but are not covered in this document. + </div><p> + </p></div></div><div class="section" title="3.4.2.3. Exporting Changes for External (Upstream) Submission"><div class="titlepage"><div><div><h4 class="title"><a id="export-for-external-upstream-submission"></a>3.4.2.3. Exporting Changes for External (Upstream) Submission</h4></div></div></div><p> + This section describes how to export changes for external upstream submission. + If the patch series is large or the maintainer prefers to pull + changes, you can submit these changes by using a pull request. + However, it is common to send patches as an email series. + This method allows easy review and integration of the changes. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Before sending patches for review be sure you understand the + community standards for submitting and documenting changes and follow their best practices. + For example, kernel patches should follow standards such as: + <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + <a class="ulink" href="http://linux.yyz.us/patch-format.html" target="_top">http://linux.yyz.us/patch-format.html</a></p></li><li class="listitem"><p>Documentation/SubmittingPatches (in any linux + kernel source tree)</p></li></ul></div></div><p> + </p><p> + The messages used to commit changes are a large part of these standards. + Consequently, be sure that the headers for each commit have the required information. + For information on how to follow the Yocto Project commit message standards, see the + "<a class="link" href="#how-to-submit-a-change" target="_top">How to Submit a + Change</a>" section in the Yocto Project Development Manual. + </p><p> + If the initial commits were not properly documented or do not meet those standards, + you can re-base by using the <code class="filename">git rebase -i</code> command to + manipulate the commits and + get them into the required format. + Other techniques such as branching and cherry-picking commits are also viable options. + </p><p> + Once you complete the commits, you can generate the email that sends the patches + to the maintainer(s) or lists that review and integrate changes. + The command <code class="filename">git send-email</code> is commonly used to ensure + that patches are properly + formatted for easy application and avoid mailer-induced patch damage. + </p><p> + The following is an example of dumping patches for external submission: + </p><pre class="literallayout"> + # dump the last 4 commits + $ git format-patch --thread -n -o ~/rr/ HEAD^^^^ + $ git send-email --compose --subject '[RFC 0/N] <patch series summary>' \ + --to foo@yoctoproject.org --to bar@yoctoproject.org \ + --cc list@yoctoproject.org ~/rr + # the editor is invoked for the 0/N patch, and when complete the entire + # series is sent via email for review + </pre><p> + </p></div><div class="section" title="3.4.2.4. Exporting Changes for Import into Another SCM"><div class="titlepage"><div><div><h4 class="title"><a id="export-for-import-into-other-scm"></a>3.4.2.4. Exporting Changes for Import into Another SCM</h4></div></div></div><p> + When you want to export changes for import into another + Source Code Manager (SCM), you can use any of the previously discussed + techniques. + However, if the patches are manually applied to a secondary tree and then + that tree is checked into the SCM, you can lose change information such as + commit logs. + This process is not recommended. + </p><p> + Many SCMs can directly import Git commits, or can translate Git patches so that + information is not lost. + Those facilities are SCM-dependent and you should use them whenever possible. + </p></div></div><div class="section" title="3.4.3. Working with the Yocto Project Kernel in Another SCM"><div class="titlepage"><div><div><h3 class="title"><a id="scm-working-with-the-yocto-project-kernel-in-another-scm"></a>3.4.3. Working with the Yocto Project Kernel in Another SCM</h3></div></div></div><p> + This section describes kernel development in an SCM other than Git, + which is not the same as exporting changes to another SCM described earlier. + For this scenario, you use the OpenEmbedded build system to + develop the kernel in a different SCM. + The following must be true for you to accomplish this: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The delivered Yocto Project kernel must be exported into the second + SCM.</p></li><li class="listitem"><p>Development must be exported from that secondary SCM into a + format that can be used by the OpenEmbedded build system.</p></li></ul></div><p> + </p><div class="section" title="3.4.3.1. Exporting the Delivered Kernel to the SCM"><div class="titlepage"><div><div><h4 class="title"><a id="exporting-delivered-kernel-to-scm"></a>3.4.3.1. Exporting the Delivered Kernel to the SCM</h4></div></div></div><p> + Depending on the SCM, it might be possible to export the entire Yocto Project + kernel Git repository, branches and all, into a new environment. + This method is preferred because it has the most flexibility and potential to maintain + the meta data associated with each commit. + </p><p> + When a direct import mechanism is not available, it is still possible to + export a branch (or series of branches) and check them into a new repository. + </p><p> + The following commands illustrate some of the steps you could use to + import the <code class="filename">yocto/standard/common-pc/base</code> + kernel into a secondary SCM: + </p><pre class="literallayout"> + $ git checkout yocto/standard/common-pc/base + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + </pre><p> + </p><p> + You could now relocate the CVS repository and use it in a centralized manner. + </p><p> + The following commands illustrate how you can condense and merge two BSPs into a + second SCM: + </p><pre class="literallayout"> + $ git checkout yocto/standard/common-pc/base + $ git merge yocto/standard/common-pc-64/base + # resolve any conflicts and commit them + $ cd .. ; echo linux/.git > .cvsignore + $ cvs import -m "initial import" linux MY_COMPANY start + </pre><p> + </p></div><div class="section" title="3.4.3.2. Importing Changes for the Build"><div class="titlepage"><div><div><h4 class="title"><a id="importing-changes-for-build"></a>3.4.3.2. Importing Changes for the Build</h4></div></div></div><p> + Once development has reached a suitable point in the second development + environment, you need to export the changes as patches. + To export them, place the changes in a recipe and + automatically apply them to the kernel during patching. + </p></div></div><div class="section" title="3.4.4. Creating a BSP Based on an Existing Similar BSP"><div class="titlepage"><div><div><h3 class="title"><a id="bsp-creating"></a>3.4.4. Creating a BSP Based on an Existing Similar BSP</h3></div></div></div><p> + This section overviews the process of creating a BSP based on an + existing similar BSP. + The information is introductory in nature and does not provide step-by-step examples. + For detailed information on how to create a BSP given an existing similar BSP, see + the "<a class="link" href="#dev-manual-bsp-appendix" target="_top">BSP Development + Example</a>" appendix in the Yocto Project Development Manual, or see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another" target="_top">Transcript:_creating_one_generic_Atom_BSP_from_another</a> + wiki page. + </p><p> + The basic steps you need to follow are: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Make sure you have set up a local source directory:</em></span> + You must create a local <a class="link" href="#source-directory" target="_top">source + directory</a> by either creating a Git repository (recommended) or + extracting a Yocto Project release tarball.</p></li><li class="listitem"><p><span class="emphasis"><em>Choose an existing BSP available with the Yocto Project:</em></span> + Try to map your board features as closely to the features of a BSP that is + already supported and exists in the Yocto Project. + Starting with something as close as possible to your board makes developing + your BSP easier. + You can find all the BSPs that are supported and ship with the Yocto Project + on the Yocto Project's Download page at + <a class="ulink" href="http://www.yoctoproject.org/download" target="_top">http://www.yoctoproject.org/download</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Be sure you have the Base BSP:</em></span> + You need to either have a local Git repository of the base BSP set up or + have downloaded and extracted the files from a release BSP tarball. + Either method gives you access to the BSP source files.</p></li><li class="listitem"><p><span class="emphasis"><em>Make a copy of the existing BSP, thus isolating your new + BSP work:</em></span> + Copying the existing BSP file structure gives you a new area in which to work.</p></li><li class="listitem"><p><span class="emphasis"><em>Make configuration and recipe changes to your new BSP:</em></span> + Configuration changes involve the files in the BSP's <code class="filename">conf</code> + directory. + Changes include creating a machine-specific configuration file and editing the + <code class="filename">layer.conf</code> file. + The configuration changes identify the kernel you will be using. + Recipe changes include removing, modifying, or adding new recipe files that + instruct the build process on what features to include in the image.</p></li><li class="listitem"><p><span class="emphasis"><em>Prepare for the build:</em></span> + Before you actually initiate the build, you need to set up the build environment + by sourcing the environment initialization script. + After setting up the environment, you need to make some build configuration + changes to the <code class="filename">local.conf</code> and <code class="filename">bblayers.conf</code> + files.</p></li><li class="listitem"><p><span class="emphasis"><em>Build the image:</em></span> + The OpenEmbedded build system uses BitBake to create the image. + You need to decide on the type of image you are going to build (e.g. minimal, base, + core, sato, and so forth) and then start the build using the <code class="filename">bitbake</code> + command.</p></li></ol></div><p> + </p></div><div class="section" title="3.4.5. "-dirty" String"><div class="titlepage"><div><div><h3 class="title"><a id="tip-dirty-string"></a>3.4.5. "-dirty" String</h3></div></div></div><p> + If kernel images are being built with "-dirty" on the end of the version + string, this simply means that modifications in the source + directory have not been committed. + </p><pre class="literallayout"> + $ git status + </pre><p> + </p><p> + You can use the above Git command to report modified, removed, or added files. + You should commit those changes to the tree regardless of whether they will be saved, + exported, or used. + Once you commit the changes you need to rebuild the kernel. + </p><p> + To brute force pickup and commit all such pending changes, enter the following: + </p><pre class="literallayout"> + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + </pre><p> + </p><p> + Next, rebuild the kernel. + </p></div></div></div> + + + +</div> + +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="100%"><tr><td align="left"><img src="figures/poky-title.png" align="left" width="100%" /></td></tr></table> + + <div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="poky-ref-manual"></a></h1></div><div><div class="authorgroup"> + <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"> + <span class="orgname">Linux Foundation<br /></span> + </div><code class="email"><<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>></code></div> + + </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1506919"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. + </p> + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + Yocto Project Reference Manual on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> + <tr><td align="left">Revision 4.0+git</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr> + <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> + <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> + <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> + <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr><td align="left">Revision 1.3</td><td align="left">Sometime in 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + </table></div></div></div><hr /></div> + + + <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-welcome"></a>1.1. Introduction</h2></div></div></div><p> + This manual provides reference information for the current release of the Yocto Project. + The Yocto Project is an open-source collaboration project focused on embedded Linux + developers. + Amongst other things, the Yocto Project uses the OpenEmbedded build system, which + is based on the Poky project, to construct complete Linux images. + You can find complete introductory and getting started information on the Yocto Project + by reading the + Yocto Project Quick Start. + For task-based information using the Yocto Project, see the + Yocto Project Development Manual. + You can also find lots of information on the Yocto Project on the + <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>. + </p></div><div class="section" title="1.2. Documentation Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div><p> + This reference manual consists of the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#usingpoky" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter + provides an overview of the components that make up the Yocto Project + followed by information about debugging images created in the Yocto Project. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#technical-details" title="Chapter 3. Technical Details">Technical Details</a>:</em></span> + This chapter describes fundamental Yocto Project components as well as an explanation + behind how the Yocto Project uses shared state (sstate) cache to speed build time. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-structure" title="Chapter 4. Source Directory Structure">Directory Structure</a>:</em></span> + This chapter describes the + <a class="link" href="#source-directory" target="_top">source directory</a> created + either by unpacking a released Yocto Project tarball on your host development system, + or by cloning the upstream + <a class="link" href="#poky" target="_top">Poky</a> Git repository. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-bitbake" title="Chapter 5. BitBake">BitBake</a>:</em></span> + This chapter provides an overview of the BitBake tool and its role within + the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-classes" title="Chapter 6. Classes">Classes</a>:</em></span> + This chapter describes the classes used in the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-images" title="Chapter 7. Images">Images</a>:</em></span> + This chapter describes the standard images that the Yocto Project supports. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-features" title="Chapter 8. Reference: Features">Features</a>:</em></span> + This chapter describes mechanisms for creating distribution, machine, and image + features during the build process using the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-variables-glos" title="Chapter 9. Variables Glossary">Variables Glossary</a>:</em></span> + This chapter presents most variables used by the OpenEmbedded build system, which + using BitBake. + Entries describe the function of the variable and how to apply them. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-varlocality" title="Chapter 10. Variable Context">Variable Context</a>:</em></span> + This chapter provides variable locality or context.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#faq" title="Chapter 11. FAQ">FAQ</a>:</em></span> + This chapter provides answers for commonly asked questions in the Yocto Project + development environment.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#resources" title="Chapter 12. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span> + This chapter provides guidance on how you can contribute back to the Yocto + Project.</p></li></ul></div><p> + </p></div><div class="section" title="1.3. System Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-requirements"></a>1.3. System Requirements</h2></div></div></div><p> + For Yocto Project system requirements, see the + <a class="link" href="#yp-resources" target="_top"> + What You Need and How You Get It</a> section in the Yocto Project Quick Start. + </p></div><div class="section" title="1.4. Obtaining the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div><p> + The Yocto Project development team makes the Yocto Project available through a number + of methods: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_top">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at + <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_top">http://autobuilder.yoctoproject.org/nightly</a>. + These builds include Yocto Project releases, meta-toolchain tarballs, and + experimental builds.</p></li><li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases + of the Yocto Project and supported BSPs at the + <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>. + Along with these downloads, you can find lots of other information at this site. + </p></li></ul></div><p> + </p></div><div class="section" title="1.5. Development Checkouts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div><p> + Development using the Yocto Project requires a local + <a class="link" href="#source-directory" target="_top">source directory</a>. + You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, + or by cloning a copy of the upstream + <a class="link" href="#poky" target="_top">Poky</a> Git repository. + For information on both these methods, see the + "<a class="link" href="#getting-setup" target="_top">Getting Setup</a>" + section in the Yocto Project Development Manual. + </p></div></div> + + <div class="chapter" title="Chapter 2. Using the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd></dl></div><p> + This chapter describes common usage for the Yocto Project. + The information is introductory in nature as other manuals in the Yocto Project + documentation set provide more details on how to use the Yocto Project. + </p><div class="section" title="2.1. Running a Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div><p> + You can find general information on how to build an image using the OpenEmbedded build + system in the + "<a class="link" href="#building-image" target="_top">Building an Image</a>" + section of the Yocto Project Quick Start. + This section provides a summary of the build process and provides information + for less obvious aspects of the build process. + </p><div class="section" title="2.1.1. Build Overview"><div class="titlepage"><div><div><h3 class="title"><a id="build-overview"></a>2.1.1. Build Overview</h3></div></div></div><p> + The first thing you need to do is set up the OpenEmbedded build environment by sourcing + the environment setup script as follows: + </p><pre class="literallayout"> + $ source oe-init-build-env [build_dir] + </pre><p> + </p><p> + The <code class="filename">build_dir</code> is optional and specifies the directory the + OpenEmbedded build system uses for the build - + the <a class="link" href="#build-directory" target="_top">build directory</a>. + If you do not specify a build directory it defaults to <code class="filename">build</code> + in your current working directory. + A common practice is to use a different build directory for different targets. + For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code> + target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target. + See <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a> + for more information on this script. + </p><p> + Once the build environment is set up, you can build a target using: + </p><pre class="literallayout"> + $ bitbake <target> + </pre><p> + </p><p> + The <code class="filename">target</code> is the name of the recipe you want to build. + Common targets are the images in <code class="filename">meta/recipes-core/images</code>, + <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + Or, the target can be the name of a recipe for a specific piece of software such as + <span class="application">busybox</span>. + For more details about the images the OpenEmbedded build system supports, see the + "<a class="link" href="#ref-images" title="Chapter 7. Images">Images</a>" chapter. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Building an image without GNU Public License Version 3 (GPLv3) components is + only supported for minimal and base images. + See the "<a class="link" href="#ref-images" title="Chapter 7. Images">Images</a>" chapter for more information. + </div></div><div class="section" title="2.1.2. Building an Image Using GPL Components"><div class="titlepage"><div><div><h3 class="title"><a id="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div><p> + When building an image using GPL components, you need to maintain your original + settings and not switch back and forth applying different versions of the GNU + Public License. + If you rebuild using different versions of GPL, dependency errors might occur + due to some components not being rebuilt. + </p></div></div><div class="section" title="2.2. Installing and Using the Result"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div><p> + Once an image has been built, it often needs to be installed. + The images and kernels built by the OpenEmbedded build system are placed in the + <a class="link" href="#build-directory" target="_top">build directory</a> in + <code class="filename">tmp/deploy/images</code>. + For information on how to run pre-built images such as <code class="filename">qemux86</code> + and <code class="filename">qemuarm</code>, see the + "<a class="link" href="#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>" + section in the Yocto Project Quick Start. + For information about how to install these images, see the documentation for your + particular board/machine. + </p></div><div class="section" title="2.3. Debugging Build Failures"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div><p> + The exact method for debugging build failures depends on the nature of the + problem and on the system's area from which the bug originates. + Standard debugging practices such as comparison against the last + known working version with examination of the changes and the re-application of steps + to identify the one causing the problem are + valid for the Yocto Project just as they are for any other system. + Even though it is impossible to detail every possible potential failure, + this section provides some general tips to aid in debugging. + </p><div class="section" title="2.3.1. Task Failures"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in + <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. + For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86 + machine (<code class="filename">qemux86</code>) might be + <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</code>. + To see what BitBake runs to generate that log, look at the corresponding + <code class="filename">run.do_taskname.pid</code> file located in the same directory. + </p><p> + Presently, the output from Python tasks is sent directly to the console. + </p></div><div class="section" title="2.3.2. Running Specific Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div><p> + Any given package consists of a set of tasks. + The standard BitBake behavior in most cases is: <code class="filename">fetch</code>, + <code class="filename">unpack</code>, + <code class="filename">patch</code>, <code class="filename">configure</code>, + <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>, + <code class="filename">package_write</code>, and <code class="filename">build</code>. + The default task is <code class="filename">build</code> and any tasks on which it depends + build first. + Some tasks exist, such as <code class="filename">devshell</code>, that are not part of the + default build chain. + If you wish to run a task that is not part of the default build chain, you can use the + <code class="filename">-c</code> option in BitBake as follows: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop -c devshell + </pre><p> + </p><p> + If you wish to rerun a task, use the <code class="filename">-f</code> force option. + For example, the following sequence forces recompilation after changing files in the + working directory. + </p><pre class="literallayout"> + $ bitbake matchbox-desktop + . + . + [make some changes to the source code in the working directory] + . + . + $ bitbake matchbox-desktop -c compile -f + $ bitbake matchbox-desktop + </pre><p> + </p><p> + This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it. + The last command reruns all tasks (basically the packaging tasks) after the compile. + BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore + understands that the other tasks also need to be run again. + </p><p> + You can view a list of tasks in a given package by running the + <code class="filename">listtasks</code> task as follows: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop -c listtasks + </pre><p> + The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>. + </p></div><div class="section" title="2.3.3. Dependency Graphs"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div><p> + Sometimes it can be hard to see why BitBake wants to build some other packages before a given + package you have specified. + The <code class="filename">bitbake -g targetname</code> command creates the + <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>, + and <code class="filename">task-depends.dot</code> files in the current directory. + These files show the package and task dependencies and are useful for debugging problems. + You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to + display the results in a more human-readable form. + </p></div><div class="section" title="2.3.4. General BitBake Problems"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div><p> + You can see debug output from BitBake by using the <code class="filename">-D</code> option. + The debug output gives more information about what BitBake + is doing and the reason behind it. + Each <code class="filename">-D</code> option you use increases the logging level. + The most common usage is <code class="filename">-DDD</code>. + </p><p> + The output from <code class="filename">bitbake -DDD -v targetname</code> can reveal why + BitBake chose a certain version of a package or why BitBake + picked a certain provider. + This command could also help you in a situation where you think BitBake did something + unexpected. + </p></div><div class="section" title="2.3.5. Building with No Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div><p> + If you really want to build a specific <code class="filename">.bb</code> file, you can use + the command form <code class="filename">bitbake -b <somepath/somefile.bb></code>. + This command form does not check for dependencies so you should use it + only when you know its dependencies already exist. + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match. + </p></div><div class="section" title="2.3.6. Variables"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div><p> + The <code class="filename">-e</code> option dumps the resulting environment for + either the configuration (no package specified) or for a + specific package when specified; or <code class="filename">-b recipename</code> + to show the environment from parsing a single recipe file only. + </p></div><div class="section" title="2.3.7. Recipe Logging Mechanisms"><div class="titlepage"><div><div><h3 class="title"><a id="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div><p> + Best practices exist while writing recipes that both log build progress and + act on build conditions such as warnings and errors. + Both Python and Bash language bindings exist for the logging mechanism: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake + supports several loglevels: <code class="filename">bb.fatal</code>, + <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>, + <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>, + and <code class="filename">bb.debug</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set + of loglevels exist and are accessed with a similar syntax: + <code class="filename">bbfatal</code>, <code class="filename">bberror</code>, + <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>, + <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li></ul></div><p> + </p><p> + For guidance on how logging is handled in both Python and Bash recipes, see the + <code class="filename">logging.bbclass</code> file in the + <code class="filename">meta/classes</code> folder of the + <a class="link" href="#source-directory" target="_top">source directory</a>. + </p><div class="section" title="2.3.7.1. Logging With Python"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div><p> + When creating recipes using Python and inserting code that handles build logs + keep in mind the goal is to have informative logs while keeping the console as + "silent" as possible. + Also, if you want status messages in the log use the "debug" loglevel. + </p><p> + Following is an example written in Python. + The code handles logging for a function that determines the number of tasks + needed to be run: + </p><pre class="literallayout"> + python do_listtasks() { + bb.debug(2, "Starting to figure out the task list") + if noteworthy_condition: + bb.note("There are 47 tasks to run") + bb.debug(2, "Got to point xyz") + if warning_trigger: + bb.warn("Detected warning_trigger, this might be a problem later.") + if recoverable_error: + bb.error("Hit recoverable_error, you really need to fix this!") + if fatal_error: + bb.fatal("fatal_error detected, unable to print the task list") + bb.plain("The tasks present are abc") + bb.debug(2, "Finished figuring out the tasklist") + } + </pre><p> + </p></div><div class="section" title="2.3.7.2. Logging With Bash"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div><p> + When creating recipes using Bash and inserting code that handles build + logs you have the same goals - informative with minimal console output. + The syntax you use for recipes written in Bash is similar to that of + recipes written in Python described in the previous section. + </p><p> + Following is an example written in Bash. + The code logs the progress of the <code class="filename">do_my_function</code> function. + </p><pre class="literallayout"> + do_my_function() { + bbdebug 2 "Running do_my_function" + if [ exceptional_condition ]; then + bbnote "Hit exceptional_condition" + fi + bbdebug 2 "Got to point xyz" + if [ warning_trigger ]; then + bbwarn "Detected warning_trigger, this might cause a problem later." + fi + if [ recoverable_error ]; then + bberror "Hit recoverable_error, correcting" + fi + if [ fatal_error ]; then + bbfatal "fatal_error detected" + fi + bbdebug 2 "Completed do_my_function" + } + </pre><p> + </p></div></div><div class="section" title="2.3.8. Other Tips"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div><p> + Here are some other tips that you might find useful: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>When adding new packages, it is worth watching for + undesirable items making their way into compiler command lines. + For example, you do not want references to local system files like + <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>. + </p></li><li class="listitem"><p>If you want to remove the psplash boot splashscreen, + add <code class="filename">psplash=false</code> to the kernel command line. + Doing so prevents psplash from loading and thus allows you to see the console. + It is also possible to switch out of the splashscreen by + switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). + </p></li></ul></div><p> + </p></div></div></div> + + <div class="chapter" title="Chapter 3. Technical Details"><div class="titlepage"><div><div><h2 class="title"><a id="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></div><p> + This chapter provides technical details for various parts of the Yocto Project. + Currently, topics include Yocto Project components and shared state (sstate) cache. + </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div><p> + The BitBake task executor together with various types of configuration files form the + OpenEmbedded Core. + This section overviews the BitBake task executor and the + configuration files by describing what they are used for and how they interact. + </p><p> + BitBake handles the parsing and execution of the data files. + The data itself is of various types: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular + pieces of software</p></li><li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build + information (e.g. how to build a Linux kernel).</p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings, + policy decisions, etc. + Configuration data acts as the glue to bind everything together.</p></li></ul></div><p> + For more information on data, see the + "<a class="link" href="#yocto-project-terms" target="_top">Yocto Project Terms</a>" + section in the Yocto Project Development Manual. + </p><p> + BitBake knows how to combine multiple data sources together and refers to each data source + as a layer. + For information on layers, see the + "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding and + Creating Layers</a>" section of the Yocto Project Development Manual. + </p><p> + Following are some brief details on these core components. + For more detailed information on these components see the + "<a class="link" href="#ref-structure" title="Chapter 4. Source Directory Structure">Directory Structure</a>" chapter. + </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div><p> + BitBake is the tool at the heart of the OpenEmbedded build system and is responsible + for parsing the metadata, generating a list of tasks from it, + and then executing those tasks. + To see a list of the options BitBake supports, use the following help command: + </p><pre class="literallayout"> + $ bitbake --help + </pre><p> + </p><p> + The most common usage for BitBake is <code class="filename">bitbake <packagename></code>, where + <code class="filename">packagename</code> is the name of the package you want to build + (referred to as the "target" in this manual). + The target often equates to the first part of a <code class="filename">.bb</code> filename. + So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you + might type the following: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop + </pre><p> + Several different versions of <code class="filename">matchbox-desktop</code> might exist. + BitBake chooses the one selected by the distribution configuration. + You can get more details about how BitBake chooses between different + target versions and providers in the + "<a class="link" href="#ref-bitbake-providers" title="5.2. Preferences and Providers">Preferences and Providers</a>" section. + </p><p> + BitBake also tries to execute any dependent tasks first. + So for example, before building <code class="filename">matchbox-desktop</code>, BitBake + would build a cross compiler and <code class="filename">eglibc</code> if they had not already + been built. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code> + GNU version of the Unix standard C library. By default, the OpenEmbedded build system + builds with <code class="filename">eglibc</code>.</div><p> + </p><p> + A useful BitBake option to consider is the <code class="filename">-k</code> or + <code class="filename">--continue</code> option. + This option instructs BitBake to try and continue processing the job as much + as possible even after encountering an error. + When an error occurs, the target that + failed and those that depend on it cannot be remade. + However, when you use this option other dependencies can still be processed. + </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div><p> + The <code class="filename">.bb</code> files are usually referred to as "recipes." + In general, a recipe contains information about a single piece of software. + The information includes the location from which to download the source patches + (if any are needed), which special configuration options to apply, + how to compile the source files, and how to package the compiled output. + </p><p> + The term "package" can also be used to describe recipes. + However, since the same word is used for the packaged output from the OpenEmbedded + build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files), + this document avoids using the term "package" when referring to recipes. + </p></div><div class="section" title="3.1.3. Classes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div><p> + Class files (<code class="filename">.bbclass</code>) contain information that is useful to share + between metadata files. + An example is the Autotools class, which contains + common settings for any application that Autotools uses. + The "<a class="link" href="#ref-classes" title="Chapter 6. Classes">Reference: Classes</a>" chapter provides details + about common classes and how to use them. + </p></div><div class="section" title="3.1.4. Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div><p> + The configuration files (<code class="filename">.conf</code>) define various configuration variables + that govern the OpenEmbedded build process. + These files fall into several areas that define machine configuration options, + distribution configuration options, compiler tuning options, general common configuration + options and user configuration options (<code class="filename">local.conf</code>, which is found + in the <a class="ulink" href="build-directory" target="_top">build directory</a>). + </p></div></div><div class="section" title="3.2. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div><p> + By design, the OpenEmbedded build system builds everything from scratch unless + BitBake can determine that parts don't need to be rebuilt. + Fundamentally, building from scratch is attractive as it means all parts are + built fresh and there is no possibility of stale data causing problems. + When developers hit problems, they typically default back to building from scratch + so they know the state of things from the start. + </p><p> + Building an image from scratch is both an advantage and a disadvantage to the process. + As mentioned in the previous paragraph, building from scratch ensures that + everything is current and starts from a known state. + However, building from scratch also takes much longer as it generally means + rebuilding things that don't necessarily need rebuilt. + </p><p> + The Yocto Project implements shared state code that supports incremental builds. + The implementation of the shared state code answers the following questions that + were fundamental roadblocks within the OpenEmbedded incremental build support system: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">What pieces of the system have changed and what pieces have not changed?</li><li class="listitem">How are changed pieces of software removed and replaced?</li><li class="listitem">How are pre-built components that don't need to be rebuilt from scratch + used when they are available?</li></ul></div><p> + </p><p> + For the first question, the build system detects changes in the "inputs" to a given task by + creating a checksum (or signature) of the task's inputs. + If the checksum changes, the system assumes the inputs have changed and the task needs to be + rerun. + For the second question, the shared state (sstate) code tracks which tasks add which output + to the build process. + This means the output from a given task can be removed, upgraded or otherwise manipulated. + The third question is partly addressed by the solution for the second question + assuming the build system can fetch the sstate objects from remote locations and + install them if they are deemed to be valid. + </p><p> + The rest of this section goes into detail about the overall incremental build + architecture, the checksums (signatures), shared state, and some tips and tricks. + </p><div class="section" title="3.2.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title"><a id="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div><p> + When determining what parts of the system need to be built, BitBake + uses a per-task basis and does not use a per-recipe basis. + You might wonder why using a per-task basis is preferred over a per-recipe basis. + To help explain, consider having the IPK packaging backend enabled and then switching to DEB. + In this case, <code class="filename">do_install</code> and <code class="filename">do_package</code> + output are still valid. + However, with a per-recipe approach, the build would not include the + <code class="filename">.deb</code> files. + Consequently, you would have to invalidate the whole build and rerun it. + Rerunning everything is not the best situation. + Also in this case, the core must be "taught" much about specific tasks. + This methodology does not scale well and does not allow users to easily add new tasks + in layers or as external recipes without touching the packaged-staging core. + </p></div><div class="section" title="3.2.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title"><a id="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div><p> + The shared state code uses a checksum, which is a unique signature of a task's + inputs, to determine if a task needs to be run again. + Because it is a change in a task's inputs that triggers a rerun, the process + needs to detect all the inputs to a given task. + For shell tasks, this turns out to be fairly easy because + the build process generates a "run" shell script for each task and + it is possible to create a checksum that gives you a good idea of when + the task's data changes. + </p><p> + To complicate the problem, there are things that should not be included in + the checksum. + First, there is the actual specific build path of a given task - + the <code class="filename">WORKDIR</code>. + It does not matter if the working directory changes because it should not + affect the output for target packages. + Also, the build process has the objective of making native/cross packages relocatable. + The checksum therefore needs to exclude <code class="filename">WORKDIR</code>. + The simplistic approach for excluding the working directory is to set + <code class="filename">WORKDIR</code> to some fixed value and create the checksum + for the "run" script. + </p><p> + Another problem results from the "run" scripts containing functions that + might or might not get called. + The incremental build solution contains code that figures out dependencies + between shell functions. + This code is used to prune the "run" scripts down to the minimum set, + thereby alleviating this problem and making the "run" scripts much more + readable as a bonus. + </p><p> + So far we have solutions for shell scripts. + What about python tasks? + The same approach applies even though these tasks are more difficult. + The process needs to figure out what variables a python function accesses + and what functions it calls. + Again, the incremental build solution contains code that first figures out + the variable and function dependencies, and then creates a checksum for the data + used as the input to the task. + </p><p> + Like the <code class="filename">WORKDIR</code> case, situations exist where dependencies + should be ignored. + For these cases, you can instruct the build process to ignore a dependency + by using a line like the following: + </p><pre class="literallayout"> + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + </pre><p> + This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not + depend on the value of <code class="filename">MACHINE</code>, even if it does reference it. + </p><p> + Equally, there are cases where we need to add dependencies BitBake is not able to find. + You can accomplish this by using a line like the following: + </p><pre class="literallayout"> + PACKAGE_ARCHS[vardeps] = "MACHINE" + </pre><p> + This example explicitly adds the <code class="filename">MACHINE</code> variable as a + dependency for <code class="filename">PACKAGE_ARCHS</code>. + </p><p> + Consider a case with inline python, for example, where BitBake is not + able to figure out dependencies. + When running in debug mode (i.e. using <code class="filename">-DDD</code>), BitBake + produces output when it discovers something for which it cannot figure out + dependencies. + The Yocto Project team has currently not managed to cover those dependencies + in detail and is aware of the need to fix this situation. + </p><p> + Thus far, this section has limited discussion to the direct inputs into a task. + Information based on direct inputs is referred to as the "basehash" in the + code. + However, there is still the question of a task's indirect inputs - the + things that were already built and present in the build directory. + The checksum (or signature) for a particular task needs to add the hashes + of all the tasks on which the particular task depends. + Choosing which dependencies to add is a policy decision. + However, the effect is to generate a master checksum that combines the basehash + and the hashes of the task's dependencies. + </p><p> + At the code level, there are a variety of ways both the basehash and the + dependent task hashes can be influenced. + Within the BitBake configuration file, we can give BitBake some extra information + to help it construct the basehash. + The following statements effectively result in a list of global variable + dependency excludes - variables never included in any checksum: + </p><pre class="literallayout"> + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" + BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" + BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" + BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" + </pre><p> + The previous example actually excludes + <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a> + since it is actually constructed as a path within + <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on + the whitelist. + </p><p> + The rules for deciding which hashes of dependent tasks to include through + dependency chains are more complex and are generally accomplished with a + python function. + The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows two examples + of this and also illustrates how you can insert your own policy into the system + if so desired. + This file defines the two basic signature generators <code class="filename">OE-Core</code> + uses: "OEBasic" and "OEBasicHash". + By default, there is a dummy "noop" signature handler enabled in BitBake. + This means that behavior is unchanged from previous versions. + <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default + through this setting in the <code class="filename">bitbake.conf</code> file: + </p><pre class="literallayout"> + BB_SIGNATURE_HANDLER ?= "OEBasic" + </pre><p> + The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the + "OEBasic" version but adds the task hash to the stamp files. + This results in any metadata change that changes the task hash, automatically + causing the task to be run again. + This removes the need to bump <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> + values and changes to metadata automatically ripple across the build. + Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code> + but is the default in <code class="filename">poky</code>. + </p><p> + It is also worth noting that the end result of these signature generators is to + make some dependency and hash information available to the build. + This information includes: + </p><pre class="literallayout"> + BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe + BB_BASEHASH_<filename:taskname> - the base hashes for each dependent task + BBHASHDEPS_<filename:taskname> - The task dependencies for each task + BB_TASKHASH - the hash of the currently running task + </pre><p> + </p></div><div class="section" title="3.2.3. Shared State"><div class="titlepage"><div><div><h3 class="title"><a id="shared-state"></a>3.2.3. Shared State</h3></div></div></div><p> + Checksums and dependencies, as discussed in the previous section, solve half the + problem. + The other part of the problem is being able to use checksum information during the build + and being able to reuse or rebuild specific components. + </p><p> + The shared state class (<code class="filename">sstate.bbclass</code>) + is a relatively generic implementation of how to "capture" a snapshot of a given task. + The idea is that the build process does not care about the source of a task's output. + Output could be freshly built or it could be downloaded and unpacked from + somewhere - the build process doesn't need to worry about its source. + </p><p> + There are two types of output, one is just about creating a directory + in <code class="filename">WORKDIR</code>. + A good example is the output of either <code class="filename">do_install</code> or + <code class="filename">do_package</code>. + The other type of output occurs when a set of data is merged into a shared directory + tree such as the sysroot. + </p><p> + The Yocto Project team has tried to keep the details of the implementation hidden in + <code class="filename">sstate.bbclass</code>. + From a user's perspective, adding shared state wrapping to a task + is as simple as this <code class="filename">do_deploy</code> example taken from + <code class="filename">do_deploy.bbclass</code>: + </p><pre class="literallayout"> + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-name] = "deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + </pre><p> + In the example, we add some extra flags to the task, a name field ("deploy"), an + input directory where the task sends data, and the output + directory where the data from the task should eventually be copied. + We also add a <code class="filename">_setscene</code> variant of the task and add the task + name to the <code class="filename">SSTATETASKS</code> list. + </p><p> + If you have a directory whose contents you need to preserve, you can do this with + a line like the following: + </p><pre class="literallayout"> + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + </pre><p> + This method, as well as the following example, also works for multiple directories. + </p><pre class="literallayout"> + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + do_package[sstate-lockfile] = "${PACKAGELOCK}" + </pre><p> + These methods also include the ability to take a lockfile when manipulating + shared state directory structures since some cases are sensitive to file + additions or removals. + </p><p> + Behind the scenes, the shared state code works by looking in + <code class="filename">SSTATE_DIR</code> and + <code class="filename">SSTATE_MIRRORS</code> for shared state files. + Here is an example: + </p><pre class="literallayout"> + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/ \n \ + file://.* file:///some/local/dir/sstate/" + </pre><p> + </p><p> + The shared state package validity can be detected just by looking at the + filename since the filename contains the task checksum (or signature) as + described earlier in this section. + If a valid shared state package is found, the build process downloads it + and uses it to accelerate the task. + </p><p> + The build processes uses the <code class="filename">*_setscene</code> tasks + for the task acceleration phase. + BitBake goes through this phase before the main execution code and tries + to accelerate any tasks for which it can find shared state packages. + If a shared state package for a task is available, the shared state + package is used. + This means the task and any tasks on which it is dependent are not + executed. + </p><p> + As a real world example, the aim is when building an IPK-based image, + only the <code class="filename">do_package_write_ipk</code> tasks would have their + shared state packages fetched and extracted. + Since the sysroot is not used, it would never get extracted. + This is another reason why a task-based approach is preferred over a + recipe-based approach, which would have to install the output from every task. + </p></div><div class="section" title="3.2.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title"><a id="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div><p> + The code in the build system that supports incremental builds is not + simple code. + This section presents some tips and tricks that help you work around + issues related to shared state code. + </p><div class="section" title="3.2.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title"><a id="debugging"></a>3.2.4.1. Debugging</h4></div></div></div><p> + When things go wrong, debugging needs to be straightforward. + Because of this, the Yocto Project team included strong debugging + tools: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Whenever a shared state package is written out, so is a + corresponding <code class="filename">.siginfo</code> file. + This practice results in a pickled python database of all + the metadata that went into creating the hash for a given shared state + package.</p></li><li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code> + (or <code class="filename">-S</code>) option, BitBake dumps out + <code class="filename">.siginfo</code> files in + the stamp directory for every task it would have executed instead of + building the specified target package.</p></li><li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that + can process these <code class="filename">.siginfo</code> files. + If one file is specified, it will dump out the dependency + information in the file. + If two files are specified, it will compare the two files and dump out + the differences between the two. + This allows the question of "What changed between X and Y?" to be + answered easily.</p></li></ul></div><p> + </p></div><div class="section" title="3.2.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title"><a id="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div><p> + The shared state code uses checksums and shared state + cache to avoid unnecessarily rebuilding tasks. + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes that are not factored + into the checksum calculation, but do affect a task's output. + A good example is perhaps when a tool changes its output. + Let's say that the output of <code class="filename">rpmdeps</code> needed to change. + The result of the change should be that all the "package", "package_write_rpm", + and "package_deploy-rpm" shared state cache items would become invalid. + But, because this is a change that is external to the code and therefore implicit, + the associated shared state cache items do not become invalidated. + In this case, the build process would use the cached items rather than running the + task again. + Obviously, these types of implicit changes can cause problems. + </p><p> + To avoid these problems during the build, you need to understand the effects of any + change you make. + Note that any changes you make directly to a function automatically are factored into + the checksum calculation and thus, will invalidate the associated area of sstate cache. + You need to be aware of any implicit changes that are not obvious changes to the + code and could affect the output of a given task. + Once you are aware of such a change, you can take steps to invalidate the cache + and force the task to run. + The step to take is as simple as changing a function's comments in the source code. + For example, to invalidate package shared state files, change the comment statements + of <code class="filename">do_package</code> or the comments of one of the functions it calls. + The change is purely cosmetic, but it causes the checksum to be recalculated and + forces the task to be run again. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + For an example of a commit that makes a cosmetic change to invalidate + a shared state, see this + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>. + </div></div></div></div><div class="section" title="3.3. x32"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="x32"></a>3.3. x32</h2></div></div></div><p> + x32 is a new processor-specific Application Binary Interface (psABI) for x86_64. + An ABI defines the calling conventions between functions in a processing environment. + The interface determines what registers are used and what the sizes are for various C data types. + </p><p> + Some processing environments prefer using 32-bit applications even when running + on Intel 64-bit platforms. + Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms. + The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources, + leaving the system underutilized. + Now consider the x86_64 psABI. + This ABI is newer and uses 64-bits for data sizes and program pointers. + The extra bits increase the footprint size of the programs, libraries, + and also increases the memory and file system size requirements. + Executing under the x32 psABI enables user programs to utilize CPU and system resources + more efficiently while keeping the memory footprint of the applications low. + Extra bits are used for registers but not for addressing mechanisms. + </p><div class="section" title="3.3.1. Support"><div class="titlepage"><div><div><h3 class="title"><a id="support"></a>3.3.1. Support</h3></div></div></div><p> + While the x32 psABI specifications are not fully finalized, this Yocto Project + release supports current development specifications of x32 psABI. + As of this release of the Yocto Project, x32 psABI support exists as follows: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets. + </p></li><li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code> + layer on top of the OE-core/Yocto layer.</p></li><li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer + is used for building x32 psABI program binaries.</p></li><li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li><li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and + <code class="filename">core-image-sato</code> images.</p></li></ul></div><p> + </p></div><div class="section" title="3.3.2. Future Development and Limitations"><div class="titlepage"><div><div><h3 class="title"><a id="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div><p> + As of this Yocto Project release, the x32 psABI kernel and library interfaces + specifications are not finalized. + </p><p> + Future Plans for the x32 psABI in the Yocto Project include the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enhance and fix the few remaining recipes so they + work with and support x32 toolchains.</p></li><li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li><li class="listitem"><p>Support larger images.</p></li><li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from + <code class="filename">experimental/meta-x32</code> into OE-core.</p></li></ul></div><p> + </p></div><div class="section" title="3.3.3. Using x32 Right Now"><div class="titlepage"><div><div><h3 class="title"><a id="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div><p> + Despite the fact the x32 psABI support is in development state for this release of the + Yocto Project, you can follow these steps to use the x32 spABI: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local + <a class="link" href="#build-directory" target="_top">build directory</a>. + You can find the <code class="filename">experimental/meta-x32</code> source repository at + <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>.</p></li><li class="listitem"><p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes + the <code class="filename">meta-x32</code>. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + /home/nitin/prj/meta-x32.git \ + " + </pre></li><li class="listitem"><p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code> + machines by editing the <code class="filename">conf/local.conf</code> like this: + </p><pre class="literallayout"> + MACHINE = "qemux86-64" + DEFAULTTUNE = "x86-64-x32" + baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ + or 'INVALID'), True) or 'lib'}" + #MACHINE = "atom-pc" + #DEFAULTTUNE = "core2-64-x32" + </pre></li><li class="listitem"><p>As usual, use BitBake to build an image that supports the x32 psABI. + Here is an example: + </p><pre class="literallayout"> + $ bitake core-image-sato + </pre></li><li class="listitem"><p>As usual, run your image using QEMU: + </p><pre class="literallayout"> + $ runqemu qemux86-64 core-image-sato + </pre></li></ul></div><p> + </p></div></div><div class="section" title="3.4. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licenses"></a>3.4. Licenses</h2></div></div></div><p> + This section describes the mechanism by which the OpenEmbedded build system + tracks changes to licensing text. + The section also describes how to enable commercially licensed recipes, + which by default are disabled. + </p><div class="section" title="3.4.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div><p> + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code> + variable tracks changes to the license text. The checksums are validated at the end of the + configure step, and if the checksums do not match, the build will fail. + </p><div class="section" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.4.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div><p> + The <code class="filename">LIC_FILES_CHKSUM</code> + variable contains checksums of the license text in the source code for the recipe. + Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>: + </p><pre class="literallayout"> + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + </pre><p> + </p><p> + The build system uses the + <code class="filename"><a class="link" href="#var-S" title="S">S</a></code> variable as the + default directory used when searching files listed in + <code class="filename">LIC_FILES_CHKSUM</code>. + The previous example employs the default directory. + </p><p> + You can also use relative paths as shown in the following example: + </p><pre class="literallayout"> + LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + </pre><p> + </p><p> + In this example, the first line locates a file in + <code class="filename">${S}/src/ls.c</code>. + The second line refers to a file in + <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent + of <code class="filename"><a class="link" href="#var-S" title="S">S</a></code>. + </p><p> + Note that this variable is mandatory for all recipes, unless the + <code class="filename">LICENSE</code> variable is set to "CLOSED". + </p></div><div class="section" title="3.4.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div><p> + As mentioned in the previous section, the + <code class="filename">LIC_FILES_CHKSUM</code> variable lists all the + important files that contain the license text for the source code. + It is possible to specify a checksum for an entire file, or a specific section of a + file (specified by beginning and ending line numbers with the "beginline" and "endline" + parameters, respectively). + The latter is useful for source files with a license notice header, + README documents, and so forth. + If you do not use the "beginline" parameter, then it is assumed that the text begins on the + first line of the file. + Similarly, if you do not use the "endline" parameter, it is assumed that the license text + ends with the last line of the file. + </p><p> + The "md5" parameter stores the md5 checksum of the license text. + If the license text changes in any way as compared to this parameter + then a mismatch occurs. + This mismatch triggers a build failure and notifies the developer. + Notification allows the developer to review and address the license text changes. + Also note that if a mismatch occurs during the build, the correct md5 + checksum is placed in the build log and can be easily copied to the recipe. + </p><p> + There is no limit to how many files you can specify using the + <code class="filename">LIC_FILES_CHKSUM</code> variable. + Generally, however, every project requires a few specifications for license tracking. + Many projects have a "COPYING" file that stores the license information for all the source + code files. + This practice allows you to just track the "COPYING" file as long as it is kept up to date. + </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match + error and displays the correct "md5" parameter value during the build. + The correct parameter is also captured in the build log. + </div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + If the whole file contains only license text, you do not need to use the "beginline" and + "endline" parameters. + </div></div></div><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div><p> + By default, the OpenEmbedded build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the <code class="filename">LICENSE_FLAGS</code> variable + definition in the affected recipe. + For instance, the + <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> + recipe contains the following statement: + </p><pre class="literallayout"> + LICENSE_FLAGS = "commercial" + </pre><p> + Here is a slightly more complicated example that contains both an + explicit package name and version (after variable expansion): + </p><pre class="literallayout"> + LICENSE_FLAGS = "license_${PN}_${PV}" + </pre><p> + In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code> + definition to be enabled and included in an image, it + needs to have a matching entry in the global + <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable + typically defined in your <code class="filename">local.conf</code> file. + For example, to enable + the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>. + See the + "<a class="link" href="#license-flag-matching" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section + for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works. + Here is the example: + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + </pre><p> + Likewise, to additionally enable the package containing + <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming + that the actual recipe name was <code class="filename">emgd_1.10.bb</code>, + the following string would enable that package as well as + the original <code class="filename">gst-plugins-ugly</code> package: + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + </pre><p> + As a convenience, you do not need to specify the complete license string + in the whitelist for every package. + you can use an abbreviated form, which consists + of just the first portion or portions of the license string before + the initial underscore character or characters. + A partial string will match + any license that contains the given string as the first + portion of its license. + For example, the following + whitelist string will also match both of the packages + previously mentioned as well as any other packages that have + licenses starting with "commercial" or "license". + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial license" + </pre><p> + </p><div class="section" title="3.4.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title"><a id="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div><p> + The definition of 'matching' in reference to a + recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple. + However, some things exist that you should know about in order to + correctly and effectively use it. + </p><p> + Before a flag + defined by a particular recipe is tested against the + contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the + string <code class="filename">_${PN}</code> (with + <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is + appended to the flag, thus automatically making each + <code class="filename">LICENSE_FLAGS</code> value recipe-specific. + That string is + then matched against the whitelist. + So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe + "foo" for example, the string <code class="filename">"commercial_foo"</code> + would normally be what is specified in the whitelist in order for it to + match. + </p><p> + You can broaden the match by + putting any "_"-separated beginning subset of a + <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also + match. + For example, simply specifying "commercial" in + the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code> + definition starting with "commercial" such as + "commercial_foo" and "commercial_bar", which are the + strings that would be automatically generated for + hypothetical "foo" and "bar" recipes assuming those + recipes had simply specified the following: + </p><pre class="literallayout"> + LICENSE_FLAGS = "commercial" + </pre><p> + </p><p> + Broadening the match allows for a range of specificity for the items + in the whitelist, from more general to perfectly + specific. + So you have the choice of exhaustively + enumerating each license flag in the whitelist to + allow only those specific recipes into the image, or + of using a more general string to pick up anything + matching just the first component or components of the specified + string. + </p><p> + This scheme works even if the flag already + has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is + redundant, but does not affect the outcome. + For example, a license flag of "commercial_1.2_foo" would + turn into "commercial_1.2_foo_foo" and would match + both the general "commercial" and the specific + "commercial_1.2_foo", as expected. + The flag would also match + "commercial_1.2_foo_foo" and "commercial_1.2", which + does not make much sense regarding use in the whitelist. + </p><p> + For a versioned string, you could instead specify + "commercial_foo_1.2", which would turn into + "commercial_foo_1.2_foo". + And, as expected, this flag allows + you to pick up this package along with + anything else "commercial" when you specify "commercial" + in the whitelist. + Or, the flag allows you to pick up this package along with anything "commercial_foo" + regardless of version when you use "commercial_foo" in the whitelist. + Finally, you can be completely specific about the package and version and specify + "commercial_foo_1.2" package and version. + </p></div><div class="section" title="3.4.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title"><a id="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div><p> + Other helpful variables related to commercial + license handling exist and are defined in the + <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file: + </p><pre class="literallayout"> + COMMERCIAL_AUDIO_PLUGINS ?= "" + COMMERCIAL_VIDEO_PLUGINS ?= "" + COMMERCIAL_QT = "" + </pre><p> + If you want to enable these components, you can do so by making sure you have + the following statements in your <code class="filename">local.conf</code> configuration file: + </p><pre class="literallayout"> + COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ + gst-plugins-ugly-mpegaudioparse" + COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ + gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" + COMMERCIAL_QT ?= "qmmp" + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" + </pre><p> + Of course, you could also create a matching whitelist + for those components using the more general "commercial" + in the whitelist, but that would also enable all the + other packages with <code class="filename">LICENSE_FLAGS</code> containing + "commercial", which you may or may not want: + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial" + </pre><p> + </p><p> + Specifying audio and video plug-ins as part of the + <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and + <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements + or commercial qt components as part of + the <code class="filename">COMMERCIAL_QT</code> statement (along + with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the + plug-ins or components into built images, thus adding + support for media formats or components. + </p></div></div></div></div> + + <div class="chapter" title="Chapter 4. Source Directory Structure"><div class="titlepage"><div><div><h2 class="title"><a id="ref-structure"></a>Chapter 4. Source Directory Structure</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#structure-core">4.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">4.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">4.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">4.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">4.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-demoapps">4.1.5. <code class="filename">meta-demoapps/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-rt">4.1.6. <code class="filename">meta-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">4.1.7. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">4.1.8. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">4.1.9. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">4.1.10. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">4.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">4.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">4.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">4.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">4.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">4.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">4.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">4.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">4.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">4.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">4.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">4.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">4.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">4.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">4.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">4.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">4.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">4.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">4.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">4.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">4.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">4.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">4.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">4.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">4.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">4.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">4.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">4.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">4.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">4.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">4.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">4.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">4.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">4.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">4.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">4.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">4.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">4.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">4.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">4.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">4.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></div><p> + The <a class="link" href="#source-directory" target="_top">source directory</a> consists of several components. + Understanding them and knowing where they are located is key to using the Yocto Project well. + This chapter describes the source directory and gives information about the various + files and directories. +</p><p> + For information on how to establish a local source directory on your development system, see the + "<a class="link" href="#getting-setup" target="_top">Getting Set Up</a>" + section in the Yocto Project Development Manual. +</p><div class="section" title="4.1. Top level core components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-core"></a>4.1. Top level core components</h2></div></div></div><div class="section" title="4.1.1. bitbake/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-bitbake"></a>4.1.1. <code class="filename">bitbake/</code></h3></div></div></div><p> + The <a class="ulink" href="source-directory" target="_top">source directory</a> + includes a copy of BitBake for ease of use. + The copy usually matches the current stable BitBake release from the BitBake project. + BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks + defined by that data. + Failures are usually from the metadata and not from BitBake itself. + Consequently, most users do not need to worry about BitBake. + </p><p> + When you run the <code class="filename">bitbake</code> command, the wrapper script in + <code class="filename">scripts/</code> is executed to run the main BitBake executable, + which resides in the <code class="filename">bitbake/bin/</code> directory. + Sourcing the <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a> + script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code> + directories (in that order) into the shell's <code class="filename">PATH</code> environment + variable. + </p><p> + For more information on BitBake, see the BitBake on-line manual at + <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">http://docs.openembedded.org/bitbake/html/</a>. + </p></div><div class="section" title="4.1.2. build/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-build"></a>4.1.2. <code class="filename">build/</code></h3></div></div></div><p> + This directory contains user configuration files and the output + generated by the OpenEmbedded build system in its standard configuration where + the source tree is combined with the output. + The <a class="link" href="#build-directory" target="_top">build directory</a> + is created initially when you <code class="filename">source</code> + the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>. + </p><p> + It is also possible to place output and configuration + files in a directory separate from the + <a class="link" href="#source-directory" target="_top">source directory</a> + by providing a directory name when you <code class="filename">source</code> + the setup script. + For information on separating output from your local source directory files, see <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a>. + </p></div><div class="section" title="4.1.3. documentation"><div class="titlepage"><div><div><h3 class="title"><a id="handbook"></a>4.1.3. <code class="filename">documentation</code></h3></div></div></div><p> + This directory holds the source for the Yocto Project documentation + as well as templates and tools that allow you to generate PDF and HTML + versions of the manuals. + Each manual is contained in a sub-folder. + For example, the files for this manual reside in + <code class="filename">poky-ref-manual</code>. + </p></div><div class="section" title="4.1.4. meta/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta"></a>4.1.4. <code class="filename">meta/</code></h3></div></div></div><p> + This directory contains the OpenEmbedded Core metadata. + The directory holds machine definitions, the Yocto Project distribution, + and the packages that make up a given system. + </p></div><div class="section" title="4.1.5. meta-demoapps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-demoapps"></a>4.1.5. <code class="filename">meta-demoapps/</code></h3></div></div></div><p> + This directory contains recipes for applications and demos that are not part of the + OpenEmbedded core. + </p></div><div class="section" title="4.1.6. meta-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-rt"></a>4.1.6. <code class="filename">meta-rt/</code></h3></div></div></div><p> + This directory contains recipes for real-time kernels. + </p></div><div class="section" title="4.1.7. meta-skeleton/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-skeleton"></a>4.1.7. <code class="filename">meta-skeleton/</code></h3></div></div></div><p> + This directory contains template recipes for BSP and kernel development. + </p></div><div class="section" title="4.1.8. scripts/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-scripts"></a>4.1.8. <code class="filename">scripts/</code></h3></div></div></div><p> + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The <a class="link" href="#structure-core-script" title="4.1.9. oe-init-build-env">oe-init-build-env</a> script appends this + directory to the shell's <code class="filename">PATH</code> environment variable. + </p><p> + The <code class="filename">scripts</code> directory has useful scripts that assist contributing + back to the Yocto Project, such as <code class="filename">create_pull_request</code> and + <code class="filename">send_pull_request</code>. + </p></div><div class="section" title="4.1.9. oe-init-build-env"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-script"></a>4.1.9. <code class="filename">oe-init-build-env</code></h3></div></div></div><p> + This script sets up the OpenEmbedded build environment. + Running this script with the <code class="filename">source</code> command in + a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the + current working directory. + You need to run this script before running BitBake commands. + The script uses other scripts within the <code class="filename">scripts</code> directory to do + the bulk of the work. + </p><p> + By default, running this script without a build directory argument creates the + <code class="filename">build</code> directory. + If you provide a build directory argument when you <code class="filename">source</code> + the script, you direct OpenEmbedded build system to create a + <a class="link" href="#build-directory" target="_top">build directory</a> of your choice. + For example, the following command creates a build directory named + <code class="filename">mybuilds</code> that is outside of the + <a class="link" href="#source-directory" target="_top">source directory</a>: + </p><pre class="literallayout"> + $ source oe-init-build-env ~/mybuilds + </pre><p> + </p></div><div class="section" title="4.1.10. LICENSE, README, and README.hardware"><div class="titlepage"><div><div><h3 class="title"><a id="structure-basic-top-level"></a>4.1.10. <code class="filename">LICENSE, README, and README.hardware</code></h3></div></div></div><p> + These files are standard top-level files. + </p></div></div><div class="section" title="4.2. The Build Directory - build/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-build"></a>4.2. The Build Directory - <code class="filename">build/</code></h2></div></div></div><div class="section" title="4.2.1. build/pseudodone"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-pseudodone"></a>4.2.1. <code class="filename">build/pseudodone</code></h3></div></div></div><p> + This tag file indicates that the initial pseudo binary was created. + The file is built the first time BitBake is invoked. + </p></div><div class="section" title="4.2.2. build/conf/local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-local.conf"></a>4.2.2. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p> + This file contains all the local user configuration for your build environment. + If there is no <code class="filename">local.conf</code> present, it is created from + <code class="filename">local.conf.sample</code>. + The <code class="filename">local.conf</code> file contains documentation on the various configuration options. + Any variable set here overrides any variable set elsewhere within the environment unless + that variable is hard-coded within a file (e.g. by using '=' instead of '?='). + Some variables are hard-coded for various reasons but these variables are + relatively rare. + </p><p> + Edit this file to set the <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> + for which you want to build, which package types you + wish to use (<code class="filename">PACKAGE_CLASSES</code>), or where you want to downloaded files + (<code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>). + </p></div><div class="section" title="4.2.3. build/conf/bblayers.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-bblayers.conf"></a>4.2.3. <code class="filename">build/conf/bblayers.conf</code></h3></div></div></div><p> + This file defines layers, which is a directory tree, traversed (or walked) by BitBake. + If <code class="filename">bblayers.conf</code> + is not present, it is created from <code class="filename">bblayers.conf.sample</code> when + you <code class="filename">source</code> the environment setup script. + </p></div><div class="section" title="4.2.4. build/conf/sanity_info"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-sanity_info"></a>4.2.4. <code class="filename">build/conf/sanity_info</code></h3></div></div></div><p> + This file is created during the build to indicate the state of the sanity checks. + </p></div><div class="section" title="4.2.5. build/downloads/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-downloads"></a>4.2.5. <code class="filename">build/downloads/</code></h3></div></div></div><p> + This directory is used for the upstream source tarballs. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable. + </p></div><div class="section" title="4.2.6. build/sstate-cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-sstate-cache"></a>4.2.6. <code class="filename">build/sstate-cache/</code></h3></div></div></div><p> + This directory is used for the shared state cache. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <code class="filename"><a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable. + </p></div><div class="section" title="4.2.7. build/tmp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp"></a>4.2.7. <code class="filename">build/tmp/</code></h3></div></div></div><p> + This directory receives all the OpenEmbedded build system's output. + BitBake creates this directory if it does not exist. + As a last resort, to clean up a build and start it from scratch (other than the downloads), + you can remove everything in the <code class="filename">tmp</code> directory or get rid of the + directory completely. + If you do, you should also completely remove the <code class="filename">build/sstate-cache</code> + directory as well. + </p></div><div class="section" title="4.2.8. build/tmp/buildstats/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-buildstats"></a>4.2.8. <code class="filename">build/tmp/buildstats/</code></h3></div></div></div><p> + This directory stores the build statistics. + </p></div><div class="section" title="4.2.9. build/tmp/cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-cache"></a>4.2.9. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p> + When BitBake parses the metadata, it creates a cache file of the result that can + be used when subsequently running commands. + These results are stored here on a per-machine basis. + </p></div><div class="section" title="4.2.10. build/tmp/deploy/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy"></a>4.2.10. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p> + This directory contains any 'end result' output from the OpenEmbedded build process. + </p></div><div class="section" title="4.2.11. build/tmp/deploy/deb/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-deb"></a>4.2.11. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p> + This directory receives any <code class="filename">.deb</code> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </p></div><div class="section" title="4.2.12. build/tmp/deploy/rpm/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-rpm"></a>4.2.12. <code class="filename">build/tmp/deploy/rpm/</code></h3></div></div></div><p> + This directory receives any <code class="filename">.rpm</code> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </p></div><div class="section" title="4.2.13. build/tmp/deploy/licenses/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-licenses"></a>4.2.13. <code class="filename">build/tmp/deploy/licenses/</code></h3></div></div></div><p> + This directory receives package licensing information. + For example, the directory contains sub-directories for <code class="filename">bash</code>, + <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn + contain appropriate <code class="filename">COPYING</code> license files with other licensing information. + </p></div><div class="section" title="4.2.14. build/tmp/deploy/images/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-images"></a>4.2.14. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p> + This directory receives complete filesystem images. + If you want to flash the resulting image from a build onto a device, look here for the image. + </p><p> + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>, + etc.). + However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.), + bootloader and other supplementary files might be deployed here prior to building an + image. + Because these files, however, are not directly produced from the image, if you + delete them they will not be automatically re-created when you build the image again. + </p><p> + If you do accidentally delete files here, you will need to force them to be + re-created. + In order to do that, you will need to know the target that produced them. + For example, these commands rebuild and re-create the kernel files: + </p><pre class="literallayout"> + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + </pre><p> + </p></div><div class="section" title="4.2.15. build/tmp/deploy/ipk/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-ipk"></a>4.2.15. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p> + This directory receives <code class="filename">.ipk</code> packages produced by + the build process.</p></div><div class="section" title="4.2.16. build/tmp/sysroots/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-sysroots"></a>4.2.16. <code class="filename">build/tmp/sysroots/</code></h3></div></div></div><p> + This directory contains shared header files and libraries as well as other shared + data. + Packages that need to share output with other packages do so within this directory. + The directory is subdivided by architecture so multiple builds can run within + the one build directory. + </p></div><div class="section" title="4.2.17. build/tmp/stamps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-stamps"></a>4.2.17. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p> + This directory holds information that that BitBake uses for accounting purposes + to track what tasks have run and when they have run. + The directory is sub-divided by architecture. + The files in the directory are empty of data. + However, BitBake uses the filenames and timestamps for tracking purposes. + </p></div><div class="section" title="4.2.18. build/tmp/log/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-log"></a>4.2.18. <code class="filename">build/tmp/log/</code></h3></div></div></div><p> + This directory contains general logs that are not otherwise placed using the + package's <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>. + Examples of logs are the output from the <code class="filename">check_pkg</code> or + <code class="filename">distro_check</code> tasks. + Running a build does not necessarily mean this directory is created. + </p></div><div class="section" title="4.2.19. build/tmp/pkgdata/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-pkgdata"></a>4.2.19. <code class="filename">build/tmp/pkgdata/</code></h3></div></div></div><p> + This directory contains intermediate packaging data that is used later in the packaging process. + For more information, see the "<a class="link" href="#ref-classes-package" title="6.12. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section. + </p></div><div class="section" title="4.2.20. build/tmp/work/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-work"></a>4.2.20. <code class="filename">build/tmp/work/</code></h3></div></div></div><p> + This directory contains architecture-specific work sub-directories for packages built by BitBake. + All tasks execute from a work directory. + For example, the source for a particular package is unpacked, patched, configured and compiled all + within its own work directory. + Within the work directory, organization is based on the package group for which the source + is being compiled. + </p><p> + It is worth considering the structure of a typical work directory. + As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code> + on the machine <code class="filename">qemux86</code> + built within the Yocto Project. + For this package, a work directory of + <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+<.....></code>, + referred to as <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created. + Within this directory, the source is unpacked to + <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt + (see the + "<a class="link" href="#using-a-quilt-workflow" target="_top">Modifying Package + Source Code with Quilt</a>" section in the Yocto Project Development Manual. + Within the <code class="filename">linux-qemux86-standard-build</code> directory, + standard Quilt directories <code class="filename">linux-3.0/patches</code> + and <code class="filename">linux-3.0/.pc</code> are created, + and standard Quilt commands can be used. + </p><p> + There are other directories generated within WORKDIR. + The most important directory is WORKDIR<code class="filename">/temp/</code>, which has log files for each + task (<code class="filename">log.do_*.pid</code>) and contains the scripts BitBake runs for + each task (<code class="filename">run.do_*.pid</code>). + The WORKDIR<code class="filename">/image/</code> directory is where "make + install" places its output that is then split into sub-packages + within WORKDIR<code class="filename">/packages-split/</code>. + </p></div></div><div class="section" title="4.3. The Metadata - meta/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-meta"></a>4.3. The Metadata - <code class="filename">meta/</code></h2></div></div></div><p> + As mentioned previously, metadata is the core of the Yocto Project. + Metadata has several important subdivisions: + </p><div class="section" title="4.3.1. meta/classes/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-classes"></a>4.3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p> + This directory contains the <code class="filename">*.bbclass</code> files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the <code class="filename">base.bbclass</code> file. + Examples of other important classes are <code class="filename">autotools.bbclass</code>, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions + for working with the Linux kernel. + Functions like image generation or packaging also have their specific class files + such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and + <code class="filename">package*.bbclass</code>. + </p></div><div class="section" title="4.3.2. meta/conf/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf"></a>4.3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p> + This directory contains the core set of configuration files that start from + <code class="filename">bitbake.conf</code> and from which all other configuration + files are included. + See the include statements at the end of the file and you will note that even + <code class="filename">local.conf</code> is loaded from there. + While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override + these by using the (<code class="filename">local.conf</code>) file, machine file or + the distribution configuration file. + </p></div><div class="section" title="4.3.3. meta/conf/machine/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-machine"></a>4.3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p> + This directory contains all the machine configuration files. + If you set <code class="filename">MACHINE="qemux86"</code>, + the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this + directory. + The <code class="filename">include</code> directory contains various data common to multiple machines. + If you want to add support for a new machine to the Yocto Project, look in this directory. + </p></div><div class="section" title="4.3.4. meta/conf/distro/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-distro"></a>4.3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p> + Any distribution-specific configuration is controlled from this directory. + For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here. + This directory includes the versions and the + <code class="filename">SRCDATE</code> definitions for applications that are configured here. + An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>. + Although this file mainly inherits its configuration from Poky. + </p></div><div class="section" title="4.3.5. meta/recipes-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-bsp"></a>4.3.5. <code class="filename">meta/recipes-bsp/</code></h3></div></div></div><p> + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + </p></div><div class="section" title="4.3.6. meta/recipes-connectivity/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-connectivity"></a>4.3.6. <code class="filename">meta/recipes-connectivity/</code></h3></div></div></div><p> + This directory contains libraries and applications related to communication with other devices. + </p></div><div class="section" title="4.3.7. meta/recipes-core/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-core"></a>4.3.7. <code class="filename">meta/recipes-core/</code></h3></div></div></div><p> + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + </p></div><div class="section" title="4.3.8. meta/recipes-devtools/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-devtools"></a>4.3.8. <code class="filename">meta/recipes-devtools/</code></h3></div></div></div><p> + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + </p></div><div class="section" title="4.3.9. meta/recipes-extended/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-extended"></a>4.3.9. <code class="filename">meta/recipes-extended/</code></h3></div></div></div><p> + This directory contains non-essential applications that add features compared to the + alternatives in core. + You might need this directory for full tool functionality or for Linux Standard Base (LSB) + compliance. + </p></div><div class="section" title="4.3.10. meta/recipes-gnome/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-gnome"></a>4.3.10. <code class="filename">meta/recipes-gnome/</code></h3></div></div></div><p> + This directory contains all things related to the GTK+ application framework. + </p></div><div class="section" title="4.3.11. meta/recipes-graphics/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-graphics"></a>4.3.11. <code class="filename">meta/recipes-graphics/</code></h3></div></div></div><p> + This directory contains X and other graphically related system libraries + </p></div><div class="section" title="4.3.12. meta/recipes-kernel/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-kernel"></a>4.3.12. <code class="filename">meta/recipes-kernel/</code></h3></div></div></div><p> + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + </p></div><div class="section" title="4.3.13. meta/recipes-multimedia/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-multimedia"></a>4.3.13. <code class="filename">meta/recipes-multimedia/</code></h3></div></div></div><p> + This directory contains codecs and support utilities for audio, images and video. + </p></div><div class="section" title="4.3.14. meta/recipes-qt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-qt"></a>4.3.14. <code class="filename">meta/recipes-qt/</code></h3></div></div></div><p> + This directory contains all things related to the Qt application framework. + </p></div><div class="section" title="4.3.15. meta/recipes-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-rt"></a>4.3.15. <code class="filename">meta/recipes-rt/</code></h3></div></div></div><p> + This directory contains package and image recipes for using and testing + the <code class="filename">PREEMPT_RT</code> kernel. + </p></div><div class="section" title="4.3.16. meta/recipes-sato/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-sato"></a>4.3.16. <code class="filename">meta/recipes-sato/</code></h3></div></div></div><p> + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + </p></div><div class="section" title="4.3.17. meta/recipes-support/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-support"></a>4.3.17. <code class="filename">meta/recipes-support/</code></h3></div></div></div><p> + This directory contains recipes that used by other recipes, but that are not directly + included in images (i.e. dependencies of other recipes). + </p></div><div class="section" title="4.3.18. meta/site/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-site"></a>4.3.18. <code class="filename">meta/site/</code></h3></div></div></div><p> + This directory contains a list of cached results for various architectures. + Because certain "autoconf" test results cannot be determined when cross-compiling due to + the tests not able to run on a live system, the information in this directory is + passed to "autoconf" for the various architectures. + </p></div><div class="section" title="4.3.19. meta/recipes.txt"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-txt"></a>4.3.19. <code class="filename">meta/recipes.txt</code></h3></div></div></div><p> + This file is a description of the contents of <code class="filename">recipes-*</code>. + </p></div></div></div> + + <div class="chapter" title="Chapter 5. BitBake"><div class="titlepage"><div><div><h2 class="title"><a id="ref-bitbake"></a>Chapter 5. BitBake</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-bitbake-parsing">5.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">5.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">5.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">5.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">5.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">5.7. Fetchers</a></span></dt></dl></div><p> + BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded + build system. + At some point, developers wonder what actually happens when you enter: + </p><pre class="literallayout"> + $ bitbake core-image-sato + </pre><p> + </p><p> + This chapter provides an overview of what happens behind the scenes from BitBake's perspective. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships. + As such, it has no real knowledge of what the tasks being executed actually do. + BitBake just considers a list of tasks with dependencies and handles metadata + that consists of variables in a certain format that get passed to the tasks. + </div><div class="section" title="5.1. Parsing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-parsing"></a>5.1. Parsing</h2></div></div></div><p> + BitBake parses configuration files, classes, and <code class="filename">.bb</code> files. + </p><p> + The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file. + This file resides in the + <a class="link" href="#source-directory" target="_top">source directory</a> + within the <code class="filename">meta/conf/</code> directory. + BitBake finds it by examining its + <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment + variable and looking for the <code class="filename">meta/conf/</code> + directory. + </p><p> + The <code class="filename">bitbake.conf</code> file lists other configuration + files to include from a <code class="filename">conf/</code> + directory below the directories listed in <code class="filename">BBPATH</code>. + In general, the most important configuration file from a user's perspective + is <code class="filename">local.conf</code>, which contains a user's customized + settings for the OpenEmbedded build environment. + Other notable configuration files are the distribution + configuration file (set by the + <code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> variable) + and the machine configuration file + (set by the + <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> variable). + The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment + variables are both usually set in + the <code class="filename">local.conf</code> file. + Valid distribution + configuration files are available in the <code class="filename">meta/conf/distro/</code> directory + and valid machine configuration + files in the <code class="filename">meta/conf/machine/</code> directory. + Within the <code class="filename">meta/conf/machine/include/</code> + directory are various <code class="filename">tune-*.inc</code> configuration files that provide common + "tuning" settings specific to and shared between particular architectures and machines. + </p><p> + After the parsing of the configuration files, some standard classes are included. + The <code class="filename">base.bbclass</code> file is always included. + Other classes that are specified in the configuration using the + <code class="filename"><a class="link" href="#var-INHERIT" title="INHERIT">INHERIT</a></code> + variable are also included. + Class files are searched for in a <code class="filename">classes</code> subdirectory + under the paths in <code class="filename">BBPATH</code> in the same way as + configuration files. + </p><p> + After classes are included, the variable + <code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code> + is set, usually in + <code class="filename">local.conf</code>, and defines the list of places to search for + <code class="filename">.bb</code> files. + By default, the <code class="filename">BBFILES</code> variable specifies the + <code class="filename">meta/recipes-*/</code> directory within Poky. + Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of + BitBake layers as described in the + "<a class="link" href="#understanding-and-creating-layers" target="_top">Understanding and + Creating Layers</a>" section of the Yocto Project Development Manual. + </p><p> + BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and + stores the values of various variables. + In summary, for each <code class="filename">.bb</code> + file the configuration plus the base class of variables are set, followed + by the data in the <code class="filename">.bb</code> file + itself, followed by any inherit commands that + <code class="filename">.bb</code> file might contain. + </p><p> + Because parsing <code class="filename">.bb</code> files is a time + consuming process, a cache is kept to speed up subsequent parsing. + This cache is invalid if the timestamp of the <code class="filename">.bb</code> + file itself changes, or if the timestamps of any of the include, + configuration or class files the <code class="filename">.bb</code> + file depends on changes. + </p></div><div class="section" title="5.2. Preferences and Providers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-providers"></a>5.2. Preferences and Providers</h2></div></div></div><p> + Once all the <code class="filename">.bb</code> files have been + parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code> + in the previous section's example) and looks for providers of that target. + Once a provider is selected, BitBake resolves all the dependencies for + the target. + In the case of <code class="filename">core-image-sato</code>, it would lead to + <code class="filename">task-base.bb</code>, + which in turn leads to packages like <code class="filename">Contacts</code>, + <code class="filename">Dates</code> and <code class="filename">BusyBox</code>. + These packages in turn depend on <code class="filename">eglibc</code> and the toolchain. + </p><p> + Sometimes a target might have multiple providers. + A common example is "virtual/kernel", which is provided by each kernel package. + Each machine often selects the best kernel provider by using a line similar to the + following in the machine configuration file: + </p><pre class="literallayout"> + PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" + </pre><p> + The default <code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code> + is the provider with the same name as the target. + </p><p> + Understanding how providers are chosen is made complicated by the fact + that multiple versions might exist. + BitBake defaults to the highest version of a provider. + Version comparisons are made using the same method as Debian. + You can use the + <code class="filename"><a class="link" href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code> + variable to specify a particular version (usually in the distro configuration). + You can influence the order by using the + <code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code> + variable. + By default, files have a preference of "0". + Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the + package unlikely to be used unless it is explicitly referenced. + Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used. + <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting. + <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package + versions until they have undergone sufficient testing to be considered stable. + </p><p> + In summary, BitBake has created a list of providers, which is prioritized, for each target. + </p></div><div class="section" title="5.3. Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-dependencies"></a>5.3. Dependencies</h2></div></div></div><p> + Each target BitBake builds consists of multiple tasks such as + <code class="filename">fetch</code>, <code class="filename">unpack</code>, + <code class="filename">patch</code>, <code class="filename">configure</code>, + and <code class="filename">compile</code>. + For best performance on multi-core systems, BitBake considers each task as an independent + entity with its own set of dependencies. + </p><p> + Dependencies are defined through several variables. + You can find information about variables BitBake uses in the + <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">BitBake manual</a>. + At a basic level, it is sufficient to know that BitBake uses the + <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and + <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when + calculating dependencies. + </p></div><div class="section" title="5.4. The Task List"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-tasklist"></a>5.4. The Task List</h2></div></div></div><p> + Based on the generated list of providers and the dependency information, + BitBake can now calculate exactly what tasks it needs to run and in what + order it needs to run them. + The build now starts with BitBake forking off threads up to the limit set in the + <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></code> variable. + BitBake continues to fork threads as long as there are tasks ready to run, + those tasks have all their dependencies met, and the thread threshold has not been + exceeded. + </p><p> + It is worth noting that you can greatly speed up the build time by properly setting + the <code class="filename">BB_NUMBER_THREADS</code> variable. + See the + "<a class="link" href="#building-image" target="_top">Building an Image</a>" + section in the Yocto Project Quick Start for more information. + </p><p> + As each task completes, a timestamp is written to the directory specified by the + <code class="filename"><a class="link" href="#var-STAMP" title="STAMP">STAMP</a></code> variable (usually + <code class="filename">build/tmp/stamps/*/</code>). + On subsequent runs, BitBake looks at the <code class="filename">/build/tmp/stamps</code> + directory and does not rerun + tasks that are already completed unless a timestamp is found to be invalid. + Currently, invalid timestamps are only considered on a per + <code class="filename">.bb</code> file basis. + So, for example, if the configure stamp has a timestamp greater than the + compile timestamp for a given target, then the compile task would rerun. + Running the compile task again, however, has no effect on other providers + that depend on that target. + This behavior could change or become configurable in future versions of BitBake. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Some tasks are marked as "nostamp" tasks. + No timestamp file is created when these tasks are run. + Consequently, "nostamp" tasks are always rerun. + </div></div><div class="section" title="5.5. Running a Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-runtask"></a>5.5. Running a Task</h2></div></div></div><p> + Tasks can either be a shell task or a Python task. + For shell tasks, BitBake writes a shell script to + <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> and then executes the script. + The generated shell script contains all the exported variables, and the shell functions + with all variables expanded. + Output from the shell script goes to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. + Looking at the expanded shell functions in the run file and the output in the log files + is a useful debugging technique. + </p><p> + For Python tasks, BitBake executes the task internally and logs information to the + controlling terminal. + Future versions of BitBake will write the functions to files similar to the way + shell tasks are handled. + Logging will be handled in way similar to shell tasks as well. + </p><p> + Once all the tasks have been completed BitBake exits. + </p><p> + When running a task, BitBake tightly controls the execution environment + of the build tasks to make sure unwanted contamination from the build machine + cannot influence the build. + Consequently, if you do want something to get passed into the build + task's environment, you must take a few steps: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Tell BitBake to load what you want from the environment + into the data store. + You can do so through the <code class="filename">BB_ENV_WHITELIST</code> + variable. + For example, assume you want to prevent the build system from + accessing your <code class="filename">$HOME/.ccache</code> directory. + The following command tells BitBake to load + <code class="filename">CCACHE_DIR</code> from the environment into the data + store: + </p><pre class="literallayout"> + export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" + </pre></li><li class="listitem"><p>Tell BitBake to export what you have loaded into the + environment store to the task environment of every running task. + Loading something from the environment into the data store + (previous step) only makes it available in the datastore. + To export it to the task environment of every running task, + use a command similar to the following in your + <code class="filename">local.conf</code> or distro configuration file: + </p><pre class="literallayout"> + export CCACHE_DIR + </pre></li></ol></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + A side effect of the previous steps is that BitBake records the variable + as a dependency of the build process in things like the shared state + checksums. + If doing so results in unnecessary rebuilds of tasks, you can whitelist the + variable so that the shared state code ignores the dependency when it creates + checksums. + For information on this process, see the <code class="filename">BB_HASHBASE_WHITELIST</code> + example in the "<a class="link" href="#checksums" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section. + </div></div><div class="section" title="5.6. BitBake Command Line"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-commandline"></a>5.6. BitBake Command Line</h2></div></div></div><p> + Following is the BitBake help output: + </p><pre class="screen"> +$ bitbake --help +Usage: bitbake [options] [package ...] + +Executes the specified task (default is 'build') for a given set of BitBake files. +It expects that BBFILES is defined, which is a space separated list of files to +be executed. BBFILES does support wildcards. +Default BBFILES are the .bb files in the current directory. + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + -b BUILDFILE, --buildfile=BUILDFILE + execute the task against this .bb file, rather than a + package from BBFILES. Does not handle any + dependencies. + -k, --continue continue as much as possible after an error. While the + target that failed, and those that depend on it, + cannot be remade, the other dependencies of these + targets can be processed all the same. + -a, --tryaltconfigs continue with builds by trying to use alternative + providers where possible. + -f, --force force run of specified cmd, regardless of stamp status + -c CMD, --cmd=CMD Specify task to execute. Note that this only executes + the specified task for the providee and the packages + it depends on, i.e. 'compile' does not implicitly call + stage for the dependencies (IOW: use only if you know + what you are doing). Depending on the base.bbclass a + listtasks tasks is defined and will show available + tasks + -r PREFILE, --read=PREFILE + read the specified file before bitbake.conf + -R POSTFILE, --postread=POSTFILE + read the specified file after bitbake.conf + -v, --verbose output more chit-chat to the terminal + -D, --debug Increase the debug level. You can specify this more + than once. + -n, --dry-run don't execute, just go through the motions + -S, --dump-signatures + don't execute, just dump out the signature + construction information + -p, --parse-only quit after parsing the BB files (developers only) + -s, --show-versions show current and preferred versions of all packages + -e, --environment show the global or per-package environment (this is + what used to be bbread) + -g, --graphviz emit the dependency trees of the specified packages in + the dot syntax + -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED + Assume these dependencies don't exist and are already + provided (equivalent to ASSUME_PROVIDED). Useful to + make dependency graphs more appealing + -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS + Show debug logging for the specified logging domains + -P, --profile profile the command and print a report + -u UI, --ui=UI userinterface to use + -t SERVERTYPE, --servertype=SERVERTYPE + Choose which server to use, none, process or xmlrpc + --revisions-changed Set the exit code depending on whether upstream + floating revisions have changed or not + </pre></div><div class="section" title="5.7. Fetchers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-fetchers"></a>5.7. Fetchers</h2></div></div></div><p> + BitBake also contains a set of "fetcher" modules that allow + retrieval of source code from various types of sources. + For example, BitBake can get source code from a disk with the metadata, from websites, + from remote shell accounts or from Source Code Management (SCM) systems + like <code class="filename">cvs/subversion/git</code>. + </p><p> + Fetchers are usually triggered by entries in + <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>. + You can find information about the options and formats of entries for specific + fetchers in the <a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top">BitBake manual</a>. + </p><p> + One useful feature for certain Source Code Manager (SCM) fetchers is the ability to + "auto-update" when the upstream SCM changes version. + Since this ability requires certain functionality from the SCM, not all + systems support it. + Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". + This feature works using the <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code> + variable. + See the + "<a class="link" href="#platdev-appdev-srcrev" target="_top">Using an External SCM</a>" section + in the Yocto Project Development Manual for more information. + </p></div></div> + + <div class="chapter" title="Chapter 6. Classes"><div class="titlepage"><div><div><h2 class="title"><a id="ref-classes"></a>Chapter 6. Classes</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-classes-base">6.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">6.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">6.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">6.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">6.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">6.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">6.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">6.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">6.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">6.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">6.12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">6.13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">6.14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">6.15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">6.16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">6.17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">6.18. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">6.19. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">6.20. Other Classes</a></span></dt></dl></div><p> + Class files are used to abstract common functionality and share it amongst multiple + <code class="filename">.bb</code> files. + Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class + file. + Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed + in a <code class="filename">classes/</code> directory beneath the + <code class="filename">meta*/</code> directory found in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as + <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. + Class files are searched for in <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> + using the same method by which <code class="filename">.conf</code> files are searched. +</p><p> + In most cases inheriting the class is enough to enable its features, although + for some classes you might need to set variables or override some of the + default behaviour. +</p><div class="section" title="6.1. The base class - base.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-base"></a>6.1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p> + The base class is special in that every <code class="filename">.bb</code> + file inherits it automatically. + This class contains definitions for standard basic + tasks such as fetching, unpacking, configuring (empty by default), compiling + (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging + (empty by default). + These classes are often overridden or extended by other classes + such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>. + The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>. + </p></div><div class="section" title="6.2. Autotooled Packages - autotools.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-autotools"></a>6.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p> + Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>, + and <code class="filename">libtool</code>) bring standardization. + This class defines a set of tasks (configure, compile etc.) that + work for all Autotooled packages. + It should usually be enough to define a few standard variables + and then simply <code class="filename">inherit autotools</code>. + This class can also work with software that emulates Autotools. + For more information, see the + "<a class="link" href="#usingpoky-extend-addpkg-autotools" target="_top">Autotooled Package</a>" + section in the Yocto Project Development Manual. + </p><p> + It's useful to have some idea of how the tasks defined by this class work + and what they do behind the scenes. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">do_configure</code> ‐ regenerates the + configure script (using <code class="filename">autoreconf</code>) and then launches it + with a standard set of arguments used during cross-compilation. + You can pass additional parameters to <code class="filename">configure</code> through the + <code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable. + </p></li><li class="listitem"><p><code class="filename">do_compile</code> ‐ runs <code class="filename">make</code> with + arguments that specify the compiler and linker. + You can pass additional arguments through + the <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable. + </p></li><li class="listitem"><p><code class="filename">do_install</code> ‐ runs <code class="filename">make install</code> + and passes a DESTDIR option, which takes its value from the standard + <code class="filename"><a class="link" href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable. + </p></li></ul></div><p> + </p></div><div class="section" title="6.3. Alternatives - update-alternatives.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-alternatives"></a>6.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p> + Several programs can fulfill the same or similar function and be installed with the same name. + For example, the <code class="filename">ar</code> command is available from the + <code class="filename">busybox</code>, <code class="filename">binutils</code> and + <code class="filename">elfutils</code> packages. + The <code class="filename">update-alternatives.bbclass</code> class handles renaming the + binaries so that multiple packages can be installed without conflicts. + The <code class="filename">ar</code> command still works regardless of which packages are installed + or subsequently removed. + The class renames the conflicting binary in each package and symlinks the highest + priority binary during installation or removal of packages. + </p><p> + Four variables control this class: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> ‐ The name of the + binary that is replaced (<code class="filename">ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> ‐ The path to + the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> ‐ The path to the + real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> ‐ The priority of + the binary. + The version with the most features should have the highest priority.</p></li></ul></div><p> + </p><p> + Currently, the OpenEmbedded build system supports only one binary per package. + </p></div><div class="section" title="6.4. Initscripts - update-rc.d.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-rc.d"></a>6.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p> + This class uses <code class="filename">update-rc.d</code> to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system takes care of details such as making sure the script is stopped before + a package is removed and started when the package is installed. + Three variables control this class: + <code class="filename"><a class="link" href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>, + <code class="filename"><a class="link" href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and + <code class="filename"><a class="link" href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>. + See the variable links for details. + </p></div><div class="section" title="6.5. Binary config scripts - binconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-binconfig"></a>6.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p> + Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell + scripts to give information about the libraries and include paths needed + to build software (usually named <code class="filename">LIBNAME-config</code>). + This class assists any recipe using such scripts. + </p><p> + During staging, BitBake installs such scripts into the + <code class="filename">sysroots/</code> directory. + BitBake also changes all paths to point into the <code class="filename">sysroots/</code> + directory so all builds that use the script will use the correct + directories for the cross compiling layout. + </p></div><div class="section" title="6.6. Debian renaming - debian.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-debian"></a>6.6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p> + This class renames packages so that they follow the Debian naming + policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code> + and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>. + </p></div><div class="section" title="6.7. Pkg-config - pkgconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-pkgconfig"></a>6.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p> + <code class="filename">pkg-config</code> brought standardization and this class aims to make its + integration smooth for all libraries that make use of it. + </p><p> + During staging, BitBake installs <code class="filename">pkg-config</code> data into the + <code class="filename">sysroots/</code> directory. + By making use of sysroot functionality within <code class="filename">pkg-config</code>, + this class no longer has to manipulate the files. + </p></div><div class="section" title="6.8. Distribution of sources - src_distribute_local.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-src-distribute"></a>6.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p> + Many software licenses require that source files be provided along with the binaries. + To simplify this process, two classes were created: + <code class="filename">src_distribute.bbclass</code> and + <code class="filename">src_distribute_local.bbclass</code>. + </p><p> + The results of these classes are <code class="filename">tmp/deploy/source/</code> + subdirs with sources sorted by + <code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a></code> field. + If recipes list few licenses (or have entries like "Bitstream Vera"), + the source archive is placed in each license directory. + </p><p> + This class operates using three modes: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the + distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the + distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into + the distribute directory and then symlinks them back.</p></li></ul></div><p> + </p></div><div class="section" title="6.9. Perl modules - cpan.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-perl"></a>6.9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p> + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and then inherit the + proper <code class="filename">.bbclass</code> file. + Building is split into two methods depending on which method the module authors used. + </p><p> + Modules that use old <code class="filename">Makefile.PL</code>-based build system require + <code class="filename">cpan.bbclass</code> in their recipes. + </p><p> + Modules that use <code class="filename">Build.PL</code>-based build system require + using <code class="filename">cpan_build.bbclass</code> in their recipes. + </p></div><div class="section" title="6.10. Python extensions - distutils.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-distutils"></a>6.10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p> + Recipes for Python extensions are simple. + These recipes usually only need to point to the source's archive and then inherit + the proper <code class="filename">.bbclass</code> file. + Building is split into two methods dependling on which method the module authors used. + </p><p> + Extensions that use an Autotools-based build system require Autotools and + <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes. + </p><p> + Extensions that use <code class="filename">distutils</code>-based build systems require + <code class="filename">distutils.bbclass</code> in their recipes. + </p></div><div class="section" title="6.11. Developer Shell - devshell.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-devshell"></a>6.11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p> + This class adds the <code class="filename">devshell</code> task. + Distribution policy dictates whether to include this class. + See the + "<a class="link" href="#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section + in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>. + </p></div><div class="section" title="6.12. Packaging - package*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-package"></a>6.12. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p> + The packaging classes add support for generating packages from a build's + output. + The core generic functionality is in <code class="filename">package.bbclass</code>. + The code specific to particular package types is contained in various sub-classes such as + <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>, + and <code class="filename">package_rpm.bbclass</code>. + Most users will want one or more of these classes. + </p><p> + You can control the list of resulting package formats by using the + <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code> + variable defined in the <code class="filename">local.conf</code> configuration file, + which is located in the <code class="filename">conf</code> folder of the + <a class="link" href="#source-directory" target="_top">source directory</a>. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + </p><p> + The package class you choose can affect build-time performance and has space + ramifications. + In general, building a package with RPM takes about thirty percent more time as + compared to using IPK to build the same or similar package. + This comparison takes into account a complete build of the package with all + dependencies previously built. + The reason for this discrepancy is because the RPM package manager creates and + processes more metadata than the IPK package manager. + Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code> + to "package_ipk" if you are building smaller systems. + </p><p> + Keep in mind, however, that RPM starts to provide more abilities than IPK due to + the fact that it processes more metadata. + For example, this information includes individual file types, file checksum generation + and evaluation on install, sparse file support, conflict detection and resolution + for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks. + </p><p> + Another consideration for packages built using the RPM package manager is space. + For smaller systems, the extra space used for the Berkley Database and the amount + of metadata can affect your ability to do on-device upgrades. + </p><p> + You can find additional information on the effects of the package class at these + two Yocto Project mailing list links: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_top"> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_top"> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li></ul></div><p> + </p></div><div class="section" title="6.13. Building kernels - kernel.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-kernel"></a>6.13. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p> + This class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + <code class="filename"><a class="link" href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code> + directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>. + </p><p> + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the <code class="filename">modinfo</code> output. + If all modules are required, then installing the <code class="filename">kernel-modules</code> + package installs all packages with modules and various other kernel packages + such as <code class="filename">kernel-vmlinux</code>. + </p><p> + Various other classes are used by the kernel and module classes internally including + <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>, + <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>. + </p></div><div class="section" title="6.14. Creating images - image.bbclass and rootfs*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-image"></a>6.14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p> + These classes add support for creating images in several formats. + First, the root filesystem is created from packages using + one of the <code class="filename">rootfs_*.bbclass</code> + files (depending on the package format used) and then the image is created. + </p><p> + The <code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code> + variable controls the types of images to generate. + </p><p> + The <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code> + variable controls the list of packages to install into the image. + </p></div><div class="section" title="6.15. Host System sanity checks - sanity.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-sanity"></a>6.15. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p> + This class checks to see if prerequisite software is present so that + users can be notified of potential problems that might affect their build. + The class also performs basic user configuration checks from + the <code class="filename">local.conf</code> configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually determines whether to include this class. + </p></div><div class="section" title="6.16. Generated output quality assurance checks - insane.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-insane"></a>6.16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p> + This class adds a step to the package generation process that sanity checks the + packages generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + </p><p> + You can configure the sanity checks so that specific test failures either raise a warning or + an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error message + once the metadata is in a known and good condition. + You use the <code class="filename">WARN_QA</code> variable to specify tests for which you + want to generate a warning message on failure. + You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you + want to generate an error message on failure. + </p><p> + The following list shows the tests you can list with the <code class="filename">WARN_QA</code> + and <code class="filename">ERROR_QA</code> variables: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span> + Ensures that the binaries were linked with the + <code class="filename">LDFLAGS</code> options provided by the build system. + If this test fails, check that the <code class="filename">LDFLAGS</code> variable + is being passed to the linker command.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span> + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>). + While these paths will not cause any breakage, they do waste space and + are unnecessary.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span> + Checks for rpaths in the binaries that contain build system paths such + as <code class="filename">TMPDIR</code>. + If this test fails, bad <code class="filename">-rpath</code> options are being + passed to the linker commands and your binaries have potential security + issues.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span> + Checks that the <code class="filename">.so</code> symbolic links are in the + <code class="filename">-dev</code> package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the <code class="filename">-dev</code> package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span> + Checks for <code class="filename">.debug</code> directories in anything but the + <code class="filename">-dbg</code> package. + The debug files should all be in the <code class="filename">-dbg</code> package. + Thus, anything packaged elsewhere is incorrect packaging.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span> + Checks the Executable and Linkable Format (ELF) type, bit size and endianness + of any binaries to ensure it matches the target architecture. + This test fails if any binaries don't match the type since there would be an + incompatibility. + Sometimes software, like bootloaders, might need to bypass this check. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span> + Checks that <code class="filename">-dbg</code> packages only depend on other + <code class="filename">-dbg</code> packages and not on any other types of packages, + which would cause a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span> + Checks that <code class="filename">-dev</code> packages only depend on other + <code class="filename">-dev</code> packages and not on any other types of packages, + which would be a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span> + Checks <code class="filename">.pc</code> files for any + <code class="filename">TMPDIR/WORKDIR</code> paths. + Any <code class="filename">.pc</code> file containing these paths is incorrect + since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix + when the files are accessed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span> + Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code> + paths. + Any <code class="filename">.la</code> file continaing these paths is incorrect since + <code class="filename">libtool</code> adds the correct sysroot prefix when using the + files automatically itself.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span> + Runs the <code class="filename">desktop-file-validate</code> program against any + <code class="filename">.desktop</code> files to validate their contents against + the specification for <code class="filename">.desktop</code> files.</p></li></ul></div><p> + </p></div><div class="section" title="6.17. Autotools configuration data cache - siteinfo.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-siteinfo"></a>6.17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p> + Autotools can require tests that must execute on the target hardware. + Since this is not possible in general when cross compiling, site information is + used to provide cached test results so these tests can be skipped over but + still make the correct values available. + The <code class="filename"><a class="link" href="#structure-meta-site" title="4.3.18. meta/site/">meta/site directory</a></code> + contains test results sorted into different categories such as architecture, endianness, and + the <code class="filename">libc</code> used. + Site information provides a list of files containing data relevant to + the current build in the + <code class="filename"><a class="link" href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable + that Autotools automatically picks up. + </p><p> + The class also provides variables like + <code class="filename"><a class="link" href="#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code> + and <code class="filename"><a class="link" href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code> + that can be used elsewhere in the metadata. + </p><p> + Because this class is included from <code class="filename">base.bbclass</code>, it is always active. + </p></div><div class="section" title="6.18. Adding Users - useradd.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-useradd"></a>6.18. Adding Users - <code class="filename">useradd.bbclass</code></h2></div></div></div><p> + If you have packages that install files that are owned by custom users or groups, + you can use this class to specify those packages and associate the users and groups + with those packages. + The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code> + recipe in the <a class="link" href="#source-directory" target="_top">source directory</a> + provides a simple exmample that shows how to add three + users and groups to two packages. + See the <code class="filename">useradd-example.bb</code> for more information on how to + use this class. + </p></div><div class="section" title="6.19. Using External Source - externalsrc.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-externalsrc"></a>6.19. Using External Source - <code class="filename">externalsrc.bbclass</code></h2></div></div></div><p> + You can use this class to build software from source code that is external to the + OpenEmbedded build system. + In other words, your source code resides in an external tree outside of the Yocto Project. + Building software from an external source tree means that the normal fetch, unpack, and + patch process is not used. + </p><p> + To use the class, you need to define the + <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> variable to point to the directory that contains the source files. + You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class. + </p><p> + This class expects the source code to support recipe builds that use the + <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable to point to the directory in + which the OpenEmbedded build system places the generated objects built from the recipes. + By default, the <code class="filename">B</code> directory is set to the following, which is separate from the + source directory (<code class="filename">S</code>): + </p><pre class="literallayout"> + ${WORKDIR}/${BPN}-{PV}/ + </pre><p> + See the glossary entries for the + <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>, + <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a>, + <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>, + <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>, and + <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> for more information. + </p><p> + You can build object files in the external tree by setting the + <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>. + However, this practice does not work well if you use the source for more than one variant + (i.e., "natives" such as <code class="filename">quilt-native</code>, + or "crosses" such as <code class="filename">gcc-cross</code>). + So, be sure there are no "native", "cross", or "multilib" variants of the recipe. + </p><p> + If you do want to build different variants of a recipe, you can use the + <a class="link" href="#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable. + When you do, the <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable must support the + recipe's ability to build variants in different working directories. + Most autotools-based recipes support separating these directories. + The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code> + and some kernel recipes. + Alternatively, you can make sure that separate recipes exist that each + use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant. + The separate recipes can inherit a single target recipe. + </p><p> + For information on how to use this class, see the + "<a class="link" href="#building-software-from-an-external-source" target="_top">Building + Software from an External Source</a>" section in the Yocto Project Development Manual. + </p></div><div class="section" title="6.20. Other Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-others"></a>6.20. Other Classes</h2></div></div></div><p> + Thus far, this chapter has discussed only the most useful and important + classes. + However, other classes exist within the <code class="filename">meta/classes</code> directory + in the <a class="link" href="#source-directory" target="_top">source directory</a>. + You can examine the <code class="filename">.bbclass</code> files directly for more + information. + </p></div></div> + + <div class="chapter" title="Chapter 7. Images"><div class="titlepage"><div><div><h2 class="title"><a id="ref-images"></a>Chapter 7. Images</h2></div></div></div><p> + The OpenEmbedded build process supports several types of images to satisfy different needs. + When you issue the <code class="filename">bitbake</code> command you provide a “top-level” recipe + that essentially begins the build for the type of image you want. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Building an image without GNU Public License Version 3 (GPLv3) components is + only supported for minimal and base images. + Furthermore, if you are going to build an image using non-GPLv3 components, + you must make the following changes in the <code class="filename">local.conf</code> file + before using the BitBake command to build the minimal or base image: + <pre class="literallayout"> + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPLv3" + </pre></div><p> + From within the <code class="filename">poky</code> Git repository, use the following command to list + the supported images: + </p><pre class="literallayout"> + $ ls meta*/recipes*/images/*.bb + </pre><p> + These recipes reside in the <code class="filename">meta/recipes-core/images</code>, + <code class="filename">meta/recipes-extended/images</code>, + <code class="filename">meta/recipes-graphics/images</code>, and + <code class="filename">meta/recipes-sato/images</code> directories + within the <a class="link" href="#source-directory" target="_top">source directory</a>. + Although the recipe names are somewhat explanatory, here is a list that describes them: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span> + A console-only image that fully supports the target device hardware.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-core</code>:</em></span> + An X11 image with simple applications such as terminal, editor, and file manager. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span> + A small image just capable of allowing a device to boot.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span> + A <code class="filename">core-image-minimal</code> image suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span> + A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based + Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel, + which allows the system to find the first “init” program more efficiently. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span> + A <code class="filename">core-image-minimal</code> image that has support + for the Minimal MTD Utilities, which let the user interact with the + MTD subsystem in the kernel to perform operations on flash devices. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span> + A foundational basic image without support for X that can be reasonably used for + customization.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span> + A <code class="filename">core-image-basic</code> image suitable for implementations + that conform to Linux Standard Base (LSB).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span> + A <code class="filename">core-image-lsb</code> image that is suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span> + A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain + but also includes development headers and libraries to form a complete standalone SDK. + This image is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span> + An image with support for the Open GL-based toolkit Clutter, which enables development of + rich and animated graphical user interfaces.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span> + An image with Sato support, a mobile environment and visual style that works well + with mobile devices. + The image supports X11 with a Sato theme and Pimlico applications and also + contains terminal, editor, and file manager.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span> + A <code class="filename">core-image-sato</code> image suitable for development + using the host. + The image includes libraries needed to build applications on the device itself, + testing and profiling tools, and debug symbols. + This image was formerly <code class="filename">core-image-sdk</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span> + A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain. + The image also includes development headers and libraries to form a complete standalone SDK + and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span> + A <code class="filename">core-image-minimal</code> image plus a real-time test suite and + tools appropriate for real-time use.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span> + A <code class="filename">core-image-rt</code> image that includes everything in + <code class="filename">meta-toolchain</code>. + The image also includes development headers and libraries to form a complete + stand-alone SDK and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span> + An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code> + instead of X11. + In order to build, this image requires specific distro configuration that enables + <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span> + An image you can boot and run using either the + <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_top">VMware Player</a> + or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_top">VMware Workstation</a>. + For more information on this image, see the + <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> page on + the Yocto Project website.</p></li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and + <code class="filename">-directdisk</code> images have been replaced by a "live" + option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an + image file that can be + copied directly to a CD or USB device and run as is. + To build a live image, simply add + "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code> + file or wherever appropriate and then build the desired image as normal. + </div></div> + + <div class="chapter" title="Chapter 8. Reference: Features"><div class="titlepage"><div><div><h2 class="title"><a id="ref-features"></a>Chapter 8. Reference: Features</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-features-distro">8.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">8.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">8.3. Reference: Images</a></span></dt></dl></div><p> + Features provide a mechanism for working out which packages + should be included in the generated images. + Distributions can select which features they want to support through the + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code> + variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file. + Machine features are set in the + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code> + variable, which is set in the machine configuration file and + specifies the hardware features for a given machine. + </p><p> + These two variables combine to work out which kernel modules, + utilities, and other packages to include. + A given distribution can support a selected subset of features so some machine features might not + be included if the distribution itself does not support them. + </p><div class="section" title="8.1. Distro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-distro"></a>8.1. Distro</h2></div></div></div><p> + The items below are valid options for + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility + kernel modules will be installed if available).</p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only) + </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal + HDD/Microdrive for storing files (instead of Flash only devices) + </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support + </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be + loaded during boot). + </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support + </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support + </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB + networking/serial/storage) + </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external + keyboard, mouse, storage, network etc) + </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only) + </p></li><li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support + </p></li><li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support + </p></li><li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support + </p></li><li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on + device)</p></li><li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li><li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting + Samba/Microsoft Windows shares on device)</p></li></ul></div><p> + </p></div><div class="section" title="8.2. Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-machine"></a>8.2. Machine</h2></div></div></div><p> + The items below are valid options for + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only) + </p></li><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers + </p></li><li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation) + </p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT + </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive + </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support + </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard + </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus + </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets + </p></li><li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen + </p></li><li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232) + </p></li><li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen + </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable + </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable + </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi + </p></li></ul></div><p> + </p></div><div class="section" title="8.3. Reference: Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-image"></a>8.3. Reference: Images</h2></div></div></div><p> + The contents of images generated by the OpenEmbedded build system can be controlled by the + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> + and <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> + variables that you typically configure in your image recipes. + Through these variables you can add several different + predefined packages such as development utilities or packages with debug + information needed to investigate application problems or profile applications. + </p><p> + Current list of + <code class="filename">IMAGE_FEATURES</code> contains the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>apps-console-core:</em></span> Core console applications such as + <code class="filename">ssh</code>, <code class="filename">daemon</code>, <code class="filename">avahi daemon</code>, + <code class="filename">portmap</code> (for mounting NFS shares)</p></li><li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> X11 server + minimal desktop</p></li><li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> OpenedHand Sato environment</p></li><li class="listitem"><p><span class="emphasis"><em>apps-x11-core:</em></span> Core X11 applications such as an + X Terminal, file manager, and file editor</p></li><li class="listitem"><p><span class="emphasis"><em>apps-x11-games:</em></span> A set of X11 games</p></li><li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> A full SDK that runs on the device + </p></li><li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Debugging tools such as + <code class="filename">strace</code> and <code class="filename">gdb</code> + </p></li><li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Profiling tools such as + <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and + <code class="filename">LTTng</code></p></li><li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Device testing tools (e.g. + touchscreen debugging)</p></li><li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> NFS server (exports / over NFS + to everybody)</p></li><li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Development packages (headers and + extra library links) for all packages installed in a given image</p></li><li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Debug packages for all packages + installed in a given image</p></li></ul></div><p> + </p></div></div> + + <div class="chapter" title="Chapter 9. Variables Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glos"></a>Chapter 9. Variables Glossary</h2></div></div></div><div class="toc"><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p> + This chapter lists common variables used in the OpenEmbedded build system and gives an overview + of their function and contents. +</p><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glossary"></a>Glossary</h2></div></div></div><p> + <a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a> + <a class="link" href="#var-B" title="B">B</a> + <a class="link" href="#var-CFLAGS" title="CFLAGS">C</a> + <a class="link" href="#var-D" title="D">D</a> + <a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a> + <a class="link" href="#var-FILES" title="FILES">F</a> + + <a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">H</a> + <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a> + + <a class="link" href="#var-KBRANCH" title="KBRANCH">K</a> + <a class="link" href="#var-LAYERDIR" title="LAYERDIR">L</a> + <a class="link" href="#var-MACHINE" title="MACHINE">M</a> + + + <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">P</a> + + <a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">R</a> + <a class="link" href="#var-S" title="S">S</a> + <a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">T</a> + + + <a class="link" href="#var-WORKDIR" title="WORKDIR">W</a> + + + + </p><div class="glossdiv" title="A"><h3 class="title">A</h3><dl><dt><a id="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt><dd><p> + Specifies if an output package should still be produced if it is empty. + By default, BitBake does not produce empty packages. + This default behavior can cause issues when there is an + <a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or + some other runtime hard-requirement on the existence of the package. + </p><p> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + </p><pre class="literallayout"> + ALLOW_EMPTY_${PN} + </pre><p> + </p></dd><dt><a id="var-AUTHOR"></a>AUTHOR</dt><dd><p>The email address used to contact the original author or authors in + order to send patches, forward bugs, etc.</p></dd><dt><a id="var-AUTOREV"></a>AUTOREV</dt><dd><p>Specifies to use the current (newest) source revision. + This variable is with the <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code> + variable.</p></dd></dl></div><div class="glossdiv" title="B"><h3 class="title">B</h3><dl><dt><a id="var-B"></a>B</dt><dd><p> + The directory in which the OpenEmbedded build system places + generated objects during a recipe's build process. + By default, this directory is the same as the <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> + directory: + </p><pre class="literallayout"> + B = ${WORKDIR}/${BPN}-{PV}/ + </pre><p> + You can separate the source directory (<code class="filename">S</code>) and the directory pointed to + by the <code class="filename">B</code> variable. + Most autotools-based recipes support separating these directories. + The build system defaults to using separate directories for <code class="filename">gcc</code> + and some kernel recipes. + </p></dd><dt><a id="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt><dd><p> + A list of packages not to install despite being recommended by a recipe. + Support for this variable exists only for images that use the + <code class="filename">ipkg</code> packaging system. + </p></dd><dt><a id="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt><dd><p> + Allows you to extend a recipe so that it builds variants of the software. + Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>, + which is a copy of quilt built to run on the build system; + "crosses" such as <code class="filename">gcc-cross</code>, + which is a compiler built to run on the build machine but produces binaries + that run on the target <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>; + "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>; + and "mulitlibs" in the form "<code class="filename">multilib:<multilib_name></code>". + </p><p> + To build a different variant of the recipe with a minimal amount of code, it usually + is as simple as adding the following to your recipe: + </p><pre class="literallayout"> + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:<multilib_name>" + </pre><p> + </p></dd><dt><a id="var-BBMASK"></a>BBMASK</dt><dd><p>Prevents BitBake from processing recipes and recipe append files. + You can use the <code class="filename">BBMASK</code> variable to "hide" + these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files. + BitBake ignores any recipe or recipe append files that match the expression. + It is as if BitBake does not see them at all. + Consequently, matching files are not parsed or otherwise used by + BitBake.</p><p>The value you provide is passed to python's regular expression compiler. + For complete syntax information, see python's documentation at + <a class="ulink" href="http://docs.python.org/release/2.3/lib/re-syntax.html" target="_top">http://docs.python.org/release/2.3/lib/re-syntax.html</a>. + The expression is compared against the full paths to the files. + For example, the following uses a complete regular expression to tell + BitBake to ignore all recipe and recipe append files in the + <code class="filename">.*/meta-ti/recipes-misc/</code> directory: + </p><pre class="literallayout"> + BBMASK = ".*/meta-ti/recipes-misc/" + </pre><p>Use the <code class="filename">BBMASK</code> variable from within the + <code class="filename">conf/local.conf</code> file found + in the <a class="link" href="#build-directory" target="_top">build directory</a>.</p></dd><dt><a id="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>The maximum number of tasks BitBake should run in parallel at any one time. + If your host development system supports multiple cores a good rule of thumb + is to set this variable to twice the number of cores.</p></dd><dt><a id="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt><dd><p>Lists the names of configured layers. + These names are used to find the other <code class="filename">BBFILE_*</code> + variables. + Typically, each layer will append its name to this variable in its + <code class="filename">conf/layer.conf</code> file. + </p></dd><dt><a id="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt><dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer. + This variable is used in the <code class="filename">conf/layer.conf</code> file and must + be suffixed with the name of the specific layer (e.g. + <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd><dt><a id="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt><dd><p>Assigns the priority for recipe files in each layer.</p><p>This variable is useful in situations where the same package appears in + more than one layer. + Setting this variable allows you to prioritize a + layer against other layers that contain the same package - effectively + letting you control the precedence for the multiple layers. + The precedence established through this variable stands regardless of a + layer's package version (<code class="filename">PV</code> variable). + For example, a layer that has a package with a higher <code class="filename">PV</code> value but for + which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a + lower precedence.</p><p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher + precedence. + For example, the value 6 has a higher precedence than the value 5. + If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer + dependencies (see the + <code class="filename"><a class="link" href="#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for + more information. + The default priority, if unspecified + for a layer with no dependencies, is the lowest defined priority + 1 + (or 1 if no priorities are defined).</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + You can use the command <code class="filename">bitbake-layers show_layers</code> to list + all configured layers along with their priorities. + </div></dd><dt><a id="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipe files used by BitBake to build software</p></dd><dt><a id="var-BBPATH"></a>BBPATH</dt><dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files. + This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd><dt><a id="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd><dt><a id="var-BBLAYERS"></a>BBLAYERS</dt><dd><p>Lists the layers to enable during the build. + This variable is defined in the <code class="filename">bblayers.conf</code> configuration + file in the <a class="link" href="#build-directory" target="_top">build directory</a>. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-mykernel \ + " + </pre><p> + This example enables three layers, one of which is a custom, user-defined layer + named <code class="filename">meta-mykernel</code>. + </p></dd><dt><a id="var-BPN"></a>BPN</dt><dd><p>Bare name of package with any suffixes like -cross -native removed.</p></dd></dl></div><div class="glossdiv" title="C"><h3 class="title">C</h3><dl><dt><a id="var-CFLAGS"></a>CFLAGS</dt><dd><p> + Flags passed to C compiler for the target system. + This variable evaluates to the same as + <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>. + </p></dd><dt><a id="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt><dd><p>A regular expression which evaluates to match the machines the recipe + works with. + It stops recipes being run on machines for which they are not compatible. + This is particularly useful with kernels. + It also helps to increase parsing speed as further parsing of the recipe is skipped + if it is found the current machine is not compatible.</p></dd><dt><a id="var-CONFFILES"></a>CONFFILES</dt><dd><p> + Identifies editable or configurable files that are part of a package. + If the Package Management System (PMS) is being used to update + packages on the target system, it is possible that + configuration files you have changed after the original installation + and that you now want to remain unchanged are overwritten. + In other words, editable files might exist in the package that you do not + want reset as part of the package update process. + You can use the <code class="filename">CONFFILES</code> variable to list the files in the + package that you wish to prevent the PMS from overwriting during this update process. + </p><p> + To use the <code class="filename">CONFFILES</code> variable, provide a package name + override that identifies the package. + Then, provide a space-separated list of files. + Here is an example: + </p><pre class="literallayout"> + CONFFILES_${PN} += "${sysconfdir}/file1 \ + ${sysconfdir}/file2 ${sysconfdir}/file3" + </pre><p> + </p><p> + A relationship exists between the <code class="filename">CONFFILES</code> and + <code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a></code> variables. + The files listed within <code class="filename">CONFFILES</code> must be a subset of + the files listed within <code class="filename">FILES</code>. + Because the configuration files you provide with <code class="filename">CONFFILES</code> + are simply being identified so that the PMS will not overwrite them, + it makes sense that + the files must already be included as part of the package through the + <code class="filename">FILES</code> variable. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + When specifying paths as part of the <code class="filename">CONFFILES</code> variable, + it is good practice to use appropriate path variables. + For example, <code class="filename">${sysconfdir}</code> rather than + <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather + than <code class="filename">/usr/bin</code>. + You can find a list of these variables at the top of the + <code class="filename">/meta/conf/bitbake.conf</code> file in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + </div></dd><dt><a id="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p> + A list of files that contains <code class="filename">autoconf</code> test results relevant + to the current build. + This variable is used by the Autotools utilities when running + <code class="filename">configure</code>. + </p></dd><dt><a id="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt><dd><p> + Specifies the list of packages to be added to the image. + This variable should only be set in the <code class="filename">local.conf</code> + configuration file found in the + <a class="link" href="#build-directory" target="_top">build directory</a>. + </p><p> + This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported. + </p></dd></dl></div><div class="glossdiv" title="D"><h3 class="title">D</h3><dl><dt><a id="var-D"></a>D</dt><dd><p>The destination directory.</p></dd><dt><a id="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p> + Specifies to build packages with debugging information. + This influences the value of the + <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code> + variable. + </p></dd><dt><a id="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p> + The options to pass in + <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> + and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling + a system for debugging. + This variable defaults to "-O -fno-omit-frame-pointer -g". + </p></dd><dt><a id="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Specifies the priority of recipes.</p></dd><dt><a id="var-DEPENDS"></a>DEPENDS</dt><dd><p> + A list of build-time dependencies for a given recipe. + The variable indicates recipes that must have been staged before a + particular recipe can configure. + </p></dd><dt><a id="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>The package description used by package managers.</p></dd><dt><a id="var-DESTDIR"></a>DESTDIR</dt><dd><p>the destination directory.</p></dd><dt><a id="var-DISTRO"></a>DISTRO</dt><dd><p>The short name of the distribution.</p></dd><dt><a id="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p></p><p>The list of packages which extend usability of the image. + Those packages will automatically be installed but can be removed by user.</p></dd><dt><a id="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>The features of the distribution.</p></dd><dt><a id="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>The long name of the distribution.</p></dd><dt><a id="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt><dd><p>Alias names used for the recipe in various Linux distributions.</p><p>See the + "<a class="link" href="#usingpoky-configuring-DISTRO_PN_ALIAS" target="_top">Handling + a Package Name Alias</a>" section in the Yocto Project Development + Manual for more information.</p></dd><dt><a id="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>the version of the distribution.</p></dd><dt><a id="var-DL_DIR"></a>DL_DIR</dt><dd><p> + The central download directory used by the build process to store downloads. + You can set this directory by defining the <code class="filename">DL_DIR</code> + variable in the <code class="filename">/conf/local.conf</code> file. + This directory is self-maintaining and you should not have + to touch it. + By default, the directory is <code class="filename">downloads</code> in the + <a class="link" href="#build-directory" target="_top">build directory</a>. + </p><pre class="literallayout"> + #DL_DIR ?= "${TOPDIR}/downloads" + </pre><p> + To specify a different download directory, simply uncomment the line + and provide your directory. + </p><p> + During a first build, the system downloads many different source code + tarballs from various upstream projects. + Downloading can take a while, particularly if your network + connection is slow. + Tarballs are all stored in the directory defined by + <code class="filename">DL_DIR</code> and the build system looks there first + to find source tarballs. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + When wiping and rebuilding, you can preserve this directory to speed + up this part of subsequent builds. + </div><p> + </p><p> + You can safely share this directory between multiple builds on the + same development machine. + For additional information on how the build process gets source files + when working behind a firewall or proxy server, see the + "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server">FAQ</a>" + chapter. + </p></dd></dl></div><div class="glossdiv" title="E"><h3 class="title">E</h3><dl><dt><a id="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p></p><p>Variable that controls which locales for <code class="filename">eglibc</code> are + to be generated during the build (useful if the target device has 64Mbytes + of RAM or less).</p></dd><dt><a id="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt><dd><p>Allows extra packages to be added to the generated images. + You set this variable in the <code class="filename">local.conf</code> + configuration file. + Note that some image features are also added using the + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> + variable generally configured in image recipes. + You can use this variable to add more features in addition to those. + Here are some examples of features you can add:</p><pre class="literallayout"> +"dbg-pkgs" - Adds -dbg packages for all installed packages + including symbol information for debugging and + profiling. + +"dev-pkgs" - Adds -dev packages for all installed packages. + This is useful if you want to develop against + the libraries in the image. + +"tools-sdk" - Adds development tools such as gcc, make, + pkgconfig and so forth. + +"tools-debug" - Adds debugging tools such as gdb and + strace. + +"tools-profile" - Adds profiling tools such as oprofile, + exmap, lttng and valgrind (x86 only). + +"tools-testapps" - Adds useful testing tools such as + ts_print, aplay, arecord and so + forth. + +"debug-tweaks" - Makes an image suitable for development. + For example, ssh root access has a blank + password. You should remove this feature + before you produce a production image. + + There are other application targets too, see + <code class="filename">meta/classes/poky-image.bbclass</code> + and <code class="filename">meta/packages/tasks/task-poky.bb</code> + for more details. + </pre></dd><dt><a id="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt><dd><p>A list of recipes to be built that do not provide packages to be installed in + the root filesystem. + </p><p>Sometimes a recipe is required to build the final image but is not + needed in the root filesystem. + You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to + list these recipes and thus, specify the dependencies. + A typical example is a required bootloader in a machine configuration. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + To add packages to the root filesystem, see the various + <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code> + variables. + </div></dd><dt><a id="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt><dd><p>Additional <code class="filename">cmake</code> options.</p></dd><dt><a id="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional <code class="filename">configure</code> script options.</p></dd><dt><a id="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU <code class="filename">make</code> options.</p></dd></dl></div><div class="glossdiv" title="F"><h3 class="title">F</h3><dl><dt><a id="var-FILES"></a>FILES</dt><dd><p> + The list of directories or files that are placed in packages. + </p><p> + To use the <code class="filename">FILES</code> variable, provide a package name + override that identifies the package. + Then, provide a space-separated list of files or paths that identifies the + files you want included as part of the package. + Here is an example: + </p><pre class="literallayout"> + FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + When specifying paths as part of the <code class="filename">FILES</code> variable, + it is good practice to use appropriate path variables. + For example, <code class="filename">${sysconfdir}</code> rather than + <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather + than <code class="filename">/usr/bin</code>. + You can find a list of these variables at the top of the + <code class="filename">/meta/conf/bitbake.conf</code> file in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + </div><p> + If some of the files you provide with the <code class="filename">FILES</code> variable + are editable and you know they should not be + overwritten during the package update process by the Package Management + System (PMS), you can identify these files so that the PMS will not + overwrite them. + See the <code class="filename"><a class="link" href="#var-CONFFILES" title="CONFFILES">CONFFILES</a></code> + variable for information on how to identify these files to the PMS. + </p></dd><dt><a id="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt><dd><p> + Extends the search path the OpenEmbedded build system uses when + looking for files and patches as it processes recipes. + The directories BitBake uses when it processes recipes is defined by the + <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable. + You can add directories to the search path by defining the + <code class="filename">FILESEXTRAPATHS</code> variable. + </p><p> + To add paths to the search order, provide a list of directories and separate + each path using a colon character as follows: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" + </pre><p> + Typically, you want your directories search first. + To make sure that happens, use <code class="filename">_prepend</code> and + the immediate expansion (<code class="filename">:=</code>) operator as shown in the + previous example. + Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable, + you must include the appropriate beginning or ending (as needed) colon character. + </p><p> + The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in + <code class="filename">.bbappend</code> files to include any additional files provided in that layer. + You typically accomplish this with the following: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </pre><p> + </p></dd><dt><a id="var-FILESPATH"></a>FILESPATH</dt><dd><p> + The default set of directories the OpenEmbedded build system uses + when searching for patches and files. + During the build process, BitBake searches each directory in + <code class="filename">FILESPATH</code> in the specified order when looking for + files and patches specified by each <code class="filename">file://</code> URI in a recipe. + </p><p> + The default value for the <code class="filename">FILESPATH</code> variable is defined + in the <code class="filename">base.bbclass</code> class found in + <code class="filename">meta/classes</code> in the + <a class="link" href="#source-directory" target="_top">source directory</a>: + </p><pre class="literallayout"> +FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ + "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \ + "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ + "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" + </pre><p> + Do not hand-edit the <code class="filename">FILESPATH</code> variable. + If you want to extend the set of pathnames that BitBake uses when searching for + files and patches, use the + <a class="link" href="#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable. + </p></dd><dt><a id="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt><dd><p>Allows you to define your own file permissions settings table as part of + your configuration for the packaging process. + For example, suppose you need a consistent set of custom permissions for + a set of groups and users across an entire work project. + It is best to do this in the packages themselves but this is not always + possible. + </p><p> + By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which + is located in the <code class="filename">meta/files</code> folder in the + <a class="link" href="#source-directory" target="_top">source directory</a>. + If you create your own file permissions setting table, you should place it in your + layer or the distros layer. + </p><p> + You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the + <code class="filename">conf/local.conf</code> file, which is found in the + <a class="link" href="#build-directory" target="_top">build directory</a>, to + point to your custom <code class="filename">fs-perms.txt</code>. + You can specify more than a single file permissions setting table. + The paths you specify to these files must be defined within the + <code class="filename">BBPATH</code> variable. + </p><p> + For guidance on how to create your own file permissions settings table file, + examine the existing <code class="filename">fs-perms.txt</code>. + </p></dd><dt><a id="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p> + The options to pass in + <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> + and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> + when compiling an optimized system. + This variable defaults to + "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". + </p></dd></dl></div><div class="glossdiv" title="H"><h3 class="title">H</h3><dl><dt><a id="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more info about package can be found</p></dd></dl></div><div class="glossdiv" title="I"><h3 class="title">I</h3><dl><dt><a id="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p>The list of features present in images. + Typically, you configure this variable in image recipes. + Note that you can add extra features to the image by using the + <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> variable. + See the "<a class="link" href="#ref-features-image" title="8.3. Reference: Images">Images</a>" chapter for the + list of features present in images built by the OpenEmbedded build system.</p></dd><dt><a id="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of root filesystem images that you want to have created.</p></dd><dt><a id="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p> + Specifies the packages to install into an image. + The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image + recipe and you should use it with care to avoid ordering issues. + </p><p> + Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the + packages to install into an image through <code class="filename">image.bbclass</code>. + Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>, + that can take + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists + and turn these into auto-generated entries in + <code class="filename">IMAGE_INSTALL</code> in addition to its default contents. + </p><p> + Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code> + operator from the <code class="filename">/conf/local.conf</code> file or from within + an image recipe is not recommended as it can cause ordering issues. + Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code> + to a default value using the <code class="filename">?=</code> operator, using a + <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code> + will result in unexpected behavior when used in + <code class="filename">/conf/local.conf</code>. + Furthermore, the same operation from with an image recipe may or may not + succeed depending on the specific situation. + In both these cases, the behavior is contrary to how most users expect + the <code class="filename">+=</code> operator to work. + </p><p> + When you use this variable, it is best to use it as follows: + </p><pre class="literallayout"> + IMAGE_INSTALL_append = " package-name" + </pre><p> + Be sure to include the space between the quotation character and the start of the + package name. + </p></dd><dt><a id="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt><dd><p> + Defines a multiplier that the build system applies to the initial image + size for cases when the multiplier times the returned disk usage value + for the image is greater than the sum of + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> + and + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>. + The result of the multiplier applied to the initial image size creates + free disk space in the image as overhead. + By default, the build process uses a multiplier of 1.3 for this variable. + This default value results in 30% free disk space added to the image when this + method is used to determine the final generated image size. + You should be aware that post install scripts and the package management + system uses disk space inside this overhead area. + Consequently, the multiplier does not produce an image with + all the theoretical free disk space. + See <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> + for information on how the build system determines the overall image size. + </p><p> + The default 30% free disk space typically gives the image enough room to boot + and allows for basic post installs while still leaving a small amount of + free disk space. + If 30% free space is inadequate, you can increase the default value. + For example, the following setting gives you 50% free space added to the image: + </p><pre class="literallayout"> + IMAGE_OVERHEAD_FACTOR = "1.5" + </pre><p> + </p><p> + Alternatively, you can ensure a specific amount of free disk space is added + to the image by using + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code> + the variable. + </p></dd><dt><a id="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt><dd><p> + Defines additional free disk space created in the image in Kbytes. + By default, this variable is set to "0". + This free disk space is added to the image after the build system determines + the image size as described in + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>. + </p><p> + This variable is particularly useful when you want to ensure that a + specific amount of free disk space is available on a device after an image + is installed and running. + For example, to be sure 5 Gbytes of free disk space is available, set the + variable as follows: + </p><pre class="literallayout"> + IMAGE_ROOTFS_EXTRA_SPACE = "5242880" + </pre><p> + </p></dd><dt><a id="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt><dd><p> + Defines the size in Kbytes for the generated image. + The OpenEmbedded build system determines the final size for the generated + image using an algorithm that takes into account the initial disk space used + for the generated image, a requested size for the image, and requested + additional free disk space to be added to the image. + Programatically, the build system determines the final size of the + generated image as follows: + </p><pre class="literallayout"> + if (image-du * overhead) < rootfs-size: + internal-rootfs-size = rootfs-size + xspace + else: + internal-rootfs-size = (image-du * overhead) + xspace + + where: + + image-du = Returned value of the du command on + the image. + + overhead = IMAGE_OVERHEAD_FACTOR + + rootfs-size = IMAGE_ROOTFS_SIZE + + internal-rootfs-size = Initial root filesystem + size before any modifications. + + xspace = IMAGE_ROOTFS_EXTRA_SPACE + </pre><p> + + </p></dd><dt><a id="var-INC_PR"></a>INC_PR</dt><dd><p>Defines the Package revision. + You manually combine values for <code class="filename">INC_PR</code> into the + <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> field of the parent recipe. + When you change this variable, you change the <code class="filename">PR</code> + value for every person that includes the file.</p><p> + The following example shows how to use the <code class="filename">INC_PR</code> variable + given a common <code class="filename">.inc</code> file that defines the variable. + Once defined, you can use the variable to set the + <code class="filename">PR</code> value: + </p><pre class="literallayout"> +recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" +recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" +recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" +recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" + </pre></dd><dt><a id="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p> + Causes the build to not strip binaries in resulting packages. + </p></dd><dt><a id="var-INHERIT"></a>INHERIT</dt><dd><p> + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + </p></dd><dt><a id="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p> + A list of the packages that contain initscripts. + If multiple packages are specified, you need to append the package name + to the other <code class="filename">INITSCRIPT_*</code> as an override.</p><p> + This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. + The variable is optional and defaults to the <code class="filename">PN</code> variable. + </p></dd><dt><a id="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p> + The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>. + </p><p> + This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. + The variable is Mandatory. + </p></dd><dt><a id="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p> + Specifies the options to pass to <code class="filename">update-rc.d</code>. + An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a + runlevel of 99, starts the script in initlevels 2 and 5, and + stops the script in levels 0, 1 and 6. + </p><p> + The variable is mandatory and is used in recipes when using + <code class="filename">update-rc.d.bbclass</code>. + </p></dd></dl></div><div class="glossdiv" title="K"><h3 class="title">K</h3><dl><dt><a id="var-KBRANCH"></a>KBRANCH</dt><dd><p> + A regular expression used by the build process to explicitly identify the kernel + branch that is validated, patched and configured during a build. + The <code class="filename">KBRANCH</code> variable is optional. + You can use it to trigger checks to ensure the exact kernel branch you want is + being used by the build process. + </p><p> + Values for this variable are set in the kernel's recipe file and the kernel's + append file. + For example, if you are using the Yocto Project kernel that is based on the + Linux 3.2 kernel, the kernel recipe file is the + <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.2.bb</code> file. + Following is the default value for <code class="filename">KBRANCH</code> and the five overrides + for the architectures the Yocto Project supports: + </p><pre class="literallayout"> + KBRANCH = "standard/default/base" + KBRANCH_qemux86 = "standard/default/common-pc/base" + KBRANCH_qemux86-64 = "standard/default/common-pc-64/base" + KBRANCH_qemuppc = "standard/default/qemu-ppc32" + KBRANCH_qemumips = "standard/default/mti-malta32-be" + KBRANCH_qemuarm = "standard/default/arm-versatile-926ejs" + </pre><p> + Each of the above branches exist in the <code class="filename">linux-yocto-3.2</code> kernel Git + repository <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.2/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.2/refs/heads</a>. + </p><p> + This variable is also used from the kernel's append file to identify the kernel + branch specific to a particular machine or target hardware. + The kernel's append file is located in the BSP layer for a given machine. + For example, the kernel append file for the Crown Bay BSP is in the + <code class="filename">meta-intel</code> Git repository and is named + <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.2.bbappend</code>. + Here are the related statements from the append file: + </p><pre class="literallayout"> + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/default/crownbay" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/default/crownbay" + </pre><p> + The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to + use when building for the Crown Bay BSP. + In this case there are two identical statements: one for each type of + Crown Bay machine. + </p></dd><dt><a id="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt><dd><p>Includes additional metadata from the Yocto Project kernel Git repository. + In the OpenEmbedded build system, the default Board Support Packages (BSPs) + metadata is provided through + the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables. + You can use the <code class="filename">KERNEL_FEATURES</code> variable to further + add metadata for all BSPs.</p><p>The metadata you add through this variable includes config fragments and + features descriptions, + which usually includes patches as well as config fragments. + You typically override the <code class="filename">KERNEL_FEATURES</code> variable + for a specific machine. + In this way, you can provide validated, but optional, sets of kernel + configurations and features.</p><p>For example, the following adds <code class="filename">netfilter</code> to all + the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code> + machine: + </p><pre class="literallayout"> + # Add netfilter to all linux-yocto kernels + KERNEL_FEATURES="features/netfilter" + + # Add sound support to the qemux86 machine + KERNEL_FEATURES_append_qemux86="cfg/sound" + </pre></dd><dt><a id="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the + machine configuration files and defaults to "zImage". + This variable is used + when building the kernel and is passed to <code class="filename">make</code> as the target to + build.</p></dd><dt><a id="var-KMACHINE"></a>KMACHINE</dt><dd><p> + The machine as known by the kernel. + Sometimes the machine name used by the kernel does not match the machine name + used by the OpenEmbedded build system. + For example, the machine name that the OpenEmbedded build system understands as + <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel. + The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>. + For cases like these, the <code class="filename">KMACHINE</code> variable maps the + kernel machine name to the OpenEmbedded build system machine name. + </p><p> + Kernel machine names are initially defined in the + <a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a> in + the <code class="filename">meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</code> file. + For example, in the <code class="filename">linux-yocto-3.4</code> kernel in the + <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file, + has the following: + </p><pre class="literallayout"> + define KMACHINE cedartrail + define KTYPE standard + define KARCH i386 + + include ktypes/standard + branch cedartrail + + include cedartrail.scc + </pre><p> + You can see that the kernel understands the machine name for the Cedar Trail BSP as + <code class="filename">cedartrail</code>. + </p><p> + If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source + repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>, + you will find the following statements among others: + </p><pre class="literallayout"> + COMPATIBLE_MACHINE_cedartrail = "cedartrail" + KMACHINE_cedartrail = "cedartrail" + KBRANCH_cedartrail = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" + KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" + + COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" + KMACHINE_cedartrail-nopvr = "cedartrail" + KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" + </pre><p> + The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that + the OpenEmbedded build system and the Yocto Linux kernel understand the same machine + names. + </p><p> + This append file uses two <code class="filename">KMACHINE</code> statements. + The first is not really necessary but does ensure that the machine known to the + OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine + in the kernel also known as <code class="filename">cedartrail</code>: + </p><pre class="literallayout"> + KMACHINE_cedartrail = "cedartrail" + </pre><p> + </p><p> + The second statement is a good example of why the <code class="filename">KMACHINE</code> variable + is needed. + In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code> + machine name to refer to the Cedar Trail BSP that does not support the propriatory + PowerVR driver. + The kernel, however, uses the machine name <code class="filename">cedartrail</code>. + Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to + the kernel's <code class="filename">cedartrail</code> name: + </p><pre class="literallayout"> + KMACHINE_cedartrail-nopvr = "cedartrail" + </pre><p> + </p><p> + BSPs that ship with the Yocto Project release provide all mappings between the Yocto + Project kernel machine names and the OpenEmbedded machine names. + Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine + name you use is different than that used in the kernel. + </p></dd></dl></div><div class="glossdiv" title="L"><h3 class="title">L</h3><dl><dt><a id="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt><dd><p>Lists the layers that this recipe depends upon, separated by spaces. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" + to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case). + An error will be produced if any dependency is missing or + the version numbers do not match exactly (if specified). + This variable is used in the <code class="filename">conf/layer.conf</code> file + and must be suffixed with the name of the specific layer (e.g. + <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd><dt><a id="var-LAYERDIR"></a>LAYERDIR</dt><dd><p>When used inside the <code class="filename">layer.conf</code> configuration + file, this variable provides the path of the current layer. + This variable requires immediate expansion + (see the BitBake manual) as lazy expansion can result in + the expansion happening in the wrong directory and therefore + giving the wrong value.</p></dd><dt><a id="var-LAYERVERSION"></a>LAYERVERSION</dt><dd><p>Optionally specifies the version of a layer as a single number. + You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to + depend on a specific version of the layer. + This variable is used in the <code class="filename">conf/layer.conf</code> file + and must be suffixed with the name of the specific layer (e.g. + <code class="filename">LAYERVERSION_mylayer</code>).</p></dd><dt><a id="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt><dd><p>Checksums of the license text in the recipe source code.</p><p>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.</p><p> + This variable must be defined for all recipes (unless <code class="filename">LICENSE</code> + is set to "CLOSED")</p><p>For more information, see the + <a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" title="3.4.1. Tracking License Changes"> + Tracking License Changes</a> section</p></dd><dt><a id="var-LICENSE"></a>LICENSE</dt><dd><p>The list of package source licenses.</p></dd><dt><a id="var-LICENSE_DIR"></a>LICENSE_DIR</dt><dd><p>Path to additional licenses used during the build. + By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code> + to define the directory that holds common license text used during the build. + The <code class="filename">LICENSE_DIR</code> variable allows you to extend that + location to other areas that have additional licenses: + </p><pre class="literallayout"> + LICENSE_DIR += "/path/to/additional/common/licenses" + </pre></dd></dl></div><div class="glossdiv" title="M"><h3 class="title">M</h3><dl><dt><a id="var-MACHINE"></a>MACHINE</dt><dd><p>Specifies the target device.</p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt><dd><p></p><p> + A list of required packages to install as part of the package being + built. + The build process depends on these packages being present. + Furthermore, because this is a "machine essential" variable, the list of + packages are essential for the machine to boot. + The impact of this variable affects images based on <code class="filename">task-core-boot</code>, + including the <code class="filename">core-image-minimal</code> image. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code> + variable with the exception that the package being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </p><p> + For example, suppose you are building a runtime package that depends + on a certain disk driver. + In this case, you would use the following: + </p><pre class="literallayout"> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "<disk_driver>" + </pre><p> + </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt><dd><p></p><p> + A list of recommended packages to install as part of the package being + built. + The build process does not depend on these packages being present. + Furthermore, because this is a "machine essential" variable, the list of + packages are essential for the machine to boot. + The impact of this variable affects images based on <code class="filename">task-core-boot</code>, + including the <code class="filename">core-image-minimal</code> image. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS</a></code> + variable with the exception that the package being built does not have a build + dependency on the variable's list of packages. + In other words, the image will build if a file in this list is not found. + However, because this is one of the "essential" variables, the resulting image + might not boot on the machine. + Or, if the machine does boot using the image, the machine might not be fully + functional. + </p><p> + Consider an example where you have a custom kernel with a disk driver + built into the kernel itself, rather than using the driver built as a module. + If you include the package that has the driver module as part of + the variable's list, the + build process will not find that package. + However, because these packages are "recommends" packages, the build will + not fail due to the missing package. + Not accounting for any other problems, the custom kernel would still boot the machine. + </p><p> + Some example packages of these machine essentials are flash, screen, keyboard, mouse, + or touchscreen drivers (depending on the machine). + </p><p> + For example, suppose you are building a runtime package that depends + on a mouse driver. + In this case, you would use the following: + </p><pre class="literallayout"> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "<mouse_driver>" + </pre><p> + </p></dd><dt><a id="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p> + A list of optional but non-machine essential packages to install as + part of the package being built. + Even though these packages are not essential for the machine to boot, + the build process depends on them being present. + The impact of this variable affects all images based on + <code class="filename">task-base</code>, which does not include the + <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> + images. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code> + variable with the exception that the package being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </p><p> + An example is a machine that might or might not have a WiFi card. + The package containing the WiFi support is not essential for the + machine to boot the image. + If it is not there, the machine will boot but not be able to use the + WiFi functionality. + However, if you include the package with the WiFi support as part of the + variable's package list, the build + process depends on finding the package. + In this case, you would use the following: + </p><pre class="literallayout"> + MACHINE_EXTRA_RDEPENDS += "<wifi_driver>" + </pre><p> + </p></dd><dt><a id="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt><dd><p></p><p> + A list of optional but non-machine essential packages to install as + part of the package being built. + The package being built has no build dependency on the list of packages + with this variable. + The impact of this variable affects only images based on + <code class="filename">task-base</code>, which does not include the + <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> + images. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code> + variable with the exception that the package being built does not have a build + dependency on the variable's list of packages. + In other words, the image will build if a file in this list is not found. + </p><p> + An example is a machine that might or might not have a WiFi card. + The package containing the WiFi support is not essential for the + machine to boot the image. + If it is not there, the machine will boot but not be able to use the + WiFi functionality. + You are free to either include or not include the + the package with the WiFi support as part of the + variable's package list, the build + process does not depend on finding the package. + If you include the package, you would use the following: + </p><pre class="literallayout"> + MACHINE_EXTRA_RRECOMMENDS += "<wifi_driver>" + </pre><p> + </p></dd><dt><a id="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>Specifies the list of device features. + See the <a class="link" href="#ref-features-machine" title="8.2. Machine">Machine</a> section for + more information.</p></dd><dt><a id="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>The email address of the distribution maintainer.</p></dd></dl></div><div class="glossdiv" title="P"><h3 class="title">P</h3><dl><dt><a id="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>The architecture of the resulting package.</p></dd><dt><a id="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>This variable, which is set in the <code class="filename">local.conf</code> configuration + file found in the <code class="filename">conf</code> folder of the + <a class="link" href="#source-directory" target="_top">source directory</a>, + specifies the package manager to use when packaging data. + You can provide one or more arguments for the variable with the first + argument being the package manager used to create images: + </p><pre class="literallayout"> + PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" + </pre><p> + For information on build performance effects as a result of the + package manager use, see + <a class="link" href="#ref-classes-package" title="6.12. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a> + in this manual. + </p></dd><dt><a id="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>Specifies the list of architectures compatible with the device CPU. + This variable is useful when you build for several different devices that use + miscellaneous processors such as XScale and ARM926-EJS).</p></dd><dt><a id="var-PACKAGES"></a>PACKAGES</dt><dd><p>The list of packages to be created from the recipe. + The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev".</p></dd><dt><a id="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt><dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the + compile tasks. + This variable is usually in the form <code class="filename">-j 4</code>, where the number + represents the maximum number of parallel threads make can run. + If you development host supports multiple cores a good rule of thumb is to set + this variable to twice the number of cores on the host.</p></dd><dt><a id="var-PN"></a>PN</dt><dd><p>The name of the package. + </p></dd><dt><a id="var-PR"></a>PR</dt><dd><p>The revision of the package. + The default value for this variable is "r0". + </p></dd><dt><a id="var-PV"></a>PV</dt><dd><p>The version of the package. + The version is normally extracted from the recipe name. + For example, if the recipe is named + <code class="filename">expat_2.0.1.bb</code>, then <code class="filename">PV</code> + will be <code class="filename">2.0.1</code>. + <code class="filename">PV</code> is generally not overridden within + a recipe unless it is building an unstable version from a source code repository + (e.g. Git or Subversion). + </p></dd><dt><a id="var-PE"></a>PE</dt><dd><p> + the epoch of the package. + The default value is "0". + The field is used to make upgrades possible when the versioning scheme changes in + some backwards incompatible way. + </p></dd><dt><a id="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p> + If multiple recipes provide an item, this variable + determines which recipe should be given preference. + The variable must always be suffixed with the name of the + provided item, and should be set to the + <code class="filename">$PN</code> of the recipe + to which you want to give precedence. + Here is an example: + </p><pre class="literallayout"> + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + </pre><p> + </p></dd><dt><a id="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p> + If there are multiple versions of recipes available, this + variable determines which recipe should be given preference. + The variable must always be suffixed with the <code class="filename">$PN</code> + for which to select, and should be set to the + <code class="filename">$PV</code> to which you want to give precedence. + You can use the "<code class="filename">%</code>" character as a wildcard + to match any number of characters, which can be useful when + specifying versions that contain long revision number that could + potentially change. + Here are two examples: + </p><pre class="literallayout"> + PREFERRED_VERSION_python = "2.6.6" + PREFERRED_VERSION_linux-yocto = "3.0+git%" + </pre><p> + </p></dd></dl></div><div class="glossdiv" title="R"><h3 class="title">R</h3><dl><dt><a id="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>The list of packages that conflict with this package. + Note that the package will not be installed if the conflicting packages are not + first removed.</p></dd><dt><a id="var-RDEPENDS"></a>RDEPENDS</dt><dd><p> + A list of packages that must be installed as part of a package being built. + The package being built has a runtime dependency on the packages in the + variable's list. + In other words, in order for the package being built to run correctly, + it depends on these listed packages. + If a package in this list cannot be found during the build, the build + will not complete. + </p><p> + Because the <code class="filename">RDEPENDS</code> variable applies to packages + being built, you should + always attach an override to the variable to specify the particular runtime package + that has the dependency. + For example, suppose you are building a development package that depends + on the <code class="filename">perl</code> package. + In this case, you would use the following <code class="filename">RDEPENDS</code> + statement: + </p><pre class="literallayout"> + RDEPENDS_${PN}-dev += "perl" + </pre><p> + In the example, the package name (<code class="filename">${PN}-dev</code>) must + appear as it would in the + <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any + renaming of the output package by classes like <code class="filename">debian.bbclass</code>. + </p><p> + Some automatic handling occurs around the <code class="filename">RDEPENDS</code> + variable: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If a runtime + package contains a shared library (<code class="filename">.so</code>), the build + processes the library in order to determine other libraries to which it + is dynamically linked. + The build process adds these libraries to <code class="filename">RDEPENDS</code> + to create the runtime package.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If the package + ships a <code class="filename">pkg-config</code> information file, the build process + uses this file to add items to the <code class="filename">RDEPENDS</code> + variable to create the runtime packages. + </p></li></ul></div><p> + </p></dd><dt><a id="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p> + A list of packages that extend the usability of a package being + built. + The package being built does not depend on this list of packages in + order to successfully build, but needs them for the extended usability. + To specify runtime dependencies for packages, see the + <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable. + </p><p> + The OpenEmbedded build process automatically installs the list of packages + as part of the built package. + However, you can remove them later if you want. + If, during the build, a package from the list cannot be found, the build + process continues without an error. + </p><p> + Because the <code class="filename">RRECOMMENDS</code> variable applies to packages + being built, you should + always attach an override to the variable to specify the particular package + whose usability is being extended. + For example, suppose you are building a development package that is extended + to support wireless functionality. + In this case, you would use the following: + </p><pre class="literallayout"> + RRECOMMENDS_${PN}-dev += "<wireless_package_name>" + </pre><p> + In the example, the package name (<code class="filename">${PN}-dev</code>) must + appear as it would in the + <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any + renaming of the output package by classes like <code class="filename">debian.bbclass</code>. + </p></dd><dt><a id="var-RREPLACES"></a>RREPLACES</dt><dd><p>The list of packages that are replaced with this package.</p></dd></dl></div><div class="glossdiv" title="S"><h3 class="title">S</h3><dl><dt><a id="var-S"></a>S</dt><dd><p> + The location in the <a class="link" href="#build-directory" target="_top">build directory</a> + where unpacked package source code resides. + This location is within the working directory + (<code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which + is not static. + The unpacked source location depends on the package name + (<code class="filename"><a class="link" href="#var-PN" title="PN">PN</a></code>) and + package version (<code class="filename"><a class="link" href="#var-PV" title="PV">PV</a></code>) as + follows: + </p><pre class="literallayout"> + ${WORKDIR}/${PN}-${PV} + </pre><p> + As an example, assume a + <a class="link" href="#source-directory" target="_top">source directory</a> top-level + folder named <code class="filename">poky</code> + and a default <a class="link" href="#build-directory" target="_top">build directory</a> + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">db</code> package is the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19 + </pre><p> + </p></dd><dt><a id="var-SECTION"></a>SECTION</dt><dd><p>The section where package should be put. + Package managers use this variable.</p></dd><dt><a id="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p> + The variable takes the value of + <code class="filename"><a class="link" href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code> + unless <code class="filename"><a class="link" href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1". + In this case the value of + <code class="filename"><a class="link" href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used. + </p></dd><dt><a id="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>The speed and device for the serial port used to attach the serial console. + This variable is given to the kernel as the "console" + parameter and after booting occurs <code class="filename">getty</code> is started on that port + so remote login is possible.</p></dd><dt><a id="var-SSTATE_DIR"></a>SSTATE_DIR</dt><dd><p>The directory for the shared state.</p></dd><dt><a id="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt><dd><p> + Specifies the endian byte order of the target system. + The variable is either "le" for little-endian or "be" for big-endian. + </p></dd><dt><a id="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p> + Specifies the number of bits for the target system CPU. + The variable is either "32" or "64". + </p></dd><dt><a id="var-SRC_URI"></a>SRC_URI</dt><dd><p>The list of source files - local or remote.</p></dd><dt><a id="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p></p><p> + By default, the OpenEmbedded build system automatically detects whether + <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> + contains files that are machine-specific. + If so, the build system automatically changes + <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>. + Setting this variable to "0" disables this behavior. + </p></dd><dt><a id="var-SRCDATE"></a>SRCDATE</dt><dd><p> + 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). + </p></dd><dt><a id="var-SRCREV"></a>SRCREV</dt><dd><p> + The revision of the source code used to build the package. + This variable applies to Subversion, Git, Mercurial and Bazaar + only. + Note that if you wish to build a fixed revision and you wish + to avoid performing a query on the remote repository every time + BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a + full revision identifier and not just a tag. + </p></dd><dt><a id="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p> + The directory with kernel headers that are required to build out-of-tree + modules. + </p></dd><dt><a id="var-STAMP"></a>STAMP</dt><dd><p> + The directory (usually <code class="filename">TMPDIR/stamps</code>) with timestamps of + executed tasks. + </p></dd><dt><a id="var-SUMMARY"></a>SUMMARY</dt><dd><p>The short (72 characters or less) summary of the binary package for packaging + systems such as <code class="filename">ipkg</code>, <code class="filename">rpm</code> or + <code class="filename">debian</code>. + By default, this variable inherits <code class="filename">DESCRIPTION</code>.</p></dd></dl></div><div class="glossdiv" title="T"><h3 class="title">T</h3><dl><dt><a id="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device being built. + While a number of values are possible, the OpenEmbedded build system primarily supports + <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd><dt><a id="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p> + Flags passed to the C compiler for the target system. + This variable evaluates to the same as + <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>. + </p></dd><dt><a id="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Specifies the method for handling FPU code. + For FPU-less targets, which include most ARM CPUs, the variable must be + set to "soft". + If not, the kernel emulation gets used, which results in a performance penalty.</p></dd><dt><a id="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Specifies the target's operating system. + The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and + to "linux-uclibc" for <code class="filename">uclibc</code>. + For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-uclibc-gnueabi" values possible.</p></dd><dt><a id="var-TCLIBC"></a>TCLIBC</dt><dd><p> + Specifies which variant of the GNU standard C library (<code class="filename">libc</code>) + to use during the build process. + This variable replaces <code class="filename">POKYLIBC</code>, which is no longer + supported. + </p><p> + You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + This release of the Yocto Project does not support the + <code class="filename">glibc</code> implementation of <code class="filename">libc</code>. + </div><p> + </p></dd><dt><a id="var-TCMODE"></a>TCMODE</dt><dd><p> + The toolchain selector. + This variable replaces <code class="filename">POKYMODE</code>, which is no longer + supported. + </p><p> + The <code class="filename">TCMODE</code> variable selects the external toolchain + built using the OpenEmbedded build system or a few supported combinations of + the upstream GCC or CodeSourcery Labs toolchain. + The variable determines which of the <code class="filename">tcmode-*</code> files in + the <code class="filename">meta/conf/distro/include</code> directory, which is found in the + <a class="link" href="#source-directory" target="_top">source directory</a>, + is used. + </p><p> + By default, <code class="filename">TCMODE</code> is set to "default", which + chooses the <code class="filename">tcmode-default.inc</code> file. + The variable is similar to + <a class="link" href="#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls + the variant of the GNU standard C library (<code class="filename">libc</code>) + used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. + </p></dd><dt><a id="var-TMPDIR"></a>TMPDIR</dt><dd><p> + This variable is the temporary directory the OpenEmbedded build system + uses when it does its work building images. + By default, the <code class="filename">TMPDIR</code> variable is named + <code class="filename">tmp</code> within the + <a class="link" href="#build-directory" target="_top">build directory</a>. + </p><p> + If you want to establish this directory in a location other than the + default, you can uncomment the following statement in the + <code class="filename">conf/local.conf</code> file in the + <a class="link" href="#source-directory" target="_top">source directory</a>: + </p><pre class="literallayout"> + #TMPDIR = "${TOPDIR}/tmp" + </pre><p> + </p></dd><dt><a id="var-TOPDIR"></a>TOPDIR</dt><dd><p> + This variable is the + <a class="link" href="#build-directory" target="_top">build directory</a>. + BitBake automatically sets this variable. + The OpenEmbedded build system uses the build directory when building images. + </p></dd></dl></div><div class="glossdiv" title="W"><h3 class="title">W</h3><dl><dt><a id="var-WORKDIR"></a>WORKDIR</dt><dd><p> + The pathname of the working directory in which the OpenEmbedded build system + builds packages. + This directory is located within the + <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes + as different packages are built. + </p><p> + The actual <code class="filename">WORKDIR</code> directory depends on several things: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The temporary directory - <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a></li><li class="listitem">The package architecture - <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH"><code class="filename">PACKAGE_ARCH</code></a></li><li class="listitem">The target machine - <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a></li><li class="listitem">The target operating system - <a class="link" href="#var-TARGET_OS" title="TARGET_OS"><code class="filename">TARGET_OS</code></a></li><li class="listitem">The package name - <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a></li><li class="listitem">The package version - <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a></li><li class="listitem">The package revision - <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a></li></ul></div><p> + </p><p> + For packages that are not dependent on a particular machine, + <code class="filename">WORKDIR</code> is defined as follows: + </p><pre class="literallayout"> + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + </pre><p> + As an example, assume a + <a class="link" href="#source-directory" target="_top">source directory</a> top-level + folder name <code class="filename">poky</code> and a default + <a class="link" href="#build-directory" target="_top">build directory</a> + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">v86d</code> package is the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0 + </pre><p> + </p><p> + For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code> + is defined slightly different: + </p><pre class="literallayout"> + ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + </pre><p> + As an example, again assume a source directory top-level folder + named <code class="filename">poky</code> and a default build directory + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">acl</code> package, which is dependent on a + MIPS-based device, is the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 + </pre><p> + </p></dd></dl></div></div></div> + + <div class="chapter" title="Chapter 10. Variable Context"><div class="titlepage"><div><div><h2 class="title"><a id="ref-varlocality"></a>Chapter 10. Variable Context</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#ref-varlocality-configuration">10.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">10.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">10.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">10.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">10.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">10.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">10.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">10.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">10.2.4. Extra Build Information</a></span></dt></dl></dd></dl></div><p> + While most variables can be used in almost any context such as + <code class="filename">.conf</code>, <code class="filename">.bbclass</code>, + <code class="filename">.inc</code>, and <code class="filename">.bb</code> files, + some variables are often associated with a particular locality or context. + This chapter describes some common associations. + </p><div class="section" title="10.1. Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-configuration"></a>10.1. Configuration</h2></div></div></div><p> + The following subsections provide lists of variables whose context is + configuration: distribution, machine, and local. + </p><div class="section" title="10.1.1. Distribution (Distro)"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-distro"></a>10.1.1. Distribution (Distro)</h3></div></div></div><p> + This section lists variables whose context is the distribution, or distro. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCLIBC" title="TCLIBC">TCLIBC</a></code> + </p></li></ul></div><p> + </p></div><div class="section" title="10.1.2. Machine"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-machine"></a>10.1.2. Machine</h3></div></div></div><p> + This section lists variables whose context is the machine. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li></ul></div><p> + </p></div><div class="section" title="10.1.3. Local"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-local"></a>10.1.3. Local</h3></div></div></div><p> + This section lists variables whose context is the local configuration through the + <code class="filename">local.conf</code> file. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION"> + ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li></ul></div><p> + </p></div></div><div class="section" title="10.2. Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-recipes"></a>10.2. Recipes</h2></div></div></div><p> + The following subsections provide lists of variables whose context is + recipes: required, dependencies, path, and extra build information. + </p><div class="section" title="10.2.1. Required"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-required"></a>10.2.1. Required</h3></div></div></div><p> + This section lists variables that are required for recipes. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DESCRIPTION" title="DESCRIPTION">DESCRIPTION</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SECTION" title="SECTION">SECTION</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">HOMEPAGE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-AUTHOR" title="AUTHOR">AUTHOR</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a> + </code></p></li></ul></div><p> + </p></div><div class="section" title="10.2.2. Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-dependencies"></a>10.2.2. Dependencies</h3></div></div></div><p> + This section lists variables that define recipe dependencies. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RREPLACES" title="RREPLACES">RREPLACES</a> + </code></p></li></ul></div><p> + </p></div><div class="section" title="10.2.3. Paths"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-paths"></a>10.2.3. Paths</h3></div></div></div><p> + This section lists variables that define recipe paths. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-S" title="S">S</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a> + </code></p></li></ul></div><p> + </p></div><div class="section" title="10.2.4. Extra Build Information"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-build"></a>10.2.4. Extra Build Information</h3></div></div></div><p> + This section lists variables that define extra build information for recipes. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_PN_ALIAS" title="DISTRO_PN_ALIAS">DISTRO_PN_ALIAS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE + </a></code></p></li></ul></div><p> + </p></div></div></div> + + <div class="chapter" title="Chapter 11. FAQ"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Chapter 11. FAQ</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><a id="id1519542"></a><table border="0" width="100%" summary="Q and A Set"><col align="left" width="1%" /><col /><tbody><tr class="question" title="11.1."><td align="left" valign="top"><a id="id1519546"></a><a id="id1519547"></a><p><b>11.1.</b></p></td><td align="left" valign="top"><p> + How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The term "Poky" is sometimes used to refer to the build system that the + Yocto Project uses. + The build system used in the Yocto project is referred to as the + OpenEmbedded build system because "Poky" was derived from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>. + Poky is a stable, smaller subset focused on the mobile environment. + Development in the Yocto Project using Poky is closely tied to OpenEmbedded with + features being merged regularly between the two for mutual benefit. + For a fuller description of the term "Poky", see the + <a class="link" href="#poky" target="_top">poky</a> term in the Yocto Project + Development Manual. + </p></td></tr><tr class="question" title="11.2."><td align="left" valign="top"><a id="id1519579"></a><a id="id1519580"></a><p><b>11.2.</b></p></td><td align="left" valign="top"><p> + I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. + Can I still use the Yocto Project? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You can use a stand-alone tarball to provide Python 2.6. + You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2" target="_top">32-bit tarball</a></p></li><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2" target="_top">64-bit tarball</a></p></li></ul></div><p> + </p><p> + These tarballs are self-contained with all required libraries and should work + on most Linux systems. + To use the tarballs extract them into the root + directory and run the appropriate command: + </p><pre class="literallayout"> + $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH + $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH + </pre><p> + </p><p> + Once you run the command, BitBake uses Python 2.6. + </p></td></tr><tr class="question" title="11.3."><td align="left" valign="top"><a id="id1519623"></a><a id="id1519624"></a><p><b>11.3.</b></p></td><td align="left" valign="top"><p> + How can you claim Poky is stable? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + There are three areas that help with stability; + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Yocto Project team keeps + <a class="link" href="#poky" target="_top">Poky</a> small and focused. + It contains around 650 packages as compared to over 5000 for full + OpenEmbedded.</p></li><li class="listitem"><p>The Yocto Project only supports hardware that the + team has access to for testing.</p></li><li class="listitem"><p>The Yocto Project uses an an autobuilder, + which provides continuous build and integration tests.</p></li></ul></div><p> + </p></td></tr><tr class="question" title="11.4."><td align="left" valign="top"><a id="id1519656"></a><a id="id1519657"></a><p><b>11.4.</b></p></td><td align="left" valign="top"><p> + How do I get support for my board added to the Yocto Project? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + There are two main ways to get a board supported in the Yocto Project; + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Send the Yocto Project team information on the board + and if the team does not have it yet they will consider adding it.</p></li><li class="listitem"><p>Send the Yocto Project team the BitBake recipes if you have them. + </p></li></ul></div><p> + Usually, if the board is not completely exotic, adding support in + the Yocto Project is fairly straightforward. + </p></td></tr><tr class="question" title="11.5."><td align="left" valign="top"><a id="id1519678"></a><a id="id1519679"></a><p><b>11.5.</b></p></td><td align="left" valign="top"><p> + Are there any products using the OpenEmbedded build system (poky)? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The <a class="ulink" href="http://vernier.com/labquest/" target="_top">Vernier LabQuest</a> is using + the OpenEmbedded build system. + See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_top">Vernier LabQuest</a> + for more information. + There are a number of pre-production devices using the OpenEmbedded build system + and the Yocto Project team + announces them as soon as they are released. + </p></td></tr><tr class="question" title="11.6."><td align="left" valign="top"><a id="id1519700"></a><a id="id1519702"></a><p><b>11.6.</b></p></td><td align="left" valign="top"><p> + What does the OpenEmbedded build system produce as output? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Because the same set of recipes can be used to create output of various formats, the + output of an OpenEmbedded build depends on how it was started. + Usually, the output is a flashable image ready for the target device. + </p></td></tr><tr class="question" title="11.7."><td align="left" valign="top"><a id="id1519711"></a><a id="id1519712"></a><p><b>11.7.</b></p></td><td align="left" valign="top"><p> + How do I add my package to the Yocto Project? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + To add a package, you need to create a BitBake recipe. + For information on how to add a package, see the section + "<a class="link" href="#usingpoky-extend-addpkg" target="_top">Adding a Package</a>" + in the Yocto Project Development Manual. + </p></td></tr><tr class="question" title="11.8."><td align="left" valign="top"><a id="id1519726"></a><a id="id1519727"></a><p><b>11.8.</b></p></td><td align="left" valign="top"><p> + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The OpenEmbedded build system can build packages in various formats such as + <code class="filename">ipk</code> for <code class="filename">ipkg</code>/<code class="filename">opkg</code>, + Debian package (<code class="filename">.deb</code>), or RPM. + The packages can then be upgraded using the package tools on the device, much like + on a desktop distribution such as Ubuntu or Fedora. + </p></td></tr><tr class="question" title="11.9."><td align="left" valign="top"><a id="id1519761"></a><a id="id1519762"></a><p><b>11.9.</b></p></td><td align="left" valign="top"><p> + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_top">GNOME</a> + platform targeted at mobile and embedded devices. + The the main difference between GNOME Mobile and standard GNOME is that + desktop-orientated libraries have been removed, along with deprecated libraries, + creating a much smaller footprint. + </p></td></tr><tr class="question" title="11.10."><td align="left" valign="top"><a id="id1519778"></a><a id="id1519780"></a><p><b>11.10.</b></p></td><td align="left" valign="top"><p> + I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'. + What is wrong? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You are probably running the build on an NTFS filesystem. + Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead. + </p></td></tr><tr class="question" title="11.11."><td align="left" valign="top"><a id="id1519811"></a><a id="id1519812"></a><p><b>11.11.</b></p></td><td align="left" valign="top"><p> + How do I make the Yocto Project work in RHEL/CentOS? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + To get the Yocto Project working under RHEL/CentOS 5.1 you need to first + install some required packages. + The standard CentOS packages needed are: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>"Development tools" (selected during installation)</p></li><li class="listitem"><p><code class="filename">texi2html</code></p></li><li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li></ul></div><p> + On top of these, you need the following external packages: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">python-sqlite2</code> from + <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG repository</a> + </p></li><li class="listitem"><p><code class="filename">help2man</code> from + <a class="ulink" href="http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html" target="_top">Karan repository</a></p></li></ul></div><p> + </p><p> + Once these packages are installed, the OpenEmbedded build system will be able + to build standard images. + However, there might be a problem with the QEMU emulator segfaulting. + You can either disable the generation of binary locales by setting + <code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a> + </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code> + from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. + </p></td></tr><tr class="question" title="11.12."><td align="left" valign="top"><a id="id1519899"></a><a id="id1519900"></a><p><b>11.12.</b></p></td><td align="left" valign="top"><p> + I see lots of 404 responses for files on + <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Nothing is wrong. + The OpenEmbedded build system checks any configured source mirrors before downloading + from the upstream sources. + The build system does this searching for both source archives and + pre-checked out versions of SCM managed software. + These checks help in large installations because it can reduce load on the SCM servers + themselves. + The address above is one of the default mirrors configured into the + build system. + Consequently, if an upstream source disappears, the team + can place sources there so builds continue to work. + </p></td></tr><tr class="question" title="11.13."><td align="left" valign="top"><a id="id1519919"></a><a id="id1519920"></a><p><b>11.13.</b></p></td><td align="left" valign="top"><p> + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Set <code class="filename"><a class="link" href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a> + </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is + manually marked as + machine-specific in the case that needs it. + The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>. + </p></td></tr><tr class="question" title="11.14."><td align="left" valign="top"><a id="id1519958"></a><a id="id1519959"></a><p><b>11.14.</b></p></td><td align="left" valign="top"><p> + I'm behind a firewall and need to use a proxy server. How do I do that? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code> + and you therefore need to specify the proxy settings in a + <code class="filename">.wgetrc</code> file in your home directory. + Example settings in that file would be + </p><pre class="literallayout"> + http_proxy = http://proxy.yoyodyne.com:18023/ + ftp_proxy = http://proxy.yoyodyne.com:18023/ + </pre><p> + The Yocto Project also includes a <code class="filename">site.conf.sample</code> + file that shows how to configure CVS and Git proxy servers + if needed. + </p></td></tr><tr class="question" title="11.15."><td align="left" valign="top"><a id="id1519996"></a><a id="id1519997"></a><p><b>11.15.</b></p></td><td align="left" valign="top"><p> + I'm using Ubuntu Intrepid and am seeing build failures. What’s wrong? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + In Intrepid, Ubuntu turns on by default the normally optional compile-time security features + and warnings. + There are more details at + <a class="ulink" href="https://wiki.ubuntu.com/CompilerFlags" target="_top">https://wiki.ubuntu.com/CompilerFlags</a>. + You can work around this problem by disabling those options by adding + the following to the <code class="filename">BUILD_CPPFLAGS</code> variable in the + <code class="filename">conf/bitbake.conf</code> file. + </p><pre class="literallayout"> + " -Wno-format-security -U_FORTIFY_SOURCE" + </pre><p> + </p></td></tr><tr class="question" title="11.16."><td align="left" valign="top"><a id="id1520034"></a><a id="id1520035"></a><p><b>11.16.</b></p></td><td align="left" valign="top"><p> + What’s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The <code class="filename">*-native</code> targets are designed to run on the system + being used for the build. + These are usually tools that are needed to assist the build in some way such as + <code class="filename">quilt-native</code>, which is used to apply patches. + The non-native version is the one that runs on the target device. + </p></td></tr><tr class="question" title="11.17."><td align="left" valign="top"><a id="id1520068"></a><a id="id1520070"></a><p><b>11.17.</b></p></td><td align="left" valign="top"><p> + I'm seeing random build failures. Help?! + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + If the same build is failing in totally different and random ways, + the most likely explanation is that either the hardware you're running the + build on has some problem, or, if you are running the build under virtualisation, + the virtualisation probably has bugs. + The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and + CPU activity and is sensitive to even single bit failures in any of these areas. + True random failures have always been traced back to hardware or virtualisation issues. + </p></td></tr><tr class="question" title="11.18."><td align="left" valign="top"><a id="id1520082"></a><a id="id1520083"></a><p><b>11.18.</b></p></td><td align="left" valign="top"><p> + What do we need to ship for license compliance? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + This is a difficult question and you need to consult your lawyer for the answer + for your specific case. + It is worth bearing in mind that for GPL compliance there needs to be enough + information shipped to allow someone else to rebuild the same end result + you are shipping. + This means sharing the source code, any patches applied to it, and also any + configuration information about how that package was configured and built. + </p></td></tr><tr class="question" title="11.19."><td align="left" valign="top"><a id="id1520094"></a><a id="id1520095"></a><p><b>11.19.</b></p></td><td align="left" valign="top"><p> + How do I disable the cursor on my touchscreen device? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You need to create a form factor file as described in the + "<a class="link" href="#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>" + section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows: + </p><pre class="literallayout"> + HAVE_TOUCHSCREEN=1 + </pre><p> + </p></td></tr><tr class="question" title="11.20."><td align="left" valign="top"><a id="id1520125"></a><a id="id1520126"></a><p><b>11.20.</b></p></td><td align="left" valign="top"><p> + How do I make sure connected network interfaces are brought up by default? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The default interfaces file provided by the netbase recipe does not + automatically bring up network interfaces. + Therefore, you will need to add a BSP-specific netbase that includes an interfaces + file. + See the "<a class="link" href="#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>" + section for information on creating these types of miscellaneous recipe files. + </p><p> + For example, add the following files to your layer: + </p><pre class="literallayout"> + meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces + meta-MACHINE/recipes-bsp/netbase/netbase_4.44.bbappend + </pre><p> + </p></td></tr><tr class="question" title="11.21."><td align="left" valign="top"><a id="id1520156"></a><a id="id1520157"></a><p><b>11.21.</b></p></td><td align="left" valign="top"><p> + How do I create images with more free space? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Images are created to be 1.2 times the size of the populated root filesystem. + To modify this ratio so that there is more free space available, you need to + set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>. + For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets + the image size ratio to one and a half times the size of the populated + root filesystem. + </p><pre class="literallayout"> + IMAGE_OVERHEAD_FACTOR = "1.5" + </pre><p> + </p></td></tr><tr class="question" title="11.22."><td align="left" valign="top"><a id="id1520188"></a><a id="id1520190"></a><p><b>11.22.</b></p></td><td align="left" valign="top"><p> + Why don't you support directories with spaces in the pathnames? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The Yocto Project team has tried to do this before but too many of the tools + the OpenEmbedded build system depends on such as <code class="filename">autoconf</code> + break when they find spaces in pathnames. + Until that situation changes, the team will not support spaces in pathnames. + </p></td></tr><tr class="question" title="11.23."><td align="left" valign="top"><a id="id1520206"></a><a id="id1520207"></a><p><b>11.23.</b></p></td><td align="left" valign="top"><p> + How do I use an external toolchain? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The toolchain configuration is very flexible and customizable. + It is primarily controlled with the + <code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> variable. + This variable controls which <code class="filename">tcmode-*.inc</code> file to include + from the <code class="filename">meta/conf/distro/include</code> directory within the + <a class="link" href="#source-directory" target="_top">source directory</a>. + </p><p> + The default value of <code class="filename">TCMODE</code> is "default" + (i.e. <code class="filename">tcmode-default.inc</code>). + However, other patterns are accepted. + In particular, "external-*" refers to external toolchains of which there are some + basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>). + You can use your own custom toolchain definition in your own layer + (or as defined in the <code class="filename">local.conf</code> file) at the location + <code class="filename">conf/distro/include/tcmode-*.inc</code>. + </p><p> + In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. + This recipe file needs to package up any pre-built objects in the toolchain such as + <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>, + any locales, and <code class="filename">libc</code>. + An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located + in <code class="filename">meta/recipes-core/meta/</code> within the source directory. + </p></td></tr><tr class="question" title="11.24."><td align="left" valign="top"><a id="id1520281"></a><a id="id1520316"></a><p><b>11.24.</b></p></td><td align="left" valign="top"><p><a id="how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server"></a> + How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The way the build system obtains source code is highly configurable. + You can setup the build system to get source code in most environments if + HTTP transport is available. + </p><p> + When the build system searches for source code, it first tries the local download directory. + If that location fails, Poky tries PREMIRRORS, the upstream source, + and then MIRRORS in that order. + </p><p> + By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS + for SCM-based sources, + upstreams for normal tarballs, and then falls back to a number of other mirrors + including the Yocto Project source mirror if those fail. + </p><p> + As an example, you could add a specific server for Poky to attempt before any + others by adding something like the following to the <code class="filename">local.conf</code> + configuration file: + </p><pre class="literallayout"> + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + </pre><p> + </p><p> + These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS + requests and direct them to the <code class="filename">http://</code> sources mirror. + You can use <code class="filename">file://</code> URLs to point to local directories + or network shares as well. + </p><p> + Aside from the previous technique, these options also exist: + </p><pre class="literallayout"> + BB_NO_NETWORK = "1" + </pre><p> + This statement tells BitBake to throw an error instead of trying to access the + Internet. + This technique is useful if you want to ensure code builds only from local sources. + </p><p> + Here is another technique: + </p><pre class="literallayout"> + BB_FETCH_PREMIRRORONLY = "1" + </pre><p> + This statement limits Poky to pulling source from the PREMIRRORS only. + Again, this technique is useful for reproducing builds. + </p><p> + Here is another technique: + </p><pre class="literallayout"> + BB_GENERATE_MIRROR_TARBALLS = "1" + </pre><p> + This statement tells Poky to generate mirror tarballs. + This technique is useful if you want to create a mirror server. + If not, however, the technique can simply waste time during the build. + </p><p> + Finally, consider an example where you are behind an HTTP-only firewall. + You could make the following changes to the <code class="filename">local.conf</code> + configuration file as long as the PREMIRROR server is up to date: + </p><pre class="literallayout"> + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + BB_FETCH_PREMIRRORONLY = "1" + </pre><p> + These changes would cause Poky to successfully fetch source over HTTP and + any network accesses to anything other than the PREMIRROR would fail. + </p><p> + The build system also honors the standard shell environment variables + <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>, + <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code> + to redirect requests through proxy servers. + </p></td></tr><tr class="question" title="11.25."><td align="left" valign="top"><a id="id1520463"></a><a id="id1520464"></a><p><b>11.25.</b></p></td><td align="left" valign="top"><p> + Can I get rid of build output so I can start over? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Yes - you can easily do this. + When you use BitBake to build an image, all the build output goes into the + directory created when you source the <code class="filename">oe-init-build-env</code> + setup file. + By default, this <a class="link" href="#build-directory" target="_top">build directory</a> + is named <code class="filename">build</code> but can be named + anything you want. + </p><p> + Within the build directory is the <code class="filename">tmp</code> directory. + To remove all the build output yet preserve any source code or downloaded files + from previous builds, simply remove the <code class="filename">tmp</code> directory. + </p></td></tr></tbody></table></div></div> + + <div class="chapter" title="Chapter 12. Contributing to the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="resources"></a>Chapter 12. Contributing to the Yocto Project</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#resources-intro">12.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">12.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">12.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">12.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">12.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">12.6. Contributions</a></span></dt></dl></div><div class="section" title="12.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-intro"></a>12.1. Introduction</h2></div></div></div><p> + The Yocto Project team is happy for people to experiment with the Yocto Project. + A number of places exist to find help if you run into difficulties or find bugs. + To find out how to download source code, + see the "<a class="link" href="#local-yp-release" target="_top">Yocto Project Release</a>" + list item in the Yocto Project Development Manual. + </p></div><div class="section" title="12.2. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-bugtracker"></a>12.2. Tracking Bugs</h2></div></div></div><p> + If you find problems with the Yocto Project, you should report them using the + Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>. + </p></div><div class="section" title="12.3. Mailing lists"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-mailinglist"></a>12.3. Mailing lists</h2></div></div></div><p> + There are a number of mailing lists maintained by the Yocto Project as well as + related OpenEmbedded mailing lists for discussion, patch submission and announcements. + To subscribe to one of the following mailing lists, click on the appropriate URL + in the following list and follow the instructions: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> - + General Yocto Project discussion mailing list. </p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core</a> - + Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel</a> - + Discussion mailing list about OpenEmbedded.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel</a> - + Discussion mailing list about the BitBake build tool.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> - + Discussion mailing list about Poky.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> - + Mailing list to receive official Yocto Project release and milestone + announcements.</p></li></ul></div><p> + </p></div><div class="section" title="12.4. Internet Relay Chat (IRC)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-irc"></a>12.4. Internet Relay Chat (IRC)</h2></div></div></div><p> + Two IRC channels on freenode are available for the Yocto Project and Poky discussions: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">#yocto</code></p></li><li class="listitem"><p><code class="filename">#poky</code></p></li></ul></div><p> + </p></div><div class="section" title="12.5. Links"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-links"></a>12.5. Links</h2></div></div></div><p> + Following is a list of resources you will find helpful: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_top">The Yocto Project website</a>: + </em></span> The home site for the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span> + The company who acquired OpenedHand in 2008 and began development on the + Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span> + The upstream, generic, embedded distribution used as the basis for the build system in the + Yocto Project. + Poky derives from and contributes back to the OpenEmbedded project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top"> + BitBake</a>:</em></span> The tool used to process metadata.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://docs.openembedded.org/bitbake/html/" target="_top"> + BitBake User Manual</a>:</em></span> A comprehensive guide to the BitBake tool. + </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>: + </em></span> An open source machine emulator and virtualizer.</p></li></ul></div><p> + </p></div><div class="section" title="12.6. Contributions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-contributions"></a>12.6. Contributions</h2></div></div></div><p> + The Yocto Project gladly accepts contributions. + You can submit changes to the project either by creating and sending pull requests, + or by submitting patches through email. + For information on how to do both, see the + "<a class="link" href="#how-to-submit-a-change" target="_top">How to Submit a Change</a>" + section in the Yocto Project Development Manual. + </p></div></div> + + + +</div> + + + +</div></body></html> |