path: root/documentation/mega-manual
diff options
authorScott Rifenbark <>2012-08-27 14:19:12 (GMT)
committerRichard Purdie <>2012-09-04 11:55:01 (GMT)
commitd9b2ceeea3c8dc8d4437679621d8ee87cdc56b55 (patch)
tree702d5775c58d75d149cd4dff96a887d736cc693f /documentation/mega-manual
parente4bb6b7be871b2a205e5a42dc9c9b1a340c9c0b5 (diff)
documentation/mega-manual: New mega-manual directory
This new directory contains the files for the mega-manual HTML document. Mega-manual is a compilation of all the existing YP manuals and guides. It is a single HTML file that simply lists each individual HTML document for the existing YP manuals and guides. The figures directory contains all the figures (duplicated) from the individual manuals and guides. (From yocto-docs rev: 5620c20ea4c7c69c96601b7480471e6166fd9409) Signed-off-by: Scott Rifenbark <> Signed-off-by: Richard Purdie <>
Diffstat (limited to 'documentation/mega-manual')
-rw-r--r--documentation/mega-manual/figures/adt-title.pngbin0 -> 13498 bytes
-rw-r--r--documentation/mega-manual/figures/app-dev-flow.pngbin0 -> 52670 bytes
-rw-r--r--documentation/mega-manual/figures/bsp-dev-flow.pngbin0 -> 57479 bytes
-rw-r--r--documentation/mega-manual/figures/bsp-title.pngbin0 -> 17388 bytes
-rwxr-xr-xdocumentation/mega-manual/figures/building-an-image.pngbin0 -> 14891 bytes
-rw-r--r--documentation/mega-manual/figures/dev-title.pngbin0 -> 11813 bytes
-rw-r--r--documentation/mega-manual/figures/git-workflow.pngbin0 -> 26610 bytes
-rw-r--r--documentation/mega-manual/figures/index-downloads.pngbin0 -> 58263 bytes
-rwxr-xr-xdocumentation/mega-manual/figures/kernel-architecture-overview.pngbin0 -> 40748 bytes
-rw-r--r--documentation/mega-manual/figures/kernel-dev-flow.pngbin0 -> 61916 bytes
-rw-r--r--documentation/mega-manual/figures/kernel-example-repos-denzil.pngbin0 -> 34344 bytes
-rw-r--r--documentation/mega-manual/figures/kernel-overview-1.pngbin0 -> 35839 bytes
-rw-r--r--documentation/mega-manual/figures/kernel-overview-2.pngbin0 -> 34013 bytes
-rw-r--r--documentation/mega-manual/figures/kernel-overview-3-denzil.pngbin0 -> 42285 bytes
-rw-r--r--documentation/mega-manual/figures/kernel-title.pngbin0 -> 13970 bytes
-rw-r--r--documentation/mega-manual/figures/poky-title.pngbin0 -> 11592 bytes
-rw-r--r--documentation/mega-manual/figures/source-repos.pngbin0 -> 188986 bytes
-rw-r--r--documentation/mega-manual/figures/using-a-pre-built-image.pngbin0 -> 12733 bytes
-rw-r--r--documentation/mega-manual/figures/wip.pngbin0 -> 35309 bytes
-rw-r--r--documentation/mega-manual/figures/yocto-environment.pngbin0 -> 73095 bytes
-rwxr-xr-xdocumentation/mega-manual/figures/yocto-project-transp.pngbin0 -> 8626 bytes
-rw-r--r--documentation/mega-manual/figures/yp-download.pngbin0 -> 118882 bytes
-rw-r--r--documentation/mega-manual/mega-manual.tgzbin0 -> 1155592 bytes
27 files changed, 13681 insertions, 0 deletions
diff --git a/documentation/mega-manual/figures/adt-title.png b/documentation/mega-manual/figures/adt-title.png
new file mode 100644
index 0000000..6e71e41
--- /dev/null
+++ b/documentation/mega-manual/figures/adt-title.png
Binary files differ
diff --git a/documentation/mega-manual/figures/app-dev-flow.png b/documentation/mega-manual/figures/app-dev-flow.png
new file mode 100644
index 0000000..4927b93
--- /dev/null
+++ b/documentation/mega-manual/figures/app-dev-flow.png
Binary files differ
diff --git a/documentation/mega-manual/figures/bsp-dev-flow.png b/documentation/mega-manual/figures/bsp-dev-flow.png
new file mode 100644
index 0000000..b20ee19
--- /dev/null
+++ b/documentation/mega-manual/figures/bsp-dev-flow.png
Binary files differ
diff --git a/documentation/mega-manual/figures/bsp-title.png b/documentation/mega-manual/figures/bsp-title.png
new file mode 100644
index 0000000..f624dd4
--- /dev/null
+++ b/documentation/mega-manual/figures/bsp-title.png
Binary files differ
diff --git a/documentation/mega-manual/figures/building-an-image.png b/documentation/mega-manual/figures/building-an-image.png
new file mode 100755
index 0000000..1fbea5a
--- /dev/null
+++ b/documentation/mega-manual/figures/building-an-image.png
Binary files differ
diff --git a/documentation/mega-manual/figures/dev-title.png b/documentation/mega-manual/figures/dev-title.png
new file mode 100644
index 0000000..d3cac4a
--- /dev/null
+++ b/documentation/mega-manual/figures/dev-title.png
Binary files differ
diff --git a/documentation/mega-manual/figures/git-workflow.png b/documentation/mega-manual/figures/git-workflow.png
new file mode 100644
index 0000000..4fdf42f
--- /dev/null
+++ b/documentation/mega-manual/figures/git-workflow.png
Binary files differ
diff --git a/documentation/mega-manual/figures/index-downloads.png b/documentation/mega-manual/figures/index-downloads.png
new file mode 100644
index 0000000..c907997
--- /dev/null
+++ b/documentation/mega-manual/figures/index-downloads.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-architecture-overview.png b/documentation/mega-manual/figures/kernel-architecture-overview.png
new file mode 100755
index 0000000..2aad172
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-architecture-overview.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-dev-flow.png b/documentation/mega-manual/figures/kernel-dev-flow.png
new file mode 100644
index 0000000..f200af6
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-dev-flow.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-example-repos-denzil.png b/documentation/mega-manual/figures/kernel-example-repos-denzil.png
new file mode 100644
index 0000000..79fc606
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-example-repos-denzil.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-overview-1.png b/documentation/mega-manual/figures/kernel-overview-1.png
new file mode 100644
index 0000000..116c0b9
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-overview-1.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-overview-2.png b/documentation/mega-manual/figures/kernel-overview-2.png
new file mode 100644
index 0000000..5fee847
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-overview-2.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-overview-3-denzil.png b/documentation/mega-manual/figures/kernel-overview-3-denzil.png
new file mode 100644
index 0000000..5f2ea05
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-overview-3-denzil.png
Binary files differ
diff --git a/documentation/mega-manual/figures/kernel-title.png b/documentation/mega-manual/figures/kernel-title.png
new file mode 100644
index 0000000..59d86c0
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-title.png
Binary files differ
diff --git a/documentation/mega-manual/figures/poky-title.png b/documentation/mega-manual/figures/poky-title.png
new file mode 100644
index 0000000..2893d84
--- /dev/null
+++ b/documentation/mega-manual/figures/poky-title.png
Binary files differ
diff --git a/documentation/mega-manual/figures/source-repos.png b/documentation/mega-manual/figures/source-repos.png
new file mode 100644
index 0000000..65c5f29
--- /dev/null
+++ b/documentation/mega-manual/figures/source-repos.png
Binary files differ
diff --git a/documentation/mega-manual/figures/using-a-pre-built-image.png b/documentation/mega-manual/figures/using-a-pre-built-image.png
new file mode 100644
index 0000000..b03130d
--- /dev/null
+++ b/documentation/mega-manual/figures/using-a-pre-built-image.png
Binary files differ
diff --git a/documentation/mega-manual/figures/wip.png b/documentation/mega-manual/figures/wip.png
new file mode 100644
index 0000000..8811637
--- /dev/null
+++ b/documentation/mega-manual/figures/wip.png
Binary files differ
diff --git a/documentation/mega-manual/figures/yocto-environment.png b/documentation/mega-manual/figures/yocto-environment.png
new file mode 100644
index 0000000..82b7a55
--- /dev/null
+++ b/documentation/mega-manual/figures/yocto-environment.png
Binary files differ
diff --git a/documentation/mega-manual/figures/yocto-project-transp.png b/documentation/mega-manual/figures/yocto-project-transp.png
new file mode 100755
index 0000000..31d2b14
--- /dev/null
+++ b/documentation/mega-manual/figures/yocto-project-transp.png
Binary files differ
diff --git a/documentation/mega-manual/figures/yp-download.png b/documentation/mega-manual/figures/yp-download.png
new file mode 100644
index 0000000..a10b2e2
--- /dev/null
+++ b/documentation/mega-manual/figures/yp-download.png
Binary files differ
diff --git a/documentation/mega-manual/mega-manual-customization.xsl b/documentation/mega-manual/mega-manual-customization.xsl
new file mode 100644
index 0000000..3be182d
--- /dev/null
+++ b/documentation/mega-manual/mega-manual-customization.xsl
@@ -0,0 +1,8 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="" xmlns="" xmlns:fo="" version="1.0">
4 <xsl:import href="" />
6 <xsl:param name="generate.toc" select="'chapter toc'"></xsl:param>
diff --git a/documentation/mega-manual/mega-manual.html b/documentation/mega-manual/mega-manual.html
new file mode 100644
index 0000000..1b4419f
--- /dev/null
+++ b/documentation/mega-manual/mega-manual.html
@@ -0,0 +1,12646 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
3<html xmlns=""><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>
5 <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>
6 Welcome to the Yocto Project!
7 The Yocto Project is an open-source collaboration project focused on embedded Linux
8 developers.
9 Among other things, the Yocto Project uses a build system based on the Poky project
10 to construct complete Linux images.
11 The Poky project, in turn, draws from and contributes back to the OpenEmbedded project.
12 </p><p>
13 If you don't have a system that runs Linux and you want to give the Yocto Project a test run,
14 you might consider using the Yocto Project Build Appliance.
15 The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto
16 Project using a non-Linux development system.
17 See the <a class="ulink" href="" target="_top">Yocto
18 Project Build Appliance</a> for more information.
19 </p><p>
20 On the other hand, if you know all about open-source development, Linux development environments,
21 Git source repositories and the like and you just want some quick information that lets you try out
22 the Yocto Project on your Linux system, skip right to the
23 "<a class="link" href="#super-user" title="6. Super User">Super User</a>" section at the end of this quick start.
24 </p><p>
25 For the rest of you, this short document will give you some basic information about the environment and
26 let you experience it in its simplest form.
27 After reading this document, you will have a basic understanding of what the Yocto Project is
28 and how to use some of its core components.
29 This document steps you through a simple example showing you how to build a small image
30 and run it using the Quick EMUlator (QEMU emulator).
31 </p><p>
32 For more detailed information on the Yocto Project, you should check out these resources:
33 </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="" target="_top">Yocto Project Website</a>
34 provides the latest builds, breaking news, full development documentation, and a rich Yocto
35 Project Development Community into which you can tap.
36 </p></li><li class="listitem"><p><span class="emphasis"><em>FAQs:</em></span> Lists commonly asked Yocto Project questions and answers.
37 You can find two FAQs: <a class="ulink" href="" target="_top">Yocto Project FAQ</a> on
38 a wiki, and the
39 <a class="link" href="#faq" target="_top">FAQ</a> chapter in
40 the Yocto Project Reference Manual.
41 </p></li><li class="listitem"><p><span class="emphasis"><em>Developer Screencast:</em></span> The
42 <a class="ulink" href="" target="_top">Getting Started with the Yocto Project - New
43 Developer Screencast Tutorial</a> provides a 30-minute video for the user
44 new to the Yocto Project but familiar with Linux build systems.</p></li></ul></div><p>
45 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
46 Due to production processes, there could be differences between the Yocto Project
47 documentation bundled in a released tarball and the
48 Yocto Project Quick Start on
49 the <a class="ulink" href="" target="_top">Yocto Project</a> website.
50 For the latest version of this manual, see the manual on the website.
51 </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>
52 The Yocto Project through the OpenEmbedded build system provides an open source development
53 environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of
54 platforms including x86-64 and emulated ones.
55 You can use components from the Yocto Project to design, develop, build, debug, simulate,
56 and test the complete software stack using Linux, the X Window System, GNOME Mobile-based
57 application frameworks, and Qt frameworks.
58 </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>
59 Here are some highlights for the Yocto Project:
60 </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,
61 GuPNP and Qt (among others) so you can create a richer user interface experience on
62 devices that use displays or have a GUI.
63 For devices that don't have a GUI or display, you simply would not employ these
64 components.</p></li><li class="listitem"><p>Creates a focused and stable core compatible with the OpenEmbedded
65 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
66 Emulator.</p></li></ul></div><p>
67 The Yocto Project can generate images for many kinds of devices.
68 However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS,
69 and PPC-based architectures as well as specific hardware such as the
70 <span class="trademark">Intel</span>® Desktop Board DH55TC.
71 Because an image developed with the Yocto Project can boot inside a QEMU emulator, the
72 development environment works nicely as a test platform for developing embedded software.
73 </p><p>
74 Another important Yocto Project feature is the Sato reference User Interface.
75 This optional GNOME mobile-based UI, which is intended for devices with
76 restricted screen sizes, sits neatly on top of a device using the
77 GNOME Mobile Stack and provides a well-defined user experience.
78 Implemented in its own layer, it makes it clear to developers how they can implement
79 their own user interface on top of a Linux image created with the Yocto Project.
80 </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>
81 You need these things to develop in the Yocto Project environment:
82 </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
83 Fedora, openSUSE, CentOS, and Ubuntu).
84 If the host system supports multiple cores and threads, you can configure the
85 Yocto Project build system to decrease the time needed to build images
86 significantly.
87 </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>
88 The Yocto Project team is continually verifying more and more Linux
89 distributions with each release.
90 In general, if you have the current release minus one of the following
91 distributions you should have no problems.
92 </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>
93 For a list of the distributions under validation and their status, see the
94 <a class="ulink" href="" target="_top">Distribution
95 Support</a> wiki page.
96 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
97 For notes about using the Yocto Project on a RHEL 4-based host, see the
98 <a class="ulink" href="" target="_top">BuildingOnRHEL4</a>
99 wiki page.
100 </div><p>
101 </p><p>
102 The OpenEmbedded build system should be able to run on any modern distribution with Python 2.6 or 2.7.
103 Earlier releases of Python are known to not work and the system does not support Python 3 at this time.
104 This document assumes you are running one of the previously noted distributions on your Linux-based
105 host systems.
106 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
107 If you attempt to use a distribution not in the above list, you may or may not have success - you
108 are venturing into untested territory.
109 Refer to
110 <a class="ulink" href=";action=historysubmit&amp;diff=4309&amp;okdid=4225" target="_top">OE and Your Distro</a> and
111 <a class="ulink" href=";action=historysubmit&amp;diff=4311&amp;oldid=4251" target="_top">Required Software</a>
112 for information for other distributions used with the OpenEmbedded project, which might be
113 a starting point for exploration.
114 If you go down this path, you should expect problems.
115 When you do, please go to <a class="ulink" href="" target="_top">Yocto Project Bugzilla</a>
116 and submit a bug.
117 We are interested in hearing about your experience.
118 </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>
119 Packages and package installation vary depending on your development system.
120 In general, you need to have root access and then install the required packages.
121 The next few sections show you how to get set up with the right packages for
122 Ubuntu, Fedora, openSUSE, and CentOS.
123 </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>
124 The packages you need for a supported Ubuntu distribution are shown in the following command:
125 </p><pre class="literallayout">
126 $ sudo apt-get install sed wget subversion git-core coreutils \
127 unzip texi2html texinfo libsdl1.2-dev docbook-utils fop gawk \
128 python-pysqlite2 diffstat make gcc build-essential xsltproc \
129 g++ desktop-file-utils chrpath libgl1-mesa-dev libglu1-mesa-dev \
130 autoconf automake groff libtool xterm libxml-parser-perl dblatex
131 </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>
132 The packages you need for a supported Fedora distribution are shown in the following
133 commands:
134 </p><pre class="literallayout">
135 $ sudo yum groupinstall "development tools"
136 $ sudo yum install python m4 make wget curl ftp tar bzip2 gzip \
137 unzip perl texinfo texi2html diffstat openjade \
138 docbook-style-dsssl sed docbook-style-xsl docbook-dtds fop libxslt \
139 docbook-utils sed bc eglibc-devel ccache pcre pcre-devel quilt \
140 groff linuxdoc-tools patch cmake \
141 perl-ExtUtils-MakeMaker tcl-devel gettext chrpath ncurses apr \
142 SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \
143 autoconf automake libtool xterm dblatex
144 </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>
145 The packages you need for a supported openSUSE distribution are shown in the following
146 command:
147 </p><pre class="literallayout">
148 $ sudo zypper install python gcc gcc-c++ libtool fop \
149 subversion git chrpath automake make wget xsltproc \
150 diffstat texinfo freeglut-devel libSDL-devel dblatex
151 </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>
152 The packages you need for a supported CentOS distribution are shown in the following
153 commands:
154 </p><pre class="literallayout">
155 $ sudo yum -y groupinstall "development tools"
156 $ sudo yum -y install tetex gawk sqlite-devel vim-common redhat-lsb xz \
157 m4 make wget curl ftp tar bzip2 gzip python-devel \
158 unzip perl texinfo texi2html diffstat openjade zlib-devel \
159 docbook-style-dsssl sed docbook-style-xsl docbook-dtds \
160 docbook-utils bc glibc-devel pcre pcre-devel \
161 groff linuxdoc-tools patch cmake \
162 tcl-devel gettext ncurses apr \
163 SDL-devel mesa-libGL-devel mesa-libGLU-devel gnome-doc-utils \
164 autoconf automake libtool xterm dblatex
165 </pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
166 Depending on the CentOS version you are using, other requirements and dependencies
167 might exist.
168 For details, you should look at the CentOS sections on the
169 <a class="ulink" href="" target="_top">Poky/GettingStarted/Dependencies</a>
170 wiki page.
171 </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>
172 You can download the latest Yocto Project release by going to the
173 <a class="ulink" href="" target="_top">Yocto Project Download page</a>.
174 Just go to the page and click the "Yocto Downloads" link found in the "Download"
175 navigation pane to the right to view all available Yocto Project releases.
176 Then, click the "Yocto Release" link for the release you want from the list to
177 begin the download.
178 Nightly and developmental builds are also maintained at
179 <a class="ulink" href="" target="_top"></a>.
180 However, for this document a released version of Yocto Project is used.
181 </p><p>
182 You can also get the Yocto Project files you need by setting up (cloning in Git terms)
183 a local copy of the <code class="filename">poky</code> Git repository on your host development
184 system.
185 Doing so allows you to contribute back to the Yocto Project project.
186 For information on how to get set up using this method, see the
187 "<a class="link" href="#local-yp-release" target="_top">Yocto
188 Project Release</a>" item in the Yocto Project Development Manual.
189 </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>
190 Now that you have your system requirements in order, you can give the Yocto Project a try.
191 This section presents some steps that let you do the following:
192 </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>
193 In the development environment you will need to build an image whenever you change hardware
194 support, add or change system libraries, or add or change services that have dependencies.
195 </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>
196 Use the following commands to build your image.
197 The OpenEmbedded build process creates an entire Linux distribution, including the toolchain,
198 from source.
199 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
200 The build process using Sato currently consumes about 50GB of disk space.
201 To allow for variations in the build process and for future package expansion, we
202 recommend having at least 100GB of free disk space.
203 </p></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
204 By default, the build process searches for source code using a pre-determined order
205 through a set of locations.
206 If you encounter problems with the build process finding and downloading source code, see the
207 "<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
208 firewall or proxy server?</a>" in the Yocto Project Reference Manual.
209 </p></div><p>
210 </p><pre class="literallayout">
211 $ wget
212 $ tar xjf poky-1.2+snapshot-8.0.tar.bz2
213 $ source poky-1.2+snapshot-8.0/oe-init-build-env poky-1.2+snapshot-8.0-build
214 </pre><p>
215 </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
216 To help conserve disk space during builds, you can add the following statement
217 to your project's configuration file, which for this example
218 is <code class="filename">poky-1.2+snapshot-8.0-build/conf/local.conf</code>.
219 Adding this statement deletes the work directory used for building a package
220 once the package is built.
221 </p><pre class="literallayout">
222 INHERIT += "rm_work"
223 </pre><p>
224 </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
225 release tarball from the source repositories using the
226 <code class="filename">wget</code> command.
227 Alternatively, you can go to the
228 <a class="ulink" href="" target="_top">Yocto Project website's Downloads page</a>
229 to retrieve the tarball.</p></li><li class="listitem"><p>The second command extracts the files from the tarball and places
230 them into a directory named <code class="filename">poky-1.2+snapshot-8.0</code> in the current
231 directory.</p></li><li class="listitem"><p>The third command runs the Yocto Project environment setup script.
232 Running this script defines OpenEmbedded build environment settings needed to
233 complete the build.
234 The script also creates the
235 <a class="link" href="#build-directory" target="_top">build directory</a>,
236 which is <code class="filename">poky-1.2+snapshot-8.0-build</code> in this case.
237 After the script runs, your current working directory is set
238 to the build directory.
239 Later, when the build completes, the build directory contains all the files
240 created during the build.
241 </p></li></ul></div><p>
242 Take some time to examine your <code class="filename">local.conf</code> file
243 in your project's configuration directory.
244 The defaults in that file should work fine.
245 However, there are some variables of interest at which you might look.
246 </p><p>
247 By default, the target architecture for the build is <code class="filename">qemux86</code>,
248 which produces an image that can be used in the QEMU emulator and is targeted at an
249 <span class="trademark">Intel</span>® 32-bit based architecture.
250 To change this default, edit the value of the <code class="filename">MACHINE</code> variable
251 in the configuration file before launching the build.
252 </p><p>
253 Another couple of variables of interest are the
254 <a class="link" href="#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a> and the
255 <a class="link" href="#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a> variables.
256 By default, these variables are commented out.
257 However, if you have a multi-core CPU you might want to uncomment
258 the lines and set both variables equal to twice the number of your
259 host's processor cores.
260 Setting these variables can significantly shorten your build time.
261 </p><p>
262 Another consideration before you build is the package manager used when creating
263 the image.
264 By default, the OpenEmbedded build system uses the RPM package manager.
265 You can control this configuration by using the
266 <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a></code> variable.
267 For additional package manager selection information, see
268 "<a class="link" href="#ref-classes-package" target="_top">Packaging - <code class="filename">package*.bbclass</code></a>"
269 in the Yocto Project Reference Manual.
270 </p><p>
271 Continue with the following command to build an OS image for the target, which is
272 <code class="filename">core-image-sato</code> in this example.
273 For information on the <code class="filename">-k</code> option use the
274 <code class="filename">bitbake --help</code> command or see the
275 "<a class="link" href="#usingpoky-components-bitbake" target="_top">BitBake</a>" section in
276 the Yocto Project Reference Manual.
277 </p><pre class="literallayout">
278 $ bitbake -k core-image-sato
279 </pre><p>
280 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
281 BitBake requires Python 2.6 or 2.7. For more information on this requirement,
282 see the
283 <a class="link" href="#faq" target="_top">FAQ</a> in the Yocto Project Reference
284 Manual.
285 </p></div><p>
286 The final command runs the image:
287 </p><pre class="literallayout">
288 $ runqemu qemux86
289 </pre><p>
290 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
291 Depending on the number of processors and cores, the amount or RAM, the speed of your
292 Internet connection and other factors, the build process could take several hours the first
293 time you run it.
294 Subsequent builds run much faster since parts of the build are cached.
295 </p></div><p>
296 </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>
297 If hardware, libraries and services are stable, you can get started by using a pre-built binary
298 of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
299 This scenario is useful for developing application software.
300 </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>
301 For this scenario, you need to do several things:
302 </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.
303 You need to be sure to get the QEMU image that matches your target machine’s
304 architecture (e.g. x86, ARM, etc.).</p></li><li class="listitem"><p>Download the filesystem image for your target machine's architecture.
305 </p></li><li class="listitem"><p>Set up the environment to emulate the hardware and then start the QEMU emulator.
306 </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>
307 You can download a tarball with the pre-built toolchain, which includes the
308 <code class="filename">runqemu</code>
309 script and support files, from the appropriate directory under
310 <a class="ulink" href="" target="_top"></a>.
311 Toolchains are available for 32-bit and 64-bit development systems from the
312 <code class="filename">i686</code> and <code class="filename">x86-64</code> directories, respectively.
313 Each type of development system supports five target architectures.
314 The names of the tarballs are such that a string representing the host system appears
315 first in the filename and then is immediately followed by a string representing
316 the target architecture.
317 </p><pre class="literallayout">
318 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
320 Where:
321 &lt;<span class="emphasis"><em>host_system</em></span>&gt; is a string representing your development system:
322 i686 or x86_64.
324 &lt;<span class="emphasis"><em>arch</em></span>&gt; is a string representing the target architecture:
325 i586, x86_64, powerpc, mips, or arm.
327 &lt;<span class="emphasis"><em>release</em></span>&gt; is the version of Yocto Project.
328 </pre><p>
329 For example, the following toolchain tarball is for a 64-bit development
330 host system and a 32-bit target architecture:
331 </p><pre class="literallayout">
332 poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2
333 </pre><p>
334 The toolchain tarballs are self-contained and must be installed into <code class="filename">/opt/poky</code>.
335 The following commands show how you install the toolchain tarball given a 64-bit development
336 host system and a 32-bit target architecture.
337 The example assumes the toolchain tarball is located in <code class="filename">~/toolchains/</code>.
338 You must have your working directory set to root before unpacking the tarball:
339 </p><p>
340 </p><pre class="literallayout">
341 $ cd /
342 $ sudo tar -xvjf ~/toolchains/poky-eglibc-x86_64-i586-toolchain-gmae-1.3.tar.bz2
343 </pre><p>
344 </p><p>
345 For more information on how to install tarballs, see the
346 "<a class="link" href="#using-an-existing-toolchain-tarball" target="_top">Using a Cross-Toolchain Tarball</a>" and
347 "<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.
348 </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>
349 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
350 <a class="ulink" href="" target="_top"></a>.
351 Be sure to use the kernel that matches the architecture you want to simulate.
352 Download areas exist for the five supported machine architectures:
353 <code class="filename">qemuarm</code>, <code class="filename">qemumips</code>, <code class="filename">qemuppc</code>,
354 <code class="filename">qemux86</code>, and <code class="filename">qemux86-64</code>.
355 </p><p>
356 Most kernel files have one of the following forms:
357 </p><pre class="literallayout">
358 *zImage-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.bin
359 vmlinux-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.bin
361 Where:
362 &lt;<span class="emphasis"><em>arch</em></span>&gt; is a string representing the target architecture:
363 x86, x86-64, ppc, mips, or arm.
364 </pre><p>
365 </p><p>
366 You can learn more about downloading a Yocto Project kernel in the
367 "<a class="link" href="#local-kernel-files" target="_top">Yocto Project Kernel</a>"
368 bulleted item in the Yocto Project Development Manual.
369 </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>
370 You can also download the filesystem image suitable for your target architecture from
371 <a class="ulink" href="" target="_top"></a>.
372 Again, be sure to use the filesystem that matches the architecture you want
373 to simulate.
374 </p><p>
375 The filesystem image has two tarball forms: <code class="filename">ext3</code> and
376 <code class="filename">tar</code>.
377 You must use the <code class="filename">ext3</code> form when booting an image using the
378 QEMU emulator.
379 The <code class="filename">tar</code> form can be flattened out in your host development system
380 and used for build purposes with the Yocto Project.
381 </p><pre class="literallayout">
382 core-image-&lt;<span class="emphasis"><em>profile</em></span>&gt;-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.ext3
383 core-image-&lt;<span class="emphasis"><em>profile</em></span>&gt;-qemu&lt;<span class="emphasis"><em>arch</em></span>&gt;.tar.bz2
385 Where:
386 &lt;<span class="emphasis"><em>profile</em></span>&gt; is the filesystem image's profile:
387 lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, sato-dev, or sato-sdk.
388 For information on these types of image profiles, see the
389 "<a class="link" href="#ref-images" target="_top">Images</a>" chapter
390 in the Yocto Project Reference Manual.
392 &lt;<span class="emphasis"><em>arch</em></span>&gt; is a string representing the target architecture:
393 x86, x86-64, ppc, mips, or arm.
394 </pre><p>
395 </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>
396 Before you start the QEMU emulator, you need to set up the emulation environment.
397 The following command form sets up the emulation environment.
398 </p><pre class="literallayout">
399 $ 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;
401 Where:
402 &lt;<span class="emphasis"><em>arch</em></span>&gt; is a string representing the target architecture:
403 i586, x86_64, ppc603e, mips, or armv5te.
405 &lt;<span class="emphasis"><em>if</em></span>&gt; is a string representing an embedded application binary interface.
406 Not all setup scripts include this string.
407 </pre><p>
408 </p><p>
409 Finally, this command form invokes the QEMU emulator
410 </p><pre class="literallayout">
411 $ 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;
413 Where:
414 &lt;<span class="emphasis"><em>qemuarch</em></span>&gt; is a string representing the target architecture: qemux86, qemux86-64,
415 qemuppc, qemumips, or qemuarm.
417 &lt;<span class="emphasis"><em>kernel-image</em></span>&gt; is the architecture-specific kernel image.
419 &lt;<span class="emphasis"><em>filesystem-image</em></span>&gt; is the .ext3 filesystem image.
421 </pre><p>
422 </p><p>
423 Continuing with the example, the following two commands setup the emulation
424 environment and launch QEMU.
425 This example assumes the root filesystem (<code class="filename">.ext3</code> file) and
426 the pre-built kernel image file both reside in your home directory.
427 The kernel and filesystem are for a 32-bit target architecture.
428 </p><pre class="literallayout">
429 $ cd $HOME
430 $ source /opt/poky/1.3/environment-setup-i586-poky-linux
431 $ runqemu qemux86 bzImage-qemux86.bin \
432 core-image-sato-qemux86.ext3
433 </pre><p>
434 </p><p>
435 The environment in which QEMU launches varies depending on the filesystem image and on the
436 target architecture.
437 For example, if you source the environment for the ARM target
438 architecture and then boot the minimal QEMU image, the emulator comes up in a new
439 shell in command-line mode.
440 However, if you boot the SDK image, QEMU comes up with a GUI.
441 </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
442 command-line mode.</div><p>
443 </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
445 This section
446 <sup>[<a id="id1482592" href="#ftn.id1482592" class="footnote">1</a>]</sup>
447 gives you a very fast description of how to use the Yocto Project to build images
448 for a BeagleBoard xM starting from scratch.
449 The steps were performed on a 64-bit Ubuntu 10.04 system.
450 </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>
451 Set up your <a class="link" href="#source-directory" target="_top">source directory</a>
452 one of two ways:
453 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Tarball:</em></span>
454 Use if you want the latest stable release:
455 </p><pre class="literallayout">
456 $ wget
457 $ tar xvjf poky-1.2+snapshot-8.0.tar.bz2
458 </pre></li><li class="listitem"><p><span class="emphasis"><em>Git Repository:</em></span>
459 Use if you want to work with cutting edge development content:
460 </p><pre class="literallayout">
461 $ git clone git://
462 </pre></li></ul></div><p>
463 The remainder of the section assumes the Git repository method.
464 </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>
465 You need some packages for everything to work.
466 Rather than duplicate them here, look at the "<a class="link" href="#packages" title="4.2. The Packages">The Packages</a>"
467 section earlier in this quick start.
468 </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>
469 From the parent directory of local source directory, initialize your environment
470 and provide a meaningful
471 <a class="link" href="#build-directory" target="_top">build directory</a>
472 name:
473 </p><pre class="literallayout">
474 $ source poky/oe-init-build-env mybuilds
475 </pre><p>
476 At this point, the <code class="filename">mybuilds</code> directory has been created for you
477 and it is now your current working directory.
478 If you don't provide your own directory name it defaults to <code class="filename">build</code>.
479 </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>
480 Initializing the build environment creates a <code class="filename">conf/local.conf</code> configuration file
481 in the build directory.
482 You need to manually edit this file to specify the machine you are building and to optimize
483 your build time.
484 Here are the minimal changes to make:
485 </p><pre class="literallayout">
487 PARALLEL_MAKE = "-j 8"
488 MACHINE ?= "beagleboard"
489 </pre><p>
490 Briefly, set <a class="link" href="#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a>
491 and <a class="link" href="#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a> to
492 twice your host processor's number of cores.
493 </p><p>
494 A good deal that goes into a Yocto Project build is simply downloading all of the source
495 tarballs.
496 Maybe you have been working with another build system (OpenEmbedded, Angstrom, etc) for which
497 you've built up a sizable directory of source tarballs.
498 Or perhaps someone else has such a directory for which you have read access.
499 If so, you can save time by adding the <code class="filename">PREMIRRORS</code>
500 statement to your configuration file so that local directories are first checked for existing
501 tarballs before running out to the net:
502 </p><pre class="literallayout">
503 PREMIRRORS_prepend = "\
504 git://.*/.* file:///home/you/dl/ \n \
505 svn://.*/.* file:///home/you/dl/ \n \
506 cvs://.*/.* file:///home/you/dl/ \n \
507 ftp://.*/.* file:///home/you/dl/ \n \
508 http://.*/.* file:///home/you/dl/ \n \
509 https://.*/.* file:///home/you/dl/ \n"
510 </pre><p>
511 </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>
512 At this point, you need to select an image to build for the BeagleBoard xM.
513 If this is your first build using the Yocto Project, you should try the smallest and simplest
514 image:
515 </p><pre class="literallayout">
516 $ bitbake core-image-minimal
517 </pre><p>
518 Now you just wait for the build to finish.
519 </p><p>
520 Here are some variations on the build process that could be helpful:
521 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Fetch all the necessary sources without starting the build:
522 </p><pre class="literallayout">
523 $ bitbake -c fetchall core-image-minimal
524 </pre><p>
525 This variation guarantees that you have all the sources for that BitBake target
526 should you to disconnect from the net and want to do the build later offline.
527 </p></li><li class="listitem"><p>Specify to continue the build even if BitBake encounters an error.
528 By default, BitBake aborts the build when it encounters an error.
529 This command keeps a faulty build going:
530 </p><pre class="literallayout">
531 $ bitbake -k core-image-minimal
532 </pre></li></ul></div><p>
533 </p><p>
534 Once you have your image, you can take steps to load and boot it on the target hardware.
535 </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>
536 Kudos and thanks to Robert P. J. Day of
537 <a class="ulink" href="" target="_top">CrashCourse</a> for providing the basis
538 for this "expert" section with information from one of his
539 <a class="ulink" href="" target="_top">wiki</a>
540 pages.
541 </p></div></div></div>
543<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>
545 <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">
546 <div class="author"><h3 class="author"><span class="firstname">Scott</span> <span class="surname">Rifenbark</span></h3><div class="affiliation">
547 <span class="orgname">Intel Corporation<br /></span>
548 </div><code class="email">&lt;<a class="email" href=""></a>&gt;</code></div>
549 </div></div><div><p class="copyright">Copyright © 2010-2012 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="id1482939"></a>
550 <p>
551 Permission is granted to copy, distribute and/or modify this document under
552 the terms of the <a class="ulink" href="" target="_top">
553 Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</a> as published by
554 Creative Commons.
555 </p>
557 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
558 Due to production processes, there could be differences between the Yocto Project
559 documentation bundled in the release tarball and the
560 Yocto Project Development Manual on
561 the <a class="ulink" href="" target="_top">Yocto Project</a> website.
562 For the latest version of this manual, see the manual on the website.
563 </div>
564 </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>
565 <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>
566 <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>
567 <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>
568 </table></div></div></div><hr /></div>
571 <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>
572 Welcome to the Yocto Project Development Manual!
573 This manual gives you an idea of how to use the Yocto Project to develop embedded Linux
574 images and user-space applications to run on targeted devices.
575 Reading this manual gives you an overview of image, kernel, and user-space application development
576 using the Yocto Project.
577 Because much of the information in this manual is general, it contains many references to other
578 sources where you can find more detail.
579 For example, detailed information on Git, repositories and open source in general
580 can be found in many places.
581 Another example is how to get set up to use the Yocto Project, which our Yocto Project
582 Quick Start covers.
583 </p><p>
584 The Yocto Project Development Manual, however, does provide detailed examples on how to create a
585 Board Support Package (BSP), change the kernel source code, and reconfigure the kernel.
586 You can find this information in the appendices of the manual.
587 </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>
588 The following list describes what you can get from this guide:
589 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Information that lets you get set
590 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
591 and to the distributed revision control system Git, which the Yocto Project
592 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
593 applications.</p></li><li class="listitem"><p>An overview and understanding of the emulation environment used with
594 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>
595 </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>
596 This manual will not give you the following:
597 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Step-by-step instructions if those instructions exist in other Yocto
598 Project documentation.
599 For example, the Yocto Project Development Manual contains detailed
600 instruction on how to obtain and configure the
601 <span class="trademark">Eclipse</span>™ Yocto Plug-in.</p></li><li class="listitem"><p>Reference material.
602 This type of material resides in an appropriate reference manual.
603 For example, system variables are documented in the
604 Yocto Project Reference Manual.</p></li><li class="listitem"><p>Detailed public information that is not specific to the Yocto Project.
605 For example, exhaustive information on how to use Git is covered better through the
606 Internet than in this manual.</p></li></ul></div><p>
607 </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>
608 Because this manual presents overview information for many different topics, you will
609 need to supplement it with other information.
610 The following list presents other sources of information you might find helpful:
611 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The <a class="ulink" href="" target="_top">Yocto Project Website</a>:
612 </em></span> The home page for the Yocto Project provides lots of information on the project
613 as well as links to software and documentation.</p></li><li class="listitem"><p><span class="emphasis"><em>
614 Yocto Project Quick Start:</em></span> This short document lets you get started
615 with the Yocto Project quickly and start building an image.</p></li><li class="listitem"><p><span class="emphasis"><em>
616 Yocto Project Reference Manual:</em></span> This manual is a reference
617 guide to the OpenEmbedded build system known as "Poky."
618 The manual also contains a reference chapter on Board Support Package (BSP)
619 layout.</p></li><li class="listitem"><p><span class="emphasis"><em>
620 Yocto Project Application Developer's Guide:</em></span>
621 This guide provides information that lets you get going with the Application
622 Development Toolkit (ADT) and stand-alone cross-development toolchains to
623 develop projects using the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>
624 Yocto Project Board Support Package (BSP) Developer's Guide:</em></span>
625 This guide defines the structure for BSP components.
626 Having a commonly understood structure encourages standardization.</p></li><li class="listitem"><p><span class="emphasis"><em>
627 Yocto Project Kernel Architecture and Use Manual:</em></span>
628 This manual describes the architecture of the Yocto Project kernel and provides
629 some work flow examples.</p></li><li class="listitem"><p><span class="emphasis"><em>
630 <a class="ulink" href="" target="_top">
631 Eclipse IDE Yocto Plug-in</a>:</em></span> A step-by-step instructional video that
632 demonstrates how an application developer uses Yocto Plug-in features within
633 the Eclipse IDE.</p></li><li class="listitem"><p><span class="emphasis"><em>
634 <a class="ulink" href="" target="_top">FAQ</a>:</em></span>
635 A list of commonly asked questions and their answers.</p></li><li class="listitem"><p><span class="emphasis"><em>
636 <a class="ulink" href="" target="_top">
637 Release Notes</a>:</em></span> Features, updates and known issues for the current
638 release of the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>
639 <a class="ulink" href="" target="_top">
640 Hob</a>:</em></span> A graphical user interface for BitBake.
641 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>
642 <a class="ulink" href="" target="_top">
643 Build Appliance</a>:</em></span> A bootable custom embedded Linux image you can
644 either build using a non-Linux development system (VMware applications) or download
645 from the Yocto Project website.
646 See the <a class="ulink" href="" target="_top">Build Appliance</a>
647 page for more information.</p></li><li class="listitem"><p><span class="emphasis"><em>
648 <a class="ulink" href="" target="_top">Bugzilla</a>:</em></span>
649 The bug tracking application the Yocto Project uses.
650 If you find problems with the Yocto Project, you should report them using this
651 application.</p></li><li class="listitem"><p><span class="emphasis"><em>
652 Yocto Project Mailing Lists:</em></span> To subscribe to the Yocto Project mailing
653 lists, click on the following URLs and follow the instructions:
654 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="ulink" href="" target="_top"></a> for a
655 Yocto Project Discussions mailing list.</p></li><li class="listitem"><p><a class="ulink" href="" target="_top"></a> for a
656 Yocto Project Discussions mailing list about the Poky build system.</p></li><li class="listitem"><p><a class="ulink" href="" target="_top"></a>
657 for a mailing list to receive official Yocto Project announcements for developments and
658 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>
659 Two IRC channels on freenode are available
660 for Yocto Project and Poky discussions: <code class="filename">#yocto</code> and
661 <code class="filename">#poky</code>, respectively.</p></li><li class="listitem"><p><span class="emphasis"><em>
662 <a class="ulink" href="" target="_top">OpenedHand</a>:</em></span>
663 The company that initially developed the Poky project, which is the basis
664 for the OpenEmbedded build system used by the Yocto Project.
665 OpenedHand was acquired by Intel Corporation in 2008.</p></li><li class="listitem"><p><span class="emphasis"><em>
666 <a class="ulink" href="" target="_top">Intel Corporation</a>:</em></span>
667 A multinational semiconductor chip manufacturer company whose Software and
668 Services Group created and supports the Yocto Project.
669 Intel acquired OpenedHand in 2008.</p></li><li class="listitem"><p><span class="emphasis"><em>
670 <a class="ulink" href="" target="_top">OpenEmbedded</a>:</em></span>
671 The build system used by the Yocto Project.
672 This project is the upstream, generic, embedded distribution from which the Yocto
673 Project derives its build system (Poky) from and to which it contributes.</p></li><li class="listitem"><p><span class="emphasis"><em>
674 <a class="ulink" href="" target="_top">
675 BitBake</a>:</em></span> The tool used by the OpenEmbedded build system
676 to process project metadata.</p></li><li class="listitem"><p><span class="emphasis"><em>
677 <a class="ulink" href="" target="_top">
678 BitBake User Manual</a>:</em></span> A comprehensive guide to the BitBake tool.
679 </p></li><li class="listitem"><p><span class="emphasis"><em>
680 <a class="ulink" href="" target="_top">QEMU</a>:
681 </em></span> An open-source machine emulator and virtualizer.</p></li></ul></div><p>
682 </p></div></div>
684 <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>
685 This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
686 You can find enough information to set up your development host and build or use images for
687 hardware supported by the Yocto Project by reading the
688 Yocto Project Quick Start.
690 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
691 some higher-level concepts you might want to consider.
692</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>
693 The Yocto Project is an open-source collaboration project focused on embedded Linux development.
694 The project currently provides a build system, which is
695 referred to as the OpenEmbedded build system in the Yocto Project documentation.
696 The Yocto Project provides various ancillary tools suitable for the embedded developer
697 and also features the Sato reference User Interface, which is optimized for
698 stylus driven, low-resolution screens.
699 </p><p>
700 You can use the OpenEmbedded build system, which uses
701 <a class="ulink" href="" target="_top">BitBake</a>, to develop complete Linux
702 images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
703 x86 and x86-64.
704 While the Yocto Project does not provide a strict testing framework,
705 it does provide or generate for you artifacts that let you perform target-level and
706 emulated testing and debugging.
707 Additionally, if you are an <span class="trademark">Eclipse</span>™
708 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
709 develop within that familiar environment.
710 </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>
711 Here is what you need to get set up to use the Yocto Project:
712 </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
713 Linux-based host system.
714 You will have the best results with a recent release of Fedora,
715 OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
716 and officially supported.
717 You should also have about 100 gigabytes of free disk space for building images.
718 </p></li><li class="listitem"><p><span class="emphasis"><em>Packages:</em></span> The OpenEmbedded build system
719 requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
720 See "<a class="link" href="#packages" target="_top">The Packages</a>"
721 section in the Yocto Project Quick Start for the exact package
722 requirements and the installation commands to install them
723 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>
724 You need a release of the Yocto Project.
725 You set up a with local <a class="link" href="#source-directory">source directory</a>
726 one of two ways depending on whether you
727 are going to contribute back into the Yocto Project or not.
728 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
729 Regardless of the method you use, this manual refers to the resulting local
730 hierarchical set of files as the "source directory."
731 </div><p>
732 </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
733 back into the Yocto Project, you can simply download a Yocto Project release you want
734 from the website’s <a class="ulink" href="" target="_top">download page</a>.
735 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
736 release tarball
737 into the current working directory and sets up the local source directory
738 with a top-level folder named <code class="filename">poky-1.2+snapshot-8.0</code>:
739 </p><pre class="literallayout">
740 $ tar xfj poky-1.2+snapshot-8.0.tar.bz2
741 </pre><p>This method does not produce a local Git repository.
742 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
743 back into the Yocto Project or you simply want to keep up
744 with the latest developments, you should use Git commands to set up a local
745 Git repository of the upstream <code class="filename">poky</code> source repository.
746 Doing so creates a repository with a complete history of changes and allows
747 you to easily submit your changes upstream to the project.
748 Because you cloned the repository, you have access to all the Yocto Project development
749 branches and tag names used in the upstream repository.</p><p>The following transcript shows how to clone the <code class="filename">poky</code>
750 Git repository into the current working directory.
751 </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
752 <a class="ulink" href="" target="_top"></a></div><p>
753 The command creates the local repository in a directory named <code class="filename">poky</code>.
754 For information on Git used within the Yocto Project, see the
755 "<a class="link" href="#git" title="3.6. Git">Git</a>" section.
756 </p><pre class="literallayout">
757 $ git clone git://
758 Initialized empty Git repository in /home/scottrif/poky/.git/
759 remote: Counting objects: 141863, done.
760 remote: Compressing objects: 100% (38624/38624), done.
761 remote: Total 141863 (delta 99661), reused 141816 (delta 99614)
762 Receiving objects: 100% (141863/141863), 76.64 MiB | 126 KiB/s, done.
763 Resolving deltas: 100% (99661/99661), done.
764 </pre><p>For another example of how to set up your own local Git repositories, see this
765 <a class="ulink" href="" target="_top">
766 wiki page</a>, which describes how to create both <code class="filename">poky</code>
767 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>
768 If you are going to be making modifications to a supported Yocto Project kernel, you
769 need to establish local copies of the source.
770 You can find Git repositories of supported Yocto Project Kernels organized under
771 "Yocto Project Linux Kernel" in the Yocto Project Source Repositories at
772 <a class="ulink" href="" target="_top"></a>.</p><p>This setup involves creating a bare clone of the Yocto Project kernel and then
773 copying that cloned repository.
774 You can create the bare clone and the copy of the bare clone anywhere you like.
775 For simplicity, it is recommended that you create these structures outside of the
776 source directory (usually <code class="filename">poky</code>).</p><p>As an example, the following transcript shows how to create the bare clone
777 of the <code class="filename">linux-yocto-3.2</code> kernel and then create a copy of
778 that clone.
779 </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
780 reference that repository rather than the upstream Git repository as
781 part of the <code class="filename">clone</code> command.
782 Doing so can speed up the process.</div><p>In the following example, the bare clone is named
783 <code class="filename">linux-yocto-3.2.git</code>, while the
784 copy is named <code class="filename">my-linux-yocto-3.2-work</code>:
785 </p><pre class="literallayout">
786 $ git clone --bare git:// linux-yocto-3.2.git
787 Initialized empty Git repository in /home/scottrif/linux-yocto-3.2.git/
788 remote: Counting objects: 2468027, done.
789 remote: Compressing objects: 100% (392255/392255), done.
790 remote: Total 2468027 (delta 2071693), reused 2448773 (delta 2052498)
791 Receiving objects: 100% (2468027/2468027), 530.46 MiB | 129 KiB/s, done.
792 Resolving deltas: 100% (2071693/2071693), done.
793 </pre><p>Now create a clone of the bare clone just created:
794 </p><pre class="literallayout">
795 $ git clone linux-yocto-3.2.git my-linux-yocto-3.2-work
796 Initialized empty Git repository in /home/scottrif/my-linux-yocto-3.2-work/.git/
797 Checking out files: 100% (37619/37619), done.
798 </pre></li><li class="listitem"><p><a id="poky-extras-repo"></a><span class="emphasis"><em>
799 The <code class="filename">poky-extras</code> Git Repository</em></span>:
800 The <code class="filename">poky-extras</code> Git repository contains metadata needed
801 only if you are modifying and building the kernel image.
802 In particular, it contains the kernel BitBake append (<code class="filename">.bbappend</code>)
803 files that you
804 edit to point to your locally modified kernel source files and to build the kernel
805 image.
806 Pointing to these local files is much more efficient than requiring a download of the
807 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
808 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
809 <a class="ulink" href="" target="_top"></a>.
810 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
811 repository inside the source directory, which is named <code class="filename">poky</code>
812 in this case:
813 </p><pre class="literallayout">
814 $ git clone git:// poky-extras
815 Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
816 remote: Counting objects: 618, done.
817 remote: Compressing objects: 100% (558/558), done.
818 remote: Total 618 (delta 192), reused 307 (delta 39)
819 Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done.
820 Resolving deltas: 100% (192/192), done.
821 </pre></li><li class="listitem"><p><a id="supported-board-support-packages-(bsps)"></a><span class="emphasis"><em>Supported Board
822 Support Packages (BSPs):</em></span>
823 The Yocto Project provides a layer called <code class="filename">meta-intel</code> and
824 it is maintained in its own separate Git repository.
825 The <code class="filename">meta-intel</code> layer contains many supported
826 <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>
827 layer.
828 You can get set up for BSP development one of two ways: tarball extraction or
829 with a local Git repository.
830 It is a good idea to use the same method that you used to set up the source directory.
831 Regardless of the method you use, the Yocto Project uses the following BSP layer
832 naming scheme:
833 </p><pre class="literallayout">
834 meta-&lt;BSP_name&gt;
835 </pre><p>
836 where &lt;BSP_name&gt; is the recognized BSP name.
837 Here are some examples:
838 </p><pre class="literallayout">
839 meta-crownbay
840 meta-emenlow
841 meta-n450
842 </pre><p>
843 See the
844 "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>"
845 section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
846 information on BSP Layers.
847 </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
848 BSP tarball from the same
849 <a class="ulink" href="" target="_top">download site</a> used
850 to get the Yocto Project release.
851 Once you have the tarball, just extract it into a directory of your choice.
852 Again, this method just produces a snapshot of the BSP layer in the form
853 of a hierarchical directory structure.</p></li><li class="listitem"><p><span class="emphasis"><em>Git Repository Method:</em></span> If you are working
854 with a local Git repository for your source directory, you should also use this method
855 to set up the <code class="filename">meta-intel</code> Git repository.
856 You can locate the <code class="filename">meta-intel</code> Git repository in the
857 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
858 <a class="ulink" href="" target="_top"></a>.</p><p>Typically, you set up the <code class="filename">meta-intel</code> Git repository inside
859 the source directory.
860 For example, the following transcript shows the steps to clone the
861 <code class="filename">meta-intel</code>
862 Git repository inside the local <code class="filename">poky</code> Git repository.
863 </p><pre class="literallayout">
864 $ git clone git://
865 Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
866 remote: Counting objects: 3380, done.
867 remote: Compressing objects: 100% (2750/2750), done.
868 remote: Total 3380 (delta 1689), reused 227 (delta 113)
869 Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done.
870 Resolving deltas: 100% (1689/1689), done.
871 </pre><p>The same
872 <a class="ulink" href="" target="_top">
873 wiki page</a> referenced earlier covers how to
874 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
875 applications using the Eclipse Integrated Development Environment (IDE),
876 you will need this plug-in.
877 See the
878 "<a class="link" href="#setting-up-the-eclipse-ide" title=" Setting Up the Eclipse IDE">Setting up the Eclipse IDE</a>"
879 section for more information.</p></li></ul></div><p>
880 </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>
881 The build process creates an entire Linux distribution, including the toolchain, from source.
882 For more information on this topic, see the
883 "<a class="link" href="#building-image" target="_top">Building an Image</a>"
884 section in the Yocto Project Quick Start.
885 </p><p>
886 The build process is as follows:
887 </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
888 previous section.</p></li><li class="listitem"><p>Initialize the build environment by sourcing a build environment
889 script.</p></li><li class="listitem"><p>Optionally ensure the <code class="filename">conf/local.conf</code> configuration file,
890 which is found in the
891 <a class="link" href="#build-directory">build directory</a>,
892 is set up how you want it.
893 This file defines many aspects of the build environment including
894 the target machine architecture through the
895 <code class="filename"><a class="link" href="#var-MACHINE" target="_top">MACHINE</a></code> variable,
896 the development machine's processor use through the
897 <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" target="_top">BB_NUMBER_THREADS</a></code> and
898 <code class="filename"><a class="link" href="#var-PARALLEL_MAKE" target="_top">PARALLEL_MAKE</a></code> variables, and
899 a centralized tarball download directory through the
900 <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.
901 If you want information on BitBake, see the user manual at
902 <a class="ulink" href="" target="_top"></a>.</p></li><li class="listitem"><p>Run the image either on the actual hardware or using the QEMU
903 emulator.</p></li></ol></div><p>
904 </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>
905 Another option you have to get started is to use pre-built binaries.
906 The Yocto Project provides many types of binaries with each release.
907 See the <a class="link" href="#ref-images" target="_top">Images</a>
908 chapter in the Yocto Project Reference Manual
909 for descriptions of the types of binaries that ship with a Yocto Project
910 release.
911 </p><p>
912 Using a pre-built binary is ideal for developing software applications to run on your
913 target hardware.
914 To do this, you need to be able to access the appropriate cross-toolchain tarball for
915 the architecture on which you are developing.
916 If you are using an SDK type image, the image ships with the complete toolchain native to
917 the architecture.
918 If you are not using an SDK type image, you need to separately download and
919 install the stand-alone Yocto Project cross-toolchain tarball.
920 </p><p>
921 Regardless of the type of image you are using, you need to download the pre-built kernel
922 that you will boot in the QEMU emulator and then download and extract the target root
923 filesystem for your target machine’s architecture.
924 You can get architecture-specific binaries and filesystem from
925 <a class="ulink" href="" target="_top">machines</a>.
926 You can get stand-alone toolchains from
927 <a class="ulink" href="" target="_top">toolchains</a>.
928 Once you have all your files, you set up the environment to emulate the hardware
929 by sourcing an environment setup script.
930 Finally, you start the QEMU emulator.
931 You can find details on all these steps in the
932 "<a class="link" href="#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>"
933 section of the Yocto Project Quick Start.
934 </p><p>
935 Using QEMU to emulate your hardware can result in speed issues
936 depending on the target and host architecture mix.
937 For example, using the <code class="filename">qemux86</code> image in the emulator
938 on an Intel-based 32-bit (x86) host machine is fast because the target and
939 host architectures match.
940 On the other hand, using the <code class="filename">qemuarm</code> image on the same Intel-based
941 host can be slower.
942 But, you still achieve faithful emulation of ARM-specific issues.
943 </p><p>
944 To speed things up, the QEMU images support using <code class="filename">distcc</code>
945 to call a cross-compiler outside the emulated system.
946 If you used <code class="filename">runqemu</code> to start QEMU, and the
947 <code class="filename">distccd</code> application is present on the host system, any
948 BitBake cross-compiling toolchain available from the build system is automatically
949 used from within QEMU simply by calling <code class="filename">distcc</code>.
950 You can accomplish this by defining the cross-compiler variable
951 (e.g. <code class="filename">export CC="distcc"</code>).
952 Alternatively, if you are using a suitable SDK image or the appropriate
953 stand-alone toolchain is present in <code class="filename">/opt/poky</code>,
954 the toolchain is also automatically used.
955 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
956 Several mechanisms exist that let you connect to the system running on the
957 QEMU emulator:
958 <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>QEMU provides a framebuffer interface that makes standard
959 consoles available.</p></li><li class="listitem"><p>Generally, headless embedded devices have a serial port.
960 If so, you can configure the operating system of the running image
961 to use that port to run a console.
962 The connection uses standard IP networking.</p></li><li class="listitem"><p>SSH servers exist in some QEMU images.
963 The <code class="filename">core-image-sato</code> QEMU image has a Dropbear secure
964 shell (ssh) server that runs with the root password disabled.
965 The <code class="filename">core-image-basic</code> and <code class="filename">core-image-lsb</code> QEMU images
966 have OpenSSH instead of Dropbear.
967 Including these SSH servers allow you to use standard <code class="filename">ssh</code> and
968 <code class="filename">scp</code> commands.
969 The <code class="filename">core-image-minimal</code> QEMU image, however, contains no ssh
970 server.</p></li><li class="listitem"><p>You can use a provided, user-space NFS server to boot the QEMU session
971 using a local copy of the root filesystem on the host.
972 In order to make this connection, you must extract a root filesystem tarball by using the
973 <code class="filename">runqemu-extract-sdk</code> command.
974 After running the command, you must then point the <code class="filename">runqemu</code>
975 script to the extracted directory instead of a root filesystem image file.</p></li></ul></div></div></div></div>
977 <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>
978 This chapter helps you understand the Yocto Project as an open source development project.
979 In general, working in an open source environment is very different from working in a
980 closed, proprietary environment.
981 Additionally, the Yocto Project uses specific tools and constructs as part of its development
982 environment.
983 This chapter specifically addresses open source philosophy, licensing issues, code repositories,
984 the open source distributed version control system Git, and best practices using the Yocto Project.
985</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>
986 Open source philosophy is characterized by software development directed by peer production
987 and collaboration through an active community of developers.
988 Contrast this to the more standard centralized development models used by commercial software
989 companies where a finite set of developers produces a product for sale using a defined set
990 of procedures that ultimately result in an end product whose architecture and source material
991 are closed to the public.
992 </p><p>
993 Open source projects conceptually have differing concurrent agendas, approaches, and production.
994 These facets of the development process can come from anyone in the public (community) that has a
995 stake in the software project.
996 The open source environment contains new copyright, licensing, domain, and consumer issues
997 that differ from the more traditional development environment.
998 In an open source environment, the end product, source material, and documentation are
999 all available to the public at no cost.
1000 </p><p>
1001 A benchmark example of an open source project is the Linux Kernel, which was initially conceived
1002 and created by Finnish computer science student Linus Torvalds in 1991.
1003 Conversely, a good example of a non-open source project is the
1004 <span class="trademark">Windows</span>® family of operating
1005 systems developed by <span class="trademark">Microsoft</span>® Corporation.
1006 </p><p>
1007 Wikipedia has a good historical description of the Open Source Philosophy
1008 <a class="ulink" href="" target="_top">here</a>.
1009 You can also find helpful information on how to participate in the Linux Community
1010 <a class="ulink" href="" target="_top">here</a>.
1011 </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>
1012 It might not be immediately clear how you can use the Yocto Project in a team environment,
1013 or scale it for a large team of developers.
1014 The specifics of any situation determine the best solution.
1015 Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
1016 that experience has shown work well.
1017 </p><p>
1018 The core component of any development effort with the Yocto Project is often an
1019 automated build and testing framework along with an image generation process.
1020 You can use these core components to check that the metadata can be built,
1021 highlight when commits break the build, and provide up-to-date images that
1022 allow developers to test the end result and use it as a base platform for further
1023 development.
1024 Experience shows that buildbot is a good fit for this role.
1025 What works well is to configure buildbot to make two types of builds:
1026 incremental and full (from scratch).
1027 See <a class="ulink" href="" target="_top">the buildbot for the
1028 Yocto Project</a> for an example implementation that uses buildbot.
1029 </p><p>
1030 You can tie incremental builds to a commit hook that triggers the build
1031 each time a commit is made to the metadata.
1032 This practice results in useful acid tests that determine whether a given commit
1033 breaks the build in some serious way.
1034 Associating a build to a commit can catch a lot of simple errors.
1035 Furthermore, the tests are fast so developers can get quick feedback on changes.
1036 </p><p>
1037 Full builds build and test everything from the ground up.
1038 These types of builds usually happen at predetermined times like during the
1039 night when the machine load is low.
1040 </p><p>
1041 Most teams have many pieces of software undergoing active development at any given time.
1042 You can derive large benefits by putting these pieces under the control of a source
1043 control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded
1044 build system that the Yocto Project uses.
1045 You can then set the autobuilder to pull the latest revisions of the packages
1046 and test the latest commits by the builds.
1047 This practice quickly highlights issues.
1048 The build system easily supports testing configurations that use both a
1049 stable known good revision and a floating revision.
1050 The build system can also take just the changes from specific source control branches.
1051 This capability allows you to track and test specific changes.
1052 </p><p>
1053 Perhaps the hardest part of setting this up is defining the software project or
1054 the metadata policies that surround the different source control systems.
1055 Of course circumstances will be different in each case.
1056 However, this situation reveals one of the Yocto Project's advantages -
1057 the system itself does not
1058 force any particular policy on users, unlike a lot of build systems.
1059 The system allows the best policies to be chosen for the given circumstances.
1060 </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>
1061 The Yocto Project team maintains complete source repositories for all Yocto Project files
1062 at <a class="ulink" href="" target="_top"></a>.
1063 This web-based source code browser is organized into categories by function such as
1064 IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth.
1065 From the interface, you can click on any particular item in the "Name" column and
1066 see the URL at the bottom of the page that you need to set up a Git repository for
1067 that particular item.
1068 Having a local Git repository of the source directory (poky) allows you to
1069 make changes, contribute to the history, and ultimately enhance the Yocto Project's
1070 tools, Board Support Packages, and so forth.
1071 </p><p>
1072 Conversely, if you are a developer that is not interested in contributing back to the
1073 Yocto Project, you have the ability to simply download and extract release tarballs
1074 and use them within the Yocto Project environment.
1075 All that is required is a particular release of the Yocto Project and
1076 your application source code.
1077 </p><p>
1078 For any supported release of Yocto Project, you can go to the Yocto Project website’s
1079 <a class="ulink" href="" target="_top">download page</a> and get a
1080 tarball of the release.
1081 You can also go to this site to download any supported BSP tarballs.
1082 Unpacking the tarball gives you a hierarchical source directory that lets you develop
1083 using the Yocto Project.
1084 </p><p>
1085 Once you are set up through either tarball extraction or creation of Git repositories,
1086 you are ready to develop.
1087 </p><p>
1088 In summary, here is where you can get the project files needed for development:
1089 </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="" target="_top">Source Repositories:</a></em></span>
1090 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
1091 Metadata Layers.
1092 You can create local copies of Git repositories for each of these areas.</p><p>
1093 </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>
1094 </p></li><li class="listitem"><p><a id="index-downloads"></a><span class="emphasis"><em><a class="ulink" href="" target="_top">Index of /releases:</a></em></span>
1095 This area contains index releases such as
1096 the <span class="trademark">Eclipse</span>™
1097 Yocto Plug-in, miscellaneous support, poky, pseudo, cross-development toolchains,
1098 and all released versions of Yocto Project in the form of images or tarballs.
1099 Downloading and extracting these files does not produce a local copy of the
1100 Git repository but rather a snapshot of a particular release or image.</p><p>
1101 </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>
1102 </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="" target="_top">Yocto Project Download Page</a></em></span>
1103 This page on the Yocto Project website allows you to download any Yocto Project
1104 release or Board Support Package (BSP) in tarball form.
1105 The tarballs are similar to those found in the
1106 <a class="ulink" href="" target="_top">Index of /releases:</a> area.</p><p>
1107 </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>
1108 </p></li></ul></div><p>
1109 </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>
1110 Following is a list of terms and definitions users new to the Yocto Project development
1111 environment might find helpful.
1112 While some of these terms are universal, the list includes them just in case:
1113 </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
1114 a recipe file.
1115 Append files are known as BitBake append files and <code class="filename">.bbappend</code> files.
1116 The OpenEmbedded build system expects every append file to have a corresponding and
1117 underlying recipe (<code class="filename">.bb</code>) file.
1118 Furthermore, the append file and the underlying recipe must have the same root filename.
1119 The filenames can differ only in the file type suffix used (e.g.
1120 <code class="filename"></code> and <code class="filename">formfactor_0.0.bbappend</code>).
1121 </p><p>Information in append files overrides the information in the similarly-named recipe file.
1122 For examples of <code class="filename">.bbappend</code> file in use, see the
1123 "<a class="link" href="#using-bbappend-files" title="4.1.4. Using .bbappend Files">Using .bbappend Files</a>" and
1124 "<a class="link" href="#changing-recipes-kernel" title="A.5.2.4. Changing  recipes-kernel">Changing <code class="filename">recipes-kernel</code></a>"
1125 sections.</p></li><li class="listitem"><p><span class="emphasis"><em>BitBake:</em></span> The task executor and scheduler used by
1126 the OpenEmbedded build system to build images.
1127 For more information on BitBake, see the <a class="ulink" href="" target="_top">
1128 BitBake documentation</a>.</p></li><li class="listitem"><p><a id="build-directory"></a><span class="emphasis"><em>Build Directory:</em></span>
1129 This term refers to the area used by the OpenEmbedded build system for builds.
1130 The area is created when you <code class="filename">source</code> the setup
1131 environment script that is found in the source directory
1132 (i.e. <code class="filename">oe-init-build-env</code>).
1133 The <a class="link" href="#var-TOPDIR" target="_top"><code class="filename">TOPDIR</code></a>
1134 variable points to the build directory.</p><p>You have a lot of flexibility when creating the build directory.
1135 Following are some examples that show how to create the directory:
1136 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Create the build directory in your current working directory
1137 and name it <code class="filename">build</code>.
1138 This is the default behavior.
1139 </p><pre class="literallayout">
1140 $ source oe-init-build-env
1141 </pre></li><li class="listitem"><p>Provide a directory path and specifically name the build
1142 directory.
1143 This next example creates a build directory named <code class="filename">YP-8.0</code>
1144 in your home directory within the directory <code class="filename">mybuilds</code>.
1145 If <code class="filename">mybuilds</code> does not exist, the directory is created for you:
1146 </p><pre class="literallayout">
1147 $ source poky-1.2+snapshot-8.0/oe-init-build-env $HOME/mybuilds/YP-8.0
1148 </pre></li><li class="listitem"><p>Provide an existing directory to use as the build directory.
1149 This example uses the existing <code class="filename">mybuilds</code> directory
1150 as the build directory.
1151 </p><pre class="literallayout">
1152 $ source poky-1.2+snapshot-8.0/oe-init-build-env $HOME/mybuilds/
1153 </pre></li></ul></div><p>
1154 </p></li><li class="listitem"><p><span class="emphasis"><em>Build System:</em></span> In the context of the Yocto Project
1155 this term refers to the OpenEmbedded build system used by the project.
1156 This build system is based on the project known as "Poky."
1157 For some historical information about Poky, see the
1158 <a class="link" href="#poky">poky</a> term further along in this section.
1159 </p></li><li class="listitem"><p><span class="emphasis"><em>Classes:</em></span> Files that provide for logic encapsulation
1160 and inheritance allowing commonly used patterns to be defined once and easily used
1161 in multiple recipes.
1162 Class files end with the <code class="filename">.bbclass</code> filename extension.
1163 </p></li><li class="listitem"><p><span class="emphasis"><em>Configuration File:</em></span> Configuration information in various
1164 <code class="filename">.conf</code> files provides global definitions of variables.
1165 The <code class="filename">conf/local.conf</code> configuration file in the
1166 <a class="link" href="#build-directory">build directory</a>
1167 contains user-defined variables that affect each build.
1168 The <code class="filename">meta-yocto/conf/distro/poky.conf</code> configuration file
1169 defines Yocto ‘distro’ configuration
1170 variables used only when building with this policy.
1171 Machine configuration files, which
1172 are located throughout the
1173 <a class="link" href="#source-directory">source directory</a>, define
1174 variables for specific hardware and are only used when building for that target
1175 (e.g. the <code class="filename">machine/beagleboard.conf</code> configuration file defines
1176 variables for the Texas Instruments ARM Cortex-A8 development board).
1177 Configuration files end with a <code class="filename">.conf</code> filename extension.
1178 </p></li><li class="listitem"><p><span class="emphasis"><em>Cross-Development Toolchain:</em></span>
1179 A collection of software development
1180 tools and utilities that allow you to develop software for targeted architectures.
1181 This toolchain contains cross-compilers, linkers, and debuggers that are specific to
1182 an architecture.
1183 You can use the OpenEmbedded build system to build cross-development toolchains in tarball
1184 form that, when
1185 unpacked, contain the development tools you need to cross-compile and test your software.
1186 The Yocto Project ships with images that contain toolchains for supported architectures
1187 as well.
1188 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
1189 BitBake processes a given collection of recipes and related metadata.
1190 Images are the binary output that run on specific hardware and for specific
1191 use cases.
1192 For a list of the supported image types that the Yocto Project provides, see the
1193 "<a class="link" href="#ref-images" target="_top">Images</a>"
1194 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,
1195 a BSP, or an application stack.
1196 For a discussion on BSP Layers, see the
1197 "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>"
1198 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
1199 building an image.
1200 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
1201 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
1202 This metadata is found in the <code class="filename">meta</code> directory of the source
1203 directory.</p></li><li class="listitem"><p><span class="emphasis"><em>Package:</em></span> The packaged output from a baked recipe.
1204 A package is generally the compiled binaries produced from the recipe's sources.
1205 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.
1206 In its most general sence, it is an open-source project that was initially developed
1207 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
1208 build system becoming a build system for embedded images.
1209 After Intel Corporation aquired OpenedHand, the project poky became the basis for
1210 the Yocto Project's build system.
1211 Within the Yocto Project source repositories, poky exists as a separate Git repository
1212 that can be cloned to yield a local copy on the host system.
1213 Thus, "poky" can refer to the local copy of the source directory used to develop within
1214 the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>Recipe:</em></span> A set of instructions for building packages.
1215 A recipe describes where you get source code and which patches to apply.
1216 Recipes describe dependencies for libraries or for other recipes, and they
1217 also contain configuration and compilation options.
1218 Recipes contain the logical unit of execution, the software/images to build, and
1219 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>
1220 This term refers to the directory structure created as a result of either downloading
1221 and unpacking a Yocto Project release tarball or creating a local copy of
1222 <code class="filename">poky</code> Git repository <code class="filename">git://</code>.
1223 Sometimes you might here the term "poky directory" used to refer to this
1224 directory structure.</p><p>The source directory contains BitBake, Documentation, metadata and
1225 other files that all support the Yocto Project.
1226 Consequently, you must have the source directory in place on your development
1227 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
1228 is derived from the Yocto Project release tarball.
1229 For example, downloading and unpacking <code class="filename">poky-1.2+snapshot-8.0.tar.bz2</code>
1230 results in a source directory whose top-level folder is named
1231 <code class="filename">poky-1.2+snapshot-8.0</code>.
1232 If you create a local copy of the Git repository, then you can name the repository
1233 anything you like.
1234 Throughout much of the documentation, <code class="filename">poky</code> is used as the name of
1235 the top-level folder of the local copy of the poky Git repository.
1236 So, for example, cloning the <code class="filename">poky</code> Git repository results in a
1237 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
1238 by unpacking a released tarball as compared to cloning
1239 <code class="filename">git://</code>.
1240 When you unpack a tarball, you have an exact copy of the files based on the time of
1241 release - a fixed release point.
1242 Any changes you make to your local files in the source directory are on top of the release.
1243 On the other hand, when you clone the <code class="filename">poky</code> Git repository, you have an
1244 active development repository.
1245 In this case, any local changes you make to the source directory can be later applied
1246 to active development branches of the upstream <code class="filename">poky</code> Git
1247 repository.</p><p>Finally, if you want to track a set of local changes while starting from the same point
1248 as a release tarball, you can create a local Git branch that
1249 reflects the exact copy of the files at the time of their release.
1250 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,
1251 see the
1252 "<a class="link" href="#repositories-tags-and-branches" title="3.6.1. Repositories, Tags, and Branches">Repositories, Tags, and Branches</a>"
1253 section.</p></li><li class="listitem"><p><span class="emphasis"><em>Tasks:</em></span> Arbitrary groups of software Recipes.
1254 You simply use Tasks to hold recipes that, when built, usually accomplish a single task.
1255 For example, a task could contain the recipes for a company’s proprietary or value-add software.
1256 Or, the task could contain the recipes that enable graphics.
1257 A task is really just another recipe.
1258 Because task files are recipes, they end with the <code class="filename">.bb</code> filename
1259 extension.</p></li><li class="listitem"><p><span class="emphasis"><em>Upstream:</em></span> A reference to source code or repositories
1260 that are not local to the development system but located in a master area that is controlled
1261 by the maintainer of the source code.
1262 For example, in order for a developer to work on a particular piece of code, they need to
1263 first get a copy of it from an "upstream" source.</p></li></ul></div><p>
1264 </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>
1265 Because open source projects are open to the public, they have different licensing structures in place.
1266 License evolution for both Open Source and Free Software has an interesting history.
1267 If you are interested in this history, you can find basic information here:
1268 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="" target="_top">Open source license history</a>
1269 </p></li><li class="listitem"><p><a class="ulink" href="" target="_top">Free software license
1270 history</a></p></li></ul></div><p>
1271 </p><p>
1272 In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
1273 (MIT) License.
1274 MIT licensing permits the reuse of software within proprietary software as long as the
1275 license is distributed with that software.
1276 MIT is also compatible with the GNU General Public License (GPL).
1277 Patches to the Yocto Project follow the upstream licensing scheme.
1278 You can find information on the MIT license at
1279 <a class="ulink" href="" target="_top">here</a>.
1280 You can find information on the GNU GPL <a class="ulink" href="" target="_top">
1281 here</a>.
1282 </p><p>
1283 When you build an image using Yocto Project, the build process uses a known list of licenses to
1284 ensure compliance.
1285 You can find this list in the Yocto Project files directory at
1286 <code class="filename">meta/files/common-licenses</code>.
1287 Once the build completes, the list of all licenses found and used during that build are
1288 kept in the
1289 <a class="link" href="#build-directory">build directory</a> at
1290 <code class="filename">tmp/deploy/images/licenses</code>.
1291 </p><p>
1292 If a module requires a license that is not in the base list, the build process
1293 generates a warning during the build.
1294 These tools make it easier for a developer to be certain of the licenses with which
1295 their shipped products must comply.
1296 However, even with these tools it is still up to the developer to resolve potential licensing issues.
1297 </p><p>
1298 The base list of licenses used by the build process is a combination of the Software Package
1299 Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
1300 <a class="ulink" href="" target="_top">SPDX Group</a> is a working group of the Linux Foundation
1301 that maintains a specification
1302 for a standard format for communicating the components, licenses, and copyrights
1303 associated with a software package.
1304 <a class="ulink" href="" target="_top">OSI</a> is a corporation dedicated to the Open Source
1305 Definition and the effort for reviewing and approving licenses that are OSD-conformant.
1306 </p><p>
1307 You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
1308 <a class="ulink" href="" target="_top">here</a>.
1309 This wiki page discusses the license infrastructure used by the Yocto Project.
1310 </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>
1311 The Yocto Project uses Git, which is a free, open source distributed version control system.
1312 Git supports distributed development, non-linear development, and can handle large projects.
1313 It is best that you have some fundamental understanding of how Git tracks projects and
1314 how to work with Git if you are going to use Yocto Project for development.
1315 This section provides a quick overview of how Git works and provides you with a summary
1316 of some essential Git commands.
1317 </p><p>
1318 For more information on Git, see
1319 <a class="ulink" href="" target="_top"></a>.
1320 If you need to download Git, go to <a class="ulink" href="" target="_top"></a>.
1321 </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>
1322 As mentioned earlier in section
1323 "<a class="link" href="#yocto-project-repositories" title="3.3. Yocto Project Source Repositories">Yocto Project Source Repositories</a>",
1324 the Yocto Project maintains source repositories at
1325 <a class="ulink" href="" target="_top"></a>.
1326 If you look at this web-interface of the repositories, each item is a separate
1327 Git repository.
1328 </p><p>
1329 Git repositories use branching techniques that track content change (not files)
1330 within a project (e.g. a new feature or updated documentation).
1331 Creating a tree-like structure based on project divergence allows for excellent historical
1332 information over the life of a project.
1333 This methodology also allows for an environment in which you can do lots of
1334 local experimentation on a project as you develop changes or new features.
1335 </p><p>
1336 A Git repository represents all development efforts for a given project.
1337 For example, the Git repository <code class="filename">poky</code> contains all changes
1338 and developments for Poky over the course of its entire life.
1339 That means that all changes that make up all releases are captured.
1340 The repository maintains a complete history of changes.
1341 </p><p>
1342 You can create a local copy of any repository by "cloning" it with the Git
1343 <code class="filename">clone</code> command.
1344 When you clone a Git repository, you end up with an identical copy of the
1345 repository on your development system.
1346 Once you have a local copy of a repository, you can take steps to develop locally.
1347 For examples on how to clone Git repositories, see the section
1348 "<a class="link" href="#getting-setup" title="2.2. Getting Set Up">Getting Set Up</a>" earlier in this manual.
1349 </p><p>
1350 It is important to understand that Git tracks content change and not files.
1351 Git uses "branches" to organize different development efforts.
1352 For example, the <code class="filename">poky</code> repository has
1353 <code class="filename">laverne</code>, <code class="filename">bernard</code>,
1354 <code class="filename">edison</code>, <code class="filename">denzil</code> and
1355 <code class="filename">master</code> branches among
1356 others.
1357 You can see all the branches by going to
1358 <a class="ulink" href="" target="_top"></a> and
1359 clicking on the
1360 <code class="filename"><a class="ulink" href="" target="_top">[...]</a></code>
1361 link beneath the "Branch" heading.
1362 </p><p>
1363 Each of these branches represents a specific area of development.
1364 The <code class="filename">master</code> branch represents the current or most recent
1365 development.
1366 All other branches represent off-shoots of the <code class="filename">master</code>
1367 branch.
1368 </p><p>
1369 When you create a local copy of a Git repository, the copy has the same set
1370 of branches as the original.
1371 This means you can use Git to create a local working area (also called a branch)
1372 that tracks a specific development branch from the source Git repository.
1373 in other words, you can define your local Git environment to work on any development
1374 branch in the repository.
1375 To help illustrate, here is a set of commands that creates a local copy of the
1376 <code class="filename">poky</code> Git repository and then creates and checks out a local
1377 Git branch that tracks the Yocto Project 1.3 Release (1.2+snapshot) development:
1378 </p><pre class="literallayout">
1379 $ cd ~
1380 $ git clone git://
1381 $ cd poky
1382 $ git checkout -b 1.2+snapshot origin/1.2+snapshot
1383 </pre><p>
1384 In this example, the name of the top-level directory of your local Yocto Project
1385 Files Git repository is <code class="filename">poky</code>,
1386 and the name of the local working area (or local branch) you have created and checked
1387 out is <code class="filename">1.2+snapshot</code>.
1388 The files in your repository now reflect the same files that are in the
1389 <code class="filename">1.2+snapshot</code> development branch of the Yocto Project's
1390 <code class="filename">poky</code> repository.
1391 It is important to understand that when you create and checkout a
1392 local working branch based on a branch name,
1393 your local environment matches the "tip" of that development branch
1394 at the time you created your local branch, which could be
1395 different than the files at the time of a similarly named release.
1396 In other words, creating and checking out a local branch based on the
1397 <code class="filename">1.2+snapshot</code> branch name is not the same as creating and
1398 checking out a local branch based on the <code class="filename">1.2+snapshot-1.3</code>
1399 release.
1400 Keep reading to see how you create a local snapshot of a Yocto Project Release.
1401 </p><p>
1402 Git uses "tags" to mark specific changes in a repository.
1403 Typically, a tag is used to mark a special point such as the final change
1404 before a project is released.
1405 You can see the tags used with the <code class="filename">poky</code> Git repository
1406 by going to <a class="ulink" href="" target="_top"></a> and
1407 clicking on the
1408 <code class="filename"><a class="ulink" href="" target="_top">[...]</a></code>
1409 link beneath the "Tag" heading.
1410 </p><p>
1411 Some key tags are <code class="filename">laverne-4.0</code>, <code class="filename">bernard-5.0</code>,
1412 and <code class="filename">1.2+snapshot-8.0</code>.
1413 These tags represent Yocto Project releases.
1414 </p><p>
1415 When you create a local copy of the Git repository, you also have access to all the
1416 tags.
1417 Similar to branches, you can create and checkout a local working Git branch based
1418 on a tag name.
1419 When you do this, you get a snapshot of the Git repository that reflects
1420 the state of the files when the change was made associated with that tag.
1421 The most common use is to checkout a working branch that matches a specific
1422 Yocto Project release.
1423 Here is an example:
1424 </p><pre class="literallayout">
1425 $ cd ~
1426 $ git clone git://
1427 $ cd poky
1428 $ git checkout -b my-1.2+snapshot-8.0 1.2+snapshot-8.0
1429 </pre><p>
1430 In this example, the name of the top-level directory of your local Yocto Project
1431 Files Git repository is <code class="filename">poky</code>.
1432 And, the name of the local branch you have created and checked out is
1433 <code class="filename">my-1.2+snapshot-8.0</code>.
1434 The files in your repository now exactly match the Yocto Project 1.3
1435 Release tag (<code class="filename">1.2+snapshot-8.0</code>).
1436 It is important to understand that when you create and checkout a local
1437 working branch based on a tag, your environment matches a specific point
1438 in time and not a development branch.
1439 </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>
1440 Git has an extensive set of commands that lets you manage changes and perform
1441 collaboration over the life of a project.
1442 Conveniently though, you can manage with a small set of basic operations and workflows
1443 once you understand the basic philosophy behind Git.
1444 You do not have to be an expert in Git to be functional.
1445 A good place to look for instruction on a minimal set of Git commands is
1446 <a class="ulink" href="" target="_top">here</a>.
1447 If you need to download Git, you can do so
1448 <a class="ulink" href="" target="_top">here</a>.
1449 </p><p>
1450 If you don’t know much about Git, we suggest you educate
1451 yourself by visiting the links previously mentioned.
1452 </p><p>
1453 The following list briefly describes some basic Git operations as a way to get started.
1454 As with any set of commands, this list (in most cases) simply shows the base command and
1455 omits the many arguments they support.
1456 See the Git documentation for complete descriptions and strategies on how to use these commands:
1457 </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.
1458 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.
1459 During collaboration, this command allows you to create a local repository that is on
1460 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
1461 to the index that
1462 Git uses to track changes.
1463 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
1464 the changes you made.
1465 Commits are used for historical purposes, for determining if a maintainer of a project
1466 will allow the change, and for ultimately pushing the change from your local Git repository
1467 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
1468 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
1469 your working branch.
1470 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
1471 a working branch on your local machine where you can isolate work.
1472 It is a good idea to use local branches when adding specific features or changes.
1473 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
1474 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>
1475 Deletes an existing branch.
1476 You need to be in a branch other than the one you are deleting
1477 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
1478 from an upstream Git
1479 repository and places it in your local Git repository.
1480 You use this command to make sure you are synchronized with the repository
1481 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
1482 have committed to an upstream Git repository (e.g. a contribution repository).
1483 The maintainer of the project draws from these repositories when adding your changes to the
1484 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
1485 local branch of your repository with another branch.
1486 When you create a local Git repository, the default branch is named “master”.
1487 A typical workflow is to create a temporary branch for isolated work, make and commit your
1488 changes, switch to your local master branch, merge the changes from the temporary branch into the
1489 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
1490 commits from one branch into another branch.
1491 There are times when you might not be able to merge all the changes in one branch with
1492 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
1493 and changes in your local Git repository.
1494 This command is a good way to graphically see where things have diverged in your
1495 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
1496 repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git diff</code>:</em></span> Displays line-by-line differences
1497 between your local working files and the same files in the upstream Git repository that your
1498 branch currently tracks.</p></li></ul></div><p>
1499 </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>
1500 This section provides some overview on workflows using Git.
1501 In particular, the information covers basic practices that describe roles and actions in a
1502 collaborative development environment.
1503 Again, if you are familiar with this type of development environment, you might want to just
1504 skip this section.
1505 </p><p>
1506 The Yocto Project files are maintained using Git in a "master" branch whose Git history
1507 tracks every change and whose structure provides branches for all diverging functionality.
1508 Although there is no need to use Git, many open source projects do so.
1509 For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
1510 branch of the Git repository.
1511 The "master" branch is the “upstream” repository where the final builds of the project occur.
1512 The maintainer is responsible for allowing changes in from other developers and for
1513 organizing the underlying branch structure to reflect release strategies and so forth.
1514 </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
1515 <code class="filename"></code> file in the Yocto Project
1516 <code class="filename">meta/conf/distro/include</code> directory.</div><p>
1517 </p><p>
1518 The project also has contribution repositories known as “contrib” areas.
1519 These areas temporarily hold changes to the project that have been submitted or committed
1520 by the Yocto Project development team and by community members that contribute to the project.
1521 The maintainer determines if the changes are qualified to be moved from the "contrib" areas
1522 into the "master" branch of the Git repository.
1523 </p><p>
1524 Developers (including contributing community members) create and maintain cloned repositories
1525 of the upstream "master" branch.
1526 These repositories are local to their development platforms and are used to develop changes.
1527 When a developer is satisfied with a particular feature or change, they “push” the changes
1528 to the appropriate "contrib" repository.
1529 </p><p>
1530 Developers are responsible for keeping their local repository up-to-date with "master".
1531 They are also responsible for straightening out any conflicts that might arise within files
1532 that are being worked on simultaneously by more than one person.
1533 All this work is done locally on the developer’s machine before anything is pushed to a
1534 "contrib" area and examined at the maintainer’s level.
1535 </p><p>
1536 A somewhat formal method exists by which developers commit changes and push them into the
1537 "contrib" area and subsequently request that the maintainer include them into "master"
1538 This process is called “submitting a patch” or “submitting a change.”
1539 </p><p>
1540 To summarize the environment: we have a single point of entry for changes into the project’s
1541 "master" branch of the Git repository, which is controlled by the project’s maintainer.
1542 And, we have a set of developers who independently develop, test, and submit changes
1543 to "contrib" areas for the maintainer to examine.
1544 The maintainer then chooses which changes are going to become a permanent part of the project.
1545 </p><p>
1546 </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>
1547 </p><p>
1548 While each development environment is unique, there are some best practices or methods
1549 that help development run smoothly.
1550 The following list describes some of these practices.
1551 For more information about Git workflows, see the workflow topics in the
1552 <a class="ulink" href="" target="_top">Git Community Book</a>.
1553 </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
1554 small as compared to bundling many disparate changes into a single commit.
1555 This practice not only keeps things manageable but also allows the maintainer
1556 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
1557 still successfully build your project. In other words, do not commit half of a feature,
1558 then add the other half in a separate, later commit.
1559 Each commit should take you from one buildable project state to another
1560 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
1561 delete local branches in your working Git repository.
1562 You can name these branches anything you like.
1563 It is helpful to give them names associated with the particular feature or change
1564 on which you are working.
1565 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>
1566 command allows you to take the
1567 changes from one branch and fold them into another branch.
1568 This process is especially helpful when more than a single developer might be working
1569 on different parts of the same feature.
1570 Merging changes also automatically identifies any collisions or “conflicts”
1571 that might happen as a result of the same lines of code being altered by two different
1572 developers.</p></li><li class="listitem"><p><span class="emphasis"><em>Manage Branches:</em></span> Because branches are easy to use, you should
1573 use a system where branches indicate varying levels of code readiness.
1574 For example, you can have a “work” branch to develop in, a “test” branch where the code or
1575 change is tested, a “stage” branch where changes are ready to be committed, and so forth.
1576 As your project develops, you can merge code across the branches to reflect ever-increasing
1577 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
1578 concept of developers “pushing” local commits to a remote repository, which is
1579 usually a contribution repository.
1580 This workflow is also based on developers “pulling” known states of the project down into their
1581 local development repositories.
1582 The workflow easily allows you to pull changes submitted by other developers from the
1583 upstream repository into your work area ensuring that you have the most recent software
1584 on which to develop.
1585 The Yocto Project has two scripts named <code class="filename">create-pull-request</code> and
1586 <code class="filename">send-pull-request</code> that ship with the release to facilitate this
1587 workflow.
1588 You can find these scripts in the local Yocto Project files Git repository in
1589 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
1590 maintainer through an email that you have a change (or patch) you would like considered
1591 for the "master" branch of the Git repository.
1592 To send this type of change you format the patch and then send the email using the Git commands
1593 <code class="filename">git format-patch</code> and <code class="filename">git send-email</code>.
1594 You can find information on how to submit later in this chapter.</p></li></ul></div><p>
1595 </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>
1596 The Yocto Project uses its own implementation of
1597 <a class="ulink" href="" target="_top">Bugzilla</a> to track bugs.
1598 Implementations of Bugzilla work well for group development because they track bugs and code
1599 changes, can be used to communicate changes and problems with developers, can be used to
1600 submit and review patches, and can be used to manage quality assurance.
1601 The home page for the Yocto Project implementation of Bugzilla is
1602 <a class="ulink" href="" target="_top"></a>.
1603 </p><p>
1604 Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
1605 such as when discovering an issue with some component of the build system that acts contrary
1606 to the documentation or your expectations.
1607 Following is the general procedure for submitting a new bug using the Yocto Project
1608 Bugzilla.
1609 You can find more information on defect management, bug tracking, and feature request
1610 processes all accomplished through the Yocto Project Bugzilla on the wiki page
1611 <a class="ulink" href="" target="_top">here</a>.
1612 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Always use the Yocto Project implementation of Bugzilla to submit
1613 a bug.</p></li><li class="listitem"><p>When submitting a new bug, be sure to choose the appropriate
1614 Classification, Product, and Component for which the issue was found.
1615 Defects for Yocto Project fall into one of four classifications: Yocto Projects,
1616 Infrastructure, Poky, and Yocto Metadata Layers.
1617 Each of these Classifications break down into multiple Products and, in some
1618 cases, multiple Components.</p></li><li class="listitem"><p>Use the bug form to choose the correct Hardware and Architecture
1619 for which the bug applies.</p></li><li class="listitem"><p>Indicate the Yocto Project version you were using when the issue
1620 occurred.</p></li><li class="listitem"><p>Be sure to indicate the Severity of the bug.
1621 Severity communicates how the bug impacted your work.</p></li><li class="listitem"><p>Provide a brief summary of the issue.
1622 Try to limit your summary to just a line or two and be sure to capture the
1623 essence of the issue.</p></li><li class="listitem"><p>Provide a detailed description of the issue.
1624 You should provide as much detail as you can about the context, behavior, output,
1625 and so forth that surround the issue.
1626 You can even attach supporting files for output or log by using the "Add an attachment"
1627 button.</p></li><li class="listitem"><p>Submit the bug by clicking the "Submit Bug" button.</p></li></ol></div><p>
1628 </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>
1629 Contributions to the Yocto Project and OpenEmbedded are very welcome.
1630 Because the system is extremely configurable and flexible, we recognize that developers
1631 will want to extend, configure or optimize it for their specific uses.
1632 You should send patches to the appropriate mailing list so that they
1633 can be reviewed and merged by the appropriate maintainer.
1634 For a list of the Yocto Project and related mailing lists, see the
1635 "<a class="link" href="#resources-mailinglist" target="_top">Mailing lists</a>" section in
1636 the Yocto Project Reference Manual.
1637 </p><p>
1638 The following is some guidance on which mailing list to use for what type of change:
1639 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>For changes to the core metadata, send your patch to the
1640 <a class="ulink" href="" target="_top">openembedded-core</a> mailing list.
1641 For example, a change to anything under the <code class="filename">meta</code> or
1642 <code class="filename">scripts</code> directories
1643 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>
1644 directory), send your patch to the
1645 <a class="ulink" href="" 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
1646 <a class="ulink" href="" target="_top">poky</a> mailing list.</p></li><li class="listitem"><p>For changes to other layers hosted on (unless the
1647 layer's documentation specifies otherwise), tools, and Yocto Project
1648 documentation, use the
1649 <a class="ulink" href="" target="_top">yocto</a> mailing list.</p></li><li class="listitem"><p>For additional recipes that do not fit into the core metadata,
1650 you should determine which layer the recipe should go into and submit the
1651 change in the manner recommended by the documentation (e.g. README) supplied
1652 with the layer. If in doubt, please ask on the
1653 <a class="ulink" href="" target="_top">yocto</a> or
1654 <a class="ulink" href="" target="_top">openembedded-devel</a>
1655 mailing lists.</p></li></ul></div><p>
1656 </p><p>
1657 When you send a patch, be sure to include a "Signed-off-by:"
1658 line in the same style as required by the Linux kernel.
1659 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
1660 as follows:
1661 </p><pre class="literallayout">
1662 Developer's Certificate of Origin 1.1
1664 By making a contribution to this project, I certify that:
1666 (a) The contribution was created in whole or in part by me and I
1667 have the right to submit it under the open source license
1668 indicated in the file; or
1670 (b) The contribution is based upon previous work that, to the best
1671 of my knowledge, is covered under an appropriate open source
1672 license and I have the right under that license to submit that
1673 work with modifications, whether created in whole or in part
1674 by me, under the same open source license (unless I am
1675 permitted to submit under a different license), as indicated
1676 in the file; or
1678 (c) The contribution was provided directly to me by some other
1679 person who certified (a), (b) or (c) and I have not modified
1680 it.
1682 (d) I understand and agree that this project and the contribution
1683 are public and that a record of the contribution (including all
1684 personal information I submit with it, including my sign-off) is
1685 maintained indefinitely and may be redistributed consistent with
1686 this project or the open source license(s) involved.
1687 </pre><p>
1688 </p><p>
1689 In a collaborative environment, it is necessary to have some sort of standard
1690 or method through which you submit changes.
1691 Otherwise, things could get quite chaotic.
1692 One general practice to follow is to make small, controlled changes.
1693 Keeping changes small and isolated aids review, makes merging/rebasing easier
1694 and keeps the change history clean when anyone needs to refer to it in future.
1695 </p><p>
1696 When you make a commit, you must follow certain standards established by the
1697 OpenEmbedded and Yocto Project development teams.
1698 For each commit, you must provide a single-line summary of the change and you
1699 should almost always provide a more detailed description of what you did (i.e.
1700 the body of the commit message).
1701 The only exceptions for not providing a detailed description would be if your
1702 change is a simple, self-explanatory change that needs no description.
1703 Here are the guidelines for composing a commit message:
1704 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Provide a single-line, short summary of the change.
1705 This summary is typically viewable in the "shortlist" of changes.
1706 Thus, providing something short and descriptive that gives the reader
1707 a summary of the change is useful when viewing a list of many commits.
1708 This should be prefixed by the recipe name (if changing a recipe), or
1709 else the short form path to the file being changed.
1710 </p></li><li class="listitem"><p>For the body of the commit message, provide detailed information
1711 that describes what you changed, why you made the change, and the approach
1712 you used. It may also be helpful if you mention how you tested the change.
1713 Provide as much detail as you can in the body of the commit message.
1714 </p></li><li class="listitem"><p>If the change addresses a specific bug or issue that is
1715 associated with a bug-tracking ID, include a reference to that ID in
1716 your detailed description.
1717 For example, the Yocto Project uses a specific convention for bug
1718 references - any commit that addresses a specific bug should include the
1719 bug ID in the description (typically at the beginning) as follows:
1720 </p><pre class="literallayout">
1721 [YOCTO #&lt;bug-id&gt;]
1723 &lt;detailed description of change&gt;
1724 </pre></li></ul></div><p>
1725 </p><p>
1726 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
1727 wiki page:
1728 <a class="ulink" href="" target="_top"></a>.
1729 </p><p>
1730 Following are general instructions for both pushing changes upstream and for submitting
1731 changes as patches.
1732 </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>
1733 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
1734 </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>
1735 command on each file you changed.</p></li><li class="listitem"><p>Commit the change by using the <code class="filename">git commit</code>
1736 command and push it to the "contrib" repository.
1737 Be sure to provide a commit message that follows the project’s commit message standards
1738 as described earlier.</p></li><li class="listitem"><p>Notify the maintainer that you have pushed a change by making a pull
1739 request.
1740 The Yocto Project provides two scripts that conveniently let you generate and send
1741 pull requests to the Yocto Project.
1742 These scripts are <code class="filename">create-pull-request</code> and
1743 <code class="filename">send-pull-request</code>.
1744 You can find these scripts in the <code class="filename">scripts</code> directory of the
1745 Yocto Project file structure.</p><p>Using these scripts correctly formats the requests without introducing any
1746 whitespace or HTML formatting.
1747 The maintainer that receives your patches needs to be able to save and apply them
1748 directly from your emails.
1749 Using these scripts is the preferred method for sending patches.</p><p>For help on using these scripts, simply provide the
1750 <code class="filename">-h</code> argument as follows:
1751 </p><pre class="literallayout">
1752 $ ~/poky/scripts/create-pull-request -h
1753 $ ~/poky/scripts/send-pull-request -h
1754 </pre></li></ul></div><p>
1755 </p><p>
1756 You can find general Git information on how to push a change upstream in the
1757 <a class="ulink" href="" target="_top">Git Community Book</a>.
1758 </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>
1759 You can submit patches without using the <code class="filename">create-pull-request</code> and
1760 <code class="filename">send-pull-request</code> scripts described in the previous section.
1761 Keep in mind, the preferred method is to use the scripts, however.
1762 </p><p>
1763 Depending on the components changed, you need to submit the email to a specific
1764 mailing list.
1765 For some guidance on which mailing list to use, see the list in the
1766 "<a class="link" href="#how-to-submit-a-change" title="3.9. How to Submit a Change">How to Submit a Change</a>" section
1767 earlier in this manual.
1768 For a description of the available mailing lists, see
1769 "<a class="link" href="#resources-mailinglist" target="_top">Mailing Lists</a>"
1770 section in the Yocto Project Reference Manual.
1771 </p><p>
1772 Here is the general procedure on how to submit a patch through email without using the
1773 scripts:
1774 </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>
1775 command on each file you changed.</p></li><li class="listitem"><p>Commit the change by using the
1776 <code class="filename">git commit --signoff</code> command.
1777 Using the <code class="filename">--signoff</code> option identifies you as the person
1778 making the change and also satisfies the Developer's Certificate of
1779 Origin (DCO) shown earlier.</p><p>When you form a commit you must follow certain standards established by the
1780 Yocto Project development team.
1781 See the earlier section
1782 "<a class="link" href="#how-to-submit-a-change" title="3.9. How to Submit a Change">How to Submit a Change</a>"
1783 for Yocto Project commit message standards.</p></li><li class="listitem"><p>Format the commit into an email message.
1784 To format commits, use the <code class="filename">git format-patch</code> command.
1785 When you provide the command, you must include a revision list or a number of patches
1786 as part of the command.
1787 For example, these two commands each take the most recent single commit and
1788 format it as an email message in the current directory:
1789 </p><pre class="literallayout">
1790 $ git format-patch -1
1791 $ git format-patch HEAD~
1792 </pre><p>After the command is run, the current directory contains a
1793 numbered <code class="filename">.patch</code> file for the commit.</p><p>If you provide several commits as part of the command,
1794 the <code class="filename">git format-patch</code> command produces a numbered
1795 series of files in the current directory – one for each commit.
1796 If you have more than one patch, you should also use the
1797 <code class="filename">--cover</code> option with the command, which generates a
1798 cover letter as the first "patch" in the series.
1799 You can then edit the cover letter to provide a description for
1800 the series of patches.
1801 For information on the <code class="filename">git format-patch</code> command,
1802 see <code class="filename">GIT_FORMAT_PATCH(1)</code> displayed using the
1803 <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
1804 or to OpenEmbedded, you might consider requesting a contrib area and the
1805 necessary associated rights.</div></li><li class="listitem"><p>Import the files into your mail client by using the
1806 <code class="filename">git send-email</code> command.
1807 </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
1808 the proper Git packages installed.
1809 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
1810 or remote Mail Transport Agent (MTA) such as
1811 <code class="filename">msmtp</code>, <code class="filename">sendmail</code>, or through a direct
1812 <code class="filename">smtp</code> configuration in your Git <code class="filename">config</code>
1813 file.
1814 If you are submitting patches through email only, it is very important
1815 that you submit them without any whitespace or HTML formatting that
1816 either you or your mailer introduces.
1817 The maintainer that receives your patches needs to be able to save and
1818 apply them directly from your emails.
1819 A good way to verify that what you are sending will be applicable by the
1820 maintainer is to do a dry run and send them to yourself and then
1821 save and apply them as the maintainer would.</p><p>The <code class="filename">git send-email</code> command is the preferred method
1822 for sending your patches since there is no risk of compromising whitespace
1823 in the body of the message, which can occur when you use your own mail client.
1824 The command also has several options that let you
1825 specify recipients and perform further editing of the email message.
1826 For information on how to use the <code class="filename">git send-email</code> command,
1827 use the <code class="filename">man git-send-email</code> command.</p></li></ul></div><p>
1828 </p></div></div></div>
1830 <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
1831 <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>
1832 This chapter describes standard tasks such as adding new
1833 software packages, extending or customizing images, and porting work to
1834 new hardware (adding a new machine).
1835 The chapter also describes how to combine multiple
1836 versions of library files into a single image, how to handle a package name alias, and
1837 gives advice about how to make changes to the Yocto Project to achieve the best results.
1838 </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>
1839 The OpenEmbedded build system supports organizing <a class="link" href="#metadata">metadata</a>
1840 into multiple layers.
1841 Layers allow you to isolate different types of customizations from each other.
1842 You might find it tempting to keep everything in one layer when working on a single project.
1843 However, the more modular you organize your metadata, the easier it is to cope with future changes.
1844 </p><p>
1845 To illustrate how layers are used to keep things modular, consider machine customizations.
1846 These types of customizations typically reside in a BSP Layer.
1847 Furthermore, the machine customizations should be isolated from recipes and metadata that support
1848 a new GUI environment, for example.
1849 This situation gives you a couple a layers: one for the machine configurations, and one for the
1850 GUI environment.
1851 It is important to understand, however, that the BSP layer can still make machine-specific
1852 additions to recipes within the GUI environment layer without polluting the GUI layer itself
1853 with those machine-specific changes.
1854 You can accomplish this through a recipe that is a BitBake append
1855 (<code class="filename">.bbappend</code>) file, which is described later in this section.
1856 </p><p>
1857 </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>
1858 The source directory contains several layers right out of the box.
1859 You can easily identify a layer in the source directory by its folder name.
1860 Folders that are layers begin with the string <code class="filename">meta</code>.
1861 For example, when you set up the <a class="link" href="#source-directory">source directory</a>
1862 structure, you will see several layers: <code class="filename">meta</code>, <code class="filename">meta-demoapps</code>,
1863 <code class="filename">meta-skeleton</code>, and <code class="filename">meta-yocto</code>.
1864 Each of these folders is a layer.
1865 </p><p>
1866 Furthermore, if you set up a local copy of the <code class="filename">meta-intel</code> Git repository
1867 and then explore that folder, you will discover many BSP layers within the
1868 <code class="filename">meta-intel</code> layer.
1869 For more information on BSP layers, see the
1870 "<a class="link" href="#bsp-layers" target="_top">BSP Layers</a>"
1871 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
1872 </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>
1873 It is very easy to create your own layer to use with the OpenEmbedded build system.
1874 Follow these general steps to create your layer:
1875 </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,
1876 you should be sure someone has not already created a layer containing the metadata
1877 you need.
1878 You can see the
1879 <a class="ulink" href="" target="_top"><code class="filename">LayerIndex</code></a>
1880 for a list of layers from the OpenEmbedded community that can be used in the
1881 Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>Create a Directory:</em></span> Create the directory
1882 for your layer.
1883 Traditionally, prepend the name of the folder with the string
1884 <code class="filename">meta</code>.
1885 For example:
1886 </p><pre class="literallayout">
1887 meta-mylayer
1888 meta-GUI_xyz
1889 meta-mymachine
1890 </pre></li><li class="listitem"><p><span class="emphasis"><em>Create a Layer Configuration File:</em></span> Inside your new
1891 layer folder, you need to create a <code class="filename">conf/layer.conf</code> file.
1892 It is easiest to take an existing layer configuration file and copy that to your
1893 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
1894 required syntax:
1895 </p><pre class="literallayout">
1896 # We have a conf and classes directory, add to BBPATH
1899 # We have recipes-* directories, add to BBFILES
1900 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
1901 ${LAYERDIR}/recipes-*/*/*.bbappend"
1903 BBFILE_COLLECTIONS += "yocto"
1904 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
1905 BBFILE_PRIORITY_yocto = "5"
1906 </pre><p>In the previous example, the recipes for the layers are added to
1907 <code class="filename"><a class="link" href="#var-BBFILES" target="_top">BBFILES</a></code>.
1908 The
1909 <code class="filename"><a class="link" href="#var-BBFILE_COLLECTIONS" target="_top">BBFILE_COLLECTIONS</a></code>
1910 variable is then appended with the layer name.
1911 The
1912 <code class="filename"><a class="link" href="#var-BBFILE_PATTERN" target="_top">BBFILE_PATTERN</a></code>
1913 variable is set to a regular expression and is used to match files
1914 from <code class="filename">BBFILES</code> into a particular layer.
1915 In this case, immediate expansion of
1916 <code class="filename"><a class="link" href="#var-LAYERDIR" target="_top">LAYERDIR</a></code>
1917 sets <code class="filename">BBFILE_PATTERN</code> to the layer's path.
1918 The
1919 <code class="filename"><a class="link" href="#var-BBFILE_PRIORITY" target="_top">BBFILE_PRIORITY</a></code>
1920 variable then assigns a priority to the layer.
1921 Applying priorities is useful in situations where the same package might appear in multiple
1922 layers and allows you to choose what layer should take precedence.</p><p>Note the use of the
1923 <code class="filename"><a class="link" href="#var-LAYERDIR" target="_top">LAYERDIR</a></code>
1924 variable with the immediate expansion operator.
1925 The <code class="filename">LAYERDIR</code> variable expands to the directory of the current layer and
1926 requires the immediate expansion operator so that BitBake does not wait to expand the variable
1927 when it's parsing a different directory.</p><p>Through the use of the <code class="filename">BBPATH</code> variable,
1928 BitBake locates <code class="filename">.bbclass</code> files, configuration
1929 files, and files that are included with <code class="filename">include</code>
1930 and <code class="filename">require</code> statements.
1931 For these cases, BitBake uses the first file with the matching name found in
1932 <code class="filename">BBPATH</code>.
1933 This is similar to the way the <code class="filename">PATH</code> variable is used for binaries.
1934 We recommend, therefore, that you use unique <code class="filename">.bbclass</code>
1935 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,
1936 add the content.
1937 If the layer adds support for a machine, add the machine configuration in
1938 a <code class="filename">conf/machine/</code> file within the layer.
1939 If the layer adds distro policy, add the distro configuration in a
1940 <code class="filename">conf/distro/</code> file with the layer.
1941 If the layer introduces new recipes, put the recipes you need in
1942 <code class="filename">recipes-*</code> subdirectories within the layer.</p></li></ol></div><p>
1943 </p><p>
1944 To create layers that are easier to maintain, you should consider the following:
1945 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Avoid "overlaying" entire recipes from other layers in your
1946 configuration.
1947 In other words, don't copy an entire recipe into your layer and then modify it.
1948 Use <code class="filename">.bbappend</code> files to override the parts of the
1949 recipe you need to modify.</p></li><li class="listitem"><p>Avoid duplicating include files.
1950 Use <code class="filename">.bbappend</code> files for each recipe that uses an include
1951 file.
1952 Or, if you are introducing a new recipe that requires the included file, use the
1953 path relative to the original layer directory to refer to the file.
1954 For example, use <code class="filename">require recipes-core/somepackage/</code>
1955 instead of <code class="filename">require</code>.
1956 If you're finding you have to overlay the include file, it could indicate a
1957 deficiency in the include file in the layer to which it originally belongs.
1958 If this is the case, you need to address that deficiency instead of overlaying
1959 the include file.
1960 For example, consider how Qt 4 database support plugins are configured.
1961 The source directory does not have
1962 MySQL or PostgreSQL, however OpenEmbedded's
1963 layer <code class="filename">meta-oe</code> does.
1964 Consequently, <code class="filename">meta-oe</code> uses <code class="filename">.bbappend</code>
1965 files to modify the <code class="filename">QT_SQL_DRIVER_FLAGS</code> variable to enable
1966 the appropriate plugins.
1967 This variable was added to the <code class="filename"></code> include file in
1968 the source directory specifically to allow the <code class="filename">meta-oe</code> layer
1969 to be able to control which plugins are built.</p></li></ul></div><p>
1970 </p><p>
1971 We also recommend the following:
1972 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Store custom layers in a Git repository that uses the
1973 <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>
1974 directories in the
1975 <a class="link" href="#source-directory">source directory</a>.</p></li></ul></div><p>
1976 Following these recommendations keeps your source directory and
1977 its configuration entirely inside the Yocto Project's core base.
1978 </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>
1979 Before the OpenEmbedded build system can use your new layer, you need to enable it.
1980 To enable your layer, simply add your layer's path to the
1981 <code class="filename"><a class="link" href="#var-BBLAYERS" target="_top">BBLAYERS</a></code>
1982 variable in your <code class="filename">conf/bblayers.conf</code> file, which is found in the
1983 <a class="link" href="#build-directory">build directory</a>.
1984 The following example shows how to enable a layer named <code class="filename">meta-mylayer</code>:
1985 </p><pre class="literallayout">
1986 LCONF_VERSION = "1"
1988 BBFILES ?= ""
1989 BBLAYERS = " \
1990 /path/to/poky/meta \
1991 /path/to/poky/meta-yocto \
1992 /path/to/poky/meta-mylayer \
1993 "
1994 </pre><p>
1995 </p><p>
1996 BitBake parses each <code class="filename">conf/layer.conf</code> file as specified in the
1997 <code class="filename">BBLAYERS</code> variable within the <code class="filename">conf/bblayers.conf</code>
1998 file.
1999 During the processing of each <code class="filename">conf/layer.conf</code> file, BitBake adds the
2000 recipes, classes and configurations contained within the particular layer to the source
2001 directory.
2002 </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>
2003 Recipes used to append metadata to other recipes are called BitBake append files.
2004 BitBake append files use the <code class="filename">.bbappend</code> file type suffix, while
2005 underlying recipes to which metadata is being appended use the
2006 <code class="filename">.bb</code> file type suffix.
2007 </p><p>
2008 A <code class="filename">.bbappend</code> file allows your layer to make additions or
2009 changes to the content of another layer's recipe without having to copy the other
2010 recipe into your layer.
2011 Your <code class="filename">.bbappend</code> file resides in your layer, while the underlying
2012 <code class="filename">.bb</code> recipe file to which you are appending metadata
2013 resides in a different layer.
2014 </p><p>
2015 Append files files must have the same name as the underlying recipe.
2016 For example, the append file <code class="filename">someapp_1.3.bbappend</code> must
2017 apply to <code class="filename"></code>.
2018 This means the original recipe and append file names are version number specific.
2019 If the underlying recipe is renamed to update to a newer version, the
2020 corresponding <code class="filename">.bbappend</code> file must be renamed as well.
2021 During the build process, BitBake displays an error on starting if it detects a
2022 <code class="filename">.bbappend</code> file that does not have an underlying recipe
2023 with a matching name.
2024 </p><p>
2025 Being able to append information to an existing recipe not only avoids duplication,
2026 but also automatically applies recipe changes in a different layer to your layer.
2027 If you were copying recipes, you would have to manually merge changes as they occur.
2028 </p><p>
2029 As an example, consider the main formfactor recipe and a corresponding formfactor
2030 append file both from the
2031 <a class="link" href="#source-directory">source directory</a>.
2032 Here is the main formfactor recipe, which is named <code class="filename"></code> and
2033 located in the meta layer at <code class="filename">meta/recipes-bsp/formfactor</code>:
2034 </p><pre class="literallayout">
2035 DESCRIPTION = "Device formfactor information"
2036 SECTION = "base"
2037 LICENSE = "MIT"
2038 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
2039 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
2040 PR = "r20"
2042 SRC_URI = "file://config file://machconfig"
2043 S = "${WORKDIR}"
2048 do_install() {
2049 # Only install file if it has a contents
2050 install -d ${D}${sysconfdir}/formfactor/
2051 install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
2052 if [ -s "${S}/machconfig" ]; then
2053 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
2054 fi
2055 }
2056 </pre><p>
2057 Here is the append file, which is named <code class="filename">formfactor_0.0.bbappend</code> and is from the
2058 Crown Bay BSP Layer named <code class="filename">meta-intel/meta-crownbay</code>.
2059 The file is in <code class="filename">recipes-bsp/formfactor</code>:
2060 </p><pre class="literallayout">
2061 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2063 PRINC = "1"
2064 </pre><p>
2065 This example adds or overrides files in
2066 <a class="link" href="#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a>
2067 within a <code class="filename">.bbappend</code> by extending the path BitBake uses to search for files.
2068 The most reliable way to do this is by prepending the
2069 <code class="filename">FILESEXTRAPATHS</code> variable.
2070 For example, if you have your files in a directory that is named the same as your package
2071 (<a class="link" href="#var-PN" target="_top"><code class="filename">PN</code></a>),
2072 you can add this directory by adding the following to your <code class="filename">.bbappend</code> file:
2073 </p><pre class="literallayout">
2074 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2075 </pre><p>
2076 Using the immediate expansion assignment operator <code class="filename">:=</code> is important because
2077 of the reference to <code class="filename">THISDIR</code>.
2078 The trailing colon character is important as it ensures that items in the list remain
2079 colon-separated.
2080 </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.
2081 You should never set this variable yourself.
2082 Using <code class="filename">_prepend</code> ensures your path will be searched prior to other
2083 paths in the final list.
2084 </div><p>
2085 </p><p>
2086 For another example on how to use a <code class="filename">.bbappend</code> file, see the
2087 "<a class="link" href="#changing-recipes-kernel" title="A.5.2.4. Changing  recipes-kernel">Changing <code class="filename">recipes-kernel</code></a>"
2088 section.
2089 </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>
2090 Each layer is assigned a priority value.
2091 Priority values control which layer takes precedence if there are recipe files with
2092 the same name in multiple layers.
2093 For these cases, the recipe file from the layer with a higher priority number taking precedence.
2094 Priority values also affect the order in which multiple <code class="filename">.bbappend</code> files
2095 for the same recipe are applied.
2096 You can either specify the priority manually, or allow the build system to calculate it
2097 based on the layer's dependencies.
2098 </p><p>
2099 To specify the layer's priority manually, use the
2100 <a class="link" href="#var-BBFILE_PRIORITY" target="_top"><code class="filename">BBFILE_PRIORITY</code></a>
2101 variable.
2102 For example:
2103 </p><pre class="literallayout">
2105 </pre><p>
2106 </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
2107 <a class="link" href="#var-PV" target="_top"><code class="filename">PV</code></a>
2108 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
2109 <code class="filename">.conf</code> or <code class="filename">.bbclass</code> files.
2110 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>
2111 You can use the BitBake layer management tool to provide a view into the structure of
2112 recipes across a multi-layer project.
2113 Being able to generate output that reports on configured layers with their paths and
2114 priorities and on <code class="filename">.bbappend</code> files and their applicable recipes
2115 can help to reveal potential problems.
2116 </p><p>
2117 Use the following form when running the layer management tool.
2118 </p><pre class="literallayout">
2119 $ bitbake-layers &lt;command&gt; [arguments]
2120 </pre><p>
2121 The following list describes the available commands:
2122 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><span class="emphasis"><em>help:</em></span></code>
2123 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>
2124 Show the current configured layers.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-recipes:</em></span></code>
2125 Lists available recipes and the layers that provide them.
2126 </p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-overlayed:</em></span></code>
2127 Lists overlayed recipes.
2128 A recipe is overlayed when a recipe with the same name exists in another layer
2129 that has a higher layer priority.
2130 </p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>show-appends:</em></span></code>
2131 Lists <code class="filename">.bbappend</code> files and the recipe files to which
2132 they apply.</p></li><li class="listitem"><p><code class="filename"><span class="emphasis"><em>flatten:</em></span></code>
2133 Flattens the layer configuration into a separate output directory.
2134 Flattening your layer configuration builds a "flattened" directory that contains
2135 the contents of all layers, with any overlayed recipes removed and any
2136 <code class="filename">.bbappend</code> files appended to the corresponding recipes.
2137 You might have to perform some manual cleanup of the flattened layer as follows:
2138 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>Non-recipe files (such as patches) are overwritten.
2139 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
2140 the <code class="filename">layer.conf</code> file.
2141 Only the lowest priority layer's <code class="filename">layer.conf</code> is used.
2142 </p></li><li class="listitem"><p>Overridden and appended items from <code class="filename">.bbappend</code>
2143 files need to be cleaned up.
2144 The contents of each <code class="filename">.bbappend</code> end up in the
2145 flattened recipe.
2146 However, if there are appended or changed variable values, you need to tidy
2147 these up yourself.
2148 Consider the following example.
2149 Here, the <code class="filename">bitbake-layers</code> command adds the line
2150 <code class="filename">#### bbappended ...</code> so that you know where the following
2151 lines originate:
2152 </p><pre class="literallayout">
2153 ...
2154 DESCRIPTION = "A useful utility"
2155 ...
2156 EXTRA_OECONF = "--enable-something"
2157 ...
2159 #### bbappended from meta-anotherlayer ####
2161 DESCRIPTION = "Customized utility"
2162 EXTRA_OECONF += "--enable-somethingelse"
2163 </pre><p>
2164 Ideally, you would tidy up these utilities as follows:
2165 </p><pre class="literallayout">
2166 ...
2167 DESCRIPTION = "Customized utility"
2168 ...
2169 EXTRA_OECONF = "--enable-something --enable-somethingelse"
2170 ...
2171 </pre></li></ul></div></li></ul></div><p>
2172 </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>
2173 You can customize images to satisfy particular requirements.
2174 This section describes several methods and provides guidelines for each.
2175 </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>
2176 One way to get additional software into an image is to create a custom image.
2177 The following example shows the form for the two lines you need:
2178 </p><pre class="literallayout">
2179 IMAGE_INSTALL = "task-core-x11-base package1 package2"
2181 inherit core-image
2182 </pre><p>
2183 </p><p>
2184 By creating a custom image, a developer has total control
2185 over the contents of the image.
2186 It is important to use the correct names of packages in the
2187 <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code>
2188 variable.
2189 You must use the OpenEmbedded notation and not the Debian notation for the names
2190 (e.g. <code class="filename">eglibc-dev</code> instead of <code class="filename">libc6-dev</code>).
2191 </p><p>
2192 The other method for creating a custom image is to base it on an existing image.
2193 For example, if you want to create an image based on <code class="filename">core-image-sato</code>
2194 but add the additional package <code class="filename">strace</code> to the image,
2195 copy the <code class="filename">meta/recipes-sato/images/</code> to a
2196 new <code class="filename">.bb</code> and add the following line to the end of the copy:
2197 </p><pre class="literallayout">
2198 IMAGE_INSTALL += "strace"
2199 </pre><p>
2200 </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>
2201 For complex custom images, the best approach is to create a custom task package
2202 that is used to build the image or images.
2203 A good example of a tasks package is
2204 <code class="filename">meta/recipes-core/tasks/</code>
2205 The
2206 <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a></code>
2207 variable lists the task packages to build along with the complementary
2208 <code class="filename">-dbg</code> and <code class="filename">-dev</code> packages.
2209 For each package added, you can use
2210 <code class="filename"><a class="link" href="#var-RDEPENDS" target="_top">RDEPENDS</a></code>
2211 and
2212 <code class="filename"><a class="link" href="#var-RRECOMMENDS" target="_top">RRECOMMENDS</a></code>
2213 entries to provide a list of packages the parent task package should contain.
2214 Following is an example:
2215 </p><pre class="literallayout">
2216 DESCRIPTION = "My Custom Tasks"
2218 PACKAGES = "\
2219 task-custom-apps \
2220 task-custom-apps-dbg \
2221 task-custom-apps-dev \
2222 task-custom-tools \
2223 task-custom-tools-dbg \
2224 task-custom-tools-dev \
2225 "
2227 RDEPENDS_task-custom-apps = "\
2228 dropbear \
2229 portmap \
2230 psplash"
2232 RDEPENDS_task-custom-tools = "\
2233 oprofile \
2234 oprofileui-server \
2235 lttng-control \
2236 lttng-viewer"
2238 RRECOMMENDS_task-custom-tools = "\
2239 kernel-module-oprofile"
2240 </pre><p>
2241 </p><p>
2242 In the previous example, two task packages are created with their dependencies and their
2243 recommended package dependencies listed: <code class="filename">task-custom-apps</code>, and
2244 <code class="filename">task-custom-tools</code>.
2245 To build an image using these task packages, you need to add
2246 <code class="filename">task-custom-apps</code> and/or
2247 <code class="filename">task-custom-tools</code> to
2248 <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code>.
2249 For other forms of image dependencies see the other areas of this section.
2250 </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
2251 <code class="filename">EXTRA_IMAGE_FEATURES</code></h3></div></div></div><p>
2252 Ultimately users might want to add extra image features to the set by using the
2253 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" target="_top">IMAGE_FEATURES</a></code>
2254 variable.
2255 To create these features, the best reference is
2256 <code class="filename">meta/classes/core-image.bbclass</code>, which shows how to achieve this.
2257 In summary, the file looks at the contents of the
2258 <code class="filename">IMAGE_FEATURES</code>
2259 variable and then maps that into a set of tasks or packages.
2260 Based on this information the
2261 <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top"> IMAGE_INSTALL</a></code>
2262 variable is generated automatically.
2263 Users can add extra features by extending the class or creating a custom class for use
2264 with specialized image <code class="filename">.bb</code> files.
2265 You can also add more features by configuring the
2266 <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" target="_top">EXTRA_IMAGE_FEATURES</a></code>
2267 variable in the <code class="filename">local.conf</code> file found in the source directory
2268 located in the build directory.
2269 </p><p>
2270 The Yocto Project ships with two SSH servers you can use in your images:
2271 Dropbear and OpenSSH.
2272 Dropbear is a minimal SSH server appropriate for resource-constrained environments,
2273 while OpenSSH is a well-known standard SSH server implementation.
2274 By default, the <code class="filename">core-image-sato</code> image is configured to use Dropbear.
2275 The <code class="filename">core-image-basic</code> and <code class="filename">core-image-lsb</code>
2276 images both include OpenSSH.
2277 The <code class="filename">core-image-minimal</code> image does not contain an SSH server.
2278 To change these defaults, edit the <code class="filename">IMAGE_FEATURES</code> variable
2279 so that it sets the image you are working with to include
2280 <code class="filename">ssh-server-dropbear</code> or <code class="filename">ssh-server-openssh</code>.
2281 </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>
2282 It is possible to customize image contents by using variables from your
2283 local configuration in your <code class="filename">conf/local.conf</code> file.
2284 Because it is limited to local use, this method generally only allows you to
2285 add packages and is not as flexible as creating your own customized image.
2286 When you add packages using local variables this way, you need to realize that
2287 these variable changes affect all images at the same time and might not be
2288 what you require.
2289 </p><p>
2290 The simplest way to add extra packages to all images is by using the
2291 <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" target="_top">IMAGE_INSTALL</a></code>
2292 variable with the <code class="filename">_append</code> operator:
2293 </p><pre class="literallayout">
2294 IMAGE_INSTALL_append = " strace"
2295 </pre><p>
2296 Use of the syntax is important.
2297 Specifically, the space between the quote and the package name, which is
2298 <code class="filename">strace</code> in this example.
2299 This space is required since the <code class="filename">_append</code>
2300 operator does not add the space.
2301 </p><p>
2302 Furthermore, you must use <code class="filename">_append</code> instead of the <code class="filename">+=</code>
2303 operator if you want to avoid ordering issues.
2304 The reason for this is because doing so unconditionally appends to the variable and
2305 avoids ordering problems due to the variable being set in image recipes and
2306 <code class="filename">.bbclass</code> files with operators like <code class="filename">?=</code>.
2307 Using <code class="filename">_append</code> ensures the operation takes affect.
2308 </p><p>
2309 As shown in its simplest use, <code class="filename">IMAGE_INSTALL_append</code> affects
2310 all images.
2311 It is possible to extend the syntax so that the variable applies to a specific image only.
2312 Here is an example:
2313 </p><pre class="literallayout">
2314 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
2315 </pre><p>
2316 This example adds <code class="filename">strace</code> to <code class="filename">core-image-minimal</code>
2317 only.
2318 </p><p>
2319 You can add packages using a similar approach through the
2320 <code class="filename"><a class="link" href="#var-CORE_IMAGE_EXTRA_INSTALL" target="_top">CORE_IMAGE_EXTRA_INSTALL</a></code>
2321 variable.
2322 If you use this variable, only <code class="filename">core-image-*</code> images are affected.
2323 </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>
2324 To add a package you need to write a recipe for it.
2325 Writing a recipe means creating a <code class="filename">.bb</code> file that sets some
2326 variables.
2327 For information on variables that are useful for recipes and for information about recipe naming
2328 issues, see the
2329 "<a class="link" href="#ref-varlocality-recipe-required" target="_top">Required</a>"
2330 section of the Yocto Project Reference Manual.
2331 </p><p>
2332 Before writing a recipe from scratch, it is often useful to check
2333 whether someone else has written one already.
2334 OpenEmbedded is a good place to look as it has a wider scope and range of packages.
2335 Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
2336 you find there should work for you.
2337 </p><p>
2338 For new packages, the simplest way to add a recipe is to base it on a similar
2339 pre-existing recipe.
2340 The sections that follow provide some examples that show how to add standard
2341 types of packages.
2342 </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>
2343 Building an application from a single file that is stored locally (e.g. under
2344 <code class="filename">files/</code>) requires a recipe that has the file listed in
2345 the
2346 <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>
2347 variable.
2348 Additionally, you need to manually write the <code class="filename">do_compile</code> and
2349 <code class="filename">do_install</code> tasks.
2350 The <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code>
2351 variable defines the
2352 directory containing the source code, which is set to
2353 <code class="filename"><a class="link" href="#var-WORKDIR" target="_top">
2354 WORKDIR</a></code> in this case - the directory BitBake uses for the build.
2355 </p><pre class="literallayout">
2356 DESCRIPTION = "Simple helloworld application"
2357 SECTION = "examples"
2358 LICENSE = "MIT"
2359 LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
2360 PR = "r0"
2362 SRC_URI = "file://helloworld.c"
2364 S = "${WORKDIR}"
2366 do_compile() {
2367 ${CC} helloworld.c -o helloworld
2368 }
2370 do_install() {
2371 install -d ${D}${bindir}
2372 install -m 0755 helloworld ${D}${bindir}
2373 }
2374 </pre><p>
2375 </p><p>
2376 By default, the <code class="filename">helloworld</code>, <code class="filename">helloworld-dbg</code>,
2377 and <code class="filename">helloworld-dev</code> packages are built.
2378 For information on how to customize the packaging process, see the
2379 "<a class="link" href="#splitting-an-application-into-multiple-packages" title="4.3.4. Splitting an Application into Multiple Packages">Splitting an Application
2380 into Multiple Packages</a>" section.
2381 </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>
2382 Applications that use Autotools such as <code class="filename">autoconf</code> and
2383 <code class="filename">automake</code> require a recipe that has a source archive listed in
2384 <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code> and
2385 also inherits Autotools, which instructs BitBake to use the
2386 <code class="filename">autotools.bbclass</code> file, which contains the definitions of all the steps
2387 needed to build an Autotool-based application.
2388 The result of the build is automatically packaged.
2389 And, if the application uses NLS for localization, packages with local information are
2390 generated (one package per language).
2391 Following is one example: (<code class="filename"></code>)
2392 </p><pre class="literallayout">
2393 DESCRIPTION = "GNU Helloworld application"
2394 SECTION = "examples"
2395 LICENSE = "GPLv2+"
2396 LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
2397 PR = "r0"
2399 SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
2401 inherit autotools gettext
2402 </pre><p>
2403 </p><p>
2404 The variable
2405 <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" target="_top">LIC_FILES_CHKSUM</a></code>
2406 is used to track source license changes as described in the
2407 "<a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" target="_top">Track License Changes</a>" section.
2408 You can quickly create Autotool-based recipes in a manner similar to the previous example.
2409 </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>
2410 Applications that use GNU <code class="filename">make</code> also require a recipe that has
2411 the source archive listed in
2412 <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>.
2413 You do not need to add a <code class="filename">do_compile</code> step since by default BitBake
2414 starts the <code class="filename">make</code> command to compile the application.
2415 If you need additional <code class="filename">make</code> options you should store them in the
2416 <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" target="_top">EXTRA_OEMAKE</a></code>
2417 variable.
2418 BitBake passes these options into the <code class="filename">make</code> GNU invocation.
2419 Note that a <code class="filename">do_install</code> task is still required.
2420 Otherwise BitBake runs an empty <code class="filename">do_install</code> task by default.
2421 </p><p>
2422 Some applications might require extra parameters to be passed to the compiler.
2423 For example, the application might need an additional header path.
2424 You can accomplish this by adding to the
2425 <code class="filename"><a class="link" href="#var-CFLAGS" target="_top">CFLAGS</a></code> variable.
2426 The following example shows this:
2427 </p><pre class="literallayout">
2428 CFLAGS_prepend = "-I ${S}/include "
2429 </pre><p>
2430 </p><p>
2431 In the following example, <code class="filename">mtd-utils</code> is a makefile-based package:
2432 </p><pre class="literallayout">
2433 DESCRIPTION = "Tools for managing memory technology devices."
2434 SECTION = "base"
2435 DEPENDS = "zlib lzo e2fsprogs util-linux"
2436 HOMEPAGE = ""
2437 LICENSE = "GPLv2+"
2438 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2439 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2441 SRC_URI = "git://;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
2442 file://add-exclusion-to-mkfs-jffs2-git-2.patch"
2444 S = "${WORKDIR}/git/"
2446 PR = "r1"
2448 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
2451 do_install () {
2452 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
2453 INCLUDEDIR=${includedir}
2454 install -d ${D}${includedir}/mtd/
2455 for f in ${S}/include/mtd/*.h; do
2456 install -m 0644 $f ${D}${includedir}/mtd/
2457 done
2458 }
2462 BBCLASSEXTEND = "native"
2463 </pre><p>
2464 </p><p>
2465 If your sources are available as a tarball instead of a Git repository, you
2466 will need to provide the URL to the tarball as well as an
2467 <code class="filename">md5</code> or <code class="filename">sha256</code> sum of
2468 the download.
2469 Here is an example:
2470 </p><pre class="literallayout">
2471 SRC_URI=""
2472 SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
2473 </pre><p>
2474 You can generate the <code class="filename">md5</code> or <code class="filename">sha256</code> sums
2475 by using the <code class="filename">md5sum</code> or <code class="filename">sha256sum</code> commands
2476 with the target file as the only argument.
2477 Here is an example:
2478 </p><pre class="literallayout">
2479 $ md5sum mtd-utils-1.4.9.tar.bz2
2480 82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
2481 </pre><p>
2482 </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>
2483 You can use the variables
2484 <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a></code> and
2485 <code class="filename"><a class="link" href="#var-FILES" target="_top">FILES</a></code>
2486 to split an application into multiple packages.
2487 </p><p>
2488 Following is an example that uses the <code class="filename">libXpm</code> recipe.
2489 By default, this recipe generates a single package that contains the library along
2490 with a few binaries.
2491 You can modify the recipe to split the binaries into separate packages:
2492 </p><pre class="literallayout">
2493 require
2495 DESCRIPTION = "X11 Pixmap library"
2496 LICENSE = "X-BSD"
2497 LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
2498 DEPENDS += "libxext libsm libxt"
2499 PR = "r3"
2500 PE = "1"
2502 XORG_PN = "libXpm"
2504 PACKAGES =+ "sxpm cxpm"
2505 FILES_cxpm = "${bindir}/cxpm"
2506 FILES_sxpm = "${bindir}/sxpm"
2507 </pre><p>
2508 </p><p>
2509 In the previous example, we want to ship the <code class="filename">sxpm</code>
2510 and <code class="filename">cxpm</code> binaries in separate packages.
2511 Since <code class="filename">bindir</code> would be packaged into the main
2512 <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code>
2513 package by default, we prepend the
2514 <code class="filename"><a class="link" href="#var-PACKAGES" target="_top">PACKAGES</a>
2515 </code> variable so additional package names are added to the start of list.
2516 This results in the extra
2517 <code class="filename"><a class="link" href="#var-FILES" target="_top">FILES</a>_*</code>
2518 variables then containing information that define which files and
2519 directories go into which packages.
2520 Files included by earlier packages are skipped by latter packages.
2521 Thus, the main
2522 <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code> package
2523 does not include the above listed files.
2524 </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>
2525 If you are building a library and the library offers static linking, you can control
2526 which static library files (<code class="filename">*.a</code> files) get included in the
2527 built library.
2528 </p><p>
2529 The <code class="filename">PACKAGES</code> and <code class="filename">FILES_*</code> variables in the
2530 <code class="filename">meta/conf/bitbake.conf</code> configuration file define how files installed
2531 by the <code class="filename">do_install</code> task are packaged.
2532 By default, the <code class="filename">PACKAGES</code> variable contains
2533 <code class="filename">${PN}-staticdev</code>, which includes all static library files.
2534 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2535 Previously released versions of the Yocto Project defined the static library files
2536 through <code class="filename">${PN}-dev</code>.
2537 </div><p>
2538 Following, is part of the BitBake configuration file.
2539 You can see where the static library files are defined:
2540 </p><pre class="literallayout">
2541 PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
2542 PACKAGES_DYNAMIC = "${PN}-locale-*"
2543 FILES = ""
2545 FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
2546 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
2547 ${base_bindir}/* ${base_sbindir}/* \
2548 ${base_libdir}/*${SOLIBS} \
2549 ${datadir}/${BPN} ${libdir}/${BPN}/* \
2550 ${datadir}/pixmaps ${datadir}/applications \
2551 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
2552 ${libdir}/bonobo/servers"
2554 FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
2555 ${datadir}/gnome/help"
2556 SECTION_${PN}-doc = "doc"
2558 FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
2559 ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
2560 ${datadir}/aclocal ${base_libdir}/*.o"
2561 SECTION_${PN}-dev = "devel"
2562 ALLOW_EMPTY_${PN}-dev = "1"
2563 RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
2565 FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
2566 SECTION_${PN}-staticdev = "devel"
2567 RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
2568 </pre><p>
2569 </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>
2570 To add a post-installation script to a package, add a <code class="filename">pkg_postinst_PACKAGENAME()
2571 </code> function to the <code class="filename">.bb</code> file and use
2572 <code class="filename">PACKAGENAME</code> as the name of the package you want to attach to the
2573 <code class="filename">postinst</code> script.
2574 Normally
2575 <code class="filename"><a class="link" href="#var-PN" target="_top">PN</a></code>
2576 can be used, which automatically expands to <code class="filename">PACKAGENAME</code>.
2577 A post-installation function has the following structure:
2578 </p><pre class="literallayout">
2579 pkg_postinst_PACKAGENAME () {
2580 #!/bin/sh -e
2581 # Commands to carry out
2582 }
2583 </pre><p>
2584 </p><p>
2585 The script defined in the post-installation function is called when the
2586 root filesystem is created.
2587 If the script succeeds, the package is marked as installed.
2588 If the script fails, the package is marked as unpacked and the script is
2589 executed when the image boots again.
2590 </p><p>
2591 Sometimes it is necessary for the execution of a post-installation
2592 script to be delayed until the first boot.
2593 For example, the script might need to be executed on the device itself.
2594 To delay script execution until boot time, use the following structure in the
2595 post-installation script:
2596 </p><pre class="literallayout">
2597 pkg_postinst_PACKAGENAME () {
2598 #!/bin/sh -e
2599 if [ x"$D" = "x" ]; then
2600 # Actions to carry out on the device go here
2601 else
2602 exit 1
2603 fi
2604 }
2605 </pre><p>
2606 </p><p>
2607 The previous example delays execution until the image boots again because the
2608 <code class="filename"><a class="link" href="#var-D" target="_top">D</a></code>
2609 variable points
2610 to the directory containing the image when the root filesystem is created at build time but
2611 is unset when executed on the first boot.
2612 </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>
2613 Adding a new machine to the Yocto Project is a straightforward process.
2614 This section provides information that gives you an idea of the changes you must make.
2615 The information covers adding machines similar to those the Yocto Project already supports.
2616 Although well within the capabilities of the Yocto Project, adding a totally new architecture
2617 might require
2618 changes to <code class="filename">gcc/eglibc</code> and to the site information, which is
2619 beyond the scope of this manual.
2620 </p><p>
2621 For a complete example that shows how to add a new machine,
2622 see the
2623 "<a class="link" href="#dev-manual-bsp-appendix" target="_top">BSP Development Example</a>"
2624 in Appendix A.
2625 </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>
2626 To add a machine configuration you need to add a <code class="filename">.conf</code> file
2627 with details of the device being added to the <code class="filename">conf/machine/</code> file.
2628 The name of the file determines the name the OpenEmbedded build system
2629 uses to reference the new machine.
2630 </p><p>
2631 The most important variables to set in this file are as follows:
2632 </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">
2633 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">
2634 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">
2635 MACHINE_FEATURES</a></code> (e.g. "apm screen wifi")</p></li></ul></div><p>
2636 </p><p>
2637 You might also need these variables:
2638 </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">
2639 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">
2640 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">
2641 IMAGE_FSTYPES</a></code> (e.g. "tar.gz jffs2")</p></li></ul></div><p>
2642 </p><p>
2643 You can find full details on these variables in the reference section.
2644 You can leverage many existing machine <code class="filename">.conf</code> files from
2645 <code class="filename">meta/conf/machine/</code>.
2646 </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>
2647 The OpenEmbedded build system needs to be able to build a kernel for the machine.
2648 You need to either create a new kernel recipe for this machine, or extend an
2649 existing recipe.
2650 You can find several kernel examples in the
2651 source directory at <code class="filename">meta/recipes-kernel/linux</code>
2652 that you can use as references.
2653 </p><p>
2654 If you are creating a new recipe, normal recipe-writing rules apply for setting
2655 up a
2656 <code class="filename"><a class="link" href="#var-SRC_URI" target="_top">SRC_URI</a></code>.
2657 Thus, you need to specify any necessary patches and set
2658 <code class="filename"><a class="link" href="#var-S" target="_top">S</a></code> to point at the source code.
2659 You need to create a <code class="filename">configure</code> task that configures the
2660 unpacked kernel with a defconfig.
2661 You can do this by using a <code class="filename">make defconfig</code> command or,
2662 more commonly, by copying in a suitable <code class="filename">defconfig</code> file and and then running
2663 <code class="filename">make oldconfig</code>.
2664 By making use of <code class="filename">inherit kernel</code> and potentially some of the
2665 <code class="filename">linux-*.inc</code> files, most other functionality is
2666 centralized and the the defaults of the class normally work well.
2667 </p><p>
2668 If you are extending an existing kernel, it is usually a matter of adding a
2669 suitable defconfig file.
2670 The file needs to be added into a location similar to defconfig files
2671 used for other machines in a given kernel.
2672 A possible way to do this is by listing the file in the
2673 <code class="filename">SRC_URI</code> and adding the machine to the expression in
2674 <code class="filename"><a class="link" href="#var-COMPATIBLE_MACHINE" target="_top">COMPATIBLE_MACHINE</a></code>:
2675 </p><pre class="literallayout">
2676 COMPATIBLE_MACHINE = '(qemux86|qemumips)'
2677 </pre><p>
2678 </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>
2679 A formfactor configuration file provides information about the
2680 target hardware for which the image is being built and information that
2681 the build system cannot obtain from other sources such as the kernel.
2682 Some examples of information contained in a formfactor configuration file include
2683 framebuffer orientation, whether or not the system has a keyboard,
2684 the positioning of the keyboard in relation to the screen, and
2685 the screen resolution.
2686 </p><p>
2687 The build system uses reasonable defaults in most cases, but if customization is
2688 necessary you need to create a <code class="filename">machconfig</code> file
2689 in the <code class="filename">meta/recipes-bsp/formfactor/files</code>
2690 directory.
2691 This directory contains directories for specific machines such as
2692 <code class="filename">qemuarm</code> and <code class="filename">qemux86</code>.
2693 For information about the settings available and the defaults, see the
2694 <code class="filename">meta/recipes-bsp/formfactor/files/config</code> file found in the
2695 same area.
2696 Following is an example for qemuarm:
2697 </p><pre class="literallayout">
2705 #DISPLAY_BPP=16
2706 DISPLAY_DPI=150
2708 </pre><p>
2709 </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>
2710 The build system offers the ability to build libraries with different
2711 target optimizations or architecture formats and combine these together
2712 into one system image.
2713 You can link different binaries in the image
2714 against the different libraries as needed for specific use cases.
2715 This feature is called "Multilib."
2716 </p><p>
2717 An example would be where you have most of a system compiled in 32-bit
2718 mode using 32-bit libraries, but you have something large, like a database
2719 engine, that needs to be a 64-bit application and use 64-bit libraries.
2720 Multilib allows you to get the best of both 32-bit and 64-bit libraries.
2721 </p><p>
2722 While the Multilib feature is most commonly used for 32 and 64-bit differences,
2723 the approach the build system uses facilitates different target optimizations.
2724 You could compile some binaries to use one set of libraries and other binaries
2725 to use other different sets of libraries.
2726 The libraries could differ in architecture, compiler options, or other
2727 optimizations.
2728 </p><p>
2729 This section overviews the Multilib process only.
2730 For more details on how to implement Multilib, see the
2731 <a class="ulink" href="" target="_top">Multilib</a> wiki
2732 page.
2733 </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>
2734 User-specific requirements drive the Multilib feature,
2735 Consequently, there is no one "out-of-the-box" configuration that likely
2736 exists to meet your needs.
2737 </p><p>
2738 In order to enable Multilib, you first need to ensure your recipe is
2739 extended to support multiple libraries.
2740 Many standard recipes are already extended and support multiple libraries.
2741 You can check in the <code class="filename">meta/conf/multilib.conf</code>
2742 configuration file in the source directory to see how this is
2743 done using the <code class="filename">BBCLASSEXTEND</code> variable.
2744 Eventually, all recipes will be covered and this list will be unneeded.
2745 </p><p>
2746 For the most part, the Multilib class extension works automatically to
2747 extend the package name from <code class="filename">${PN}</code> to
2748 <code class="filename">${MLPREFIX}${PN}</code>, where <code class="filename">MLPREFIX</code>
2749 is the particular multilib (e.g. "lib32-" or "lib64-").
2750 Standard variables such as <code class="filename">DEPENDS</code>,
2751 <code class="filename">RDEPENDS</code>, <code class="filename">RPROVIDES</code>,
2752 <code class="filename">RRECOMMENDS</code>, <code class="filename">PACKAGES</code>, and
2753 <code class="filename">PACKAGES_DYNAMIC</code> are automatically extended by the system.
2754 If you are extending any manual code in the recipe, you can use the
2755 <code class="filename">${MLPREFIX}</code> variable to ensure those names are extended
2756 correctly.
2757 This automatic extension code resides in <code class="filename">multilib.bbclass</code>.
2758 </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>
2759 After you have set up the recipes, you need to define the actual
2760 combination of multiple libraries you want to build.
2761 You accomplish this through your <code class="filename">local.conf</code>
2762 configuration file in the
2763 <a class="link" href="#build-directory">build directory</a>.
2764 An example configuration would be as follows:
2765 </p><pre class="literallayout">
2766 MACHINE = "qemux86-64"
2767 require conf/multilib.conf
2768 MULTILIBS = "multilib:lib32"
2769 DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
2770 IMAGE_INSTALL = "lib32-connman"
2771 </pre><p>
2772 This example enables an
2773 additional library named <code class="filename">lib32</code> alongside the
2774 normal target packages.
2775 When combining these "lib32" alternatives, the example uses "x86" for tuning.
2776 For information on this particular tuning, see
2777 <code class="filename">meta/conf/machine/include/ia32/</code>.
2778 </p><p>
2779 The example then includes <code class="filename">lib32-connman</code>
2780 in all the images, which illustrates one method of including a
2781 multiple library dependency.
2782 You can use a normal image build to include this dependency,
2783 for example:
2784 </p><pre class="literallayout">
2785 $ bitbake core-image-sato
2786 </pre><p>
2787 You can also build Multilib packages specifically with a command like this:
2788 </p><pre class="literallayout">
2789 $ bitbake lib32-connman
2790 </pre><p>
2791 </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>
2792 Different packaging systems have different levels of native Multilib
2793 support.
2794 For the RPM Package Management System, the following implementation details
2795 exist:
2796 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A unique architecture is defined for the Multilib packages,
2797 along with creating a unique deploy folder under
2798 <code class="filename">tmp/deploy/rpm</code> in the
2799 <a class="link" href="#build-directory">build directory</a>.
2800 For example, consider <code class="filename">lib32</code> in a
2801 <code class="filename">qemux86-64</code> image.
2802 The possible architectures in the system are "all", "qemux86_64",
2803 "lib32_qemux86_64", and "lib32_x86".</p></li><li class="listitem"><p>The <code class="filename">${MLPREFIX}</code> variable is stripped from
2804 <code class="filename">${PN}</code> during RPM packaging.
2805 The naming for a normal RPM package and a Multilib RPM package in a
2806 <code class="filename">qemux86-64</code> system resolves to something similar to
2807 <code class="filename">bash-4.1-r2.x86_64.rpm</code> and
2808 <code class="filename">bash-4.1.r2.lib32_x86.rpm</code>, respectively.
2809 </p></li><li class="listitem"><p>When installing a Multilib image, the RPM backend first
2810 installs the base image and then installs the Multilib libraries.
2811 </p></li><li class="listitem"><p>The build system relies on RPM to resolve the identical files in the
2812 two (or more) Multilib packages.</p></li></ul></div><p>
2813 </p><p>
2814 For the IPK Package Management System, the following implementation details exist:
2815 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The <code class="filename">${MLPREFIX}</code> is not stripped from
2816 <code class="filename">${PN}</code> during IPK packaging.
2817 The naming for a normal RPM package and a Multilib IPK package in a
2818 <code class="filename">qemux86-64</code> system resolves to something like
2819 <code class="filename">bash_4.1-r2.x86_64.ipk</code> and
2820 <code class="filename">lib32-bash_4.1-rw_x86.ipk</code>, respectively.
2821 </p></li><li class="listitem"><p>The IPK deploy folder is not modified with
2822 <code class="filename">${MLPREFIX}</code> because packages with and without
2823 the Multilib feature can exist in the same folder due to the
2824 <code class="filename">${PN}</code> differences.</p></li><li class="listitem"><p>IPK defines a sanity check for Multilib installation
2825 using certain rules for file comparison, overridden, etc.
2826 </p></li></ul></div><p>
2827 </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>
2828 Configuring the Yocto Project kernel consists of making sure the <code class="filename">.config</code>
2829 file has all the right information in it for the image you are building.
2830 You can use the <code class="filename">menuconfig</code> tool and configuration fragments to
2831 make sure your <code class="filename">.config</code> file is just how you need it.
2832 This section describes how to use <code class="filename">menuconfig</code>, create and use
2833 configuration fragments, and how to interactively tweak your <code class="filename">.config</code>
2834 file to create the leanest kernel configuration file possible.
2835 </p><p>
2836 For concepts on kernel configuration, see the
2837 "<a class="link" href="#kernel-configuration" target="_top">Kernel Configuration</a>"
2838 section in the Yocto Project Kernel Architecture and Use Manual.
2839 </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>
2840 The easiest way to define kernel configurations is to set them through the
2841 <code class="filename">menuconfig</code> tool.
2842 For general information on <code class="filename">menuconfig</code>, see
2843 <a class="ulink" href="" target="_top"></a>.
2844 </p><p>
2845 To use the <code class="filename">menuconfig</code> tool in the Yocto Project development
2846 environment, you must build the tool using BitBake.
2847 The following commands build and invoke <code class="filename">menuconfig</code> assuming the
2848 source directory top-level folder is <code class="filename">~/poky</code>:
2849 </p><pre class="literallayout">
2850 $ cd ~/poky
2851 $ source oe-init-build-env
2852 $ bitbake linux-yocto -c menuconfig
2853 </pre><p>
2854 Once <code class="filename">menuconfig</code> comes up, its standard interface allows you to
2855 examine and configure all the kernel configuration parameters.
2856 Once you have made your changes, simply exit the tool and save your changes to
2857 create an updated version of the <code class="filename">.config</code> configuration file.
2858 </p><p>
2859 For an example that shows how to change a specific kernel option
2860 using <code class="filename">menuconfig</code>, see the
2861 "<a class="link" href="#changing-the-config-smp-configuration-using-menuconfig" title="B.2.3. Changing the  CONFIG_SMP Configuration Using  menuconfig">Changing
2862 the <code class="filename">CONFIG_SMP</code> Configuration Using <code class="filename">menuconfig</code></a>"
2863 section.
2864 </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>
2865 Configuration fragments are simply kernel options that appear in a file
2866 placed where the OpenEmbedded build system can find and apply them.
2867 Syntactically, the configuration statement is identical to what would appear
2868 in the <code class="filename">.config</code> file, which is in the
2869 <a class="link" href="#build-directory">build directory</a> in
2870 <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>.
2871 </p><p>
2872 It is simple to create a configuration fragment.
2873 For example, issuing the following from the shell creates a configuration fragment
2874 file named <code class="filename">my_smp.cfg</code> that enables multi-processor support
2875 within the kernel:
2876 </p><pre class="literallayout">
2877 $ echo "CONFIG_SMP=y" &gt;&gt; my_smp.cfg
2878 </pre><p>
2879 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2880 All configuration files must use the <code class="filename">.cfg</code> extension in order
2881 for the OpenEmbedded build system to recognize them as a configuration fragment.
2882 </div><p>
2883 </p><p>
2884 Where do you put your configuration files?
2885 You can place these configuration files in the same area pointed to by
2886 <code class="filename">SRC_URI</code>.
2887 The OpenEmbedded build system will pick up the configuration and add it to the
2888 kernel's configuration.
2889 For example, suppose you had a set of configuration options in a file called
2890 <code class="filename">myconfig.cfg</code>.
2891 If you put that file inside a directory named <code class="filename">/linux-yocto</code>
2892 that resides in the same directory as the kernel's append file and then add
2893 a <code class="filename">SRC_URI</code> statement such as the following to the kernel's append file,
2894 those configuration options will be picked up and applied when the kernel is built.
2895 </p><pre class="literallayout">
2896 SRC_URI += "file://myconfig.cfg"
2897 </pre><p>
2898 </p><p>
2899 As mentioned earlier, you can group related configurations into multiple files and
2900 name them all in the <code class="filename">SRC_URI</code> statement as well.
2901 For example, you could group separate configurations specifically for Ethernet and graphics
2902 into their own files and add those by using a <code class="filename">SRC_URI</code> statement like the
2903 following in your append file:
2904 </p><pre class="literallayout">