summaryrefslogtreecommitdiffstats
path: root/documentation/getting-started/getting-started.html
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-30 11:31:29 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:30 +0000
commitf9db48724f4800e7810daad34e4a55551f29fb1c (patch)
treee6bfe1c4a37e01571eabf36f9e95b2cf70edeeb7 /documentation/getting-started/getting-started.html
parent52b871825f9446b162cd871c829b7458e34878d7 (diff)
downloadpoky-f9db48724f4800e7810daad34e4a55551f29fb1c.tar.gz
getting-started: Removed accidental tracked files
I accidentally pushed a commit after building out the new getting-started manual before applying some key files to the .gitignore file. So, the HTML, TGZ, and eclipse/* stuff got tracked in Git. I don't want that. So I had to use the 'git rm' command to untrack those files. (From yocto-docs rev: 217f6db7f741cee266885a845b2b0e7faf96e537) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/getting-started/getting-started.html')
-rw-r--r--documentation/getting-started/getting-started.html3900
1 files changed, 0 insertions, 3900 deletions
diff --git a/documentation/getting-started/getting-started.html b/documentation/getting-started/getting-started.html
deleted file mode 100644
index 19c1384f8e..0000000000
--- a/documentation/getting-started/getting-started.html
+++ /dev/null
@@ -1,3900 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Getting Started With Yocto Project</title><link rel="stylesheet" type="text/css" href="getting-started-style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="book" title="Getting Started With Yocto Project" id="getting-started-manual" lang="en"><div class="titlepage"><div><div><h1 class="title">
3 Getting Started With Yocto Project
4 </h1></div><div><div class="authorgroup">
5 <div class="author"><h3 class="author"><span class="firstname">Scott</span> <span class="surname">Rifenbark</span></h3><div class="affiliation">
6 <span class="orgname">Scotty's Documentation Services, INC<br /></span>
7 </div><code class="email">&lt;<a class="email" href="mailto:srifenbark@gmail.com">srifenbark@gmail.com</a>&gt;</code></div>
8 </div></div><div><p class="copyright">Copyright © 2010-2018 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="idm45705112624512"></a>
9 <p>
10 Permission is granted to copy, distribute and/or modify this document under
11 the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">
12 Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</a> as published by
13 Creative Commons.
14 </p>
15 <div class="note" title="Manual Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Manual Notes</h3>
16 <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
17 This version of the
18 <span class="emphasis"><em>Yocto Project Overview Manual</em></span>
19 is for the 2.5 release of the
20 Yocto Project.
21 To be sure you have the latest version of the manual
22 for this release, use the manual from the
23 <a class="ulink" href="http://www.yoctoproject.org/documentation" target="_top">Yocto Project documentation page</a>.
24 </p></li><li class="listitem"><p>
25 For manuals associated with other releases of the Yocto
26 Project, go to the
27 <a class="ulink" href="http://www.yoctoproject.org/documentation" target="_top">Yocto Project documentation page</a>
28 and use the drop-down "Active Releases" button
29 and choose the manual associated with the desired
30 Yocto Project.
31 </p></li><li class="listitem"><p>
32 To report any inaccuracies or problems with this
33 manual, send an email to the Yocto Project
34 discussion group at
35 <code class="filename">yocto@yoctoproject.com</code> or log into
36 the freenode <code class="filename">#yocto</code> channel.
37 </p></li></ul></div>
38 </div>
39 </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><strong>Revision History</strong></th></tr>
40 <tr><td align="left">Revision 2.5</td><td align="left">April 2018</td></tr><tr><td align="left" colspan="2">The initial document released with the Yocto Project 2.5 Release.</td></tr>
41 </table></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="#overview-manual-intro">1. The Yocto Project Overview Manual</a></span></dt><dd><dl><dt><span class="section"><a href="#overview-welcome">1.1. Welcome</a></span></dt><dt><span class="section"><a href="#overview-other-information">1.2. Other Information</a></span></dt></dl></dd><dt><span class="chapter"><a href="#overview-development-environment">2. The Yocto Project Development Environment</a></span></dt><dd><dl><dt><span class="section"><a href="#yp-intro">2.1. Introduction</a></span></dt><dt><span class="section"><a href="#open-source-philosophy">2.2. Open Source Philosophy</a></span></dt><dt><span class="section"><a href="#workflows">2.3. Workflows</a></span></dt><dt><span class="section"><a href="#git">2.4. Git</a></span></dt><dd><dl><dt><span class="section"><a href="#repositories-tags-and-branches">2.4.1. Repositories, Tags, and Branches</a></span></dt><dt><span class="section"><a href="#basic-commands">2.4.2. Basic Commands</a></span></dt></dl></dd><dt><span class="section"><a href="#yocto-project-repositories">2.5. Yocto Project Source Repositories</a></span></dt><dt><span class="section"><a href="#licensing">2.6. Licensing</a></span></dt><dt><span class="section"><a href="#recipe-syntax">2.7. Recipe Syntax</a></span></dt><dt><span class="section"><a href="#development-concepts">2.8. Development Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#user-configuration">2.8.1. User Configuration</a></span></dt><dt><span class="section"><a href="#metadata-machine-configuration-and-policy-configuration">2.8.2. Metadata, Machine Configuration, and Policy Configuration</a></span></dt><dt><span class="section"><a href="#sources-dev-environment">2.8.3. Sources</a></span></dt><dt><span class="section"><a href="#package-feeds-dev-environment">2.8.4. Package Feeds</a></span></dt><dt><span class="section"><a href="#bitbake-dev-environment">2.8.5. BitBake</a></span></dt><dt><span class="section"><a href="#images-dev-environment">2.8.6. Images</a></span></dt><dt><span class="section"><a href="#sdk-dev-environment">2.8.7. Application Development SDK</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#overview-concepts">3. Yocto Project Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#yocto-project-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#metadata-virtual-providers">3.1.3. Metadata (Virtual Providers)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.4. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.5. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#cross-development-toolchain-generation">3.2. Cross-Development Toolchain Generation</a></span></dt><dt><span class="section"><a href="#shared-state-cache">3.3. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.3.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#overview-checksums">3.3.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.3.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.3.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#automatically-added-runtime-dependencies">3.4. Automatically Added Runtime Dependencies</a></span></dt><dt><span class="section"><a href="#fakeroot-and-pseudo">3.5. Fakeroot and Pseudo</a></span></dt><dt><span class="section"><a href="#wayland">3.6. Wayland</a></span></dt><dd><dl><dt><span class="section"><a href="#wayland-support">3.6.1. Support</a></span></dt><dt><span class="section"><a href="#enabling-wayland-in-an-image">3.6.2. Enabling Wayland in an Image</a></span></dt><dt><span class="section"><a href="#running-weston">3.6.3. Running Weston</a></span></dt></dl></dd><dt><span class="section"><a href="#overview-licenses">3.7. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.7.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.7.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.8. x32 psABI</a></span></dt></dl></dd></dl></div>
42
43
44 <div class="chapter" title="Chapter 1. The Yocto Project Overview Manual" id="overview-manual-intro"><div class="titlepage"><div><div><h2 class="title">Chapter 1. The Yocto Project Overview Manual<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-manual-intro">¶</a></span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#overview-welcome">1.1. Welcome</a></span></dt><dt><span class="section"><a href="#overview-other-information">1.2. Other Information</a></span></dt></dl></div><div class="section" title="1.1. Welcome"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview-welcome">1.1. Welcome<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-welcome">¶</a></span></h2></div></div></div><p>
45 Welcome to the Yocto Project Overview Manual!
46 This manual introduces the Yocto Project by providing concepts,
47 software overviews, best-known-methods (BKMs), and any other
48 high-level introductory information suitable for a new Yocto
49 Project user.
50 </p><p>
51 The following list describes what you can get from this manual:
52 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
53 <span class="emphasis"><em>Major Topic:</em></span>
54 Provide a high-level description of this major topic.
55 </p></li><li class="listitem"><p>
56 <span class="emphasis"><em>Major Topic:</em></span>
57 Provide a high-level description of this major topic.
58 </p></li><li class="listitem"><p>
59 <span class="emphasis"><em>Major Topic:</em></span>
60 Provide a high-level description of this major topic.
61 </p></li><li class="listitem"><p>
62 <span class="emphasis"><em>Major Topic:</em></span>
63 Provide a high-level description of this major topic.
64 </p></li></ul></div><p>
65 </p><p>
66 This manual does not give you the following:
67 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
68 <span class="emphasis"><em>Step-by-step Instructions for Development Tasks:</em></span>
69 Instructional procedures reside in other manuals within
70 the Yocto Project documentation set.
71 For example, the
72 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html" target="_top">Yocto Project Development Tasks Manual</a>
73 provides examples on how to perform various development
74 tasks.
75 As another example, the
76 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a>
77 manual contains detailed instructions on how to install an
78 SDK, which is used to develop applications for target
79 hardware.
80 </p></li><li class="listitem"><p>
81 <span class="emphasis"><em>Reference Material:</em></span>
82 This type of material resides in an appropriate reference
83 manual.
84 For example, system variables are documented in the
85 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html" target="_top">Yocto Project Reference Manual</a>.
86 As another example, the
87 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>
88 contains reference information on BSPs.
89 </p></li><li class="listitem"><p>
90 <span class="emphasis"><em>Detailed Public Information Not Specific to the
91 Yocto Project:</em></span>
92 For example, exhaustive information on how to use the
93 Source Control Manager Git is better covered with Internet
94 searches and official Git Documentation than through the
95 Yocto Project documentation.
96 </p></li></ul></div><p>
97 </p></div><div class="section" title="1.2. Other Information"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview-other-information">1.2. Other Information<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-other-information">¶</a></span></h2></div></div></div><p>
98 Because this manual presents information for many different
99 topics, supplemental information is recommended for full
100 comprehension.
101 For additional introductory information on the Yocto Project, see
102 the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a>.
103 You can find an introductory to using the Yocto Project by working
104 through the
105 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/yocto-project-qs/yocto-project-qs.html" target="_top">Yocto Project Quick Start</a>.
106 </p><p>
107 For a comprehensive list of links and other documentation, see the
108 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#resources-links-and-related-documentation" target="_top">Links and Related Documentation</a>"
109 section in the Yocto Project Reference Manual.
110 </p></div></div>
111
112 <div class="chapter" title="Chapter 2. The Yocto Project Development Environment" id="overview-development-environment"><div class="titlepage"><div><div><h2 class="title">Chapter 2. The Yocto Project Development Environment<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-development-environment">¶</a></span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#yp-intro">2.1. Introduction</a></span></dt><dt><span class="section"><a href="#open-source-philosophy">2.2. Open Source Philosophy</a></span></dt><dt><span class="section"><a href="#workflows">2.3. Workflows</a></span></dt><dt><span class="section"><a href="#git">2.4. Git</a></span></dt><dd><dl><dt><span class="section"><a href="#repositories-tags-and-branches">2.4.1. Repositories, Tags, and Branches</a></span></dt><dt><span class="section"><a href="#basic-commands">2.4.2. Basic Commands</a></span></dt></dl></dd><dt><span class="section"><a href="#yocto-project-repositories">2.5. Yocto Project Source Repositories</a></span></dt><dt><span class="section"><a href="#licensing">2.6. Licensing</a></span></dt><dt><span class="section"><a href="#recipe-syntax">2.7. Recipe Syntax</a></span></dt><dt><span class="section"><a href="#development-concepts">2.8. Development Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#user-configuration">2.8.1. User Configuration</a></span></dt><dt><span class="section"><a href="#metadata-machine-configuration-and-policy-configuration">2.8.2. Metadata, Machine Configuration, and Policy Configuration</a></span></dt><dt><span class="section"><a href="#sources-dev-environment">2.8.3. Sources</a></span></dt><dt><span class="section"><a href="#package-feeds-dev-environment">2.8.4. Package Feeds</a></span></dt><dt><span class="section"><a href="#bitbake-dev-environment">2.8.5. BitBake</a></span></dt><dt><span class="section"><a href="#images-dev-environment">2.8.6. Images</a></span></dt><dt><span class="section"><a href="#sdk-dev-environment">2.8.7. Application Development SDK</a></span></dt></dl></dd></dl></div><p>
113 This chapter takes a look at the Yocto Project development
114 environment and also provides a detailed look at what goes on during
115 development in that environment.
116 The chapter provides Yocto Project Development environment concepts that
117 help you understand how work is accomplished in an open source environment,
118 which is very different as compared to work accomplished in a closed,
119 proprietary environment.
120</p><p>
121 Specifically, this chapter addresses open source philosophy, workflows,
122 Git, source repositories, licensing, recipe syntax, and development
123 syntax.
124</p><div class="section" title="2.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="yp-intro">2.1. Introduction<span class="permalink"><a alt="Permalink" title="Permalink" href="#yp-intro">¶</a></span></h2></div></div></div><p>
125 The Yocto Project is an open-source collaboration project whose
126 focus is for developers of embedded Linux systems.
127 Among other things, the Yocto Project uses an
128 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-system-term" target="_top">OpenEmbedded build system</a>.
129 The build system, which is based on the OpenEmbedded (OE) project and
130 uses the
131 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a> tool,
132 constructs complete Linux images for architectures based on ARM, MIPS,
133 PowerPC, x86 and x86-64.
134 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
135 Historically, the OpenEmbedded build system, which is the
136 combination of BitBake and OE components, formed a reference
137 build host that was known as
138 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#poky" target="_top">Poky</a>"
139 (<span class="emphasis"><em>Pah</em></span>-kee).
140 The term "Poky", as used throughout the Yocto Project Documentation
141 set, can have different meanings.
142 </div><p>
143 The Yocto Project provides various ancillary tools for the embedded
144 developer and also features the Sato reference User Interface, which
145 is optimized for stylus-driven, low-resolution screens.
146 </p><div class="mediaobject" align="center"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr><td align="center"><img src="figures/YP-flow-diagram.png" align="middle" width="720" /></td></tr></table></div><p>
147 Here are some highlights for the Yocto Project:
148 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
149 Provides a recent Linux kernel along with a set of system
150 commands and libraries suitable for the embedded
151 environment.
152 </p></li><li class="listitem"><p>
153 Makes available system components such as X11, GTK+, Qt,
154 Clutter, and SDL (among others) so you can create a rich user
155 experience on devices that have display hardware.
156 For devices that do not have a display or where you wish to
157 use alternative UI frameworks, these components need not be
158 installed.
159 </p></li><li class="listitem"><p>
160 Creates a focused and stable core compatible with the
161 OpenEmbedded project with which you can easily and reliably
162 build and develop.
163 </p></li><li class="listitem"><p>
164 Fully supports a wide range of hardware and device emulation
165 through the Quick EMUlator (QEMU).
166 </p></li><li class="listitem"><p>
167 Provides a layer mechanism that allows you to easily extend
168 the system, make customizations, and keep them organized.
169 </p></li></ul></div><p>
170 You can use the Yocto Project to generate images for many kinds
171 of devices.
172 As mentioned earlier, the Yocto Project supports creation of
173 reference images that you can boot within and emulate using QEMU.
174 The standard example machines target QEMU full-system
175 emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and
176 PowerPC architectures.
177 Beyond emulation, you can use the layer mechanism to extend
178 support to just about any platform that Linux can run on and that
179 a toolchain can target.
180 </p><p>
181 Another Yocto Project feature is the Sato reference User
182 Interface.
183 This optional UI that is based on GTK+ is intended for devices with
184 restricted screen sizes and is included as part of the
185 OpenEmbedded Core layer so that developers can test parts of the
186 software stack.
187 </p><p>
188 While the Yocto Project does not provide a strict testing framework,
189 it does provide or generate for you artifacts that let you perform
190 target-level and emulated testing and debugging.
191 Additionally, if you are an
192 <span class="trademark">Eclipse</span>™ IDE user, you can
193 install an Eclipse Yocto Plug-in to allow you to develop within that
194 familiar environment.
195 </p><p>
196 By default, using the Yocto Project to build an image creates a Poky
197 distribution.
198 However, you can create your own distribution by providing key
199 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>.
200 A good example is Angstrom, which has had a distribution
201 based on the Yocto Project since its inception.
202 Other examples include commercial distributions like
203 <a class="ulink" href="https://www.yoctoproject.org/organization/wind-river-systems" target="_top">Wind River Linux</a>,
204 <a class="ulink" href="https://www.yoctoproject.org/organization/mentor-graphics" target="_top">Mentor Embedded Linux</a>,
205 <a class="ulink" href="https://www.yoctoproject.org/organization/enea-ab" target="_top">ENEA Linux</a>
206 and <a class="ulink" href="https://www.yoctoproject.org/ecosystem/member-organizations" target="_top">others</a>.
207 See the "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#creating-your-own-distribution" target="_top">Creating Your Own Distribution</a>"
208 section in the Yocto Project Development Tasks Manual for more
209 information.
210 </p></div><div class="section" title="2.2. Open Source Philosophy"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="open-source-philosophy">2.2. Open Source Philosophy<span class="permalink"><a alt="Permalink" title="Permalink" href="#open-source-philosophy">¶</a></span></h2></div></div></div><p>
211 Open source philosophy is characterized by software development
212 directed by peer production and collaboration through an active
213 community of developers.
214 Contrast this to the more standard centralized development models
215 used by commercial software companies where a finite set of developers
216 produces a product for sale using a defined set of procedures that
217 ultimately result in an end product whose architecture and source
218 material are closed to the public.
219 </p><p>
220 Open source projects conceptually have differing concurrent agendas,
221 approaches, and production.
222 These facets of the development process can come from anyone in the
223 public (community) that has a stake in the software project.
224 The open source environment contains new copyright, licensing, domain,
225 and consumer issues that differ from the more traditional development
226 environment.
227 In an open source environment, the end product, source material,
228 and documentation are all available to the public at no cost.
229 </p><p>
230 A benchmark example of an open source project is the Linux kernel,
231 which was initially conceived and created by Finnish computer science
232 student Linus Torvalds in 1991.
233 Conversely, a good example of a non-open source project is the
234 <span class="trademark">Windows</span>® family of operating
235 systems developed by
236 <span class="trademark">Microsoft</span>® Corporation.
237 </p><p>
238 Wikipedia has a good historical description of the Open Source
239 Philosophy
240 <a class="ulink" href="http://en.wikipedia.org/wiki/Open_source" target="_top">here</a>.
241 You can also find helpful information on how to participate in the
242 Linux Community
243 <a class="ulink" href="http://ldn.linuxfoundation.org/book/how-participate-linux-community" target="_top">here</a>.
244 </p></div><div class="section" title="2.3. Workflows"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="workflows">2.3. Workflows<span class="permalink"><a alt="Permalink" title="Permalink" href="#workflows">¶</a></span></h2></div></div></div><p>
245 This section provides workflow concepts using the Yocto Project and
246 Git.
247 In particular, the information covers basic practices that describe
248 roles and actions in a collaborative development environment.
249 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
250 If you are familiar with this type of development environment, you
251 might not want to read this section.
252 </div><p>
253 </p><p>
254 The Yocto Project files are maintained using Git in "master"
255 branches whose Git histories track every change and whose structures
256 provides branches for all diverging functionality.
257 Although there is no need to use Git, many open source projects do so.
258 </p><p>
259
260 </p><p>
261 For the Yocto Project, a key individual called the "maintainer" is
262 responsible for the "master" branch of a given Git repository.
263 The "master" branch is the “upstream” repository from which final or
264 most recent builds of the project occur.
265 The maintainer is responsible for accepting changes from other
266 developers and for organizing the underlying branch structure to
267 reflect release strategies and so forth.
268 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>For information on finding out who is responsible for (maintains)
269 a particular area of code, see the
270 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">Submitting a Change to the Yocto Project</a>"
271 section of the Yocto Project Development Tasks Manual.
272 </div><p>
273 </p><p>
274 The Yocto Project <code class="filename">poky</code> Git repository also has an
275 upstream contribution Git repository named
276 <code class="filename">poky-contrib</code>.
277 You can see all the branches in this repository using the web interface
278 of the
279 <a class="ulink" href="http://git.yoctoproject.org" target="_top">Source Repositories</a> organized
280 within the "Poky Support" area.
281 These branches temporarily hold changes to the project that have been
282 submitted or committed by the Yocto Project development team and by
283 community members who contribute to the project.
284 The maintainer determines if the changes are qualified to be moved
285 from the "contrib" branches into the "master" branch of the Git
286 repository.
287 </p><p>
288 Developers (including contributing community members) create and
289 maintain cloned repositories of the upstream "master" branch.
290 The cloned repositories are local to their development platforms and
291 are used to develop changes.
292 When a developer is satisfied with a particular feature or change,
293 they "push" the changes to the appropriate "contrib" repository.
294 </p><p>
295 Developers are responsible for keeping their local repository
296 up-to-date with "master".
297 They are also responsible for straightening out any conflicts that
298 might arise within files that are being worked on simultaneously by
299 more than one person.
300 All this work is done locally on the developer’s machine before
301 anything is pushed to a "contrib" area and examined at the maintainer’s
302 level.
303 </p><p>
304 A somewhat formal method exists by which developers commit changes
305 and push them into the "contrib" area and subsequently request that
306 the maintainer include them into "master".
307 This process is called “submitting a patch” or "submitting a change."
308 For information on submitting patches and changes, see the
309 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">Submitting a Change to the Yocto Project</a>"
310 section in the Yocto Project Development Tasks Manual.
311 </p><p>
312 To summarize the development workflow: a single point of entry
313 exists for changes into the project’s "master" branch of the
314 Git repository, which is controlled by the project’s maintainer.
315 And, a set of developers exist who independently develop, test, and
316 submit changes to "contrib" areas for the maintainer to examine.
317 The maintainer then chooses which changes are going to become a
318 permanent part of the project.
319 </p><p>
320 </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>
321 </p><p>
322 While each development environment is unique, there are some best
323 practices or methods that help development run smoothly.
324 The following list describes some of these practices.
325 For more information about Git workflows, see the workflow topics in
326 the
327 <a class="ulink" href="http://book.git-scm.com" target="_top">Git Community Book</a>.
328 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
329 <span class="emphasis"><em>Make Small Changes:</em></span>
330 It is best to keep the changes you commit small as compared to
331 bundling many disparate changes into a single commit.
332 This practice not only keeps things manageable but also allows
333 the maintainer to more easily include or refuse changes.</p><p>It is also good practice to leave the repository in a
334 state that allows you to still successfully build your project.
335 In other words, do not commit half of a feature,
336 then add the other half as a separate, later commit.
337 Each commit should take you from one buildable project state
338 to another buildable state.
339 </p></li><li class="listitem"><p>
340 <span class="emphasis"><em>Use Branches Liberally:</em></span>
341 It is very easy to create, use, and delete local branches in
342 your working Git repository.
343 You can name these branches anything you like.
344 It is helpful to give them names associated with the particular
345 feature or change on which you are working.
346 Once you are done with a feature or change and have merged it
347 into your local master branch, simply discard the temporary
348 branch.
349 </p></li><li class="listitem"><p>
350 <span class="emphasis"><em>Merge Changes:</em></span>
351 The <code class="filename">git merge</code> command allows you to take
352 the changes from one branch and fold them into another branch.
353 This process is especially helpful when more than a single
354 developer might be working on different parts of the same
355 feature.
356 Merging changes also automatically identifies any collisions
357 or "conflicts" that might happen as a result of the same lines
358 of code being altered by two different developers.
359 </p></li><li class="listitem"><p>
360 <span class="emphasis"><em>Manage Branches:</em></span>
361 Because branches are easy to use, you should use a system
362 where branches indicate varying levels of code readiness.
363 For example, you can have a "work" branch to develop in, a
364 "test" branch where the code or change is tested, a "stage"
365 branch where changes are ready to be committed, and so forth.
366 As your project develops, you can merge code across the
367 branches to reflect ever-increasing stable states of the
368 development.
369 </p></li><li class="listitem"><p>
370 <span class="emphasis"><em>Use Push and Pull:</em></span>
371 The push-pull workflow is based on the concept of developers
372 "pushing" local commits to a remote repository, which is
373 usually a contribution repository.
374 This workflow is also based on developers "pulling" known
375 states of the project down into their local development
376 repositories.
377 The workflow easily allows you to pull changes submitted by
378 other developers from the upstream repository into your
379 work area ensuring that you have the most recent software
380 on which to develop.
381 The Yocto Project has two scripts named
382 <code class="filename">create-pull-request</code> and
383 <code class="filename">send-pull-request</code> that ship with the
384 release to facilitate this workflow.
385 You can find these scripts in the <code class="filename">scripts</code>
386 folder of the
387 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>.
388 For information on how to use these scripts, see the
389 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#pushing-a-change-upstream" target="_top">Using Scripts to Push a Change Upstream and Request a Pull</a>"
390 section in the Yocto Project Development Tasks Manual.
391 </p></li><li class="listitem"><p>
392 <span class="emphasis"><em>Patch Workflow:</em></span>
393 This workflow allows you to notify the maintainer through an
394 email that you have a change (or patch) you would like
395 considered for the "master" branch of the Git repository.
396 To send this type of change, you format the patch and then
397 send the email using the Git commands
398 <code class="filename">git format-patch</code> and
399 <code class="filename">git send-email</code>.
400 For information on how to use these scripts, see the
401 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">Submitting a Change to the Yocto Project</a>"
402 section in the Yocto Project Development Tasks Manual.
403 </p></li></ul></div><p>
404 </p></div><div class="section" title="2.4. Git"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="git">2.4. Git<span class="permalink"><a alt="Permalink" title="Permalink" href="#git">¶</a></span></h2></div></div></div><p>
405 The Yocto Project makes extensive use of Git, which is a
406 free, open source distributed version control system.
407 Git supports distributed development, non-linear development,
408 and can handle large projects.
409 It is best that you have some fundamental understanding
410 of how Git tracks projects and how to work with Git if
411 you are going to use the Yocto Project for development.
412 This section provides a quick overview of how Git works and
413 provides you with a summary of some essential Git commands.
414 </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
415 For more information on Git, see
416 <a class="ulink" href="http://git-scm.com/documentation" target="_top">http://git-scm.com/documentation</a>.
417 </p></li><li class="listitem"><p>
418 If you need to download Git, it is recommended that you add
419 Git to your system through your distribution's "software
420 store" (e.g. for Ubuntu, use the Ubuntu Software feature).
421 For the Git download page, see
422 <a class="ulink" href="http://git-scm.com/download" target="_top">http://git-scm.com/download</a>.
423 </p></li><li class="listitem"><p>
424 For examples beyond the limited few in this section on how
425 to use Git with the Yocto Project, see the
426 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#working-with-yocto-project-source-files" target="_top">Working With Yocto Project Source Files</a>"
427 section in the Yocto Project Development Tasks Manual.
428 </p></li></ul></div></div><p>
429 </p><div class="section" title="2.4.1. Repositories, Tags, and Branches"><div class="titlepage"><div><div><h3 class="title" id="repositories-tags-and-branches">2.4.1. Repositories, Tags, and Branches<span class="permalink"><a alt="Permalink" title="Permalink" href="#repositories-tags-and-branches">¶</a></span></h3></div></div></div><p>
430 As mentioned briefly in the previous section and also in the
431 "<a class="link" href="#workflows" title="2.3. Workflows">Workflows</a>" section,
432 the Yocto Project maintains source repositories at
433 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit.cgi</a>.
434 If you look at this web-interface of the repositories, each item
435 is a separate Git repository.
436 </p><p>
437 Git repositories use branching techniques that track content
438 change (not files) within a project (e.g. a new feature or updated
439 documentation).
440 Creating a tree-like structure based on project divergence allows
441 for excellent historical information over the life of a project.
442 This methodology also allows for an environment from which you can
443 do lots of local experimentation on projects as you develop
444 changes or new features.
445 </p><p>
446 A Git repository represents all development efforts for a given
447 project.
448 For example, the Git repository <code class="filename">poky</code> contains
449 all changes and developments for Poky over the course of its
450 entire life.
451 That means that all changes that make up all releases are captured.
452 The repository maintains a complete history of changes.
453 </p><p>
454 You can create a local copy of any repository by "cloning" it
455 with the <code class="filename">git clone</code> command.
456 When you clone a Git repository, you end up with an identical
457 copy of the repository on your development system.
458 Once you have a local copy of a repository, you can take steps to
459 develop locally.
460 For examples on how to clone Git repositories, see the
461 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#working-with-yocto-project-source-files" target="_top">Working With Yocto Project Source Files</a>"
462 section in the Yocto Project Development Tasks Manual.
463 </p><p>
464 It is important to understand that Git tracks content change and
465 not files.
466 Git uses "branches" to organize different development efforts.
467 For example, the <code class="filename">poky</code> repository has
468 several branches that include the current "sumo"
469 branch, the "master" branch, and many branches for past
470 Yocto Project releases.
471 You can see all the branches by going to
472 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and
473 clicking on the
474 <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/heads" target="_top">[...]</a></code>
475 link beneath the "Branch" heading.
476 </p><p>
477 Each of these branches represents a specific area of development.
478 The "master" branch represents the current or most recent
479 development.
480 All other branches represent offshoots of the "master" branch.
481 </p><p>
482 When you create a local copy of a Git repository, the copy has
483 the same set of branches as the original.
484 This means you can use Git to create a local working area
485 (also called a branch) that tracks a specific development branch
486 from the upstream source Git repository.
487 in other words, you can define your local Git environment to
488 work on any development branch in the repository.
489 To help illustrate, consider the following example Git commands:
490 </p><pre class="literallayout">
491 $ cd ~
492 $ git clone git://git.yoctoproject.org/poky
493 $ cd poky
494 $ git checkout -b sumo origin/sumo
495 </pre><p>
496 In the previous example after moving to the home directory, the
497 <code class="filename">git clone</code> command creates a
498 local copy of the upstream <code class="filename">poky</code> Git repository.
499 By default, Git checks out the "master" branch for your work.
500 After changing the working directory to the new local repository
501 (i.e. <code class="filename">poky</code>), the
502 <code class="filename">git checkout</code> command creates
503 and checks out a local branch named "sumo", which
504 tracks the upstream "origin/sumo" branch.
505 Changes you make while in this branch would ultimately affect
506 the upstream "sumo" branch of the
507 <code class="filename">poky</code> repository.
508 </p><p>
509 It is important to understand that when you create and checkout a
510 local working branch based on a branch name,
511 your local environment matches the "tip" of that particular
512 development branch at the time you created your local branch,
513 which could be different from the files in the "master" branch
514 of the upstream repository.
515 In other words, creating and checking out a local branch based on
516 the "sumo" branch name is not the same as
517 cloning and checking out the "master" branch if the repository.
518 Keep reading to see how you create a local snapshot of a Yocto
519 Project Release.
520 </p><p>
521 Git uses "tags" to mark specific changes in a repository.
522 Typically, a tag is used to mark a special point such as the final
523 change before a project is released.
524 You can see the tags used with the <code class="filename">poky</code> Git
525 repository by going to
526 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/" target="_top">http://git.yoctoproject.org/cgit.cgi/poky/</a> and
527 clicking on the
528 <code class="filename"><a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/refs/tags" target="_top">[...]</a></code>
529 link beneath the "Tag" heading.
530 </p><p>
531 Some key tags for the <code class="filename">poky</code> are
532 <code class="filename">jethro-14.0.3</code>,
533 <code class="filename">morty-16.0.1</code>,
534 <code class="filename">pyro-17.0.0</code>, and
535 <code class="filename">sumo-20.0.0</code>.
536 These tags represent Yocto Project releases.
537 </p><p>
538 When you create a local copy of the Git repository, you also
539 have access to all the tags in the upstream repository.
540 Similar to branches, you can create and checkout a local working
541 Git branch based on a tag name.
542 When you do this, you get a snapshot of the Git repository that
543 reflects the state of the files when the change was made associated
544 with that tag.
545 The most common use is to checkout a working branch that matches
546 a specific Yocto Project release.
547 Here is an example:
548 </p><pre class="literallayout">
549 $ cd ~
550 $ git clone git://git.yoctoproject.org/poky
551 $ cd poky
552 $ git fetch --all --tags --prune
553 $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0
554 </pre><p>
555 In this example, the name of the top-level directory of your
556 local Yocto Project repository is <code class="filename">poky</code>.
557 After moving to the <code class="filename">poky</code> directory, the
558 <code class="filename">git fetch</code> command makes all the upstream
559 tags available locally in your repository.
560 Finally, the <code class="filename">git checkout</code> command
561 creates and checks out a branch named "my-pyro-17.0.0" that is
562 based on the specific change upstream in the repository
563 associated with the "pyro-17.0.0" tag.
564 The files in your repository now exactly match that particular
565 Yocto Project release as it is tagged in the upstream Git
566 repository.
567 It is important to understand that when you create and
568 checkout a local working branch based on a tag, your environment
569 matches a specific point in time and not the entire development
570 branch (i.e. the "tip" of the branch).
571 </p></div><div class="section" title="2.4.2. Basic Commands"><div class="titlepage"><div><div><h3 class="title" id="basic-commands">2.4.2. Basic Commands<span class="permalink"><a alt="Permalink" title="Permalink" href="#basic-commands">¶</a></span></h3></div></div></div><p>
572 Git has an extensive set of commands that lets you manage changes
573 and perform collaboration over the life of a project.
574 Conveniently though, you can manage with a small set of basic
575 operations and workflows once you understand the basic
576 philosophy behind Git.
577 You do not have to be an expert in Git to be functional.
578 A good place to look for instruction on a minimal set of Git
579 commands is
580 <a class="ulink" href="http://git-scm.com/documentation" target="_top">here</a>.
581 </p><p>
582 If you do not know much about Git, you should educate
583 yourself by visiting the links previously mentioned.
584 </p><p>
585 The following list of Git commands briefly describes some basic
586 Git operations as a way to get started.
587 As with any set of commands, this list (in most cases) simply shows
588 the base command and omits the many arguments they support.
589 See the Git documentation for complete descriptions and strategies
590 on how to use these commands:
591 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
592 <span class="emphasis"><em><code class="filename">git init</code>:</em></span>
593 Initializes an empty Git repository.
594 You cannot use Git commands unless you have a
595 <code class="filename">.git</code> repository.
596 </p></li><li class="listitem"><p><a id="git-commands-clone"></a>
597 <span class="emphasis"><em><code class="filename">git clone</code>:</em></span>
598 Creates a local clone of a Git repository that is on
599 equal footing with a fellow developer’s Git repository
600 or an upstream repository.
601 </p></li><li class="listitem"><p>
602 <span class="emphasis"><em><code class="filename">git add</code>:</em></span>
603 Locally stages updated file contents to the index that
604 Git uses to track changes.
605 You must stage all files that have changed before you
606 can commit them.
607 </p></li><li class="listitem"><p>
608 <span class="emphasis"><em><code class="filename">git commit</code>:</em></span>
609 Creates a local "commit" that documents the changes you
610 made.
611 Only changes that have been staged can be committed.
612 Commits are used for historical purposes, for determining
613 if a maintainer of a project will allow the change,
614 and for ultimately pushing the change from your local
615 Git repository into the project’s upstream repository.
616 </p></li><li class="listitem"><p>
617 <span class="emphasis"><em><code class="filename">git status</code>:</em></span>
618 Reports any modified files that possibly need to be
619 staged and gives you a status of where you stand regarding
620 local commits as compared to the upstream repository.
621 </p></li><li class="listitem"><p>
622 <span class="emphasis"><em><code class="filename">git checkout</code> <em class="replaceable"><code>branch-name</code></em>:</em></span>
623 Changes your working branch.
624 This command is analogous to "cd".
625 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git checkout –b</code> <em class="replaceable"><code>working-branch</code></em>:</em></span>
626 Creates and checks out a working branch on your local
627 machine that you can use to isolate your work.
628 It is a good idea to use local branches when adding
629 specific features or changes.
630 Using isolated branches facilitates easy removal of
631 changes if they do not work out.
632 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git branch</code>:</em></span>
633 Displays the existing local branches associated with your
634 local repository.
635 The branch that you have currently checked out is noted
636 with an asterisk character.
637 </p></li><li class="listitem"><p>
638 <span class="emphasis"><em><code class="filename">git branch -D</code> <em class="replaceable"><code>branch-name</code></em>:</em></span>
639 Deletes an existing local branch.
640 You need to be in a local branch other than the one you
641 are deleting in order to delete
642 <em class="replaceable"><code>branch-name</code></em>.
643 </p></li><li class="listitem"><p>
644 <span class="emphasis"><em><code class="filename">git pull</code>:</em></span>
645 Retrieves information from an upstream Git repository
646 and places it in your local Git repository.
647 You use this command to make sure you are synchronized with
648 the repository from which you are basing changes
649 (.e.g. the "master" branch).
650 </p></li><li class="listitem"><p>
651 <span class="emphasis"><em><code class="filename">git push</code>:</em></span>
652 Sends all your committed local changes to the upstream Git
653 repository that your local repository is tracking
654 (e.g. a contribution repository).
655 The maintainer of the project draws from these repositories
656 to merge changes (commits) into the appropriate branch
657 of project's upstream repository.
658 </p></li><li class="listitem"><p>
659 <span class="emphasis"><em><code class="filename">git merge</code>:</em></span>
660 Combines or adds changes from one
661 local branch of your repository with another branch.
662 When you create a local Git repository, the default branch
663 is named "master".
664 A typical workflow is to create a temporary branch that is
665 based off "master" that you would use for isolated work.
666 You would make your changes in that isolated branch,
667 stage and commit them locally, switch to the "master"
668 branch, and then use the <code class="filename">git merge</code>
669 command to apply the changes from your isolated branch
670 into the currently checked out branch (e.g. "master").
671 After the merge is complete and if you are done with
672 working in that isolated branch, you can safely delete
673 the isolated branch.
674 </p></li><li class="listitem"><p>
675 <span class="emphasis"><em><code class="filename">git cherry-pick</code>:</em></span>
676 Choose and apply specific commits from one branch
677 into another branch.
678 There are times when you might not be able to merge
679 all the changes in one branch with
680 another but need to pick out certain ones.
681 </p></li><li class="listitem"><p>
682 <span class="emphasis"><em><code class="filename">gitk</code>:</em></span>
683 Provides a GUI view of the branches and changes in your
684 local Git repository.
685 This command is a good way to graphically see where things
686 have diverged in your local repository.
687 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
688 You need to install the <code class="filename">gitk</code>
689 package on your development system to use this
690 command.
691 </div><p>
692 </p></li><li class="listitem"><p>
693 <span class="emphasis"><em><code class="filename">git log</code>:</em></span>
694 Reports a history of your commits to the repository.
695 This report lists all commits regardless of whether you
696 have pushed them upstream or not.
697 </p></li><li class="listitem"><p>
698 <span class="emphasis"><em><code class="filename">git diff</code>:</em></span>
699 Displays line-by-line differences between a local
700 working file and the same file as understood by Git.
701 This command is useful to see what you have changed
702 in any given file.
703 </p></li></ul></div><p>
704 </p></div></div><div class="section" title="2.5. Yocto Project Source Repositories"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="yocto-project-repositories">2.5. Yocto Project Source Repositories<span class="permalink"><a alt="Permalink" title="Permalink" href="#yocto-project-repositories">¶</a></span></h2></div></div></div><p>
705 The Yocto Project team maintains complete source repositories for all
706 Yocto Project files at
707 <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi</a>.
708 This web-based source code browser is organized into categories by
709 function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
710 so forth.
711 From the interface, you can click on any particular item in the "Name"
712 column and see the URL at the bottom of the page that you need to clone
713 a Git repository for that particular item.
714 Having a local Git repository of the
715 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>,
716 which is usually named "poky", allows
717 you to make changes, contribute to the history, and ultimately enhance
718 the Yocto Project's tools, Board Support Packages, and so forth.
719 </p><p>
720 For any supported release of Yocto Project, you can also go to the
721 <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a> and
722 select the "Downloads" tab and get a released tarball of the
723 <code class="filename">poky</code> repository or any supported BSP tarballs.
724 Unpacking these tarballs gives you a snapshot of the released
725 files.
726 </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
727 The recommended method for setting up the Yocto Project
728 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>
729 and the files for supported BSPs
730 (e.g., <code class="filename">meta-intel</code>) is to use
731 <a class="link" href="#git" title="2.4. Git">Git</a> to create a local copy of
732 the upstream repositories.
733 </p></li><li class="listitem"><p>
734 Be sure to always work in matching branches for both
735 the selected BSP repository and the
736 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>
737 (i.e. <code class="filename">poky</code>) repository.
738 For example, if you have checked out the "master" branch
739 of <code class="filename">poky</code> and you are going to use
740 <code class="filename">meta-intel</code>, be sure to checkout the
741 "master" branch of <code class="filename">meta-intel</code>.
742 </p></li></ul></div></div><p>
743 </p><p>
744 In summary, here is where you can get the project files needed for
745 development:
746 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a id="source-repositories"></a>
747 <span class="emphasis"><em>
748 <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi" target="_top">Source Repositories:</a>
749 </em></span>
750 This area contains IDE Plugins, Matchbox, Poky, Poky Support,
751 Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
752 You can create local copies of Git repositories for each of
753 these areas.</p><p>
754 </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>
755 For steps on how to view and access these upstream Git
756 repositories, see the
757 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#accessing-source-repositories" target="_top">Accessing Source Repositories</a>"
758 Section in the Yocto Project Development Tasks Manual.
759 </p></li><li class="listitem"><p><a id="index-downloads"></a>
760 <span class="emphasis"><em>
761 <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a>
762 </em></span>
763 This is an index of releases such as
764 the <span class="trademark">Eclipse</span>™
765 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers
766 for cross-development toolchains, and all released versions of
767 Yocto Project in the form of images or tarballs.
768 Downloading and extracting these files does not produce a local
769 copy of the Git repository but rather a snapshot of a
770 particular release or image.</p><p>
771 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 315px"><td align="center"><img src="figures/index-downloads.png" align="middle" height="315" /></td></tr></table><p>
772 For steps on how to view and access these files, see the
773 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#accessing-index-of-releases" target="_top">Accessing Index of Releases</a>"
774 section in the Yocto Project Development Tasks Manual.
775 </p></li><li class="listitem"><p><a id="downloads-page"></a>
776 <span class="emphasis"><em>"Downloads" page for the
777 <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project Website</a>:
778 </em></span></p><p class="writernotes">This section will change due to
779 reworking of the YP Website.</p><p>The Yocto Project website includes a "Downloads" tab
780 that allows you to download any Yocto Project
781 release and Board Support Package (BSP) in tarball form.
782 The tarballs are similar to those found in the
783 <a class="ulink" href="http://downloads.yoctoproject.org/releases/" target="_top">Index of /releases:</a> area.</p><p>
784 </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>
785 For steps on how to use the "Downloads" page, see the
786 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#using-the-downloads-page" target="_top">Using the Downloads Page</a>"
787 section in the Yocto Project Development Tasks Manual.
788 </p></li></ul></div><p>
789 </p></div><div class="section" title="2.6. Licensing"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="licensing">2.6. Licensing<span class="permalink"><a alt="Permalink" title="Permalink" href="#licensing">¶</a></span></h2></div></div></div><p>
790 Because open source projects are open to the public, they have
791 different licensing structures in place.
792 License evolution for both Open Source and Free Software has an
793 interesting history.
794 If you are interested in this history, you can find basic information
795 here:
796 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
797 <a class="ulink" href="http://en.wikipedia.org/wiki/Open-source_license" target="_top">Open source license history</a>
798 </p></li><li class="listitem"><p>
799 <a class="ulink" href="http://en.wikipedia.org/wiki/Free_software_license" target="_top">Free software license history</a>
800 </p></li></ul></div><p>
801 </p><p>
802 In general, the Yocto Project is broadly licensed under the
803 Massachusetts Institute of Technology (MIT) License.
804 MIT licensing permits the reuse of software within proprietary
805 software as long as the license is distributed with that software.
806 MIT is also compatible with the GNU General Public License (GPL).
807 Patches to the Yocto Project follow the upstream licensing scheme.
808 You can find information on the MIT license
809 <a class="ulink" href="http://www.opensource.org/licenses/mit-license.php" target="_top">here</a>.
810 You can find information on the GNU GPL
811 <a class="ulink" href="http://www.opensource.org/licenses/LGPL-3.0" target="_top">here</a>.
812 </p><p>
813 When you build an image using the Yocto Project, the build process
814 uses a known list of licenses to ensure compliance.
815 You can find this list in the
816 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>
817 at <code class="filename">meta/files/common-licenses</code>.
818 Once the build completes, the list of all licenses found and used
819 during that build are kept in the
820 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>
821 at <code class="filename">tmp/deploy/licenses</code>.
822 </p><p>
823 If a module requires a license that is not in the base list, the
824 build process generates a warning during the build.
825 These tools make it easier for a developer to be certain of the
826 licenses with which their shipped products must comply.
827 However, even with these tools it is still up to the developer to
828 resolve potential licensing issues.
829 </p><p>
830 The base list of licenses used by the build process is a combination
831 of the Software Package Data Exchange (SPDX) list and the Open
832 Source Initiative (OSI) projects.
833 <a class="ulink" href="http://spdx.org" target="_top">SPDX Group</a> is a working group of
834 the Linux Foundation that maintains a specification for a standard
835 format for communicating the components, licenses, and copyrights
836 associated with a software package.
837 <a class="ulink" href="http://opensource.org" target="_top">OSI</a> is a corporation
838 dedicated to the Open Source Definition and the effort for reviewing
839 and approving licenses that conform to the Open Source Definition
840 (OSD).
841 </p><p>
842 You can find a list of the combined SPDX and OSI licenses that the
843 Yocto Project uses in the
844 <code class="filename">meta/files/common-licenses</code> directory in your
845 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>.
846 </p><p>
847 For information that can help you maintain compliance with various
848 open source licensing during the lifecycle of a product created using
849 the Yocto Project, see the
850 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#maintaining-open-source-license-compliance-during-your-products-lifecycle" target="_top">Maintaining Open Source License Compliance During Your Product's Lifecycle</a>"
851 section in the Yocto Project Development Tasks Manual.
852 </p></div><div class="section" title="2.7. Recipe Syntax"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="recipe-syntax">2.7. Recipe Syntax<span class="permalink"><a alt="Permalink" title="Permalink" href="#recipe-syntax">¶</a></span></h2></div></div></div><p>
853 Understanding recipe file syntax is important for
854 writing recipes.
855 The following list overviews the basic items that make up a
856 BitBake recipe file.
857 For more complete BitBake syntax descriptions, see the
858 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual-metadata" target="_top">Syntax and Operators</a>"
859 chapter of the BitBake User Manual.
860 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Variable Assignments and Manipulations:</em></span>
861 Variable assignments allow a value to be assigned to a
862 variable.
863 The assignment can be static text or might include
864 the contents of other variables.
865 In addition to the assignment, appending and prepending
866 operations are also supported.</p><p>The following example shows some of the ways
867 you can use variables in recipes:
868 </p><pre class="literallayout">
869 S = "${WORKDIR}/postfix-${PV}"
870 CFLAGS += "-DNO_ASM"
871 SRC_URI_append = " file://fixup.patch"
872 </pre><p>
873 </p></li><li class="listitem"><p><span class="emphasis"><em>Functions:</em></span>
874 Functions provide a series of actions to be performed.
875 You usually use functions to override the default
876 implementation of a task function or to complement
877 a default function (i.e. append or prepend to an
878 existing function).
879 Standard functions use <code class="filename">sh</code> shell
880 syntax, although access to OpenEmbedded variables and
881 internal methods are also available.</p><p>The following is an example function from the
882 <code class="filename">sed</code> recipe:
883 </p><pre class="literallayout">
884 do_install () {
885 autotools_do_install
886 install -d ${D}${base_bindir}
887 mv ${D}${bindir}/sed ${D}${base_bindir}/sed
888 rmdir ${D}${bindir}/
889 }
890 </pre><p>
891 It is also possible to implement new functions that
892 are called between existing tasks as long as the
893 new functions are not replacing or complementing the
894 default functions.
895 You can implement functions in Python
896 instead of shell.
897 Both of these options are not seen in the majority of
898 recipes.</p></li><li class="listitem"><p><span class="emphasis"><em>Keywords:</em></span>
899 BitBake recipes use only a few keywords.
900 You use keywords to include common
901 functions (<code class="filename">inherit</code>), load parts
902 of a recipe from other files
903 (<code class="filename">include</code> and
904 <code class="filename">require</code>) and export variables
905 to the environment (<code class="filename">export</code>).</p><p>The following example shows the use of some of
906 these keywords:
907 </p><pre class="literallayout">
908 export POSTCONF = "${STAGING_BINDIR}/postconf"
909 inherit autoconf
910 require otherfile.inc
911 </pre><p>
912 </p></li><li class="listitem"><p><span class="emphasis"><em>Comments:</em></span>
913 Any lines that begin with the hash character
914 (<code class="filename">#</code>) are treated as comment lines
915 and are ignored:
916 </p><pre class="literallayout">
917 # This is a comment
918 </pre><p>
919 </p></li></ul></div><p>
920 </p><p>
921 This next list summarizes the most important and most commonly
922 used parts of the recipe syntax.
923 For more information on these parts of the syntax, you can
924 reference the
925 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual-metadata" target="_top">Syntax and Operators</a>
926 chapter in the BitBake User Manual.
927 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Line Continuation: <code class="filename">\</code></em></span> -
928 Use the backward slash (<code class="filename">\</code>)
929 character to split a statement over multiple lines.
930 Place the slash character at the end of the line that
931 is to be continued on the next line:
932 </p><pre class="literallayout">
933 VAR = "A really long \
934 line"
935 </pre><p>
936 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
937 You cannot have any characters including spaces
938 or tabs after the slash character.
939 </div><p>
940 </p></li><li class="listitem"><p>
941 <span class="emphasis"><em>Using Variables: <code class="filename">${...}</code></em></span> -
942 Use the <code class="filename">${<em class="replaceable"><code>VARNAME</code></em>}</code> syntax to
943 access the contents of a variable:
944 </p><pre class="literallayout">
945 SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
946 </pre><p>
947 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
948 It is important to understand that the value of a
949 variable expressed in this form does not get
950 substituted automatically.
951 The expansion of these expressions happens
952 on-demand later (e.g. usually when a function that
953 makes reference to the variable executes).
954 This behavior ensures that the values are most
955 appropriate for the context in which they are
956 finally used.
957 On the rare occasion that you do need the variable
958 expression to be expanded immediately, you can use
959 the <code class="filename">:=</code> operator instead of
960 <code class="filename">=</code> when you make the
961 assignment, but this is not generally needed.
962 </div><p>
963 </p></li><li class="listitem"><p><span class="emphasis"><em>Quote All Assignments: <code class="filename">"<em class="replaceable"><code>value</code></em>"</code></em></span> -
964 Use double quotes around the value in all variable
965 assignments.
966 </p><pre class="literallayout">
967 VAR1 = "${OTHERVAR}"
968 VAR2 = "The version is ${PV}"
969 </pre><p>
970 </p></li><li class="listitem"><p><span class="emphasis"><em>Conditional Assignment: <code class="filename">?=</code></em></span> -
971 Conditional assignment is used to assign a value to
972 a variable, but only when the variable is currently
973 unset.
974 Use the question mark followed by the equal sign
975 (<code class="filename">?=</code>) to make a "soft" assignment
976 used for conditional assignment.
977 Typically, "soft" assignments are used in the
978 <code class="filename">local.conf</code> file for variables
979 that are allowed to come through from the external
980 environment.
981 </p><p>Here is an example where
982 <code class="filename">VAR1</code> is set to "New value" if
983 it is currently empty.
984 However, if <code class="filename">VAR1</code> has already been
985 set, it remains unchanged:
986 </p><pre class="literallayout">
987 VAR1 ?= "New value"
988 </pre><p>
989 In this next example, <code class="filename">VAR1</code>
990 is left with the value "Original value":
991 </p><pre class="literallayout">
992 VAR1 = "Original value"
993 VAR1 ?= "New value"
994 </pre><p>
995 </p></li><li class="listitem"><p><span class="emphasis"><em>Appending: <code class="filename">+=</code></em></span> -
996 Use the plus character followed by the equals sign
997 (<code class="filename">+=</code>) to append values to existing
998 variables.
999 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1000 This operator adds a space between the existing
1001 content of the variable and the new content.
1002 </div><p>Here is an example:
1003 </p><pre class="literallayout">
1004 SRC_URI += "file://fix-makefile.patch"
1005 </pre><p>
1006 </p></li><li class="listitem"><p><span class="emphasis"><em>Prepending: <code class="filename">=+</code></em></span> -
1007 Use the equals sign followed by the plus character
1008 (<code class="filename">=+</code>) to prepend values to existing
1009 variables.
1010 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1011 This operator adds a space between the new content
1012 and the existing content of the variable.
1013 </div><p>Here is an example:
1014 </p><pre class="literallayout">
1015 VAR =+ "Starts"
1016 </pre><p>
1017 </p></li><li class="listitem"><p><span class="emphasis"><em>Appending: <code class="filename">_append</code></em></span> -
1018 Use the <code class="filename">_append</code> operator to
1019 append values to existing variables.
1020 This operator does not add any additional space.
1021 Also, the operator is applied after all the
1022 <code class="filename">+=</code>, and
1023 <code class="filename">=+</code> operators have been applied and
1024 after all <code class="filename">=</code> assignments have
1025 occurred.
1026 </p><p>The following example shows the space being
1027 explicitly added to the start to ensure the appended
1028 value is not merged with the existing value:
1029 </p><pre class="literallayout">
1030 SRC_URI_append = " file://fix-makefile.patch"
1031 </pre><p>
1032 You can also use the <code class="filename">_append</code>
1033 operator with overrides, which results in the actions
1034 only being performed for the specified target or
1035 machine:
1036 </p><pre class="literallayout">
1037 SRC_URI_append_sh4 = " file://fix-makefile.patch"
1038 </pre><p>
1039 </p></li><li class="listitem"><p><span class="emphasis"><em>Prepending: <code class="filename">_prepend</code></em></span> -
1040 Use the <code class="filename">_prepend</code> operator to
1041 prepend values to existing variables.
1042 This operator does not add any additional space.
1043 Also, the operator is applied after all the
1044 <code class="filename">+=</code>, and
1045 <code class="filename">=+</code> operators have been applied and
1046 after all <code class="filename">=</code> assignments have
1047 occurred.
1048 </p><p>The following example shows the space being
1049 explicitly added to the end to ensure the prepended
1050 value is not merged with the existing value:
1051 </p><pre class="literallayout">
1052 CFLAGS_prepend = "-I${S}/myincludes "
1053 </pre><p>
1054 You can also use the <code class="filename">_prepend</code>
1055 operator with overrides, which results in the actions
1056 only being performed for the specified target or
1057 machine:
1058 </p><pre class="literallayout">
1059 CFLAGS_prepend_sh4 = "-I${S}/myincludes "
1060 </pre><p>
1061 </p></li><li class="listitem"><p><span class="emphasis"><em>Overrides:</em></span> -
1062 You can use overrides to set a value conditionally,
1063 typically based on how the recipe is being built.
1064 For example, to set the
1065 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-KBRANCH" target="_top"><code class="filename">KBRANCH</code></a>
1066 variable's value to "standard/base" for any target
1067 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a>,
1068 except for qemuarm where it should be set to
1069 "standard/arm-versatile-926ejs", you would do the
1070 following:
1071 </p><pre class="literallayout">
1072 KBRANCH = "standard/base"
1073 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
1074 </pre><p>
1075 Overrides are also used to separate alternate values
1076 of a variable in other situations.
1077 For example, when setting variables such as
1078 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-FILES" target="_top"><code class="filename">FILES</code></a>
1079 and
1080 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RDEPENDS" target="_top"><code class="filename">RDEPENDS</code></a>
1081 that are specific to individual packages produced by
1082 a recipe, you should always use an override that
1083 specifies the name of the package.
1084 </p></li><li class="listitem"><p><span class="emphasis"><em>Indentation:</em></span>
1085 Use spaces for indentation rather than than tabs.
1086 For shell functions, both currently work.
1087 However, it is a policy decision of the Yocto Project
1088 to use tabs in shell functions.
1089 Realize that some layers have a policy to use spaces
1090 for all indentation.
1091 </p></li><li class="listitem"><p><span class="emphasis"><em>Using Python for Complex Operations: <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code></em></span> -
1092 For more advanced processing, it is possible to use
1093 Python code during variable assignments (e.g.
1094 search and replacement on a variable).</p><p>You indicate Python code using the
1095 <code class="filename">${@<em class="replaceable"><code>python_code</code></em>}</code>
1096 syntax for the variable assignment:
1097 </p><pre class="literallayout">
1098 SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
1099 </pre><p>
1100 </p></li><li class="listitem"><p><span class="emphasis"><em>Shell Function Syntax:</em></span>
1101 Write shell functions as if you were writing a shell
1102 script when you describe a list of actions to take.
1103 You should ensure that your script works with a generic
1104 <code class="filename">sh</code> and that it does not require
1105 any <code class="filename">bash</code> or other shell-specific
1106 functionality.
1107 The same considerations apply to various system
1108 utilities (e.g. <code class="filename">sed</code>,
1109 <code class="filename">grep</code>, <code class="filename">awk</code>,
1110 and so forth) that you might wish to use.
1111 If in doubt, you should check with multiple
1112 implementations - including those from BusyBox.
1113 </p></li></ul></div><p>
1114 </p></div><div class="section" title="2.8. Development Concepts"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="development-concepts">2.8. Development Concepts<span class="permalink"><a alt="Permalink" title="Permalink" href="#development-concepts">¶</a></span></h2></div></div></div><p>
1115 This section takes a more detailed look inside the development
1116 process.
1117 The following diagram represents development at a high level.
1118 The remainder of this chapter expands on the fundamental input, output,
1119 process, and
1120 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>) blocks
1121 that make up development in the Yocto Project environment.
1122 </p><p><a id="general-yocto-environment-figure"></a>
1123 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 383px"><td align="center"><img src="figures/yocto-environment-ref.png" align="middle" height="383" /></td></tr></table><p>
1124 </p><p>
1125 In general, development consists of several functional areas:
1126 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>User Configuration:</em></span>
1127 Metadata you can use to control the build process.
1128 </p></li><li class="listitem"><p><span class="emphasis"><em>Metadata Layers:</em></span>
1129 Various layers that provide software, machine, and
1130 distro Metadata.</p></li><li class="listitem"><p><span class="emphasis"><em>Source Files:</em></span>
1131 Upstream releases, local projects, and SCMs.</p></li><li class="listitem"><p><span class="emphasis"><em>Build System:</em></span>
1132 Processes under the control of
1133 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a>.
1134 This block expands on how BitBake fetches source, applies
1135 patches, completes compilation, analyzes output for package
1136 generation, creates and tests packages, generates images, and
1137 generates cross-development tools.</p></li><li class="listitem"><p><span class="emphasis"><em>Package Feeds:</em></span>
1138 Directories containing output packages (RPM, DEB or IPK),
1139 which are subsequently used in the construction of an image or
1140 SDK, produced by the build system.
1141 These feeds can also be copied and shared using a web server or
1142 other means to facilitate extending or updating existing
1143 images on devices at runtime if runtime package management is
1144 enabled.</p></li><li class="listitem"><p><span class="emphasis"><em>Images:</em></span>
1145 Images produced by the development process.
1146 </p></li><li class="listitem"><p><span class="emphasis"><em>Application Development SDK:</em></span>
1147 Cross-development tools that are produced along with an image
1148 or separately with BitBake.</p></li></ul></div><p>
1149 </p><div class="section" title="2.8.1. User Configuration"><div class="titlepage"><div><div><h3 class="title" id="user-configuration">2.8.1. User Configuration<span class="permalink"><a alt="Permalink" title="Permalink" href="#user-configuration">¶</a></span></h3></div></div></div><p>
1150 User configuration helps define the build.
1151 Through user configuration, you can tell BitBake the
1152 target architecture for which you are building the image,
1153 where to store downloaded source, and other build properties.
1154 </p><p>
1155 The following figure shows an expanded representation of the
1156 "User Configuration" box of the
1157 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>:
1158 </p><p>
1159 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 405px"><td align="center"><img src="figures/user-configuration.png" align="middle" height="405" /></td></tr></table><p>
1160 </p><p>
1161 BitBake needs some basic configuration files in order to complete
1162 a build.
1163 These files are <code class="filename">*.conf</code> files.
1164 The minimally necessary ones reside as example files in the
1165 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>.
1166 For simplicity, this section refers to the Source Directory as
1167 the "Poky Directory."
1168 </p><p>
1169 When you clone the <code class="filename">poky</code> Git repository or you
1170 download and unpack a Yocto Project release, you can set up the
1171 Source Directory to be named anything you want.
1172 For this discussion, the cloned repository uses the default
1173 name <code class="filename">poky</code>.
1174 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1175 The Poky repository is primarily an aggregation of existing
1176 repositories.
1177 It is not a canonical upstream source.
1178 </div><p>
1179 </p><p>
1180 The <code class="filename">meta-poky</code> layer inside Poky contains
1181 a <code class="filename">conf</code> directory that has example
1182 configuration files.
1183 These example files are used as a basis for creating actual
1184 configuration files when you source the build environment
1185 script
1186 (i.e.
1187 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#structure-core-script" target="_top"><code class="filename">oe-init-build-env</code></a>).
1188 </p><p>
1189 Sourcing the build environment script creates a
1190 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>
1191 if one does not already exist.
1192 BitBake uses the Build Directory for all its work during builds.
1193 The Build Directory has a <code class="filename">conf</code> directory that
1194 contains default versions of your <code class="filename">local.conf</code>
1195 and <code class="filename">bblayers.conf</code> configuration files.
1196 These default configuration files are created only if versions
1197 do not already exist in the Build Directory at the time you
1198 source the build environment setup script.
1199 </p><p>
1200 Because the Poky repository is fundamentally an aggregation of
1201 existing repositories, some users might be familiar with running
1202 the <code class="filename">oe-init-build-env</code> script in the context
1203 of separate OpenEmbedded-Core and BitBake repositories rather than a
1204 single Poky repository.
1205 This discussion assumes the script is executed from within a cloned
1206 or unpacked version of Poky.
1207 </p><p>
1208 Depending on where the script is sourced, different sub-scripts
1209 are called to set up the Build Directory (Yocto or OpenEmbedded).
1210 Specifically, the script
1211 <code class="filename">scripts/oe-setup-builddir</code> inside the
1212 poky directory sets up the Build Directory and seeds the directory
1213 (if necessary) with configuration files appropriate for the
1214 Yocto Project development environment.
1215 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1216 The <code class="filename">scripts/oe-setup-builddir</code> script
1217 uses the <code class="filename">$TEMPLATECONF</code> variable to
1218 determine which sample configuration files to locate.
1219 </div><p>
1220 </p><p>
1221 The <code class="filename">local.conf</code> file provides many
1222 basic variables that define a build environment.
1223 Here is a list of a few.
1224 To see the default configurations in a <code class="filename">local.conf</code>
1225 file created by the build environment script, see the
1226 <code class="filename">local.conf.sample</code> in the
1227 <code class="filename">meta-poky</code> layer:
1228 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Parallelism Options:</em></span>
1229 Controlled by the
1230 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BB_NUMBER_THREADS" target="_top"><code class="filename">BB_NUMBER_THREADS</code></a>,
1231 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PARALLEL_MAKE" target="_top"><code class="filename">PARALLEL_MAKE</code></a>,
1232 and
1233 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_NUMBER_PARSE_THREADS" target="_top"><code class="filename">BB_NUMBER_PARSE_THREADS</code></a>
1234 variables.</p></li><li class="listitem"><p><span class="emphasis"><em>Target Machine Selection:</em></span>
1235 Controlled by the
1236 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a>
1237 variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Download Directory:</em></span>
1238 Controlled by the
1239 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a>
1240 variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Shared State Directory:</em></span>
1241 Controlled by the
1242 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a>
1243 variable.</p></li><li class="listitem"><p><span class="emphasis"><em>Build Output:</em></span>
1244 Controlled by the
1245 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a>
1246 variable.</p></li></ul></div><p>
1247 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1248 Configurations set in the <code class="filename">conf/local.conf</code>
1249 file can also be set in the
1250 <code class="filename">conf/site.conf</code> and
1251 <code class="filename">conf/auto.conf</code> configuration files.
1252 </div><p>
1253 </p><p>
1254 The <code class="filename">bblayers.conf</code> file tells BitBake what
1255 layers you want considered during the build.
1256 By default, the layers listed in this file include layers
1257 minimally needed by the build system.
1258 However, you must manually add any custom layers you have created.
1259 You can find more information on working with the
1260 <code class="filename">bblayers.conf</code> file in the
1261 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#enabling-your-layer" target="_top">Enabling Your Layer</a>"
1262 section in the Yocto Project Development Tasks Manual.
1263 </p><p>
1264 The files <code class="filename">site.conf</code> and
1265 <code class="filename">auto.conf</code> are not created by the environment
1266 initialization script.
1267 If you want the <code class="filename">site.conf</code> file, you need to
1268 create that yourself.
1269 The <code class="filename">auto.conf</code> file is typically created by
1270 an autobuilder:
1271 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">site.conf</code>:</em></span>
1272 You can use the <code class="filename">conf/site.conf</code>
1273 configuration file to configure multiple build directories.
1274 For example, suppose you had several build environments and
1275 they shared some common features.
1276 You can set these default build properties here.
1277 A good example is perhaps the packaging format to use
1278 through the
1279 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a>
1280 variable.</p><p>One useful scenario for using the
1281 <code class="filename">conf/site.conf</code> file is to extend your
1282 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BBPATH" target="_top"><code class="filename">BBPATH</code></a>
1283 variable to include the path to a
1284 <code class="filename">conf/site.conf</code>.
1285 Then, when BitBake looks for Metadata using
1286 <code class="filename">BBPATH</code>, it finds the
1287 <code class="filename">conf/site.conf</code> file and applies your
1288 common configurations found in the file.
1289 To override configurations in a particular build directory,
1290 alter the similar configurations within that build
1291 directory's <code class="filename">conf/local.conf</code> file.
1292 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">auto.conf</code>:</em></span>
1293 The file is usually created and written to by
1294 an autobuilder.
1295 The settings put into the file are typically the same as
1296 you would find in the <code class="filename">conf/local.conf</code>
1297 or the <code class="filename">conf/site.conf</code> files.
1298 </p></li></ul></div><p>
1299 </p><p>
1300 You can edit all configuration files to further define
1301 any particular build environment.
1302 This process is represented by the "User Configuration Edits"
1303 box in the figure.
1304 </p><p>
1305 When you launch your build with the
1306 <code class="filename">bitbake <em class="replaceable"><code>target</code></em></code>
1307 command, BitBake sorts out the configurations to ultimately
1308 define your build environment.
1309 It is important to understand that the OpenEmbedded build system
1310 reads the configuration files in a specific order:
1311 <code class="filename">site.conf</code>, <code class="filename">auto.conf</code>,
1312 and <code class="filename">local.conf</code>.
1313 And, the build system applies the normal assignment statement
1314 rules.
1315 Because the files are parsed in a specific order, variable
1316 assignments for the same variable could be affected.
1317 For example, if the <code class="filename">auto.conf</code> file and
1318 the <code class="filename">local.conf</code> set
1319 <em class="replaceable"><code>variable1</code></em> to different values, because
1320 the build system parses <code class="filename">local.conf</code> after
1321 <code class="filename">auto.conf</code>,
1322 <em class="replaceable"><code>variable1</code></em> is assigned the value from
1323 the <code class="filename">local.conf</code> file.
1324 </p></div><div class="section" title="2.8.2. Metadata, Machine Configuration, and Policy Configuration"><div class="titlepage"><div><div><h3 class="title" id="metadata-machine-configuration-and-policy-configuration">2.8.2. Metadata, Machine Configuration, and Policy Configuration<span class="permalink"><a alt="Permalink" title="Permalink" href="#metadata-machine-configuration-and-policy-configuration">¶</a></span></h3></div></div></div><p>
1325 The previous section described the user configurations that
1326 define BitBake's global behavior.
1327 This section takes a closer look at the layers the build system
1328 uses to further control the build.
1329 These layers provide Metadata for the software, machine, and
1330 policy.
1331 </p><p>
1332 In general, three types of layer input exist:
1333 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Policy Configuration:</em></span>
1334 Distribution Layers provide top-level or general
1335 policies for the image or SDK being built.
1336 For example, this layer would dictate whether BitBake
1337 produces RPM or IPK packages.</p></li><li class="listitem"><p><span class="emphasis"><em>Machine Configuration:</em></span>
1338 Board Support Package (BSP) layers provide machine
1339 configurations.
1340 This type of information is specific to a particular
1341 target architecture.</p></li><li class="listitem"><p><span class="emphasis"><em>Metadata:</em></span>
1342 Software layers contain user-supplied recipe files,
1343 patches, and append files.
1344 </p></li></ul></div><p>
1345 </p><p>
1346 The following figure shows an expanded representation of the
1347 Metadata, Machine Configuration, and Policy Configuration input
1348 (layers) boxes of the
1349 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>:
1350 </p><p>
1351 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 675px"><td align="center"><img src="figures/layer-input.png" align="middle" width="720" /></td></tr></table><p>
1352 </p><p>
1353 In general, all layers have a similar structure.
1354 They all contain a licensing file
1355 (e.g. <code class="filename">COPYING</code>) if the layer is to be
1356 distributed, a <code class="filename">README</code> file as good practice
1357 and especially if the layer is to be distributed, a
1358 configuration directory, and recipe directories.
1359 </p><p>
1360 The Yocto Project has many layers that can be used.
1361 You can see a web-interface listing of them on the
1362 <a class="ulink" href="http://git.yoctoproject.org/" target="_top">Source Repositories</a>
1363 page.
1364 The layers are shown at the bottom categorized under
1365 "Yocto Metadata Layers."
1366 These layers are fundamentally a subset of the
1367 <a class="ulink" href="http://layers.openembedded.org/layerindex/layers/" target="_top">OpenEmbedded Metadata Index</a>,
1368 which lists all layers provided by the OpenEmbedded community.
1369 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1370 Layers exist in the Yocto Project Source Repositories that
1371 cannot be found in the OpenEmbedded Metadata Index.
1372 These layers are either deprecated or experimental in nature.
1373 </div><p>
1374 </p><p>
1375 BitBake uses the <code class="filename">conf/bblayers.conf</code> file,
1376 which is part of the user configuration, to find what layers it
1377 should be using as part of the build.
1378 </p><p>
1379 For more information on layers, see the
1380 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and Creating Layers</a>"
1381 section in the Yocto Project Development Tasks Manual.
1382 </p><div class="section" title="2.8.2.1. Distro Layer"><div class="titlepage"><div><div><h4 class="title" id="distro-layer">2.8.2.1. Distro Layer<span class="permalink"><a alt="Permalink" title="Permalink" href="#distro-layer">¶</a></span></h4></div></div></div><p>
1383 The distribution layer provides policy configurations for your
1384 distribution.
1385 Best practices dictate that you isolate these types of
1386 configurations into their own layer.
1387 Settings you provide in
1388 <code class="filename">conf/distro/<em class="replaceable"><code>distro</code></em>.conf</code> override
1389 similar
1390 settings that BitBake finds in your
1391 <code class="filename">conf/local.conf</code> file in the Build
1392 Directory.
1393 </p><p>
1394 The following list provides some explanation and references
1395 for what you typically find in the distribution layer:
1396 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>classes:</em></span>
1397 Class files (<code class="filename">.bbclass</code>) hold
1398 common functionality that can be shared among
1399 recipes in the distribution.
1400 When your recipes inherit a class, they take on the
1401 settings and functions for that class.
1402 You can read more about class files in the
1403 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes" target="_top">Classes</a>"
1404 section of the Yocto Reference Manual.
1405 </p></li><li class="listitem"><p><span class="emphasis"><em>conf:</em></span>
1406 This area holds configuration files for the
1407 layer (<code class="filename">conf/layer.conf</code>),
1408 the distribution
1409 (<code class="filename">conf/distro/<em class="replaceable"><code>distro</code></em>.conf</code>),
1410 and any distribution-wide include files.
1411 </p></li><li class="listitem"><p><span class="emphasis"><em>recipes-*:</em></span>
1412 Recipes and append files that affect common
1413 functionality across the distribution.
1414 This area could include recipes and append files
1415 to add distribution-specific configuration,
1416 initialization scripts, custom image recipes,
1417 and so forth.</p></li></ul></div><p>
1418 </p></div><div class="section" title="2.8.2.2. BSP Layer"><div class="titlepage"><div><div><h4 class="title" id="bsp-layer">2.8.2.2. BSP Layer<span class="permalink"><a alt="Permalink" title="Permalink" href="#bsp-layer">¶</a></span></h4></div></div></div><p>
1419 The BSP Layer provides machine configurations.
1420 Everything in this layer is specific to the machine for which
1421 you are building the image or the SDK.
1422 A common structure or form is defined for BSP layers.
1423 You can learn more about this structure in the
1424 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>.
1425 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1426 In order for a BSP layer to be considered compliant with the
1427 Yocto Project, it must meet some structural requirements.
1428 </div><p>
1429 </p><p>
1430 The BSP Layer's configuration directory contains
1431 configuration files for the machine
1432 (<code class="filename">conf/machine/<em class="replaceable"><code>machine</code></em>.conf</code>) and,
1433 of course, the layer (<code class="filename">conf/layer.conf</code>).
1434 </p><p>
1435 The remainder of the layer is dedicated to specific recipes
1436 by function: <code class="filename">recipes-bsp</code>,
1437 <code class="filename">recipes-core</code>,
1438 <code class="filename">recipes-graphics</code>, and
1439 <code class="filename">recipes-kernel</code>.
1440 Metadata can exist for multiple formfactors, graphics
1441 support systems, and so forth.
1442 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1443 While the figure shows several <code class="filename">recipes-*</code>
1444 directories, not all these directories appear in all
1445 BSP layers.
1446 </div><p>
1447 </p></div><div class="section" title="2.8.2.3. Software Layer"><div class="titlepage"><div><div><h4 class="title" id="software-layer">2.8.2.3. Software Layer<span class="permalink"><a alt="Permalink" title="Permalink" href="#software-layer">¶</a></span></h4></div></div></div><p>
1448 The software layer provides the Metadata for additional
1449 software packages used during the build.
1450 This layer does not include Metadata that is specific to the
1451 distribution or the machine, which are found in their
1452 respective layers.
1453 </p><p>
1454 This layer contains any new recipes that your project needs
1455 in the form of recipe files.
1456 </p></div></div><div class="section" title="2.8.3. Sources"><div class="titlepage"><div><div><h3 class="title" id="sources-dev-environment">2.8.3. Sources<span class="permalink"><a alt="Permalink" title="Permalink" href="#sources-dev-environment">¶</a></span></h3></div></div></div><p>
1457 In order for the OpenEmbedded build system to create an image or
1458 any target, it must be able to access source files.
1459 The
1460 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>
1461 represents source files using the "Upstream Project Releases",
1462 "Local Projects", and "SCMs (optional)" boxes.
1463 The figure represents mirrors, which also play a role in locating
1464 source files, with the "Source Mirror(s)" box.
1465 </p><p>
1466 The method by which source files are ultimately organized is
1467 a function of the project.
1468 For example, for released software, projects tend to use tarballs
1469 or other archived files that can capture the state of a release
1470 guaranteeing that it is statically represented.
1471 On the other hand, for a project that is more dynamic or
1472 experimental in nature, a project might keep source files in a
1473 repository controlled by a Source Control Manager (SCM) such as
1474 Git.
1475 Pulling source from a repository allows you to control
1476 the point in the repository (the revision) from which you want to
1477 build software.
1478 Finally, a combination of the two might exist, which would give the
1479 consumer a choice when deciding where to get source files.
1480 </p><p>
1481 BitBake uses the
1482 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a>
1483 variable to point to source files regardless of their location.
1484 Each recipe must have a <code class="filename">SRC_URI</code> variable
1485 that points to the source.
1486 </p><p>
1487 Another area that plays a significant role in where source files
1488 come from is pointed to by the
1489 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a>
1490 variable.
1491 This area is a cache that can hold previously downloaded source.
1492 You can also instruct the OpenEmbedded build system to create
1493 tarballs from Git repositories, which is not the default behavior,
1494 and store them in the <code class="filename">DL_DIR</code> by using the
1495 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BB_GENERATE_MIRROR_TARBALLS" target="_top"><code class="filename">BB_GENERATE_MIRROR_TARBALLS</code></a>
1496 variable.
1497 </p><p>
1498 Judicious use of a <code class="filename">DL_DIR</code> directory can
1499 save the build system a trip across the Internet when looking
1500 for files.
1501 A good method for using a download directory is to have
1502 <code class="filename">DL_DIR</code> point to an area outside of your
1503 Build Directory.
1504 Doing so allows you to safely delete the Build Directory
1505 if needed without fear of removing any downloaded source file.
1506 </p><p>
1507 The remainder of this section provides a deeper look into the
1508 source files and the mirrors.
1509 Here is a more detailed look at the source file area of the
1510 base figure:
1511 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 675px"><td align="center"><img src="figures/source-input.png" align="middle" width="630" /></td></tr></table><p>
1512 </p><div class="section" title="2.8.3.1. Upstream Project Releases"><div class="titlepage"><div><div><h4 class="title" id="upstream-project-releases">2.8.3.1. Upstream Project Releases<span class="permalink"><a alt="Permalink" title="Permalink" href="#upstream-project-releases">¶</a></span></h4></div></div></div><p>
1513 Upstream project releases exist anywhere in the form of an
1514 archived file (e.g. tarball or zip file).
1515 These files correspond to individual recipes.
1516 For example, the figure uses specific releases each for
1517 BusyBox, Qt, and Dbus.
1518 An archive file can be for any released product that can be
1519 built using a recipe.
1520 </p></div><div class="section" title="2.8.3.2. Local Projects"><div class="titlepage"><div><div><h4 class="title" id="local-projects">2.8.3.2. Local Projects<span class="permalink"><a alt="Permalink" title="Permalink" href="#local-projects">¶</a></span></h4></div></div></div><p>
1521 Local projects are custom bits of software the user provides.
1522 These bits reside somewhere local to a project - perhaps
1523 a directory into which the user checks in items (e.g.
1524 a local directory containing a development source tree
1525 used by the group).
1526 </p><p>
1527 The canonical method through which to include a local project
1528 is to use the
1529 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-externalsrc" target="_top"><code class="filename">externalsrc</code></a>
1530 class to include that local project.
1531 You use either the <code class="filename">local.conf</code> or a
1532 recipe's append file to override or set the
1533 recipe to point to the local directory on your disk to pull
1534 in the whole source tree.
1535 </p><p>
1536 For information on how to use the
1537 <code class="filename">externalsrc</code> class, see the
1538 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-externalsrc" target="_top"><code class="filename">externalsrc.bbclass</code></a>"
1539 section.
1540 </p></div><div class="section" title="2.8.3.3. Source Control Managers (Optional)"><div class="titlepage"><div><div><h4 class="title" id="scms">2.8.3.3. Source Control Managers (Optional)<span class="permalink"><a alt="Permalink" title="Permalink" href="#scms">¶</a></span></h4></div></div></div><p>
1541 Another place the build system can get source files from is
1542 through an SCM such as Git or Subversion.
1543 In this case, a repository is cloned or checked out.
1544 The
1545 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-fetch" target="_top"><code class="filename">do_fetch</code></a>
1546 task inside BitBake uses
1547 the <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a>
1548 variable and the argument's prefix to determine the correct
1549 fetcher module.
1550 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1551 For information on how to have the OpenEmbedded build system
1552 generate tarballs for Git repositories and place them in the
1553 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a>
1554 directory, see the
1555 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-BB_GENERATE_MIRROR_TARBALLS" target="_top"><code class="filename">BB_GENERATE_MIRROR_TARBALLS</code></a>
1556 variable.
1557 </div><p>
1558 When fetching a repository, BitBake uses the
1559 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRCREV" target="_top"><code class="filename">SRCREV</code></a>
1560 variable to determine the specific revision from which to
1561 build.
1562 </p></div><div class="section" title="2.8.3.4. Source Mirror(s)"><div class="titlepage"><div><div><h4 class="title" id="source-mirrors">2.8.3.4. Source Mirror(s)<span class="permalink"><a alt="Permalink" title="Permalink" href="#source-mirrors">¶</a></span></h4></div></div></div><p>
1563 Two kinds of mirrors exist: pre-mirrors and regular mirrors.
1564 The
1565 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PREMIRRORS" target="_top"><code class="filename">PREMIRRORS</code></a>
1566 and
1567 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MIRRORS" target="_top"><code class="filename">MIRRORS</code></a>
1568 variables point to these, respectively.
1569 BitBake checks pre-mirrors before looking upstream for any
1570 source files.
1571 Pre-mirrors are appropriate when you have a shared directory
1572 that is not a directory defined by the
1573 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DL_DIR" target="_top"><code class="filename">DL_DIR</code></a>
1574 variable.
1575 A Pre-mirror typically points to a shared directory that is
1576 local to your organization.
1577 </p><p>
1578 Regular mirrors can be any site across the Internet that is
1579 used as an alternative location for source code should the
1580 primary site not be functioning for some reason or another.
1581 </p></div></div><div class="section" title="2.8.4. Package Feeds"><div class="titlepage"><div><div><h3 class="title" id="package-feeds-dev-environment">2.8.4. Package Feeds<span class="permalink"><a alt="Permalink" title="Permalink" href="#package-feeds-dev-environment">¶</a></span></h3></div></div></div><p>
1582 When the OpenEmbedded build system generates an image or an SDK,
1583 it gets the packages from a package feed area located in the
1584 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>.
1585 The
1586 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>
1587 shows this package feeds area in the upper-right corner.
1588 </p><p>
1589 This section looks a little closer into the package feeds area used
1590 by the build system.
1591 Here is a more detailed look at the area:
1592 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 540px"><td align="center"><img src="figures/package-feeds.png" align="middle" width="630" /></td></tr></table><p>
1593 </p><p>
1594 Package feeds are an intermediary step in the build process.
1595 The OpenEmbedded build system provides classes to generate
1596 different package types, and you specify which classes to enable
1597 through the
1598 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a>
1599 variable.
1600 Before placing the packages into package feeds,
1601 the build process validates them with generated output quality
1602 assurance checks through the
1603 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-insane" target="_top"><code class="filename">insane</code></a>
1604 class.
1605 </p><p>
1606 The package feed area resides in the Build Directory.
1607 The directory the build system uses to temporarily store packages
1608 is determined by a combination of variables and the particular
1609 package manager in use.
1610 See the "Package Feeds" box in the illustration and note the
1611 information to the right of that area.
1612 In particular, the following defines where package files are
1613 kept:
1614 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>:
1615 Defined as <code class="filename">tmp/deploy</code> in the Build
1616 Directory.
1617 </p></li><li class="listitem"><p><code class="filename">DEPLOY_DIR_*</code>:
1618 Depending on the package manager used, the package type
1619 sub-folder.
1620 Given RPM, IPK, or DEB packaging and tarball creation, the
1621 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_RPM" target="_top"><code class="filename">DEPLOY_DIR_RPM</code></a>,
1622 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_IPK" target="_top"><code class="filename">DEPLOY_DIR_IPK</code></a>,
1623 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_DEB" target="_top"><code class="filename">DEPLOY_DIR_DEB</code></a>,
1624 or
1625 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_TAR" target="_top"><code class="filename">DEPLOY_DIR_TAR</code></a>,
1626 variables are used, respectively.
1627 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_ARCH" target="_top"><code class="filename">PACKAGE_ARCH</code></a>:
1628 Defines architecture-specific sub-folders.
1629 For example, packages could exist for the i586 or qemux86
1630 architectures.
1631 </p></li></ul></div><p>
1632 </p><p>
1633 BitBake uses the <code class="filename">do_package_write_*</code> tasks to
1634 generate packages and place them into the package holding area (e.g.
1635 <code class="filename">do_package_write_ipk</code> for IPK packages).
1636 See the
1637 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_deb" target="_top"><code class="filename">do_package_write_deb</code></a>",
1638 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_ipk" target="_top"><code class="filename">do_package_write_ipk</code></a>",
1639 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_rpm" target="_top"><code class="filename">do_package_write_rpm</code></a>",
1640 and
1641 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_tar" target="_top"><code class="filename">do_package_write_tar</code></a>"
1642 sections for additional information.
1643 As an example, consider a scenario where an IPK packaging manager
1644 is being used and package architecture support for both i586
1645 and qemux86 exist.
1646 Packages for the i586 architecture are placed in
1647 <code class="filename">build/tmp/deploy/ipk/i586</code>, while packages for
1648 the qemux86 architecture are placed in
1649 <code class="filename">build/tmp/deploy/ipk/qemux86</code>.
1650 </p></div><div class="section" title="2.8.5. BitBake"><div class="titlepage"><div><div><h3 class="title" id="bitbake-dev-environment">2.8.5. BitBake<span class="permalink"><a alt="Permalink" title="Permalink" href="#bitbake-dev-environment">¶</a></span></h3></div></div></div><p>
1651 The OpenEmbedded build system uses
1652 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a>
1653 to produce images.
1654 You can see from the
1655 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>,
1656 the BitBake area consists of several functional areas.
1657 This section takes a closer look at each of those areas.
1658 </p><p>
1659 Separate documentation exists for the BitBake tool.
1660 See the
1661 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual" target="_top">BitBake User Manual</a>
1662 for reference material on BitBake.
1663 </p><div class="section" title="2.8.5.1. Source Fetching"><div class="titlepage"><div><div><h4 class="title" id="source-fetching-dev-environment">2.8.5.1. Source Fetching<span class="permalink"><a alt="Permalink" title="Permalink" href="#source-fetching-dev-environment">¶</a></span></h4></div></div></div><p>
1664 The first stages of building a recipe are to fetch and unpack
1665 the source code:
1666 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="585"><tr style="height: 450px"><td align="center"><img src="figures/source-fetching.png" align="middle" width="585" /></td></tr></table><p>
1667 </p><p>
1668 The
1669 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-fetch" target="_top"><code class="filename">do_fetch</code></a>
1670 and
1671 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-unpack" target="_top"><code class="filename">do_unpack</code></a>
1672 tasks fetch the source files and unpack them into the work
1673 directory.
1674 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1675 For every local file (e.g. <code class="filename">file://</code>)
1676 that is part of a recipe's
1677 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a>
1678 statement, the OpenEmbedded build system takes a checksum
1679 of the file for the recipe and inserts the checksum into
1680 the signature for the <code class="filename">do_fetch</code>.
1681 If any local file has been modified, the
1682 <code class="filename">do_fetch</code> task and all tasks that
1683 depend on it are re-executed.
1684 </div><p>
1685 By default, everything is accomplished in the
1686 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>,
1687 which has a defined structure.
1688 For additional general information on the Build Directory,
1689 see the
1690 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#structure-core-build" target="_top"><code class="filename">build/</code></a>"
1691 section in the Yocto Project Reference Manual.
1692 </p><p>
1693 Unpacked source files are pointed to by the
1694 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a>
1695 variable.
1696 Each recipe has an area in the Build Directory where the
1697 unpacked source code resides.
1698 The name of that directory for any given recipe is defined from
1699 several different variables.
1700 You can see the variables that define these directories
1701 by looking at the figure:
1702 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a> -
1703 The base directory where the OpenEmbedded build system
1704 performs all its work during the build.
1705 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_ARCH" target="_top"><code class="filename">PACKAGE_ARCH</code></a> -
1706 The architecture of the built package or packages.
1707 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TARGET_OS" target="_top"><code class="filename">TARGET_OS</code></a> -
1708 The operating system of the target device.
1709 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PN" target="_top"><code class="filename">PN</code></a> -
1710 The name of the built package.
1711 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PV" target="_top"><code class="filename">PV</code></a> -
1712 The version of the recipe used to build the package.
1713 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PR" target="_top"><code class="filename">PR</code></a> -
1714 The revision of the recipe used to build the package.
1715 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a> -
1716 The location within <code class="filename">TMPDIR</code> where
1717 a specific package is built.
1718 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a> -
1719 Contains the unpacked source files for a given recipe.
1720 </p></li></ul></div><p>
1721 </p></div><div class="section" title="2.8.5.2. Patching"><div class="titlepage"><div><div><h4 class="title" id="patching-dev-environment">2.8.5.2. Patching<span class="permalink"><a alt="Permalink" title="Permalink" href="#patching-dev-environment">¶</a></span></h4></div></div></div><p>
1722 Once source code is fetched and unpacked, BitBake locates
1723 patch files and applies them to the source files:
1724 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 450px"><td align="center"><img src="figures/patching.png" align="middle" width="540" /></td></tr></table><p>
1725 </p><p>
1726 The
1727 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-patch" target="_top"><code class="filename">do_patch</code></a>
1728 task processes recipes by
1729 using the
1730 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SRC_URI" target="_top"><code class="filename">SRC_URI</code></a>
1731 variable to locate applicable patch files, which by default
1732 are <code class="filename">*.patch</code> or
1733 <code class="filename">*.diff</code> files, or any file if
1734 "apply=yes" is specified for the file in
1735 <code class="filename">SRC_URI</code>.
1736 </p><p>
1737 BitBake finds and applies multiple patches for a single recipe
1738 in the order in which it finds the patches.
1739 Patches are applied to the recipe's source files located in the
1740 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a>
1741 directory.
1742 </p><p>
1743 For more information on how the source directories are
1744 created, see the
1745 "<a class="link" href="#source-fetching-dev-environment" title="2.8.5.1. Source Fetching">Source Fetching</a>"
1746 section.
1747 </p></div><div class="section" title="2.8.5.3. Configuration and Compilation"><div class="titlepage"><div><div><h4 class="title" id="configuration-and-compilation-dev-environment">2.8.5.3. Configuration and Compilation<span class="permalink"><a alt="Permalink" title="Permalink" href="#configuration-and-compilation-dev-environment">¶</a></span></h4></div></div></div><p>
1748 After source code is patched, BitBake executes tasks that
1749 configure and compile the source code:
1750 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 450px"><td align="center"><img src="figures/configuration-compile-autoreconf.png" align="middle" width="630" /></td></tr></table><p>
1751 </p><p>
1752 This step in the build process consists of three tasks:
1753 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
1754 <span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-prepare_recipe_sysroot" target="_top"><code class="filename">do_prepare_recipe_sysroot</code></a>:</em></span>
1755 This task sets up the two sysroots in
1756 <code class="filename">${</code><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a><code class="filename">}</code>
1757 (i.e. <code class="filename">recipe-sysroot</code> and
1758 <code class="filename">recipe-sysroot-native</code>) so that
1759 the sysroots contain the contents of the
1760 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-populate_sysroot" target="_top"><code class="filename">do_populate_sysroot</code></a>
1761 tasks of the recipes on which the recipe
1762 containing the tasks depends.
1763 A sysroot exists for both the target and for the native
1764 binaries, which run on the host system.
1765 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">do_configure</code>:</em></span>
1766 This task configures the source by enabling and
1767 disabling any build-time and configuration options for
1768 the software being built.
1769 Configurations can come from the recipe itself as well
1770 as from an inherited class.
1771 Additionally, the software itself might configure itself
1772 depending on the target for which it is being built.
1773 </p><p>The configurations handled by the
1774 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-configure" target="_top"><code class="filename">do_configure</code></a>
1775 task are specific
1776 to source code configuration for the source code
1777 being built by the recipe.</p><p>If you are using the
1778 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-autotools" target="_top"><code class="filename">autotools</code></a>
1779 class,
1780 you can add additional configuration options by using
1781 the
1782 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-EXTRA_OECONF" target="_top"><code class="filename">EXTRA_OECONF</code></a>
1783 or
1784 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGECONFIG_CONFARGS" target="_top"><code class="filename">PACKAGECONFIG_CONFARGS</code></a>
1785 variables.
1786 For information on how this variable works within
1787 that class, see the
1788 <code class="filename">meta/classes/autotools.bbclass</code> file.
1789 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">do_compile</code>:</em></span>
1790 Once a configuration task has been satisfied, BitBake
1791 compiles the source using the
1792 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-compile" target="_top"><code class="filename">do_compile</code></a>
1793 task.
1794 Compilation occurs in the directory pointed to by the
1795 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-B" target="_top"><code class="filename">B</code></a>
1796 variable.
1797 Realize that the <code class="filename">B</code> directory is, by
1798 default, the same as the
1799 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a>
1800 directory.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">do_install</code>:</em></span>
1801 Once compilation is done, BitBake executes the
1802 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a>
1803 task.
1804 This task copies files from the <code class="filename">B</code>
1805 directory and places them in a holding area pointed to
1806 by the
1807 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-D" target="_top"><code class="filename">D</code></a>
1808 variable.</p></li></ul></div><p>
1809 </p></div><div class="section" title="2.8.5.4. Package Splitting"><div class="titlepage"><div><div><h4 class="title" id="package-splitting-dev-environment">2.8.5.4. Package Splitting<span class="permalink"><a alt="Permalink" title="Permalink" href="#package-splitting-dev-environment">¶</a></span></h4></div></div></div><p>
1810 After source code is configured and compiled, the
1811 OpenEmbedded build system analyzes
1812 the results and splits the output into packages:
1813 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="630"><tr style="height: 630px"><td align="center"><img src="figures/analysis-for-package-splitting.png" align="middle" width="630" /></td></tr></table><p>
1814 </p><p>
1815 The
1816 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>
1817 and
1818 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a>
1819 tasks combine to analyze
1820 the files found in the
1821 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-D" target="_top"><code class="filename">D</code></a> directory
1822 and split them into subsets based on available packages and
1823 files.
1824 The analyzing process involves the following as well as other
1825 items: splitting out debugging symbols,
1826 looking at shared library dependencies between packages,
1827 and looking at package relationships.
1828 The <code class="filename">do_packagedata</code> task creates package
1829 metadata based on the analysis such that the
1830 OpenEmbedded build system can generate the final packages.
1831 Working, staged, and intermediate results of the analysis
1832 and package splitting process use these areas:
1833 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGD" target="_top"><code class="filename">PKGD</code></a> -
1834 The destination directory for packages before they are
1835 split.
1836 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDATA_DIR" target="_top"><code class="filename">PKGDATA_DIR</code></a> -
1837 A shared, global-state directory that holds data
1838 generated during the packaging process.
1839 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDESTWORK" target="_top"><code class="filename">PKGDESTWORK</code></a> -
1840 A temporary work area used by the
1841 <code class="filename">do_package</code> task.
1842 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDEST" target="_top"><code class="filename">PKGDEST</code></a> -
1843 The parent directory for packages after they have
1844 been split.
1845 </p></li></ul></div><p>
1846 The <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-FILES" target="_top"><code class="filename">FILES</code></a>
1847 variable defines the files that go into each package in
1848 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGES" target="_top"><code class="filename">PACKAGES</code></a>.
1849 If you want details on how this is accomplished, you can
1850 look at the
1851 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-package" target="_top"><code class="filename">package</code></a>
1852 class.
1853 </p><p>
1854 Depending on the type of packages being created (RPM, DEB, or
1855 IPK), the <code class="filename">do_package_write_*</code> task
1856 creates the actual packages and places them in the
1857 Package Feed area, which is
1858 <code class="filename">${TMPDIR}/deploy</code>.
1859 You can see the
1860 "<a class="link" href="#package-feeds-dev-environment" title="2.8.4. Package Feeds">Package Feeds</a>"
1861 section for more detail on that part of the build process.
1862 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1863 Support for creating feeds directly from the
1864 <code class="filename">deploy/*</code> directories does not exist.
1865 Creating such feeds usually requires some kind of feed
1866 maintenance mechanism that would upload the new packages
1867 into an official package feed (e.g. the
1868 Ångström distribution).
1869 This functionality is highly distribution-specific
1870 and thus is not provided out of the box.
1871 </div><p>
1872 </p></div><div class="section" title="2.8.5.5. Image Generation"><div class="titlepage"><div><div><h4 class="title" id="image-generation-dev-environment">2.8.5.5. Image Generation<span class="permalink"><a alt="Permalink" title="Permalink" href="#image-generation-dev-environment">¶</a></span></h4></div></div></div><p>
1873 Once packages are split and stored in the Package Feeds area,
1874 the OpenEmbedded build system uses BitBake to generate the
1875 root filesystem image:
1876 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 630px"><td align="center"><img src="figures/image-generation.png" align="middle" width="540" /></td></tr></table><p>
1877 </p><p>
1878 The image generation process consists of several stages and
1879 depends on several tasks and variables.
1880 The
1881 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-rootfs" target="_top"><code class="filename">do_rootfs</code></a>
1882 task creates the root filesystem (file and directory structure)
1883 for an image.
1884 This task uses several key variables to help create the list
1885 of packages to actually install:
1886 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_INSTALL" target="_top"><code class="filename">IMAGE_INSTALL</code></a>:
1887 Lists out the base set of packages to install from
1888 the Package Feeds area.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_EXCLUDE" target="_top"><code class="filename">PACKAGE_EXCLUDE</code></a>:
1889 Specifies packages that should not be installed.
1890 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_FEATURES" target="_top"><code class="filename">IMAGE_FEATURES</code></a>:
1891 Specifies features to include in the image.
1892 Most of these features map to additional packages for
1893 installation.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_CLASSES" target="_top"><code class="filename">PACKAGE_CLASSES</code></a>:
1894 Specifies the package backend to use and consequently
1895 helps determine where to locate packages within the
1896 Package Feeds area.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_LINGUAS" target="_top"><code class="filename">IMAGE_LINGUAS</code></a>:
1897 Determines the language(s) for which additional
1898 language support packages are installed.
1899 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_INSTALL" target="_top"><code class="filename">PACKAGE_INSTALL</code></a>:
1900 The final list of packages passed to the package manager
1901 for installation into the image.
1902 </p></li></ul></div><p>
1903 </p><p>
1904 With
1905 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_ROOTFS" target="_top"><code class="filename">IMAGE_ROOTFS</code></a>
1906 pointing to the location of the filesystem under construction and
1907 the <code class="filename">PACKAGE_INSTALL</code> variable providing the
1908 final list of packages to install, the root file system is
1909 created.
1910 </p><p>
1911 Package installation is under control of the package manager
1912 (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or
1913 not package management is enabled for the target.
1914 At the end of the process, if package management is not
1915 enabled for the target, the package manager's data files
1916 are deleted from the root filesystem.
1917 As part of the final stage of package installation, postinstall
1918 scripts that are part of the packages are run.
1919 Any scripts that fail to run
1920 on the build host are run on the target when the target system
1921 is first booted.
1922 If you are using a
1923 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#creating-a-read-only-root-filesystem" target="_top">read-only root filesystem</a>,
1924 all the post installation scripts must succeed during the
1925 package installation phase since the root filesystem is
1926 read-only.
1927 </p><p>
1928 The final stages of the <code class="filename">do_rootfs</code> task
1929 handle post processing.
1930 Post processing includes creation of a manifest file and
1931 optimizations.
1932 </p><p>
1933 The manifest file (<code class="filename">.manifest</code>) resides
1934 in the same directory as the root filesystem image.
1935 This file lists out, line-by-line, the installed packages.
1936 The manifest file is useful for the
1937 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-testimage*" target="_top"><code class="filename">testimage</code></a>
1938 class, for example, to determine whether or not to run
1939 specific tests.
1940 See the
1941 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_MANIFEST" target="_top"><code class="filename">IMAGE_MANIFEST</code></a>
1942 variable for additional information.
1943 </p><p>
1944 Optimizing processes run across the image include
1945 <code class="filename">mklibs</code>, <code class="filename">prelink</code>,
1946 and any other post-processing commands as defined by the
1947 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-ROOTFS_POSTPROCESS_COMMAND" target="_top"><code class="filename">ROOTFS_POSTPROCESS_COMMAND</code></a>
1948 variable.
1949 The <code class="filename">mklibs</code> process optimizes the size
1950 of the libraries, while the
1951 <code class="filename">prelink</code> process optimizes the dynamic
1952 linking of shared libraries to reduce start up time of
1953 executables.
1954 </p><p>
1955 After the root filesystem is built, processing begins on
1956 the image through the
1957 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-image" target="_top"><code class="filename">do_image</code></a>
1958 task.
1959 The build system runs any pre-processing commands as defined
1960 by the
1961 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_PREPROCESS_COMMAND" target="_top"><code class="filename">IMAGE_PREPROCESS_COMMAND</code></a>
1962 variable.
1963 This variable specifies a list of functions to call before
1964 the OpenEmbedded build system creates the final image output
1965 files.
1966 </p><p>
1967 The OpenEmbedded build system dynamically creates
1968 <code class="filename">do_image_*</code> tasks as needed, based
1969 on the image types specified in the
1970 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_FSTYPES" target="_top"><code class="filename">IMAGE_FSTYPES</code></a>
1971 variable.
1972 The process turns everything into an image file or a set of
1973 image files and compresses the root filesystem image to reduce
1974 the overall size of the image.
1975 The formats used for the root filesystem depend on the
1976 <code class="filename">IMAGE_FSTYPES</code> variable.
1977 </p><p>
1978 As an example, a dynamically created task when creating a
1979 particular image <em class="replaceable"><code>type</code></em> would take the
1980 following form:
1981 </p><pre class="literallayout">
1982 do_image_<em class="replaceable"><code>type</code></em>[depends]
1983 </pre><p>
1984 So, if the <em class="replaceable"><code>type</code></em> as specified by the
1985 <code class="filename">IMAGE_FSTYPES</code> were
1986 <code class="filename">ext4</code>, the dynamically generated task
1987 would be as follows:
1988 </p><pre class="literallayout">
1989 do_image_ext4[depends]
1990 </pre><p>
1991 </p><p>
1992 The final task involved in image creation is the
1993 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-image-complete" target="_top"><code class="filename">do_image_complete</code></a>
1994 task.
1995 This task completes the image by applying any image
1996 post processing as defined through the
1997 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_POSTPROCESS_COMMAND" target="_top"><code class="filename">IMAGE_POSTPROCESS_COMMAND</code></a>
1998 variable.
1999 The variable specifies a list of functions to call once the
2000 OpenEmbedded build system has created the final image output
2001 files.
2002 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2003 The entire image generation process is run under Pseudo.
2004 Running under Pseudo ensures that the files in the root
2005 filesystem have correct ownership.
2006 </div></div><div class="section" title="2.8.5.6. SDK Generation"><div class="titlepage"><div><div><h4 class="title" id="sdk-generation-dev-environment">2.8.5.6. SDK Generation<span class="permalink"><a alt="Permalink" title="Permalink" href="#sdk-generation-dev-environment">¶</a></span></h4></div></div></div><p>
2007 The OpenEmbedded build system uses BitBake to generate the
2008 Software Development Kit (SDK) installer script for both the
2009 standard and extensible SDKs:
2010 <img src="figures/sdk-generation.png" align="middle" />
2011 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2012 For more information on the cross-development toolchain
2013 generation, see the
2014 "<a class="link" href="#cross-development-toolchain-generation" title="3.2. Cross-Development Toolchain Generation">Cross-Development Toolchain Generation</a>"
2015 section.
2016 For information on advantages gained when building a
2017 cross-development toolchain using the
2018 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-populate_sdk" target="_top"><code class="filename">do_populate_sdk</code></a>
2019 task, see the
2020 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#sdk-building-an-sdk-installer" target="_top">Building an SDK Installer</a>"
2021 section in the Yocto Project Application Development and the
2022 Extensible Software Development Kit (SDK) manual.
2023 </div><p>
2024 Like image generation, the SDK script process consists of
2025 several stages and depends on many variables.
2026 The <code class="filename">do_populate_sdk</code> and
2027 <code class="filename">do_populate_sdk_ext</code> tasks use these
2028 key variables to help create the list of packages to actually
2029 install.
2030 For information on the variables listed in the figure, see the
2031 "<a class="link" href="#sdk-dev-environment" title="2.8.7. Application Development SDK">Application Development SDK</a>"
2032 section.
2033 </p><p>
2034 The <code class="filename">do_populate_sdk</code> task helps create
2035 the standard SDK and handles two parts: a target part and a
2036 host part.
2037 The target part is the part built for the target hardware and
2038 includes libraries and headers.
2039 The host part is the part of the SDK that runs on the
2040 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>.
2041 </p><p>
2042 The <code class="filename">do_populate_sdk_ext</code> task helps create
2043 the extensible SDK and handles host and target parts
2044 differently than its counter part does for the standard SDK.
2045 For the extensible SDK, the task encapsulates the build system,
2046 which includes everything needed (host and target) for the SDK.
2047 </p><p>
2048 Regardless of the type of SDK being constructed, the
2049 tasks perform some cleanup after which a cross-development
2050 environment setup script and any needed configuration files
2051 are created.
2052 The final output is the Cross-development
2053 toolchain installation script (<code class="filename">.sh</code> file),
2054 which includes the environment setup script.
2055 </p></div><div class="section" title="2.8.5.7. Stamp Files and the Rerunning of Tasks"><div class="titlepage"><div><div><h4 class="title" id="stamp-files-and-the-rerunning-of-tasks">2.8.5.7. Stamp Files and the Rerunning of Tasks<span class="permalink"><a alt="Permalink" title="Permalink" href="#stamp-files-and-the-rerunning-of-tasks">¶</a></span></h4></div></div></div><p>
2056 For each task that completes successfully, BitBake writes a
2057 stamp file into the
2058 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-STAMPS_DIR" target="_top"><code class="filename">STAMPS_DIR</code></a>
2059 directory.
2060 The beginning of the stamp file's filename is determined by the
2061 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-STAMP" target="_top"><code class="filename">STAMP</code></a>
2062 variable, and the end of the name consists of the task's name
2063 and current
2064 <a class="link" href="#overview-checksums" title="3.3.2. Checksums (Signatures)">input checksum</a>.
2065 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2066 This naming scheme assumes that
2067 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_SIGNATURE_HANDLER" target="_top"><code class="filename">BB_SIGNATURE_HANDLER</code></a>
2068 is "OEBasicHash", which is almost always the case in
2069 current OpenEmbedded.
2070 </div><p>
2071 To determine if a task needs to be rerun, BitBake checks if a
2072 stamp file with a matching input checksum exists for the task.
2073 If such a stamp file exists, the task's output is assumed to
2074 exist and still be valid.
2075 If the file does not exist, the task is rerun.
2076 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The stamp mechanism is more general than the shared
2077 state (sstate) cache mechanism described in the
2078 "<a class="link" href="#setscene-tasks-and-shared-state" title="2.8.5.8. Setscene Tasks and Shared State">Setscene Tasks and Shared State</a>"
2079 section.
2080 BitBake avoids rerunning any task that has a valid
2081 stamp file, not just tasks that can be accelerated through
2082 the sstate cache.</p><p>However, you should realize that stamp files only
2083 serve as a marker that some work has been done and that
2084 these files do not record task output.
2085 The actual task output would usually be somewhere in
2086 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a>
2087 (e.g. in some recipe's
2088 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>.)
2089 What the sstate cache mechanism adds is a way to cache task
2090 output that can then be shared between build machines.
2091 </p></div><p>
2092 Since <code class="filename">STAMPS_DIR</code> is usually a subdirectory
2093 of <code class="filename">TMPDIR</code>, removing
2094 <code class="filename">TMPDIR</code> will also remove
2095 <code class="filename">STAMPS_DIR</code>, which means tasks will
2096 properly be rerun to repopulate <code class="filename">TMPDIR</code>.
2097 </p><p>
2098 If you want some task to always be considered "out of date",
2099 you can mark it with the
2100 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#variable-flags" target="_top"><code class="filename">nostamp</code></a>
2101 varflag.
2102 If some other task depends on such a task, then that task will
2103 also always be considered out of date, which might not be what
2104 you want.
2105 </p><p>
2106 For details on how to view information about a task's
2107 signature, see the
2108 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#dev-viewing-task-variable-dependencies" target="_top">Viewing Task Variable Dependencies</a>"
2109 section in the Yocto Project Development Tasks Manual.
2110 </p></div><div class="section" title="2.8.5.8. Setscene Tasks and Shared State"><div class="titlepage"><div><div><h4 class="title" id="setscene-tasks-and-shared-state">2.8.5.8. Setscene Tasks and Shared State<span class="permalink"><a alt="Permalink" title="Permalink" href="#setscene-tasks-and-shared-state">¶</a></span></h4></div></div></div><p>
2111 The description of tasks so far assumes that BitBake needs to
2112 build everything and there are no prebuilt objects available.
2113 BitBake does support skipping tasks if prebuilt objects are
2114 available.
2115 These objects are usually made available in the form of a
2116 shared state (sstate) cache.
2117 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2118 For information on variables affecting sstate, see the
2119 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a>
2120 and
2121 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_MIRRORS" target="_top"><code class="filename">SSTATE_MIRRORS</code></a>
2122 variables.
2123 </div><p>
2124 </p><p>
2125 The idea of a setscene task (i.e
2126 <code class="filename">do_</code><em class="replaceable"><code>taskname</code></em><code class="filename">_setscene</code>)
2127 is a version of the task where
2128 instead of building something, BitBake can skip to the end
2129 result and simply place a set of files into specific locations
2130 as needed.
2131 In some cases, it makes sense to have a setscene task variant
2132 (e.g. generating package files in the
2133 <code class="filename">do_package_write_*</code> task).
2134 In other cases, it does not make sense, (e.g. a
2135 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-patch" target="_top"><code class="filename">do_patch</code></a>
2136 task or
2137 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-unpack" target="_top"><code class="filename">do_unpack</code></a>
2138 task) since the work involved would be equal to or greater than
2139 the underlying task.
2140 </p><p>
2141 In the OpenEmbedded build system, the common tasks that have
2142 setscene variants are
2143 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>,
2144 <code class="filename">do_package_write_*</code>,
2145 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-deploy" target="_top"><code class="filename">do_deploy</code></a>,
2146 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a>,
2147 and
2148 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-populate_sysroot" target="_top"><code class="filename">do_populate_sysroot</code></a>.
2149 Notice that these are most of the tasks whose output is an
2150 end result.
2151 </p><p>
2152 The OpenEmbedded build system has knowledge of the relationship
2153 between these tasks and other tasks that precede them.
2154 For example, if BitBake runs
2155 <code class="filename">do_populate_sysroot_setscene</code> for
2156 something, there is little point in running any of the
2157 <code class="filename">do_fetch</code>, <code class="filename">do_unpack</code>,
2158 <code class="filename">do_patch</code>,
2159 <code class="filename">do_configure</code>,
2160 <code class="filename">do_compile</code>, and
2161 <code class="filename">do_install</code> tasks.
2162 However, if <code class="filename">do_package</code> needs to be run,
2163 BitBake would need to run those other tasks.
2164 </p><p>
2165 It becomes more complicated if everything can come from an
2166 sstate cache because some objects are simply not required at
2167 all.
2168 For example, you do not need a compiler or native tools, such
2169 as quilt, if there is nothing to compile or patch.
2170 If the <code class="filename">do_package_write_*</code> packages are
2171 available from sstate, BitBake does not need the
2172 <code class="filename">do_package</code> task data.
2173 </p><p>
2174 To handle all these complexities, BitBake runs in two phases.
2175 The first is the "setscene" stage.
2176 During this stage, BitBake first checks the sstate cache for
2177 any targets it is planning to build.
2178 BitBake does a fast check to see if the object exists rather
2179 than a complete download.
2180 If nothing exists, the second phase, which is the setscene
2181 stage, completes and the main build proceeds.
2182 </p><p>
2183 If objects are found in the sstate cache, the OpenEmbedded
2184 build system works backwards from the end targets specified
2185 by the user.
2186 For example, if an image is being built, the OpenEmbedded build
2187 system first looks for the packages needed for that image and
2188 the tools needed to construct an image.
2189 If those are available, the compiler is not needed.
2190 Thus, the compiler is not even downloaded.
2191 If something was found to be unavailable, or the download or
2192 setscene task fails, the OpenEmbedded build system then tries
2193 to install dependencies, such as the compiler, from the cache.
2194 </p><p>
2195 The availability of objects in the sstate cache is handled by
2196 the function specified by the
2197 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_HASHCHECK_FUNCTION" target="_top"><code class="filename">BB_HASHCHECK_FUNCTION</code></a>
2198 variable and returns a list of the objects that are available.
2199 The function specified by the
2200 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-BB_SETSCENE_DEPVALID" target="_top"><code class="filename">BB_SETSCENE_DEPVALID</code></a>
2201 variable is the function that determines whether a given
2202 dependency needs to be followed, and whether for any given
2203 relationship the function needs to be passed.
2204 The function returns a True or False value.
2205 </p></div></div><div class="section" title="2.8.6. Images"><div class="titlepage"><div><div><h3 class="title" id="images-dev-environment">2.8.6. Images<span class="permalink"><a alt="Permalink" title="Permalink" href="#images-dev-environment">¶</a></span></h3></div></div></div><p>
2206 The images produced by the OpenEmbedded build system
2207 are compressed forms of the
2208 root filesystem that are ready to boot on a target device.
2209 You can see from the
2210 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>
2211 that BitBake output, in part, consists of images.
2212 This section is going to look more closely at this output:
2213 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="495"><tr style="height: 495px"><td align="center"><img src="figures/images.png" align="middle" width="495" /></td></tr></table><p>
2214 </p><p>
2215 For a list of example images that the Yocto Project provides,
2216 see the
2217 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-images" target="_top">Images</a>"
2218 chapter in the Yocto Project Reference Manual.
2219 </p><p>
2220 Images are written out to the
2221 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>
2222 inside the
2223 <code class="filename">tmp/deploy/images/<em class="replaceable"><code>machine</code></em>/</code>
2224 folder as shown in the figure.
2225 This folder contains any files expected to be loaded on the
2226 target device.
2227 The
2228 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>
2229 variable points to the <code class="filename">deploy</code> directory,
2230 while the
2231 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR_IMAGE" target="_top"><code class="filename">DEPLOY_DIR_IMAGE</code></a>
2232 variable points to the appropriate directory containing images for
2233 the current configuration.
2234 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><em class="replaceable"><code>kernel-image</code></em></code>:
2235 A kernel binary file.
2236 The
2237 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-KERNEL_IMAGETYPE" target="_top"><code class="filename">KERNEL_IMAGETYPE</code></a>
2238 variable setting determines the naming scheme for the
2239 kernel image file.
2240 Depending on that variable, the file could begin with
2241 a variety of naming strings.
2242 The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code>
2243 directory can contain multiple image files for the
2244 machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>root-filesystem-image</code></em></code>:
2245 Root filesystems for the target device (e.g.
2246 <code class="filename">*.ext3</code> or <code class="filename">*.bz2</code>
2247 files).
2248 The
2249 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-IMAGE_FSTYPES" target="_top"><code class="filename">IMAGE_FSTYPES</code></a>
2250 variable setting determines the root filesystem image
2251 type.
2252 The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code>
2253 directory can contain multiple root filesystems for the
2254 machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>kernel-modules</code></em></code>:
2255 Tarballs that contain all the modules built for the kernel.
2256 Kernel module tarballs exist for legacy purposes and
2257 can be suppressed by setting the
2258 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MODULE_TARBALL_DEPLOY" target="_top"><code class="filename">MODULE_TARBALL_DEPLOY</code></a>
2259 variable to "0".
2260 The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code>
2261 directory can contain multiple kernel module tarballs
2262 for the machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>bootloaders</code></em></code>:
2263 Bootloaders supporting the image, if applicable to the
2264 target machine.
2265 The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code>
2266 directory can contain multiple bootloaders for the
2267 machine.</p></li><li class="listitem"><p><code class="filename"><em class="replaceable"><code>symlinks</code></em></code>:
2268 The <code class="filename">deploy/images/<em class="replaceable"><code>machine</code></em></code>
2269 folder contains
2270 a symbolic link that points to the most recently built file
2271 for each machine.
2272 These links might be useful for external scripts that
2273 need to obtain the latest version of each file.
2274 </p></li></ul></div><p>
2275 </p></div><div class="section" title="2.8.7. Application Development SDK"><div class="titlepage"><div><div><h3 class="title" id="sdk-dev-environment">2.8.7. Application Development SDK<span class="permalink"><a alt="Permalink" title="Permalink" href="#sdk-dev-environment">¶</a></span></h3></div></div></div><p>
2276 In the
2277 <a class="link" href="#general-yocto-environment-figure">general Yocto Project Development Environment figure</a>,
2278 the output labeled "Application Development SDK" represents an
2279 SDK.
2280 The SDK generation process differs depending on whether you build
2281 a standard SDK
2282 (e.g. <code class="filename">bitbake -c populate_sdk</code> <em class="replaceable"><code>imagename</code></em>)
2283 or an extensible SDK
2284 (e.g. <code class="filename">bitbake -c populate_sdk_ext</code> <em class="replaceable"><code>imagename</code></em>).
2285 This section is going to take a closer look at this output:
2286 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="810"><tr style="height: 653px"><td align="center"><img src="figures/sdk.png" align="middle" width="810" /></td></tr></table><p>
2287 </p><p>
2288 The specific form of this output is a self-extracting
2289 SDK installer (<code class="filename">*.sh</code>) that, when run,
2290 installs the SDK, which consists of a cross-development
2291 toolchain, a set of libraries and headers, and an SDK
2292 environment setup script.
2293 Running this installer essentially sets up your
2294 cross-development environment.
2295 You can think of the cross-toolchain as the "host"
2296 part because it runs on the SDK machine.
2297 You can think of the libraries and headers as the "target"
2298 part because they are built for the target hardware.
2299 The environment setup script is added so that you can initialize
2300 the environment before using the tools.
2301 </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2302 The Yocto Project supports several methods by which you can
2303 set up this cross-development environment.
2304 These methods include downloading pre-built SDK installers
2305 or building and installing your own SDK installer.
2306 </p></li><li class="listitem"><p>
2307 For background information on cross-development toolchains
2308 in the Yocto Project development environment, see the
2309 "<a class="link" href="#cross-development-toolchain-generation" title="3.2. Cross-Development Toolchain Generation">Cross-Development Toolchain Generation</a>"
2310 section.
2311 </p></li><li class="listitem"><p>
2312 For information on setting up a cross-development
2313 environment, see the
2314 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a>
2315 manual.
2316 </p></li></ul></div></div><p>
2317 Once built, the SDK installers are written out to the
2318 <code class="filename">deploy/sdk</code> folder inside the
2319 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>
2320 as shown in the figure at the beginning of this section.
2321 Depending on the type of SDK, several variables exist that help
2322 configure these files.
2323 The following list shows the variables associated with a standard
2324 SDK:
2325 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>:
2326 Points to the <code class="filename">deploy</code>
2327 directory.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>:
2328 Specifies the architecture of the machine
2329 on which the cross-development tools are run to
2330 create packages for the target hardware.
2331 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKIMAGE_FEATURES" target="_top"><code class="filename">SDKIMAGE_FEATURES</code></a>:
2332 Lists the features to include in the "target" part
2333 of the SDK.
2334 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TOOLCHAIN_HOST_TASK" target="_top"><code class="filename">TOOLCHAIN_HOST_TASK</code></a>:
2335 Lists packages that make up the host
2336 part of the SDK (i.e. the part that runs on
2337 the <code class="filename">SDKMACHINE</code>).
2338 When you use
2339 <code class="filename">bitbake -c populate_sdk <em class="replaceable"><code>imagename</code></em></code>
2340 to create the SDK, a set of default packages
2341 apply.
2342 This variable allows you to add more packages.
2343 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TOOLCHAIN_TARGET_TASK" target="_top"><code class="filename">TOOLCHAIN_TARGET_TASK</code></a>:
2344 Lists packages that make up the target part
2345 of the SDK (i.e. the part built for the
2346 target hardware).
2347 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKPATH" target="_top"><code class="filename">SDKPATH</code></a>:
2348 Defines the default SDK installation path offered by the
2349 installation script.
2350 </p></li></ul></div><p>
2351 This next list, shows the variables associated with an extensible
2352 SDK:
2353 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPLOY_DIR" target="_top"><code class="filename">DEPLOY_DIR</code></a>:
2354 Points to the <code class="filename">deploy</code> directory.
2355 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_EXT_TYPE" target="_top"><code class="filename">SDK_EXT_TYPE</code></a>:
2356 Controls whether or not shared state artifacts are copied
2357 into the extensible SDK.
2358 By default, all required shared state artifacts are copied
2359 into the SDK.
2360 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_INCLUDE_PKGDATA" target="_top"><code class="filename">SDK_INCLUDE_PKGDATA</code></a>:
2361 Specifies whether or not packagedata will be included in
2362 the extensible SDK for all recipes in the "world" target.
2363 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_INCLUDE_TOOLCHAIN" target="_top"><code class="filename">SDK_INCLUDE_TOOLCHAIN</code></a>:
2364 Specifies whether or not the toolchain will be included
2365 when building the extensible SDK.
2366 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_LOCAL_CONF_WHITELIST" target="_top"><code class="filename">SDK_LOCAL_CONF_WHITELIST</code></a>:
2367 A list of variables allowed through from the build system
2368 configuration into the extensible SDK configuration.
2369 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_LOCAL_CONF_BLACKLIST" target="_top"><code class="filename">SDK_LOCAL_CONF_BLACKLIST</code></a>:
2370 A list of variables not allowed through from the build
2371 system configuration into the extensible SDK configuration.
2372 </p></li><li class="listitem"><p><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_INHERIT_BLACKLIST" target="_top"><code class="filename">SDK_INHERIT_BLACKLIST</code></a>:
2373 A list of classes to remove from the
2374 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-INHERIT" target="_top"><code class="filename">INHERIT</code></a>
2375 value globally within the extensible SDK configuration.
2376 </p></li></ul></div><p>
2377 </p></div></div></div>
2378
2379 <div class="chapter" title="Chapter 3. Yocto Project Concepts" id="overview-concepts"><div class="titlepage"><div><div><h2 class="title">Chapter 3. Yocto Project Concepts<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-concepts">¶</a></span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#yocto-project-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#metadata-virtual-providers">3.1.3. Metadata (Virtual Providers)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.4. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.5. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#cross-development-toolchain-generation">3.2. Cross-Development Toolchain Generation</a></span></dt><dt><span class="section"><a href="#shared-state-cache">3.3. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.3.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#overview-checksums">3.3.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.3.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.3.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#automatically-added-runtime-dependencies">3.4. Automatically Added Runtime Dependencies</a></span></dt><dt><span class="section"><a href="#fakeroot-and-pseudo">3.5. Fakeroot and Pseudo</a></span></dt><dt><span class="section"><a href="#wayland">3.6. Wayland</a></span></dt><dd><dl><dt><span class="section"><a href="#wayland-support">3.6.1. Support</a></span></dt><dt><span class="section"><a href="#enabling-wayland-in-an-image">3.6.2. Enabling Wayland in an Image</a></span></dt><dt><span class="section"><a href="#running-weston">3.6.3. Running Weston</a></span></dt></dl></dd><dt><span class="section"><a href="#overview-licenses">3.7. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.7.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.7.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.8. x32 psABI</a></span></dt></dl></div><p>
2380 This chapter describes concepts for various areas of the Yocto Project.
2381 Currently, topics include Yocto Project components, cross-development
2382 generation, shared state (sstate) cache, runtime dependencies,
2383 Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses.
2384 </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="yocto-project-components">3.1. Yocto Project Components<span class="permalink"><a alt="Permalink" title="Permalink" href="#yocto-project-components">¶</a></span></h2></div></div></div><p>
2385 The
2386 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#bitbake-term" target="_top">BitBake</a>
2387 task executor together with various types of configuration files
2388 form the OpenEmbedded Core.
2389 This section overviews these components by describing their use and
2390 how they interact.
2391 </p><p>
2392 BitBake handles the parsing and execution of the data files.
2393 The data itself is of various types:
2394 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2395 <span class="emphasis"><em>Recipes:</em></span>
2396 Provides details about particular pieces of software.
2397 </p></li><li class="listitem"><p>
2398 <span class="emphasis"><em>Class Data:</em></span>
2399 Abstracts common build information (e.g. how to build a
2400 Linux kernel).
2401 </p></li><li class="listitem"><p>
2402 <span class="emphasis"><em>Configuration Data:</em></span>
2403 Defines machine-specific settings, policy decisions, and
2404 so forth.
2405 Configuration data acts as the glue to bind everything
2406 together.
2407 </p></li></ul></div><p>
2408 </p><p>
2409 BitBake knows how to combine multiple data sources together and
2410 refers to each data source as a layer.
2411 For information on layers, see the
2412 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and Creating Layers</a>"
2413 section of the Yocto Project Development Tasks Manual.
2414 </p><p>
2415 Following are some brief details on these core components.
2416 For additional information on how these components interact during
2417 a build, see the
2418 "<a class="link" href="#development-concepts" title="2.8. Development Concepts">Development Concepts</a>"
2419 section.
2420 </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-bitbake">3.1.1. BitBake<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-bitbake">¶</a></span></h3></div></div></div><p>
2421 BitBake is the tool at the heart of the OpenEmbedded build
2422 system and is responsible for parsing the
2423 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>,
2424 generating a list of tasks from it, and then executing those
2425 tasks.
2426 </p><p>
2427 This section briefly introduces BitBake.
2428 If you want more information on BitBake, see the
2429 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bitbake-user-manual" target="_top">BitBake User Manual</a>.
2430 </p><p>
2431 To see a list of the options BitBake supports, use either of
2432 the following commands:
2433 </p><pre class="literallayout">
2434 $ bitbake -h
2435 $ bitbake --help
2436 </pre><p>
2437 </p><p>
2438 The most common usage for BitBake is
2439 <code class="filename">bitbake <em class="replaceable"><code>packagename</code></em></code>,
2440 where <code class="filename">packagename</code> is the name of the
2441 package you want to build (referred to as the "target" in this
2442 manual).
2443 The target often equates to the first part of a recipe's
2444 filename (e.g. "foo" for a recipe named
2445 <code class="filename">foo_1.3.0-r0.bb</code>).
2446 So, to process the
2447 <code class="filename">matchbox-desktop_1.2.3.bb</code> recipe file, you
2448 might type the following:
2449 </p><pre class="literallayout">
2450 $ bitbake matchbox-desktop
2451 </pre><p>
2452 Several different versions of
2453 <code class="filename">matchbox-desktop</code> might exist.
2454 BitBake chooses the one selected by the distribution
2455 configuration.
2456 You can get more details about how BitBake chooses between
2457 different target versions and providers in the
2458 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#bb-bitbake-preferences" target="_top">Preferences</a>"
2459 section of the BitBake User Manual.
2460 </p><p>
2461 BitBake also tries to execute any dependent tasks first.
2462 So for example, before building
2463 <code class="filename">matchbox-desktop</code>, BitBake would build a
2464 cross compiler and <code class="filename">glibc</code> if they had not
2465 already been built.
2466 </p><p>
2467 A useful BitBake option to consider is the
2468 <code class="filename">-k</code> or <code class="filename">--continue</code>
2469 option.
2470 This option instructs BitBake to try and continue processing
2471 the job as long as possible even after encountering an error.
2472 When an error occurs, the target that failed and those that
2473 depend on it cannot be remade.
2474 However, when you use this option other dependencies can
2475 still be processed.
2476 </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-metadata">3.1.2. Metadata (Recipes)<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-metadata">¶</a></span></h3></div></div></div><p>
2477 Files that have the <code class="filename">.bb</code> suffix are
2478 "recipes" files.
2479 In general, a recipe contains information about a single piece
2480 of software.
2481 This information includes the location from which to download
2482 the unaltered source, any source patches to be applied to that
2483 source (if needed), which special configuration options to
2484 apply, how to compile the source files, and how to package the
2485 compiled output.
2486 </p><p>
2487 The term "package" is sometimes used to refer to recipes.
2488 However, since the word "package" is used for the packaged
2489 output from the OpenEmbedded build system (i.e.
2490 <code class="filename">.ipk</code> or <code class="filename">.deb</code> files),
2491 this document avoids using the term "package" when referring
2492 to recipes.
2493 </p></div><div class="section" title="3.1.3. Metadata (Virtual Providers)"><div class="titlepage"><div><div><h3 class="title" id="metadata-virtual-providers">3.1.3. Metadata (Virtual Providers)<span class="permalink"><a alt="Permalink" title="Permalink" href="#metadata-virtual-providers">¶</a></span></h3></div></div></div><p>
2494 Prior to the build, if you know that several different recipes
2495 provide the same functionality, you can use a virtual provider
2496 (i.e. <code class="filename">virtual/*</code>) as a placeholder for the
2497 actual provider.
2498 The actual provider would be determined at build time.
2499 In this case, you should add <code class="filename">virtual/*</code>
2500 to
2501 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPENDS" target="_top"><code class="filename">DEPENDS</code></a>,
2502 rather than listing the specified provider.
2503 You would select the actual provider by setting the
2504 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PREFERRED_PROVIDER" target="_top"><code class="filename">PREFERRED_PROVIDER</code></a>
2505 variable (i.e.
2506 <code class="filename">PREFERRED_PROVIDER_virtual/*</code>)
2507 in the build's configuration file (e.g.
2508 <code class="filename">poky/build/conf/local.conf</code>).
2509 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2510 Any recipe that PROVIDES a <code class="filename">virtual/*</code>
2511 item that is ultimately not selected through
2512 <code class="filename">PREFERRED_PROVIDER</code> does not get built.
2513 Preventing these recipes from building is usually the
2514 desired behavior since this mechanism's purpose is to
2515 select between mutually exclusive alternative providers.
2516 </div><p>
2517 </p><p>
2518 The following lists specific examples of virtual providers:
2519 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2520 <code class="filename">virtual/mesa</code>:
2521 Provides <code class="filename">gbm.pc</code>.
2522 </p></li><li class="listitem"><p>
2523 <code class="filename">virtual/egl</code>:
2524 Provides <code class="filename">egl.pc</code> and possibly
2525 <code class="filename">wayland-egl.pc</code>.
2526 </p></li><li class="listitem"><p>
2527 <code class="filename">virtual/libgl</code>:
2528 Provides <code class="filename">gl.pc</code> (i.e. libGL).
2529 </p></li><li class="listitem"><p>
2530 <code class="filename">virtual/libgles1</code>:
2531 Provides <code class="filename">glesv1_cm.pc</code>
2532 (i.e. libGLESv1_CM).
2533 </p></li><li class="listitem"><p>
2534 <code class="filename">virtual/libgles2</code>:
2535 Provides <code class="filename">glesv2.pc</code>
2536 (i.e. libGLESv2).
2537 </p></li></ul></div><p>
2538 </p></div><div class="section" title="3.1.4. Classes"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-classes">3.1.4. Classes<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-classes">¶</a></span></h3></div></div></div><p>
2539 Class files (<code class="filename">.bbclass</code>) contain information
2540 that is useful to share between
2541 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>
2542 files.
2543 An example is the
2544 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-autotools" target="_top"><code class="filename">autotools</code></a>
2545 class, which contains common settings for any application that
2546 Autotools uses.
2547 The
2548 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes" target="_top">Classes</a>"
2549 chapter in the Yocto Project Reference Manual provides
2550 details about classes and how to use them.
2551 </p></div><div class="section" title="3.1.5. Configuration"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-components-configuration">3.1.5. Configuration<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-components-configuration">¶</a></span></h3></div></div></div><p>
2552 The configuration files (<code class="filename">.conf</code>) define
2553 various configuration variables that govern the OpenEmbedded
2554 build process.
2555 These files fall into several areas that define machine
2556 configuration options, distribution configuration options,
2557 compiler tuning options, general common configuration options,
2558 and user configuration options in
2559 <code class="filename">local.conf</code>, which is found in the
2560 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>.
2561 </p></div></div><div class="section" title="3.2. Cross-Development Toolchain Generation"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="cross-development-toolchain-generation">3.2. Cross-Development Toolchain Generation<span class="permalink"><a alt="Permalink" title="Permalink" href="#cross-development-toolchain-generation">¶</a></span></h2></div></div></div><p>
2562 The Yocto Project does most of the work for you when it comes to
2563 creating
2564 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#cross-development-toolchain" target="_top">cross-development toolchains</a>.
2565 This section provides some technical background on how
2566 cross-development toolchains are created and used.
2567 For more information on toolchains, you can also see the
2568 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a>
2569 manual.
2570 </p><p>
2571 In the Yocto Project development environment, cross-development
2572 toolchains are used to build the image and applications that run
2573 on the target hardware.
2574 With just a few commands, the OpenEmbedded build system creates
2575 these necessary toolchains for you.
2576 </p><p>
2577 The following figure shows a high-level build environment regarding
2578 toolchain construction and use.
2579 </p><p>
2580 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="720"><tr style="height: 540px"><td align="center"><img src="figures/cross-development-toolchains.png" align="middle" width="720" /></td></tr></table><p>
2581 </p><p>
2582 Most of the work occurs on the Build Host.
2583 This is the machine used to build images and generally work within the
2584 the Yocto Project environment.
2585 When you run BitBake to create an image, the OpenEmbedded build system
2586 uses the host <code class="filename">gcc</code> compiler to bootstrap a
2587 cross-compiler named <code class="filename">gcc-cross</code>.
2588 The <code class="filename">gcc-cross</code> compiler is what BitBake uses to
2589 compile source files when creating the target image.
2590 You can think of <code class="filename">gcc-cross</code> simply as an
2591 automatically generated cross-compiler that is used internally within
2592 BitBake only.
2593 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2594 The extensible SDK does not use
2595 <code class="filename">gcc-cross-canadian</code> since this SDK
2596 ships a copy of the OpenEmbedded build system and the sysroot
2597 within it contains <code class="filename">gcc-cross</code>.
2598 </div><p>
2599 </p><p>
2600 The chain of events that occurs when <code class="filename">gcc-cross</code> is
2601 bootstrapped is as follows:
2602 </p><pre class="literallayout">
2603 gcc -&gt; binutils-cross -&gt; gcc-cross-initial -&gt; linux-libc-headers -&gt; glibc-initial -&gt; glibc -&gt; gcc-cross -&gt; gcc-runtime
2604 </pre><p>
2605 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2606 <code class="filename">gcc</code>:
2607 The build host's GNU Compiler Collection (GCC).
2608 </p></li><li class="listitem"><p>
2609 <code class="filename">binutils-cross</code>:
2610 The bare minimum binary utilities needed in order to run
2611 the <code class="filename">gcc-cross-initial</code> phase of the
2612 bootstrap operation.
2613 </p></li><li class="listitem"><p>
2614 <code class="filename">gcc-cross-initial</code>:
2615 An early stage of the bootstrap process for creating
2616 the cross-compiler.
2617 This stage builds enough of the <code class="filename">gcc-cross</code>,
2618 the C library, and other pieces needed to finish building the
2619 final cross-compiler in later stages.
2620 This tool is a "native" package (i.e. it is designed to run on
2621 the build host).
2622 </p></li><li class="listitem"><p>
2623 <code class="filename">linux-libc-headers</code>:
2624 Headers needed for the cross-compiler.
2625 </p></li><li class="listitem"><p>
2626 <code class="filename">glibc-initial</code>:
2627 An initial version of the Embedded GLIBC needed to bootstrap
2628 <code class="filename">glibc</code>.
2629 </p></li><li class="listitem"><p>
2630 <code class="filename">gcc-cross</code>:
2631 The final stage of the bootstrap process for the
2632 cross-compiler.
2633 This stage results in the actual cross-compiler that
2634 BitBake uses when it builds an image for a targeted
2635 device.
2636 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2637 If you are replacing this cross compiler toolchain
2638 with a custom version, you must replace
2639 <code class="filename">gcc-cross</code>.
2640 </div><p>
2641 This tool is also a "native" package (i.e. it is
2642 designed to run on the build host).
2643 </p></li><li class="listitem"><p>
2644 <code class="filename">gcc-runtime</code>:
2645 Runtime libraries resulting from the toolchain bootstrapping
2646 process.
2647 This tool produces a binary that consists of the
2648 runtime libraries need for the targeted device.
2649 </p></li></ul></div><p>
2650 </p><p>
2651 You can use the OpenEmbedded build system to build an installer for
2652 the relocatable SDK used to develop applications.
2653 When you run the installer, it installs the toolchain, which contains
2654 the development tools (e.g., the
2655 <code class="filename">gcc-cross-canadian</code>),
2656 <code class="filename">binutils-cross-canadian</code>, and other
2657 <code class="filename">nativesdk-*</code> tools,
2658 which are tools native to the SDK (i.e. native to
2659 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDK_ARCH" target="_top"><code class="filename">SDK_ARCH</code></a>),
2660 you need to cross-compile and test your software.
2661 The figure shows the commands you use to easily build out this
2662 toolchain.
2663 This cross-development toolchain is built to execute on the
2664 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>,
2665 which might or might not be the same
2666 machine as the Build Host.
2667 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2668 If your target architecture is supported by the Yocto Project,
2669 you can take advantage of pre-built images that ship with the
2670 Yocto Project and already contain cross-development toolchain
2671 installers.
2672 </div><p>
2673 </p><p>
2674 Here is the bootstrap process for the relocatable toolchain:
2675 </p><pre class="literallayout">
2676 gcc -&gt; binutils-crosssdk -&gt; gcc-crosssdk-initial -&gt; linux-libc-headers -&gt;
2677 glibc-initial -&gt; nativesdk-glibc -&gt; gcc-crosssdk -&gt; gcc-cross-canadian
2678 </pre><p>
2679 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2680 <code class="filename">gcc</code>:
2681 The build host's GNU Compiler Collection (GCC).
2682 </p></li><li class="listitem"><p>
2683 <code class="filename">binutils-crosssdk</code>:
2684 The bare minimum binary utilities needed in order to run
2685 the <code class="filename">gcc-crosssdk-initial</code> phase of the
2686 bootstrap operation.
2687 </p></li><li class="listitem"><p>
2688 <code class="filename">gcc-crosssdk-initial</code>:
2689 An early stage of the bootstrap process for creating
2690 the cross-compiler.
2691 This stage builds enough of the
2692 <code class="filename">gcc-crosssdk</code> and supporting pieces so that
2693 the final stage of the bootstrap process can produce the
2694 finished cross-compiler.
2695 This tool is a "native" binary that runs on the build host.
2696 </p></li><li class="listitem"><p>
2697 <code class="filename">linux-libc-headers</code>:
2698 Headers needed for the cross-compiler.
2699 </p></li><li class="listitem"><p>
2700 <code class="filename">glibc-initial</code>:
2701 An initial version of the Embedded GLIBC needed to bootstrap
2702 <code class="filename">nativesdk-glibc</code>.
2703 </p></li><li class="listitem"><p>
2704 <code class="filename">nativesdk-glibc</code>:
2705 The Embedded GLIBC needed to bootstrap the
2706 <code class="filename">gcc-crosssdk</code>.
2707 </p></li><li class="listitem"><p>
2708 <code class="filename">gcc-crosssdk</code>:
2709 The final stage of the bootstrap process for the
2710 relocatable cross-compiler.
2711 The <code class="filename">gcc-crosssdk</code> is a transitory compiler
2712 and never leaves the build host.
2713 Its purpose is to help in the bootstrap process to create the
2714 eventual relocatable <code class="filename">gcc-cross-canadian</code>
2715 compiler, which is relocatable.
2716 This tool is also a "native" package (i.e. it is
2717 designed to run on the build host).
2718 </p></li><li class="listitem"><p>
2719 <code class="filename">gcc-cross-canadian</code>:
2720 The final relocatable cross-compiler.
2721 When run on the
2722 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SDKMACHINE" target="_top"><code class="filename">SDKMACHINE</code></a>,
2723 this tool
2724 produces executable code that runs on the target device.
2725 Only one cross-canadian compiler is produced per architecture
2726 since they can be targeted at different processor optimizations
2727 using configurations passed to the compiler through the
2728 compile commands.
2729 This circumvents the need for multiple compilers and thus
2730 reduces the size of the toolchains.
2731 </p></li></ul></div><p>
2732 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2733 For information on advantages gained when building a
2734 cross-development toolchain installer, see the
2735 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#sdk-building-an-sdk-installer" target="_top">Building an SDK Installer</a>"
2736 section in the Yocto Project Application Development and the
2737 Extensible Software Development Kit (eSDK) manual.
2738 </div></div><div class="section" title="3.3. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="shared-state-cache">3.3. Shared State Cache<span class="permalink"><a alt="Permalink" title="Permalink" href="#shared-state-cache">¶</a></span></h2></div></div></div><p>
2739 By design, the OpenEmbedded build system builds everything from
2740 scratch unless BitBake can determine that parts do not need to be
2741 rebuilt.
2742 Fundamentally, building from scratch is attractive as it means all
2743 parts are built fresh and there is no possibility of stale data
2744 causing problems.
2745 When developers hit problems, they typically default back to
2746 building from scratch so they know the state of things from the
2747 start.
2748 </p><p>
2749 Building an image from scratch is both an advantage and a
2750 disadvantage to the process.
2751 As mentioned in the previous paragraph, building from scratch
2752 ensures that everything is current and starts from a known state.
2753 However, building from scratch also takes much longer as it
2754 generally means rebuilding things that do not necessarily need
2755 to be rebuilt.
2756 </p><p>
2757 The Yocto Project implements shared state code that supports
2758 incremental builds.
2759 The implementation of the shared state code answers the following
2760 questions that were fundamental roadblocks within the OpenEmbedded
2761 incremental build support system:
2762 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2763 What pieces of the system have changed and what pieces have
2764 not changed?
2765 </p></li><li class="listitem"><p>
2766 How are changed pieces of software removed and replaced?
2767 </p></li><li class="listitem"><p>
2768 How are pre-built components that do not need to be rebuilt
2769 from scratch used when they are available?
2770 </p></li></ul></div><p>
2771 </p><p>
2772 For the first question, the build system detects changes in the
2773 "inputs" to a given task by creating a checksum (or signature) of
2774 the task's inputs.
2775 If the checksum changes, the system assumes the inputs have changed
2776 and the task needs to be rerun.
2777 For the second question, the shared state (sstate) code tracks
2778 which tasks add which output to the build process.
2779 This means the output from a given task can be removed, upgraded
2780 or otherwise manipulated.
2781 The third question is partly addressed by the solution for the
2782 second question assuming the build system can fetch the sstate
2783 objects from remote locations and install them if they are deemed
2784 to be valid.
2785 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2786 The OpenEmbedded build system does not maintain
2787 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PR" target="_top"><code class="filename">PR</code></a>
2788 information as part of the shared state packages.
2789 Consequently, considerations exist that affect maintaining
2790 shared state feeds.
2791 For information on how the OpenEmbedded build system
2792 works with packages and can track incrementing
2793 <code class="filename">PR</code> information, see the
2794 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#automatically-incrementing-a-binary-package-revision-number" target="_top">Automatically Incrementing a Binary Package Revision Number</a>"
2795 section in the Yocto Project Development Tasks Manual.
2796 </div><p>
2797 </p><p>
2798 The rest of this section goes into detail about the overall
2799 incremental build architecture, the checksums (signatures), shared
2800 state, and some tips and tricks.
2801 </p><div class="section" title="3.3.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title" id="overall-architecture">3.3.1. Overall Architecture<span class="permalink"><a alt="Permalink" title="Permalink" href="#overall-architecture">¶</a></span></h3></div></div></div><p>
2802 When determining what parts of the system need to be built,
2803 BitBake works on a per-task basis rather than a per-recipe
2804 basis.
2805 You might wonder why using a per-task basis is preferred over
2806 a per-recipe basis.
2807 To help explain, consider having the IPK packaging backend
2808 enabled and then switching to DEB.
2809 In this case, the
2810 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a>
2811 and
2812 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>
2813 task outputs are still valid.
2814 However, with a per-recipe approach, the build would not
2815 include the <code class="filename">.deb</code> files.
2816 Consequently, you would have to invalidate the whole build and
2817 rerun it.
2818 Rerunning everything is not the best solution.
2819 Also, in this case, the core must be "taught" much about
2820 specific tasks.
2821 This methodology does not scale well and does not allow users
2822 to easily add new tasks in layers or as external recipes
2823 without touching the packaged-staging core.
2824 </p></div><div class="section" title="3.3.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title" id="overview-checksums">3.3.2. Checksums (Signatures)<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-checksums">¶</a></span></h3></div></div></div><p>
2825 The shared state code uses a checksum, which is a unique
2826 signature of a task's inputs, to determine if a task needs to
2827 be run again.
2828 Because it is a change in a task's inputs that triggers a
2829 rerun, the process needs to detect all the inputs to a given
2830 task.
2831 For shell tasks, this turns out to be fairly easy because
2832 the build process generates a "run" shell script for each task
2833 and it is possible to create a checksum that gives you a good
2834 idea of when the task's data changes.
2835 </p><p>
2836 To complicate the problem, there are things that should not be
2837 included in the checksum.
2838 First, there is the actual specific build path of a given
2839 task - the
2840 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>.
2841 It does not matter if the work directory changes because it
2842 should not affect the output for target packages.
2843 Also, the build process has the objective of making native
2844 or cross packages relocatable.
2845 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2846 Both native and cross packages run on the build host.
2847 However, cross packages generate output for the target
2848 architecture.
2849 </div><p>
2850 The checksum therefore needs to exclude
2851 <code class="filename">WORKDIR</code>.
2852 The simplistic approach for excluding the work directory is to
2853 set <code class="filename">WORKDIR</code> to some fixed value and
2854 create the checksum for the "run" script.
2855 </p><p>
2856 Another problem results from the "run" scripts containing
2857 functions that might or might not get called.
2858 The incremental build solution contains code that figures out
2859 dependencies between shell functions.
2860 This code is used to prune the "run" scripts down to the
2861 minimum set, thereby alleviating this problem and making the
2862 "run" scripts much more readable as a bonus.
2863 </p><p>
2864 So far we have solutions for shell scripts.
2865 What about Python tasks?
2866 The same approach applies even though these tasks are more
2867 difficult.
2868 The process needs to figure out what variables a Python
2869 function accesses and what functions it calls.
2870 Again, the incremental build solution contains code that first
2871 figures out the variable and function dependencies, and then
2872 creates a checksum for the data used as the input to the task.
2873 </p><p>
2874 Like the <code class="filename">WORKDIR</code> case, situations exist
2875 where dependencies should be ignored.
2876 For these cases, you can instruct the build process to
2877 ignore a dependency by using a line like the following:
2878 </p><pre class="literallayout">
2879 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
2880 </pre><p>
2881 This example ensures that the
2882 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PACKAGE_ARCHS" target="_top"><code class="filename">PACKAGE_ARCHS</code></a>
2883 variable does not depend on the value of
2884 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-MACHINE" target="_top"><code class="filename">MACHINE</code></a>,
2885 even if it does reference it.
2886 </p><p>
2887 Equally, there are cases where we need to add dependencies
2888 BitBake is not able to find.
2889 You can accomplish this by using a line like the following:
2890 </p><pre class="literallayout">
2891 PACKAGE_ARCHS[vardeps] = "MACHINE"
2892 </pre><p>
2893 This example explicitly adds the <code class="filename">MACHINE</code>
2894 variable as a dependency for
2895 <code class="filename">PACKAGE_ARCHS</code>.
2896 </p><p>
2897 Consider a case with in-line Python, for example, where
2898 BitBake is not able to figure out dependencies.
2899 When running in debug mode (i.e. using
2900 <code class="filename">-DDD</code>), BitBake produces output when it
2901 discovers something for which it cannot figure out dependencies.
2902 The Yocto Project team has currently not managed to cover
2903 those dependencies in detail and is aware of the need to fix
2904 this situation.
2905 </p><p>
2906 Thus far, this section has limited discussion to the direct
2907 inputs into a task.
2908 Information based on direct inputs is referred to as the
2909 "basehash" in the code.
2910 However, there is still the question of a task's indirect
2911 inputs - the things that were already built and present in the
2912 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#build-directory" target="_top">Build Directory</a>.
2913 The checksum (or signature) for a particular task needs to add
2914 the hashes of all the tasks on which the particular task
2915 depends.
2916 Choosing which dependencies to add is a policy decision.
2917 However, the effect is to generate a master checksum that
2918 combines the basehash and the hashes of the task's
2919 dependencies.
2920 </p><p>
2921 At the code level, there are a variety of ways both the
2922 basehash and the dependent task hashes can be influenced.
2923 Within the BitBake configuration file, we can give BitBake
2924 some extra information to help it construct the basehash.
2925 The following statement effectively results in a list of
2926 global variable dependency excludes - variables never
2927 included in any checksum:
2928 </p><pre class="literallayout">
2929 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
2930 SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
2931 USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
2932 PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
2933 CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
2934 </pre><p>
2935 The previous example excludes
2936 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>
2937 since that variable is actually constructed as a path within
2938 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-TMPDIR" target="_top"><code class="filename">TMPDIR</code></a>,
2939 which is on the whitelist.
2940 </p><p>
2941 The rules for deciding which hashes of dependent tasks to
2942 include through dependency chains are more complex and are
2943 generally accomplished with a Python function.
2944 The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows
2945 two examples of this and also illustrates how you can insert
2946 your own policy into the system if so desired.
2947 This file defines the two basic signature generators
2948 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#oe-core" target="_top">OE-Core</a>
2949 uses: "OEBasic" and "OEBasicHash".
2950 By default, there is a dummy "noop" signature handler enabled
2951 in BitBake.
2952 This means that behavior is unchanged from previous versions.
2953 OE-Core uses the "OEBasicHash" signature handler by default
2954 through this setting in the <code class="filename">bitbake.conf</code>
2955 file:
2956 </p><pre class="literallayout">
2957 BB_SIGNATURE_HANDLER ?= "OEBasicHash"
2958 </pre><p>
2959 The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code>
2960 is the same as the "OEBasic" version but adds the task hash to
2961 the stamp files.
2962 This results in any
2963 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#metadata" target="_top">Metadata</a>
2964 change that changes the task hash, automatically
2965 causing the task to be run again.
2966 This removes the need to bump
2967 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PR" target="_top"><code class="filename">PR</code></a>
2968 values, and changes to Metadata automatically ripple across
2969 the build.
2970 </p><p>
2971 It is also worth noting that the end result of these
2972 signature generators is to make some dependency and hash
2973 information available to the build.
2974 This information includes:
2975 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
2976 <code class="filename">BB_BASEHASH_task-</code><em class="replaceable"><code>taskname</code></em>:
2977 The base hashes for each task in the recipe.
2978 </p></li><li class="listitem"><p>
2979 <code class="filename">BB_BASEHASH_</code><em class="replaceable"><code>filename</code></em><code class="filename">:</code><em class="replaceable"><code>taskname</code></em>:
2980 The base hashes for each dependent task.
2981 </p></li><li class="listitem"><p>
2982 <code class="filename">BBHASHDEPS_</code><em class="replaceable"><code>filename</code></em><code class="filename">:</code><em class="replaceable"><code>taskname</code></em>:
2983 The task dependencies for each task.
2984 </p></li><li class="listitem"><p>
2985 <code class="filename">BB_TASKHASH</code>:
2986 The hash of the currently running task.
2987 </p></li></ul></div><p>
2988 </p></div><div class="section" title="3.3.3. Shared State"><div class="titlepage"><div><div><h3 class="title" id="shared-state">3.3.3. Shared State<span class="permalink"><a alt="Permalink" title="Permalink" href="#shared-state">¶</a></span></h3></div></div></div><p>
2989 Checksums and dependencies, as discussed in the previous
2990 section, solve half the problem of supporting a shared state.
2991 The other part of the problem is being able to use checksum
2992 information during the build and being able to reuse or rebuild
2993 specific components.
2994 </p><p>
2995 The
2996 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-sstate" target="_top"><code class="filename">sstate</code></a>
2997 class is a relatively generic implementation of how to
2998 "capture" a snapshot of a given task.
2999 The idea is that the build process does not care about the
3000 source of a task's output.
3001 Output could be freshly built or it could be downloaded and
3002 unpacked from somewhere - the build process does not need to
3003 worry about its origin.
3004 </p><p>
3005 There are two types of output, one is just about creating a
3006 directory in
3007 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>.
3008 A good example is the output of either
3009 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a>
3010 or
3011 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>.
3012 The other type of output occurs when a set of data is merged
3013 into a shared directory tree such as the sysroot.
3014 </p><p>
3015 The Yocto Project team has tried to keep the details of the
3016 implementation hidden in <code class="filename">sstate</code> class.
3017 From a user's perspective, adding shared state wrapping to a task
3018 is as simple as this
3019 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-deploy" target="_top"><code class="filename">do_deploy</code></a>
3020 example taken from the
3021 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-deploy" target="_top"><code class="filename">deploy</code></a>
3022 class:
3023 </p><pre class="literallayout">
3024 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
3025 SSTATETASKS += "do_deploy"
3026 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
3027 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
3028
3029 python do_deploy_setscene () {
3030 sstate_setscene(d)
3031 }
3032 addtask do_deploy_setscene
3033 do_deploy[dirs] = "${DEPLOYDIR} ${B}"
3034 </pre><p>
3035 The following list explains the previous example:
3036 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
3037 Adding "do_deploy" to <code class="filename">SSTATETASKS</code>
3038 adds some required sstate-related processing, which is
3039 implemented in the
3040 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-classes-sstate" target="_top"><code class="filename">sstate</code></a>
3041 class, to before and after the
3042 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-deploy" target="_top"><code class="filename">do_deploy</code></a>
3043 task.
3044 </p></li><li class="listitem"><p>
3045 The
3046 <code class="filename">do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</code>
3047 declares that <code class="filename">do_deploy</code> places its
3048 output in <code class="filename">${DEPLOYDIR}</code> when run
3049 normally (i.e. when not using the sstate cache).
3050 This output becomes the input to the shared state cache.
3051 </p></li><li class="listitem"><p>
3052 The
3053 <code class="filename">do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</code>
3054 line causes the contents of the shared state cache to be
3055 copied to <code class="filename">${DEPLOY_DIR_IMAGE}</code>.
3056 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3057 If <code class="filename">do_deploy</code> is not already in
3058 the shared state cache or if its input checksum
3059 (signature) has changed from when the output was
3060 cached, the task will be run to populate the shared
3061 state cache, after which the contents of the shared
3062 state cache is copied to
3063 <code class="filename">${DEPLOY_DIR_IMAGE}</code>.
3064 If <code class="filename">do_deploy</code> is in the shared
3065 state cache and its signature indicates that the
3066 cached output is still valid (i.e. if no
3067 relevant task inputs have changed), then the
3068 contents of the shared state cache will be copied
3069 directly to
3070 <code class="filename">${DEPLOY_DIR_IMAGE}</code> by the
3071 <code class="filename">do_deploy_setscene</code> task
3072 instead, skipping the
3073 <code class="filename">do_deploy</code> task.
3074 </div><p>
3075 </p></li><li class="listitem"><p>
3076 The following task definition is glue logic needed to
3077 make the previous settings effective:
3078 </p><pre class="literallayout">
3079 python do_deploy_setscene () {
3080 sstate_setscene(d)
3081 }
3082 addtask do_deploy_setscene
3083 </pre><p>
3084 <code class="filename">sstate_setscene()</code> takes the flags
3085 above as input and accelerates the
3086 <code class="filename">do_deploy</code> task through the
3087 shared state cache if possible.
3088 If the task was accelerated,
3089 <code class="filename">sstate_setscene()</code> returns True.
3090 Otherwise, it returns False, and the normal
3091 <code class="filename">do_deploy</code> task runs.
3092 For more information, see the
3093 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#setscene" target="_top">setscene</a>"
3094 section in the BitBake User Manual.
3095 </p></li><li class="listitem"><p>
3096 The <code class="filename">do_deploy[dirs] = "${DEPLOYDIR} ${B}"</code>
3097 line creates <code class="filename">${DEPLOYDIR}</code> and
3098 <code class="filename">${B}</code> before the
3099 <code class="filename">do_deploy</code> task runs, and also sets
3100 the current working directory of
3101 <code class="filename">do_deploy</code> to
3102 <code class="filename">${B}</code>.
3103 For more information, see the
3104 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#variable-flags" target="_top">Variable Flags</a>"
3105 section in the BitBake User Manual.
3106 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3107 In cases where
3108 <code class="filename">sstate-inputdirs</code> and
3109 <code class="filename">sstate-outputdirs</code> would be the
3110 same, you can use
3111 <code class="filename">sstate-plaindirs</code>.
3112 For example, to preserve the
3113 <code class="filename">${PKGD}</code> and
3114 <code class="filename">${PKGDEST}</code> output from the
3115 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>
3116 task, use the following:
3117 <pre class="literallayout">
3118 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
3119 </pre></div><p>
3120 </p></li><li class="listitem"><p>
3121 <code class="filename">sstate-inputdirs</code> and
3122 <code class="filename">sstate-outputdirs</code> can also be used
3123 with multiple directories.
3124 For example, the following declares
3125 <code class="filename">PKGDESTWORK</code> and
3126 <code class="filename">SHLIBWORK</code> as shared state
3127 input directories, which populates the shared state
3128 cache, and <code class="filename">PKGDATA_DIR</code> and
3129 <code class="filename">SHLIBSDIR</code> as the corresponding
3130 shared state output directories:
3131 </p><pre class="literallayout">
3132 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
3133 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
3134 </pre><p>
3135 </p></li><li class="listitem"><p>
3136 These methods also include the ability to take a
3137 lockfile when manipulating shared state directory
3138 structures, for cases where file additions or removals
3139 are sensitive:
3140 </p><pre class="literallayout">
3141 do_package[sstate-lockfile] = "${PACKAGELOCK}"
3142 </pre><p>
3143 </p></li></ul></div><p>
3144 </p><p>
3145 Behind the scenes, the shared state code works by looking in
3146 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a>
3147 and
3148 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_MIRRORS" target="_top"><code class="filename">SSTATE_MIRRORS</code></a>
3149 for shared state files.
3150 Here is an example:
3151 </p><pre class="literallayout">
3152 SSTATE_MIRRORS ?= "\
3153 file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
3154 file://.* file:///some/local/dir/sstate/PATH"
3155 </pre><p>
3156 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3157 The shared state directory
3158 (<code class="filename">SSTATE_DIR</code>) is organized into
3159 two-character subdirectories, where the subdirectory
3160 names are based on the first two characters of the hash.
3161 If the shared state directory structure for a mirror has the
3162 same structure as <code class="filename">SSTATE_DIR</code>, you must
3163 specify "PATH" as part of the URI to enable the build system
3164 to map to the appropriate subdirectory.
3165 </div><p>
3166 </p><p>
3167 The shared state package validity can be detected just by
3168 looking at the filename since the filename contains the task
3169 checksum (or signature) as described earlier in this section.
3170 If a valid shared state package is found, the build process
3171 downloads it and uses it to accelerate the task.
3172 </p><p>
3173 The build processes use the <code class="filename">*_setscene</code>
3174 tasks for the task acceleration phase.
3175 BitBake goes through this phase before the main execution
3176 code and tries to accelerate any tasks for which it can find
3177 shared state packages.
3178 If a shared state package for a task is available, the
3179 shared state package is used.
3180 This means the task and any tasks on which it is dependent
3181 are not executed.
3182 </p><p>
3183 As a real world example, the aim is when building an IPK-based
3184 image, only the
3185 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_ipk" target="_top"><code class="filename">do_package_write_ipk</code></a>
3186 tasks would have their shared state packages fetched and
3187 extracted.
3188 Since the sysroot is not used, it would never get extracted.
3189 This is another reason why a task-based approach is preferred
3190 over a recipe-based approach, which would have to install the
3191 output from every task.
3192 </p></div><div class="section" title="3.3.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title" id="tips-and-tricks">3.3.4. Tips and Tricks<span class="permalink"><a alt="Permalink" title="Permalink" href="#tips-and-tricks">¶</a></span></h3></div></div></div><p>
3193 The code in the build system that supports incremental builds
3194 is not simple code.
3195 This section presents some tips and tricks that help you work
3196 around issues related to shared state code.
3197 </p><div class="section" title="3.3.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title" id="overview-debugging">3.3.4.1. Debugging<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-debugging">¶</a></span></h4></div></div></div><p>
3198 Seeing what metadata went into creating the input signature
3199 of a shared state (sstate) task can be a useful debugging
3200 aid.
3201 This information is available in signature information
3202 (<code class="filename">siginfo</code>) files in
3203 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-SSTATE_DIR" target="_top"><code class="filename">SSTATE_DIR</code></a>.
3204 For information on how to view and interpret information in
3205 <code class="filename">siginfo</code> files, see the
3206 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#dev-viewing-task-variable-dependencies" target="_top">Viewing Task Variable Dependencies</a>"
3207 section in the Yocto Project Development Tasks Manual.
3208 </p></div><div class="section" title="3.3.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title" id="invalidating-shared-state">3.3.4.2. Invalidating Shared State<span class="permalink"><a alt="Permalink" title="Permalink" href="#invalidating-shared-state">¶</a></span></h4></div></div></div><p>
3209 The OpenEmbedded build system uses checksums and shared
3210 state cache to avoid unnecessarily rebuilding tasks.
3211 Collectively, this scheme is known as "shared state code."
3212 </p><p>
3213 As with all schemes, this one has some drawbacks.
3214 It is possible that you could make implicit changes to your
3215 code that the checksum calculations do not take into
3216 account.
3217 These implicit changes affect a task's output but do not
3218 trigger the shared state code into rebuilding a recipe.
3219 Consider an example during which a tool changes its output.
3220 Assume that the output of <code class="filename">rpmdeps</code>
3221 changes.
3222 The result of the change should be that all the
3223 <code class="filename">package</code> and
3224 <code class="filename">package_write_rpm</code> shared state cache
3225 items become invalid.
3226 However, because the change to the output is
3227 external to the code and therefore implicit,
3228 the associated shared state cache items do not become
3229 invalidated.
3230 In this case, the build process uses the cached items
3231 rather than running the task again.
3232 Obviously, these types of implicit changes can cause
3233 problems.
3234 </p><p>
3235 To avoid these problems during the build, you need to
3236 understand the effects of any changes you make.
3237 Realize that changes you make directly to a function
3238 are automatically factored into the checksum calculation.
3239 Thus, these explicit changes invalidate the associated
3240 area of shared state cache.
3241 However, you need to be aware of any implicit changes that
3242 are not obvious changes to the code and could affect
3243 the output of a given task.
3244 </p><p>
3245 When you identify an implicit change, you can easily
3246 take steps to invalidate the cache and force the tasks
3247 to run.
3248 The steps you can take are as simple as changing a
3249 function's comments in the source code.
3250 For example, to invalidate package shared state files,
3251 change the comment statements of
3252 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>
3253 or the comments of one of the functions it calls.
3254 Even though the change is purely cosmetic, it causes the
3255 checksum to be recalculated and forces the OpenEmbedded
3256 build system to run the task again.
3257 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3258 For an example of a commit that makes a cosmetic
3259 change to invalidate shared state, see this
3260 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>.
3261 </div><p>
3262 </p></div></div></div><div class="section" title="3.4. Automatically Added Runtime Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="automatically-added-runtime-dependencies">3.4. Automatically Added Runtime Dependencies<span class="permalink"><a alt="Permalink" title="Permalink" href="#automatically-added-runtime-dependencies">¶</a></span></h2></div></div></div><p>
3263 The OpenEmbedded build system automatically adds common types of
3264 runtime dependencies between packages, which means that you do not
3265 need to explicitly declare the packages using
3266 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RDEPENDS" target="_top"><code class="filename">RDEPENDS</code></a>.
3267 Three automatic mechanisms exist (<code class="filename">shlibdeps</code>,
3268 <code class="filename">pcdeps</code>, and <code class="filename">depchains</code>)
3269 that handle shared libraries, package configuration (pkg-config)
3270 modules, and <code class="filename">-dev</code> and
3271 <code class="filename">-dbg</code> packages, respectively.
3272 For other types of runtime dependencies, you must manually declare
3273 the dependencies.
3274 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
3275 <code class="filename">shlibdeps</code>:
3276 During the
3277 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>
3278 task of each recipe, all shared libraries installed by the
3279 recipe are located.
3280 For each shared library, the package that contains the
3281 shared library is registered as providing the shared
3282 library.
3283 More specifically, the package is registered as providing
3284 the
3285 <a class="ulink" href="https://en.wikipedia.org/wiki/Soname" target="_top">soname</a>
3286 of the library.
3287 The resulting shared-library-to-package mapping
3288 is saved globally in
3289 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDATA_DIR" target="_top"><code class="filename">PKGDATA_DIR</code></a>
3290 by the
3291 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a>
3292 task.</p><p>Simultaneously, all executables and shared libraries
3293 installed by the recipe are inspected to see what shared
3294 libraries they link against.
3295 For each shared library dependency that is found,
3296 <code class="filename">PKGDATA_DIR</code> is queried to
3297 see if some package (likely from a different recipe)
3298 contains the shared library.
3299 If such a package is found, a runtime dependency is added
3300 from the package that depends on the shared library to the
3301 package that contains the library.</p><p>The automatically added runtime dependency also
3302 includes a version restriction.
3303 This version restriction specifies that at least the
3304 current version of the package that provides the shared
3305 library must be used, as if
3306 "<em class="replaceable"><code>package</code></em> (&gt;= <em class="replaceable"><code>version</code></em>)"
3307 had been added to
3308 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RDEPENDS" target="_top"><code class="filename">RDEPENDS</code></a>.
3309 This forces an upgrade of the package containing the shared
3310 library when installing the package that depends on the
3311 library, if needed.</p><p>If you want to avoid a package being registered as
3312 providing a particular shared library (e.g. because the library
3313 is for internal use only), then add the library to
3314 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PRIVATE_LIBS" target="_top"><code class="filename">PRIVATE_LIBS</code></a>
3315 inside the package's recipe.
3316 </p></li><li class="listitem"><p>
3317 <code class="filename">pcdeps</code>:
3318 During the
3319 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package" target="_top"><code class="filename">do_package</code></a>
3320 task of each recipe, all pkg-config modules
3321 (<code class="filename">*.pc</code> files) installed by the recipe
3322 are located.
3323 For each module, the package that contains the module is
3324 registered as providing the module.
3325 The resulting module-to-package mapping is saved globally in
3326 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-PKGDATA_DIR" target="_top"><code class="filename">PKGDATA_DIR</code></a>
3327 by the
3328 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a>
3329 task.</p><p>Simultaneously, all pkg-config modules installed by
3330 the recipe are inspected to see what other pkg-config
3331 modules they depend on.
3332 A module is seen as depending on another module if it
3333 contains a "Requires:" line that specifies the other module.
3334 For each module dependency,
3335 <code class="filename">PKGDATA_DIR</code> is queried to see if some
3336 package contains the module.
3337 If such a package is found, a runtime dependency is added
3338 from the package that depends on the module to the package
3339 that contains the module.
3340 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3341 The <code class="filename">pcdeps</code> mechanism most often
3342 infers dependencies between <code class="filename">-dev</code>
3343 packages.
3344 </div><p>
3345 </p></li><li class="listitem"><p>
3346 <code class="filename">depchains</code>:
3347 If a package <code class="filename">foo</code> depends on a package
3348 <code class="filename">bar</code>, then <code class="filename">foo-dev</code>
3349 and <code class="filename">foo-dbg</code> are also made to depend on
3350 <code class="filename">bar-dev</code> and
3351 <code class="filename">bar-dbg</code>, respectively.
3352 Taking the <code class="filename">-dev</code> packages as an
3353 example, the <code class="filename">bar-dev</code> package might
3354 provide headers and shared library symlinks needed by
3355 <code class="filename">foo-dev</code>, which shows the need
3356 for a dependency between the packages.</p><p>The dependencies added by
3357 <code class="filename">depchains</code> are in the form of
3358 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-RRECOMMENDS" target="_top"><code class="filename">RRECOMMENDS</code></a>.
3359 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3360 By default, <code class="filename">foo-dev</code> also has an
3361 <code class="filename">RDEPENDS</code>-style dependency on
3362 <code class="filename">foo</code>, because the default value of
3363 <code class="filename">RDEPENDS_${PN}-dev</code> (set in
3364 <code class="filename">bitbake.conf</code>) includes
3365 "${PN}".
3366 </div><p>To ensure that the dependency chain is never broken,
3367 <code class="filename">-dev</code> and <code class="filename">-dbg</code>
3368 packages are always generated by default, even if the
3369 packages turn out to be empty.
3370 See the
3371 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-ALLOW_EMPTY" target="_top"><code class="filename">ALLOW_EMPTY</code></a>
3372 variable for more information.
3373 </p></li></ul></div><p>
3374 </p><p>
3375 The <code class="filename">do_package</code> task depends on the
3376 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-packagedata" target="_top"><code class="filename">do_packagedata</code></a>
3377 task of each recipe in
3378 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DEPENDS" target="_top"><code class="filename">DEPENDS</code></a>
3379 through use of a
3380 <code class="filename">[</code><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#variable-flags" target="_top"><code class="filename">deptask</code></a><code class="filename">]</code>
3381 declaration, which guarantees that the required
3382 shared-library/module-to-package mapping information will be available
3383 when needed as long as <code class="filename">DEPENDS</code> has been
3384 correctly set.
3385 </p></div><div class="section" title="3.5. Fakeroot and Pseudo"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="fakeroot-and-pseudo">3.5. Fakeroot and Pseudo<span class="permalink"><a alt="Permalink" title="Permalink" href="#fakeroot-and-pseudo">¶</a></span></h2></div></div></div><p>
3386 Some tasks are easier to implement when allowed to perform certain
3387 operations that are normally reserved for the root user (e.g.
3388 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-install" target="_top"><code class="filename">do_install</code></a>,
3389 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-package_write_deb" target="_top"><code class="filename">do_package_write*</code></a>,
3390 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-rootfs" target="_top"><code class="filename">do_rootfs</code></a>,
3391 and
3392 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#ref-tasks-image" target="_top"><code class="filename">do_image*</code></a>).
3393 For example, the <code class="filename">do_install</code> task benefits
3394 from being able to set the UID and GID of installed files to
3395 arbitrary values.
3396 </p><p>
3397 One approach to allowing tasks to perform root-only operations
3398 would be to require BitBake to run as root.
3399 However, this method is cumbersome and has security issues.
3400 The approach that is actually used is to run tasks that benefit
3401 from root privileges in a "fake" root environment.
3402 Within this environment, the task and its child processes believe
3403 that they are running as the root user, and see an internally
3404 consistent view of the filesystem.
3405 As long as generating the final output (e.g. a package or an image)
3406 does not require root privileges, the fact that some earlier
3407 steps ran in a fake root environment does not cause problems.
3408 </p><p>
3409 The capability to run tasks in a fake root environment is known as
3410 "<a class="ulink" href="http://man.he.net/man1/fakeroot" target="_top">fakeroot</a>",
3411 which is derived from the BitBake keyword/variable
3412 flag that requests a fake root environment for a task.
3413 </p><p>
3414 In the OpenEmbedded build system, the program that implements
3415 fakeroot is known as Pseudo.
3416 Pseudo overrides system calls by using the environment variable
3417 <code class="filename">LD_PRELOAD</code>, which results in the illusion
3418 of running as root.
3419 To keep track of "fake" file ownership and permissions resulting
3420 from operations that require root permissions, Pseudo uses
3421 an SQLite 3 database.
3422 This database is stored in
3423 <code class="filename">${</code><a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a><code class="filename">}/pseudo/files.db</code>
3424 for individual recipes.
3425 Storing the database in a file as opposed to in memory
3426 gives persistence between tasks and builds, which is not
3427 accomplished using fakeroot.
3428 </p><div class="note" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3>
3429 If you add your own task that manipulates the same files or
3430 directories as a fakeroot task, then that task also needs to
3431 run under fakeroot.
3432 Otherwise, the task cannot run root-only operations, and
3433 cannot see the fake file ownership and permissions set by the
3434 other task.
3435 You need to also add a dependency on
3436 <code class="filename">virtual/fakeroot-native:do_populate_sysroot</code>,
3437 giving the following:
3438 <pre class="literallayout">
3439 fakeroot do_mytask () {
3440 ...
3441 }
3442 do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
3443 </pre></div><p>
3444 For more information, see the
3445 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bitbake-user-manual/bitbake-user-manual.html#var-FAKEROOT" target="_top"><code class="filename">FAKEROOT*</code></a>
3446 variables in the BitBake User Manual.
3447 You can also reference the
3448 "<a class="ulink" href="http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html" target="_top">Pseudo</a>"
3449 and
3450 "<a class="ulink" href="https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot" target="_top">Why Not Fakeroot?</a>"
3451 articles for background information on Pseudo.
3452 </p></div><div class="section" title="3.6. Wayland"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="wayland">3.6. Wayland<span class="permalink"><a alt="Permalink" title="Permalink" href="#wayland">¶</a></span></h2></div></div></div><p>
3453 <a class="ulink" href="http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)" target="_top">Wayland</a>
3454 is a computer display server protocol that
3455 provides a method for compositing window managers to communicate
3456 directly with applications and video hardware and expects them to
3457 communicate with input hardware using other libraries.
3458 Using Wayland with supporting targets can result in better control
3459 over graphics frame rendering than an application might otherwise
3460 achieve.
3461 </p><p>
3462 The Yocto Project provides the Wayland protocol libraries and the
3463 reference
3464 <a class="ulink" href="http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston" target="_top">Weston</a>
3465 compositor as part of its release.
3466 This section describes what you need to do to implement Wayland and
3467 use the compositor when building an image for a supporting target.
3468 </p><div class="section" title="3.6.1. Support"><div class="titlepage"><div><div><h3 class="title" id="wayland-support">3.6.1. Support<span class="permalink"><a alt="Permalink" title="Permalink" href="#wayland-support">¶</a></span></h3></div></div></div><p>
3469 The Wayland protocol libraries and the reference Weston
3470 compositor ship as integrated packages in the
3471 <code class="filename">meta</code> layer of the
3472 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#source-directory" target="_top">Source Directory</a>.
3473 Specifically, you can find the recipes that build both Wayland
3474 and Weston at
3475 <code class="filename">meta/recipes-graphics/wayland</code>.
3476 </p><p>
3477 You can build both the Wayland and Weston packages for use only
3478 with targets that accept the
3479 <a class="ulink" href="https://en.wikipedia.org/wiki/Mesa_(computer_graphics)" target="_top">Mesa 3D and Direct Rendering Infrastructure</a>,
3480 which is also known as Mesa DRI.
3481 This implies that you cannot build and use the packages if your
3482 target uses, for example, the
3483 <span class="trademark">Intel</span>® Embedded Media
3484 and Graphics Driver
3485 (<span class="trademark">Intel</span>® EMGD) that
3486 overrides Mesa DRI.
3487 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3488 Due to lack of EGL support, Weston 1.0.3 will not run
3489 directly on the emulated QEMU hardware.
3490 However, this version of Weston will run under X emulation
3491 without issues.
3492 </div><p>
3493 </p></div><div class="section" title="3.6.2. Enabling Wayland in an Image"><div class="titlepage"><div><div><h3 class="title" id="enabling-wayland-in-an-image">3.6.2. Enabling Wayland in an Image<span class="permalink"><a alt="Permalink" title="Permalink" href="#enabling-wayland-in-an-image">¶</a></span></h3></div></div></div><p>
3494 To enable Wayland, you need to enable it to be built and enable
3495 it to be included in the image.
3496 </p><div class="section" title="3.6.2.1. Building"><div class="titlepage"><div><div><h4 class="title" id="enable-building">3.6.2.1. Building<span class="permalink"><a alt="Permalink" title="Permalink" href="#enable-building">¶</a></span></h4></div></div></div><p>
3497 To cause Mesa to build the <code class="filename">wayland-egl</code>
3498 platform and Weston to build Wayland with Kernel Mode
3499 Setting
3500 (<a class="ulink" href="https://wiki.archlinux.org/index.php/Kernel_Mode_Setting" target="_top">KMS</a>)
3501 support, include the "wayland" flag in the
3502 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-DISTRO_FEATURES" target="_top"><code class="filename">DISTRO_FEATURES</code></a>
3503 statement in your <code class="filename">local.conf</code> file:
3504 </p><pre class="literallayout">
3505 DISTRO_FEATURES_append = " wayland"
3506 </pre><p>
3507 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3508 If X11 has been enabled elsewhere, Weston will build
3509 Wayland with X11 support
3510 </div><p>
3511 </p></div><div class="section" title="3.6.2.2. Installing"><div class="titlepage"><div><div><h4 class="title" id="enable-installation-in-an-image">3.6.2.2. Installing<span class="permalink"><a alt="Permalink" title="Permalink" href="#enable-installation-in-an-image">¶</a></span></h4></div></div></div><p>
3512 To install the Wayland feature into an image, you must
3513 include the following
3514 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-CORE_IMAGE_EXTRA_INSTALL" target="_top"><code class="filename">CORE_IMAGE_EXTRA_INSTALL</code></a>
3515 statement in your <code class="filename">local.conf</code> file:
3516 </p><pre class="literallayout">
3517 CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
3518 </pre><p>
3519 </p></div></div><div class="section" title="3.6.3. Running Weston"><div class="titlepage"><div><div><h3 class="title" id="running-weston">3.6.3. Running Weston<span class="permalink"><a alt="Permalink" title="Permalink" href="#running-weston">¶</a></span></h3></div></div></div><p>
3520 To run Weston inside X11, enabling it as described earlier and
3521 building a Sato image is sufficient.
3522 If you are running your image under Sato, a Weston Launcher
3523 appears in the "Utility" category.
3524 </p><p>
3525 Alternatively, you can run Weston through the command-line
3526 interpretor (CLI), which is better suited for development work.
3527 To run Weston under the CLI, you need to do the following after
3528 your image is built:
3529 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
3530 Run these commands to export
3531 <code class="filename">XDG_RUNTIME_DIR</code>:
3532 </p><pre class="literallayout">
3533 mkdir -p /tmp/$USER-weston
3534 chmod 0700 /tmp/$USER-weston
3535 export XDG_RUNTIME_DIR=/tmp/$USER-weston
3536 </pre><p>
3537 </p></li><li class="listitem"><p>
3538 Launch Weston in the shell:
3539 </p><pre class="literallayout">
3540 weston
3541 </pre></li></ol></div><p>
3542 </p></div></div><div class="section" title="3.7. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="overview-licenses">3.7. Licenses<span class="permalink"><a alt="Permalink" title="Permalink" href="#overview-licenses">¶</a></span></h2></div></div></div><p>
3543 This section describes the mechanism by which the OpenEmbedded
3544 build system tracks changes to licensing text.
3545 The section also describes how to enable commercially licensed
3546 recipes, which by default are disabled.
3547 </p><p>
3548 For information that can help you maintain compliance with
3549 various open source licensing during the lifecycle of the product,
3550 see the
3551 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#maintaining-open-source-license-compliance-during-your-products-lifecycle" target="_top">Maintaining Open Source License Compliance During Your Project's Lifecycle</a>"
3552 section in the Yocto Project Development Tasks Manual.
3553 </p><div class="section" title="3.7.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title" id="usingpoky-configuring-LIC_FILES_CHKSUM">3.7.1. Tracking License Changes<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-configuring-LIC_FILES_CHKSUM">¶</a></span></h3></div></div></div><p>
3554 The license of an upstream project might change in the future.
3555 In order to prevent these changes going unnoticed, the
3556 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LIC_FILES_CHKSUM" target="_top"><code class="filename">LIC_FILES_CHKSUM</code></a>
3557 variable tracks changes to the license text. The checksums are
3558 validated at the end of the configure step, and if the
3559 checksums do not match, the build will fail.
3560 </p><div class="section" title="3.7.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title" id="usingpoky-specifying-LIC_FILES_CHKSUM">3.7.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-specifying-LIC_FILES_CHKSUM">¶</a></span></h4></div></div></div><p>
3561 The <code class="filename">LIC_FILES_CHKSUM</code>
3562 variable contains checksums of the license text in the
3563 source code for the recipe.
3564 Following is an example of how to specify
3565 <code class="filename">LIC_FILES_CHKSUM</code>:
3566 </p><pre class="literallayout">
3567 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
3568 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
3569 file://licfile2.txt;endline=50;md5=zzzz \
3570 ..."
3571 </pre><p>
3572 </p><div class="note" title="Notes" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
3573 When using "beginline" and "endline", realize
3574 that line numbering begins with one and not
3575 zero.
3576 Also, the included lines are inclusive (i.e.
3577 lines five through and including 29 in the
3578 previous example for
3579 <code class="filename">licfile1.txt</code>).
3580 </p></li><li class="listitem"><p>
3581 When a license check fails, the selected license
3582 text is included as part of the QA message.
3583 Using this output, you can determine the exact
3584 start and finish for the needed license text.
3585 </p></li></ul></div></div><p>
3586 </p><p>
3587 The build system uses the
3588 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-S" target="_top"><code class="filename">S</code></a>
3589 variable as the default directory when searching files
3590 listed in <code class="filename">LIC_FILES_CHKSUM</code>.
3591 The previous example employs the default directory.
3592 </p><p>
3593 Consider this next example:
3594 </p><pre class="literallayout">
3595 LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
3596 md5=bb14ed3c4cda583abc85401304b5cd4e"
3597 LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
3598 </pre><p>
3599 </p><p>
3600 The first line locates a file in
3601 <code class="filename">${S}/src/ls.c</code> and isolates lines five
3602 through 16 as license text.
3603 The second line refers to a file in
3604 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-WORKDIR" target="_top"><code class="filename">WORKDIR</code></a>.
3605 </p><p>
3606 Note that <code class="filename">LIC_FILES_CHKSUM</code> variable is
3607 mandatory for all recipes, unless the
3608 <code class="filename">LICENSE</code> variable is set to "CLOSED".
3609 </p></div><div class="section" title="3.7.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title" id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">3.7.1.2. Explanation of Syntax<span class="permalink"><a alt="Permalink" title="Permalink" href="#usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">¶</a></span></h4></div></div></div><p>
3610 As mentioned in the previous section, the
3611 <code class="filename">LIC_FILES_CHKSUM</code> variable lists all
3612 the important files that contain the license text for the
3613 source code.
3614 It is possible to specify a checksum for an entire file,
3615 or a specific section of a file (specified by beginning and
3616 ending line numbers with the "beginline" and "endline"
3617 parameters, respectively).
3618 The latter is useful for source files with a license
3619 notice header, README documents, and so forth.
3620 If you do not use the "beginline" parameter, then it is
3621 assumed that the text begins on the first line of the file.
3622 Similarly, if you do not use the "endline" parameter,
3623 it is assumed that the license text ends with the last
3624 line of the file.
3625 </p><p>
3626 The "md5" parameter stores the md5 checksum of the license
3627 text.
3628 If the license text changes in any way as compared to
3629 this parameter then a mismatch occurs.
3630 This mismatch triggers a build failure and notifies
3631 the developer.
3632 Notification allows the developer to review and address
3633 the license text changes.
3634 Also note that if a mismatch occurs during the build,
3635 the correct md5 checksum is placed in the build log and
3636 can be easily copied to the recipe.
3637 </p><p>
3638 There is no limit to how many files you can specify using
3639 the <code class="filename">LIC_FILES_CHKSUM</code> variable.
3640 Generally, however, every project requires a few
3641 specifications for license tracking.
3642 Many projects have a "COPYING" file that stores the
3643 license information for all the source code files.
3644 This practice allows you to just track the "COPYING"
3645 file as long as it is kept up to date.
3646 </p><div class="note" title="Tips" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tips</h3><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
3647 If you specify an empty or invalid "md5"
3648 parameter, BitBake returns an md5 mis-match
3649 error and displays the correct "md5" parameter
3650 value during the build.
3651 The correct parameter is also captured in
3652 the build log.
3653 </p></li><li class="listitem"><p>
3654 If the whole file contains only license text,
3655 you do not need to use the "beginline" and
3656 "endline" parameters.
3657 </p></li></ul></div></div><p>
3658 </p></div></div><div class="section" title="3.7.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title" id="enabling-commercially-licensed-recipes">3.7.2. Enabling Commercially Licensed Recipes<span class="permalink"><a alt="Permalink" title="Permalink" href="#enabling-commercially-licensed-recipes">¶</a></span></h3></div></div></div><p>
3659 By default, the OpenEmbedded build system disables
3660 components that have commercial or other special licensing
3661 requirements.
3662 Such requirements are defined on a
3663 recipe-by-recipe basis through the
3664 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS" target="_top"><code class="filename">LICENSE_FLAGS</code></a>
3665 variable definition in the affected recipe.
3666 For instance, the
3667 <code class="filename">poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
3668 recipe contains the following statement:
3669 </p><pre class="literallayout">
3670 LICENSE_FLAGS = "commercial"
3671 </pre><p>
3672 Here is a slightly more complicated example that contains both
3673 an explicit recipe name and version (after variable expansion):
3674 </p><pre class="literallayout">
3675 LICENSE_FLAGS = "license_${PN}_${PV}"
3676 </pre><p>
3677 In order for a component restricted by a
3678 <code class="filename">LICENSE_FLAGS</code> definition to be enabled and
3679 included in an image, it needs to have a matching entry in the
3680 global
3681 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS_WHITELIST" target="_top"><code class="filename">LICENSE_FLAGS_WHITELIST</code></a>
3682 variable, which is a variable typically defined in your
3683 <code class="filename">local.conf</code> file.
3684 For example, to enable the
3685 <code class="filename">poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
3686 package, you could add either the string
3687 "commercial_gst-plugins-ugly" or the more general string
3688 "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>.
3689 See the
3690 "<a class="link" href="#license-flag-matching" title="3.7.2.1. License Flag Matching">License Flag Matching</a>"
3691 section for a full
3692 explanation of how <code class="filename">LICENSE_FLAGS</code> matching
3693 works.
3694 Here is the example:
3695 </p><pre class="literallayout">
3696 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
3697 </pre><p>
3698 Likewise, to additionally enable the package built from the
3699 recipe containing
3700 <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>,
3701 and assuming that the actual recipe name was
3702 <code class="filename">emgd_1.10.bb</code>, the following string would
3703 enable that package as well as the original
3704 <code class="filename">gst-plugins-ugly</code> package:
3705 </p><pre class="literallayout">
3706 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
3707 </pre><p>
3708 As a convenience, you do not need to specify the complete
3709 license string in the whitelist for every package.
3710 You can use an abbreviated form, which consists
3711 of just the first portion or portions of the license
3712 string before the initial underscore character or characters.
3713 A partial string will match any license that contains the
3714 given string as the first portion of its license.
3715 For example, the following whitelist string will also match
3716 both of the packages previously mentioned as well as any other
3717 packages that have licenses starting with "commercial" or
3718 "license".
3719 </p><pre class="literallayout">
3720 LICENSE_FLAGS_WHITELIST = "commercial license"
3721 </pre><p>
3722 </p><div class="section" title="3.7.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title" id="license-flag-matching">3.7.2.1. License Flag Matching<span class="permalink"><a alt="Permalink" title="Permalink" href="#license-flag-matching">¶</a></span></h4></div></div></div><p>
3723 License flag matching allows you to control what recipes
3724 the OpenEmbedded build system includes in the build.
3725 Fundamentally, the build system attempts to match
3726 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS" target="_top"><code class="filename">LICENSE_FLAGS</code></a>
3727 strings found in recipes against
3728 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS_WHITELIST" target="_top"><code class="filename">LICENSE_FLAGS_WHITELIST</code></a>
3729 strings found in the whitelist.
3730 A match causes the build system to include a recipe in the
3731 build, while failure to find a match causes the build
3732 system to exclude a recipe.
3733 </p><p>
3734 In general, license flag matching is simple.
3735 However, understanding some concepts will help you
3736 correctly and effectively use matching.
3737 </p><p>
3738 Before a flag
3739 defined by a particular recipe is tested against the
3740 contents of the whitelist, the expanded string
3741 <code class="filename">_${PN}</code> is appended to the flag.
3742 This expansion makes each
3743 <code class="filename">LICENSE_FLAGS</code> value recipe-specific.
3744 After expansion, the string is then matched against the
3745 whitelist.
3746 Thus, specifying
3747 <code class="filename">LICENSE_FLAGS = "commercial"</code>
3748 in recipe "foo", for example, results in the string
3749 <code class="filename">"commercial_foo"</code>.
3750 And, to create a match, that string must appear in the
3751 whitelist.
3752 </p><p>
3753 Judicious use of the <code class="filename">LICENSE_FLAGS</code>
3754 strings and the contents of the
3755 <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable
3756 allows you a lot of flexibility for including or excluding
3757 recipes based on licensing.
3758 For example, you can broaden the matching capabilities by
3759 using license flags string subsets in the whitelist.
3760 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3761 When using a string subset, be sure to use the part of
3762 the expanded string that precedes the appended
3763 underscore character (e.g.
3764 <code class="filename">usethispart_1.3</code>,
3765 <code class="filename">usethispart_1.4</code>, and so forth).
3766 </div><p>
3767 For example, simply specifying the string "commercial" in
3768 the whitelist matches any expanded
3769 <code class="filename">LICENSE_FLAGS</code> definition that starts
3770 with the string "commercial" such as "commercial_foo" and
3771 "commercial_bar", which are the strings the build system
3772 automatically generates for hypothetical recipes named
3773 "foo" and "bar" assuming those recipes simply specify the
3774 following:
3775 </p><pre class="literallayout">
3776 LICENSE_FLAGS = "commercial"
3777 </pre><p>
3778 Thus, you can choose to exhaustively
3779 enumerate each license flag in the whitelist and
3780 allow only specific recipes into the image, or
3781 you can use a string subset that causes a broader range of
3782 matches to allow a range of recipes into the image.
3783 </p><p>
3784 This scheme works even if the
3785 <code class="filename">LICENSE_FLAGS</code> string already
3786 has <code class="filename">_${PN}</code> appended.
3787 For example, the build system turns the license flag
3788 "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
3789 would match both the general "commercial" and the specific
3790 "commercial_1.2_foo" strings found in the whitelist, as
3791 expected.
3792 </p><p>
3793 Here are some other scenarios:
3794 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
3795 You can specify a versioned string in the recipe
3796 such as "commercial_foo_1.2" in a "foo" recipe.
3797 The build system expands this string to
3798 "commercial_foo_1.2_foo".
3799 Combine this license flag with a whitelist that has
3800 the string "commercial" and you match the flag
3801 along with any other flag that starts with the
3802 string "commercial".
3803 </p></li><li class="listitem"><p>
3804 Under the same circumstances, you can use
3805 "commercial_foo" in the whitelist and the build
3806 system not only matches "commercial_foo_1.2" but
3807 also matches any license flag with the string
3808 "commercial_foo", regardless of the version.
3809 </p></li><li class="listitem"><p>
3810 You can be very specific and use both the
3811 package and version parts in the whitelist (e.g.
3812 "commercial_foo_1.2") to specifically match a
3813 versioned recipe.
3814 </p></li></ul></div><p>
3815 </p></div><div class="section" title="3.7.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title" id="other-variables-related-to-commercial-licenses">3.7.2.2. Other Variables Related to Commercial Licenses<span class="permalink"><a alt="Permalink" title="Permalink" href="#other-variables-related-to-commercial-licenses">¶</a></span></h4></div></div></div><p>
3816 Other helpful variables related to commercial
3817 license handling exist and are defined in the
3818 <code class="filename">poky/meta/conf/distro/include/default-distrovars.inc</code> file:
3819 </p><pre class="literallayout">
3820 COMMERCIAL_AUDIO_PLUGINS ?= ""
3821 COMMERCIAL_VIDEO_PLUGINS ?= ""
3822 </pre><p>
3823 If you want to enable these components, you can do so by
3824 making sure you have statements similar to the following
3825 in your <code class="filename">local.conf</code> configuration file:
3826 </p><pre class="literallayout">
3827 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
3828 gst-plugins-ugly-mpegaudioparse"
3829 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
3830 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
3831 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
3832 </pre><p>
3833 Of course, you could also create a matching whitelist
3834 for those components using the more general "commercial"
3835 in the whitelist, but that would also enable all the
3836 other packages with
3837 <a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#var-LICENSE_FLAGS" target="_top"><code class="filename">LICENSE_FLAGS</code></a>
3838 containing "commercial", which you may or may not want:
3839 </p><pre class="literallayout">
3840 LICENSE_FLAGS_WHITELIST = "commercial"
3841 </pre><p>
3842 </p><p>
3843 Specifying audio and video plug-ins as part of the
3844 <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and
3845 <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements
3846 (along with the enabling
3847 <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the
3848 plug-ins or components into built images, thus adding
3849 support for media formats or components.
3850 </p></div></div></div><div class="section" title="3.8. x32 psABI"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="x32">3.8. x32 psABI<span class="permalink"><a alt="Permalink" title="Permalink" href="#x32">¶</a></span></h2></div></div></div><p>
3851 x32 processor-specific Application Binary Interface
3852 (<a class="ulink" href="https://software.intel.com/en-us/node/628948" target="_top">x32 psABI</a>)
3853 is a native 32-bit processor-specific ABI for
3854 <span class="trademark">Intel</span>® 64 (x86-64)
3855 architectures.
3856 An ABI defines the calling conventions between functions in a
3857 processing environment.
3858 The interface determines what registers are used and what the sizes are
3859 for various C data types.
3860 </p><p>
3861 Some processing environments prefer using 32-bit applications even
3862 when running on Intel 64-bit platforms.
3863 Consider the i386 psABI, which is a very old 32-bit ABI for Intel
3864 64-bit platforms.
3865 The i386 psABI does not provide efficient use and access of the
3866 Intel 64-bit processor resources, leaving the system underutilized.
3867 Now consider the x86_64 psABI.
3868 This ABI is newer and uses 64-bits for data sizes and program
3869 pointers.
3870 The extra bits increase the footprint size of the programs,
3871 libraries, and also increases the memory and file system size
3872 requirements.
3873 Executing under the x32 psABI enables user programs to utilize CPU
3874 and system resources more efficiently while keeping the memory
3875 footprint of the applications low.
3876 Extra bits are used for registers but not for addressing mechanisms.
3877 </p><p>
3878 The Yocto Project supports the final specifications of x32 psABI
3879 as follows:
3880 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
3881 You can create packages and images in x32 psABI format on
3882 x86_64 architecture targets.
3883 </p></li><li class="listitem"><p>
3884 You can successfully build recipes with the x32 toolchain.
3885 </p></li><li class="listitem"><p>
3886 You can create and boot
3887 <code class="filename">core-image-minimal</code> and
3888 <code class="filename">core-image-sato</code> images.
3889 </p></li><li class="listitem"><p>
3890 RPM Package Manager (RPM) support exists for x32 binaries.
3891 </p></li><li class="listitem"><p>
3892 Support for large images exists.
3893 </p></li></ul></div><p>
3894 </p><p>
3895 For steps on how to use x32 psABI, see the
3896 "<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#using-x32-psabi" target="_top">Using x32 psABI</a>"
3897 section in the Yocto Project Development Tasks Manual.
3898 </p></div></div>
3899
3900</div></body></html> \ No newline at end of file
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-11 18:40:08 +0000