summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/mega-manual/mega-manual.html12646
-rw-r--r--documentation/mega-manual/mega-manual.tgzbin1155592 -> 0 bytes
2 files changed, 0 insertions, 12646 deletions
diff --git a/documentation/mega-manual/mega-manual.html b/documentation/mega-manual/mega-manual.html
deleted file mode 100644
index 1b4419f3b9..0000000000
--- a/documentation/mega-manual/mega-manual.html
+++ /dev/null
@@ -1,12646 +0,0 @@
-<?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&amp;action=historysubmit&amp;diff=4309&amp;okdid=4225" target="_top">OE and Your Distro</a> and
- <a class="ulink" href="http://www.openembedded.org/index.php?title=Required_software&amp;action=historysubmit&amp;diff=4311&amp;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-&lt;<span class="emphasis"><em>host_system</em></span>&gt;-&lt;<span class="emphasis"><em>arch</em></span>&gt;-toolchain-gmae-&lt;<span class="emphasis"><em>release</em></span>&gt;.tar.bz2
-
- Where:
- &lt;<span class="emphasis"><em>host_system</em></span>&gt; is a string representing your development system:
- i686 or x86_64.
-
- &lt;<span class="emphasis"><em>arch</em></span>&gt; is a string representing the target architecture:
- i586, x86_64, powerpc, mips, or arm.
-
- &lt;<span class="emphasis"><em>release</em></span>&gt; 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&lt;<span class="emphasis"><em>arch</em></span>&gt;.bin
- vmlinux-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.bin
-
- Where:
- &lt;<span class="emphasis"><em>arch</em></span>&gt; 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-&lt;<span class="emphasis"><em>profile</em></span>&gt;-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.ext3
- core-image-&lt;<span class="emphasis"><em>profile</em></span>&gt;-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.tar.bz2
-
- Where:
- &lt;<span class="emphasis"><em>profile</em></span>&gt; 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.
-
- &lt;<span class="emphasis"><em>arch</em></span>&gt; 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-&lt;<span class="emphasis"><em>arch</em></span>&gt;-poky-linux-&lt;<span class="emphasis"><em>if</em></span>&gt;
-
- Where:
- &lt;<span class="emphasis"><em>arch</em></span>&gt; is a string representing the target architecture:
- i586, x86_64, ppc603e, mips, or armv5te.
-
- &lt;<span class="emphasis"><em>if</em></span>&gt; 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 &lt;<span class="emphasis"><em>qemuarch</em></span>&gt; &lt;<span class="emphasis"><em>kernel-image</em></span>&gt; &lt;<span class="emphasis"><em>filesystem-image</em></span>&gt;
-
- Where:
- &lt;<span class="emphasis"><em>qemuarch</em></span>&gt; is a string representing the target architecture: qemux86, qemux86-64,
- qemuppc, qemumips, or qemuarm.
-
- &lt;<span class="emphasis"><em>kernel-image</em></span>&gt; is the architecture-specific kernel image.
-
- &lt;<span class="emphasis"><em>filesystem-image</em></span>&gt; 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">&lt;<a class="email" href="mailto:scott.m.rifenbark@intel.com">scott.m.rifenbark@intel.com</a>&gt;</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 &amp; 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-&lt;BSP_name&gt;
- </pre><p>
- where &lt;BSP_name&gt; 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 &lt;branch-name&gt;</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 &lt;working-branch&gt;</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 &lt;branch-name&gt;</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 &lt;branch-name&gt;.</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 #&lt;bug-id&gt;]
-
- &lt;detailed description of change&gt;
- </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-&lt;layer_name&gt;</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 &lt;command&gt; [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/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</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" &gt;&gt; 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-&lt;PN&gt; = "${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/&lt;host-arch&gt;/usr/bin/&lt;target-abi&gt;-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/&lt;target-abi&gt;/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/&lt;target-abi&gt;/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/&lt;target-abi&gt;/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">
- $ &lt;target-abi&gt;-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/&lt;machine-name&gt;/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-&lt;release&gt;-&lt;date&gt;-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 -&gt; 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 ‘&lt;-m 256 -full-screen&gt;’
- </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 -&gt; New -&gt; 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 -&gt; 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 -&gt; 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 -&gt; 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 -&gt; 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 -&gt; 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/&lt;programname&gt;</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 -&gt; Open Perspective -&gt; 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 -&gt; New -&gt; Project</code>.</p></li><li class="listitem"><p>Choose <code class="filename">LTTng -&gt; LTTng Project</code>.</p></li><li class="listitem"><p>Click <code class="filename">YoctoTools -&gt; 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 -&gt; Open Perspective -&gt; 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 -&gt; New -&gt; Project</code> to create a new Yocto
- Bitbake Commander project.</p></li><li class="listitem"><p>Choose <code class="filename">Yocto Project Bitbake Commander -&gt; 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">&lt;project_location&gt;/&lt;project_name&gt;</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 -&gt; New -&gt; Yocto BitBake Commander -&gt; 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 -&gt; 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 &lt;name_of_package&gt;
- </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 &lt;name_of_package&gt;
- </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-&lt;name&gt;</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 &lt;target&gt;'
-
- 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 &lt;target&gt;'
-
- 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">&lt;<a class="email" href="mailto:jessica.zhang@intel.com">jessica.zhang@intel.com</a>&gt;</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 &amp; 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_&lt;arch&gt;</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_&lt;arch&gt;</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_&lt;arch&gt;</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_&lt;arch&gt;</code>
- to "minimal sato-sdk", then <code class="filename">YOCTOADT_ROOTFS_&lt;arch&gt;</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_&lt;arch&gt;</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_&lt;arch&gt;</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">&lt;sysroot_dir&gt;</code>.
- Finally, have an OPKG configuration file <code class="filename">&lt;conf_file&gt;</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 &lt;conf_file&gt; -o &lt;sysroot_dir&gt; update
- $ opkg-cl –f &lt;cconf_file&gt; -o &lt;sysroot_dir&gt; \
- --force-overwrite install libglade
- $ opkg-cl –f &lt;cconf_file&gt; -o &lt;sysroot_dir&gt; \
- --force-overwrite install libglade-dbg
- $ opkg-cl –f &lt;conf_file&gt; -o &lt;sysroot_dir&gt; \
- --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=&lt;sysroot-dir&gt;
- </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=&lt;sysroot-dir&gt;</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 &lt;dir_containing_your_project-specific_m4_macros&gt;]
- $ 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=&lt;sysroot-dir&gt;”
- CXXFLAGS=”${CXXFLAGS} --sysroot=&lt;sysroot-dir&gt;”
- </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">&lt;<a class="email" href="mailto:tom.zanussi@intel.com">tom.zanussi@intel.com</a>&gt;</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">&lt;<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>&gt;</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 &amp; 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-&lt;bsp_name&gt;
- </pre><p>
- "bsp_name" is a placeholder for the machine or platform name.
- </p><p>
- The layer's base directory (<code class="filename">meta-&lt;bsp_name&gt;</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-&lt;bsp_name&gt; \
- "
- </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-&lt;bsp_name&gt;/
- meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
- meta-&lt;bsp_name&gt;/README
- meta-&lt;bsp_name&gt;/README.sources
- meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
- meta-&lt;bsp_name&gt;/conf/layer.conf
- meta-&lt;bsp_name&gt;/conf/machine/*.conf
- meta-&lt;bsp_name&gt;/recipes-bsp/*
- meta-&lt;bsp_name&gt;/recipes-core/*
- meta-&lt;bsp_name&gt;/recipes-graphics/*
- meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.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-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
- </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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
- </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-&lt;bsp_name&gt;/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">&lt;bsp_name&gt;</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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/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-&lt;bsp_name&gt;/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">&lt;bsp_name&gt;.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-&lt;bsp_name&gt;</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-&lt;bsp_name&gt;</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-&lt;bsp_name&gt;</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-&lt;bsp_name&gt;</code> directory.
- This file identifies the <code class="filename">meta-&lt;bsp_name&gt;</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/&lt;bsp_name&gt;.conf</code>
- in the <code class="filename">meta-&lt;bsp_name&gt;</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-&lt;bsp_name&gt;</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=&amp;download_type=1&amp;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 &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
- [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
-
- 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 &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
- [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
-
- 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 =&gt; [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">&lt;<a class="email" href="mailto:bruce.ashfield@windriver.com">bruce.ashfield@windriver.com</a>&gt;</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 &amp; 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">
- &lt;bsp_name&gt;-&lt;kernel_type&gt;.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">
- &lt;kernel_type&gt;/&lt;bsp_name&gt;
- </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}-&lt;kernel_type&gt;-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">&lt;commit&gt;..&lt;commit&gt;</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 &lt;tag&gt;</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 &lt;tag&gt;</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 &lt;msg&gt;
- 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 &lt;path&gt;/file
- # stage the change
- $ git add &lt;path&gt;/file
- # commit the change
- $ git commit -s
- # remove a file
- $ git rm &lt;path&gt;/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 &lt;path&gt;/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">
- # &lt;first-commit&gt; 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 &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
- </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 &lt;save dir&gt; &lt;tag&gt;
-
- # If no tags are available
- $ git format-patch -o &lt;save dir&gt; HEAD^ # last commit
- $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
- $ git whatchanged # identify last commit
- $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
- $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
- </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://&lt;master_server&gt;/&lt;path_to_repo&gt;
- &lt;local_branch&gt;:&lt;remote_branch&gt;
- </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] &lt;patch series summary&gt;' \
- --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 &gt; .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 &gt; .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. &quot;-dirty&quot; 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">&lt;<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>&gt;</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 &amp; 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" colspa