summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-manual.html
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-manual.html')
-rw-r--r--documentation/ref-manual/ref-manual.html5283
1 files changed, 0 insertions, 5283 deletions
diff --git a/documentation/ref-manual/ref-manual.html b/documentation/ref-manual/ref-manual.html
deleted file mode 100644
index d491bd023d..0000000000
--- a/documentation/ref-manual/ref-manual.html
+++ /dev/null
@@ -1,5283 +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">
3<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title></title><link rel="stylesheet" type="text/css" href="ref-style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="ref-manual"></a></h1></div><div><div class="authorgroup">
4 <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation">
5 <span class="orgname">Linux Foundation<br /></span>
6 </div><code class="email">&lt;<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>&gt;</code></div>
7
8 </div></div><div><p class="copyright">Copyright © 2010-2013 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="idm153280"></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">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</a> as published by Creative Commons.
12 </p>
13 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
14 Due to production processes, there could be differences between the Yocto Project
15 documentation bundled in the release tarball and the
16 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/ref-manual/ref-manual.html" target="_top">Yocto Project Reference Manual</a> on
17 the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website.
18 For the latest version of this manual, see the manual on the website.
19 </div>
20 </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>
21 <tr><td align="left">Revision 4.0+git</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr>
22 <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr>
23 <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr>
24 <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr>
25 <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr>
26 <tr><td align="left">Revision 1.3</td><td align="left">October 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr>
27 <tr><td align="left">Revision 1.4</td><td align="left">Sometime in 2013</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.4 Release.</td></tr>
28 </table></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#detailed-supported-distros">1.3.1. Supported Linux Distributions</a></span></dt><dt><span class="section"><a href="#required-packages-for-the-host-development-system">1.3.2. Required Packages for the Host Development System</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#usingpoky">2. Using the Yocto Project</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd><dt><span class="section"><a href="#maintaining-build-output-quality">2.4. Maintaining Build Output Quality</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-and-disabling-build-history">2.4.1. Enabling and Disabling Build History</a></span></dt><dt><span class="section"><a href="#understanding-what-the-build-history-contains">2.4.2. Understanding What the Build History Contains</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#technical-details">3. Technical Details</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#migration">4. Migrating to a Newer Yocto Project Release</a></span></dt><dd><dl><dt><span class="section"><a href="#moving-to-the-yocto-project-1.3-release">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt><dd><dl><dt><span class="section"><a href="#1.3-local-configuration">4.1.1. Local Configuration</a></span></dt><dt><span class="section"><a href="#1.3-recipes">4.1.2. Recipes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref-structure">5. Source Directory Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core">5.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">5.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">5.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">5.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">5.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto-bsp">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-hob">5.1.7. <code class="filename">meta-hob/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">5.1.9. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">5.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">5.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">5.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">5.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">5.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref-bitbake">6. BitBake</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-bitbake-parsing">6.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">6.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">6.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">6.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">6.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">6.7. Fetchers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-classes">7. Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-classes-base">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-packagegroup">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">7.21. Other Classes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-images">8. Images</a></span></dt><dt><span class="chapter"><a href="#ref-features">9. Reference: Features</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-features-distro">9.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">9.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">9.3. Images</a></span></dt><dt><span class="section"><a href="#ref-features-backfill">9.4. Feature Backfilling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-variables-glos">10. Variables Glossary</a></span></dt><dd><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-varlocality">11. Variable Context</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-configuration">11.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">11.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">11.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">11.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">11.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">11.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">11.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">11.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">11.2.4. Extra Build Information</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#faq">12. FAQ</a></span></dt><dt><span class="chapter"><a href="#resources">13. Contributing to the Yocto Project</a></span></dt><dd><dl><dt><span class="section"><a href="#resources-intro">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">13.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">13.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">13.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">13.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">13.6. Contributions</a></span></dt></dl></dd></dl></div>
29
30
31 <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#detailed-supported-distros">1.3.1. Supported Linux Distributions</a></span></dt><dt><span class="section"><a href="#required-packages-for-the-host-development-system">1.3.2. Required Packages for the Host Development System</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-welcome"></a>1.1. Introduction</h2></div></div></div><p>
32 This manual provides reference information for the current release of the Yocto Project.
33 The Yocto Project is an open-source collaboration project focused on embedded Linux
34 developers.
35 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
36 is based on the Poky project, to construct complete Linux images.
37 You can find complete introductory and getting started information on the Yocto Project
38 by reading the
39 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html" target="_top">Yocto Project Quick Start</a>.
40 For task-based information using the Yocto Project, see the
41 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html" target="_top">Yocto Project Development Manual</a>.
42 You can also find lots of information on the Yocto Project on the
43 <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>.
44 </p></div><div class="section" title="1.2. Documentation Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div><p>
45 This reference manual consists of the following:
46 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>
47 <a class="link" href="#usingpoky" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter
48 provides an overview of the components that make up the Yocto Project
49 followed by information about debugging images created in the Yocto Project.
50 </p></li><li class="listitem"><p><span class="emphasis"><em>
51 <a class="link" href="#technical-details" title="Chapter 3. Technical Details">Technical Details</a>:</em></span>
52 This chapter describes fundamental Yocto Project components as well as an explanation
53 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
54 </p></li><li class="listitem"><p><span class="emphasis"><em>
55 <a class="link" href="#ref-structure" title="Chapter 5. Source Directory Structure">Directory Structure</a>:</em></span>
56 This chapter describes the
57 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a> created
58 either by unpacking a released Yocto Project tarball on your host development system,
59 or by cloning the upstream
60 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">Poky</a> Git repository.
61 </p></li><li class="listitem"><p><span class="emphasis"><em>
62 <a class="link" href="#ref-bitbake" title="Chapter 6. BitBake">BitBake</a>:</em></span>
63 This chapter provides an overview of the BitBake tool and its role within
64 the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>
65 <a class="link" href="#ref-classes" title="Chapter 7. Classes">Classes</a>:</em></span>
66 This chapter describes the classes used in the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>
67 <a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>:</em></span>
68 This chapter describes the standard images that the Yocto Project supports.
69 </p></li><li class="listitem"><p><span class="emphasis"><em>
70 <a class="link" href="#ref-features" title="Chapter 9. Reference: Features">Features</a>:</em></span>
71 This chapter describes mechanisms for creating distribution, machine, and image
72 features during the build process using the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em>
73 <a class="link" href="#ref-variables-glos" title="Chapter 10. Variables Glossary">Variables Glossary</a>:</em></span>
74 This chapter presents most variables used by the OpenEmbedded build system, which
75 using BitBake.
76 Entries describe the function of the variable and how to apply them.
77 </p></li><li class="listitem"><p><span class="emphasis"><em>
78 <a class="link" href="#ref-varlocality" title="Chapter 11. Variable Context">Variable Context</a>:</em></span>
79 This chapter provides variable locality or context.</p></li><li class="listitem"><p><span class="emphasis"><em>
80 <a class="link" href="#faq" title="Chapter 12. FAQ">FAQ</a>:</em></span>
81 This chapter provides answers for commonly asked questions in the Yocto Project
82 development environment.</p></li><li class="listitem"><p><span class="emphasis"><em>
83 <a class="link" href="#resources" title="Chapter 13. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span>
84 This chapter provides guidance on how you can contribute back to the Yocto
85 Project.</p></li></ul></div><p>
86 </p></div><div class="section" title="1.3. System Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-requirements"></a>1.3. System Requirements</h2></div></div></div><p>
87 For general Yocto Project system requirements, see the
88 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#yp-resources" target="_top">What You Need and How You Get It</a>" section
89 in the Yocto Project Quick Start.
90 The remainder of this section provides details on system requirements
91 not covered in the Yocto Project Quick Start.
92 </p><div class="section" title="1.3.1. Supported Linux Distributions"><div class="titlepage"><div><div><h3 class="title"><a id="detailed-supported-distros"></a>1.3.1. Supported Linux Distributions</h3></div></div></div><p>
93 Currently, the Yocto Project is supported on the following distributions:
94 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Ubuntu 10.04.4 LTS</p></li><li class="listitem"><p>Ubuntu 11.10</p></li><li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li><li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li><li class="listitem"><p>Ubuntu 12.10</p></li><li class="listitem"><p>Fedora release 16 (Verne)</p></li><li class="listitem"><p>Fedora release 17 (Beefy Miracle)</p></li><li class="listitem"><p>Fedora release 18 (Spherical Cow)</p></li><li class="listitem"><p>CentOS release 5.6 (Final)</p></li><li class="listitem"><p>CentOS release 5.7 (Final)</p></li><li class="listitem"><p>CentOS release 5.8 (Final)</p></li><li class="listitem"><p>CentOS release 6.3 (Final)</p></li><li class="listitem"><p>Debian GNU/Linux 6.0.6 (squeeze)</p></li><li class="listitem"><p>openSUSE 11.4</p></li><li class="listitem"><p>openSUSE 12.1</p></li><li class="listitem"><p>openSUSE 12.2</p></li></ul></div><p>
95 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
96 For additional information on distributions that support the
97 Yocto Project, see the
98 <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_top">Distribution Support</a> wiki page.
99 </div></div><div class="section" title="1.3.2. Required Packages for the Host Development System"><div class="titlepage"><div><div><h3 class="title"><a id="required-packages-for-the-host-development-system"></a>1.3.2. Required Packages for the Host Development System</h3></div></div></div><p>
100 The list of packages you need on the host development system can
101 be large when covering all build scenarios using the Yocto Project.
102 This section provides required packages by Linux distribution and
103 further categorized by function.
104 </p><div class="section" title="1.3.2.1. Ubuntu"><div class="titlepage"><div><div><h4 class="title"><a id="ubuntu-packages"></a>1.3.2.1. Ubuntu</h4></div></div></div><p>
105 The following list shows the required packages by function
106 given a supported Ubuntu Linux distribution:
107 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
108 Packages needed to build an image on a headless
109 system:
110 </p><pre class="literallayout">
111 $ sudo apt-get install gawk wget git-core diffstat unzip texinfo \
112 build-essential chrpath
113 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
114 Packages recommended if the host system has graphics support:
115 </p><pre class="literallayout">
116 $ sudo apt-get install libsdl1.2-dev xterm
117 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
118 Packages needed if you are going to build out the
119 Yocto Project documentation manuals:
120 </p><pre class="literallayout">
121 $ sudo apt-get install make xsltproc docbook-utils fop
122 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
123 Packages needed if you are going to be using the
124 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
125 </p><pre class="literallayout">
126 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
127 </pre></li></ul></div><p>
128 </p></div><div class="section" title="1.3.2.2. Fedora Packages"><div class="titlepage"><div><div><h4 class="title"><a id="fedora-packages"></a>1.3.2.2. Fedora Packages</h4></div></div></div><p>
129 The following list shows the required packages by function
130 given a supported Fedora Linux distribution:
131 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
132 Packages needed to build an image for a headless
133 system:
134 </p><pre class="literallayout">
135 $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
136 diffutils diffstat git cpp gcc gcc-c++ eglibc-devel texinfo chrpath \
137 ccache
138 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
139 Packages recommended if the host system has graphics support:
140 </p><pre class="literallayout">
141 $ sudo yum install SDL-devel xterm
142 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
143 Packages needed if you are going to build out the
144 Yocto Project documentation manuals:
145 </p><pre class="literallayout">
146 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
147 docbook-dtds docbook-utils fop libxslt
148 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
149 Packages needed if you are going to be using the
150 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
151 </p><pre class="literallayout">
152 $ sudo yum install autoconf automake libtool glib2-devel
153 </pre></li></ul></div><p>
154 </p></div><div class="section" title="1.3.2.3. OpenSUSE Packages"><div class="titlepage"><div><div><h4 class="title"><a id="opensuse-packages"></a>1.3.2.3. OpenSUSE Packages</h4></div></div></div><p>
155 The following list shows the required packages by function
156 given a supported OpenSUSE Linux distribution:
157 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
158 Packages needed to build an image for a headless
159 system:
160 </p><pre class="literallayout">
161 $ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \
162 diffstat texinfo python-curses
163 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
164 Packages recommended if the host system has graphics support:
165 </p><pre class="literallayout">
166 $ sudo zypper install libSDL-devel xterm
167 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
168 Packages needed if you are going to build out the
169 Yocto Project documentation manuals:
170 </p><pre class="literallayout">
171 $ sudo zypper install make fop xsltproc
172 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
173 Packages needed if you are going to be using the
174 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
175 </p><pre class="literallayout">
176 $ sudo zypper install autoconf automake libtool glib2-devel
177 </pre></li></ul></div><p>
178 </p></div><div class="section" title="1.3.2.4. CentOS Packages"><div class="titlepage"><div><div><h4 class="title"><a id="centos-packages"></a>1.3.2.4. CentOS Packages</h4></div></div></div><p>
179 The following list shows the required packages by function
180 given a supported CentOS Linux distribution:
181 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
182 Packages needed to build an image for a headless
183 system:
184 </p><pre class="literallayout">
185 $ sudo yum -y install gawk make wget tar bzip2 gzip python unzip perl patch \
186 diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath
187 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
188 Packages recommended if the host system has graphics support:
189 </p><pre class="literallayout">
190 $ sudo yum -y install SDL-devel xterm
191 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
192 Packages needed if you are going to build out the
193 Yocto Project documentation manuals:
194 </p><pre class="literallayout">
195 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \
196 docbook-dtds docbook-utils fop libxslt
197 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
198 Packages needed if you are going to be using the
199 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
200 </p><pre class="literallayout">
201 $ sudo yum -y install autoconf automake libtool glib2-devel
202 </pre></li></ul></div><p>
203 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Depending on the CentOS version you are using, other requirements
204 and dependencies might exist.
205 For details, you should look at the CentOS sections on the
206 <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_top">Poky/GettingStarted/Dependencies</a>
207 wiki page.</div><p>
208 </p></div></div></div><div class="section" title="1.4. Obtaining the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div><p>
209 The Yocto Project development team makes the Yocto Project available through a number
210 of methods:
211 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through
212 <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_top">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at
213 <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_top">http://autobuilder.yoctoproject.org/nightly</a>.
214 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
215 experimental builds.</p></li><li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases
216 of the Yocto Project and supported BSPs at the
217 <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>.
218 Along with these downloads, you can find lots of other information at this site.
219 </p></li></ul></div><p>
220 </p></div><div class="section" title="1.5. Development Checkouts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div><p>
221 Development using the Yocto Project requires a local
222 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
223 You can set up the source directory by downloading a Yocto Project release tarball and unpacking it,
224 or by cloning a copy of the upstream
225 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">Poky</a> Git repository.
226 For information on both these methods, see the
227 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#getting-setup" target="_top">Getting Setup</a>"
228 section in the Yocto Project Development Manual.
229 </p></div></div>
230
231 <div class="chapter" title="Chapter 2. Using the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd><dt><span class="section"><a href="#maintaining-build-output-quality">2.4. Maintaining Build Output Quality</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-and-disabling-build-history">2.4.1. Enabling and Disabling Build History</a></span></dt><dt><span class="section"><a href="#understanding-what-the-build-history-contains">2.4.2. Understanding What the Build History Contains</a></span></dt></dl></dd></dl></div><p>
232 This chapter describes common usage for the Yocto Project.
233 The information is introductory in nature as other manuals in the Yocto Project
234 documentation set provide more details on how to use the Yocto Project.
235 </p><div class="section" title="2.1. Running a Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div><p>
236 This section provides a summary of the build process and provides information
237 for less obvious aspects of the build process.
238 For general information on how to build an image using the OpenEmbedded build
239 system, see the
240 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#building-image" target="_top">Building an Image</a>"
241 section of the Yocto Project Quick Start.
242 </p><div class="section" title="2.1.1. Build Overview"><div class="titlepage"><div><div><h3 class="title"><a id="build-overview"></a>2.1.1. Build Overview</h3></div></div></div><p>
243 The first thing you need to do is set up the OpenEmbedded build environment by sourcing
244 the <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">environment setup script</a> as follows:
245 </p><pre class="literallayout">
246 $ source oe-init-build-env [build_dir]
247 </pre><p>
248 </p><p>
249 The <code class="filename">build_dir</code> is optional and specifies the directory the
250 OpenEmbedded build system uses for the build -
251 the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
252 If you do not specify a Build Directory it defaults to <code class="filename">build</code>
253 in your current working directory.
254 A common practice is to use a different Build Directory for different targets.
255 For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code>
256 target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target.
257 See <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>
258 for more information on this script.
259 </p><p>
260 Once the build environment is set up, you can build a target using:
261 </p><pre class="literallayout">
262 $ bitbake &lt;target&gt;
263 </pre><p>
264 </p><p>
265 The <code class="filename">target</code> is the name of the recipe you want to build.
266 Common targets are the images in <code class="filename">meta/recipes-core/images</code>,
267 <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the
268 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
269 Or, the target can be the name of a recipe for a specific piece of software such as
270 <span class="application">busybox</span>.
271 For more details about the images the OpenEmbedded build system supports, see the
272 "<a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>" chapter.
273 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
274 Building an image without GNU General Public License Version 3 (GPLv3) components
275 is only supported for minimal and base images.
276 See the "<a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>" chapter for more information.
277 </div></div><div class="section" title="2.1.2. Building an Image Using GPL Components"><div class="titlepage"><div><div><h3 class="title"><a id="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div><p>
278 When building an image using GPL components, you need to maintain your original
279 settings and not switch back and forth applying different versions of the GNU
280 General Public License.
281 If you rebuild using different versions of GPL, dependency errors might occur
282 due to some components not being rebuilt.
283 </p></div></div><div class="section" title="2.2. Installing and Using the Result"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div><p>
284 Once an image has been built, it often needs to be installed.
285 The images and kernels built by the OpenEmbedded build system are placed in the
286 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> in
287 <code class="filename">tmp/deploy/images</code>.
288 For information on how to run pre-built images such as <code class="filename">qemux86</code>
289 and <code class="filename">qemuarm</code>, see the
290 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>"
291 section in the Yocto Project Quick Start.
292 For information about how to install these images, see the documentation for your
293 particular board/machine.
294 </p></div><div class="section" title="2.3. Debugging Build Failures"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div><p>
295 The exact method for debugging build failures depends on the nature of the
296 problem and on the system's area from which the bug originates.
297 Standard debugging practices such as comparison against the last
298 known working version with examination of the changes and the re-application of steps
299 to identify the one causing the problem are
300 valid for the Yocto Project just as they are for any other system.
301 Even though it is impossible to detail every possible potential failure,
302 this section provides some general tips to aid in debugging.
303 </p><div class="section" title="2.3.1. Task Failures"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in
304 <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
305 For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86
306 machine (<code class="filename">qemux86</code>) might be
307 <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</code>.
308 To see what BitBake runs to generate that log, look at the corresponding
309 <code class="filename">run.do_taskname.pid</code> file located in the same directory.
310 </p><p>
311 Presently, the output from Python tasks is sent directly to the console.
312 </p></div><div class="section" title="2.3.2. Running Specific Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div><p>
313 Any given package consists of a set of tasks.
314 The standard BitBake behavior in most cases is: <code class="filename">fetch</code>,
315 <code class="filename">unpack</code>,
316 <code class="filename">patch</code>, <code class="filename">configure</code>,
317 <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>,
318 <code class="filename">package_write</code>, and <code class="filename">build</code>.
319 The default task is <code class="filename">build</code> and any tasks on which it depends
320 build first.
321 Some tasks exist, such as <code class="filename">devshell</code>, that are not part of the
322 default build chain.
323 If you wish to run a task that is not part of the default build chain, you can use the
324 <code class="filename">-c</code> option in BitBake as follows:
325 </p><pre class="literallayout">
326 $ bitbake matchbox-desktop -c devshell
327 </pre><p>
328 </p><p>
329 If you wish to rerun a task, use the <code class="filename">-f</code> force option.
330 For example, the following sequence forces recompilation after changing files in the
331 working directory.
332 </p><pre class="literallayout">
333 $ bitbake matchbox-desktop
334 .
335 .
336 [make some changes to the source code in the working directory]
337 .
338 .
339 $ bitbake matchbox-desktop -c compile -f
340 $ bitbake matchbox-desktop
341 </pre><p>
342 </p><p>
343 This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it.
344 The last command reruns all tasks (basically the packaging tasks) after the compile.
345 BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore
346 understands that the other tasks also need to be run again.
347 </p><p>
348 You can view a list of tasks in a given package by running the
349 <code class="filename">listtasks</code> task as follows:
350 </p><pre class="literallayout">
351 $ bitbake matchbox-desktop -c listtasks
352 </pre><p>
353 The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>.
354 </p></div><div class="section" title="2.3.3. Dependency Graphs"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div><p>
355 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
356 package you have specified.
357 The <code class="filename">bitbake -g targetname</code> command creates the
358 <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>,
359 and <code class="filename">task-depends.dot</code> files in the current directory.
360 These files show the package and task dependencies and are useful for debugging problems.
361 You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to
362 display the results in a more human-readable form.
363 </p></div><div class="section" title="2.3.4. General BitBake Problems"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div><p>
364 You can see debug output from BitBake by using the <code class="filename">-D</code> option.
365 The debug output gives more information about what BitBake
366 is doing and the reason behind it.
367 Each <code class="filename">-D</code> option you use increases the logging level.
368 The most common usage is <code class="filename">-DDD</code>.
369 </p><p>
370 The output from <code class="filename">bitbake -DDD -v targetname</code> can reveal why
371 BitBake chose a certain version of a package or why BitBake
372 picked a certain provider.
373 This command could also help you in a situation where you think BitBake did something
374 unexpected.
375 </p></div><div class="section" title="2.3.5. Building with No Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div><p>
376 If you really want to build a specific <code class="filename">.bb</code> file, you can use
377 the command form <code class="filename">bitbake -b &lt;somepath/somefile.bb&gt;</code>.
378 This command form does not check for dependencies so you should use it
379 only when you know its dependencies already exist.
380 You can also specify fragments of the filename.
381 In this case, BitBake checks for a unique match.
382 </p></div><div class="section" title="2.3.6. Variables"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div><p>
383 The <code class="filename">-e</code> option dumps the resulting environment for
384 either the configuration (no package specified) or for a
385 specific package when specified; or <code class="filename">-b recipename</code>
386 to show the environment from parsing a single recipe file only.
387 </p></div><div class="section" title="2.3.7. Recipe Logging Mechanisms"><div class="titlepage"><div><div><h3 class="title"><a id="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div><p>
388 Best practices exist while writing recipes that both log build progress and
389 act on build conditions such as warnings and errors.
390 Both Python and Bash language bindings exist for the logging mechanism:
391 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake
392 supports several loglevels: <code class="filename">bb.fatal</code>,
393 <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>,
394 <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>,
395 and <code class="filename">bb.debug</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set
396 of loglevels exist and are accessed with a similar syntax:
397 <code class="filename">bbfatal</code>, <code class="filename">bberror</code>,
398 <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>,
399 <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li></ul></div><p>
400 </p><p>
401 For guidance on how logging is handled in both Python and Bash recipes, see the
402 <code class="filename">logging.bbclass</code> file in the
403 <code class="filename">meta/classes</code> folder of the
404 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
405 </p><div class="section" title="2.3.7.1. Logging With Python"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div><p>
406 When creating recipes using Python and inserting code that handles build logs
407 keep in mind the goal is to have informative logs while keeping the console as
408 "silent" as possible.
409 Also, if you want status messages in the log use the "debug" loglevel.
410 </p><p>
411 Following is an example written in Python.
412 The code handles logging for a function that determines the number of tasks
413 needed to be run:
414 </p><pre class="literallayout">
415 python do_listtasks() {
416 bb.debug(2, "Starting to figure out the task list")
417 if noteworthy_condition:
418 bb.note("There are 47 tasks to run")
419 bb.debug(2, "Got to point xyz")
420 if warning_trigger:
421 bb.warn("Detected warning_trigger, this might be a problem later.")
422 if recoverable_error:
423 bb.error("Hit recoverable_error, you really need to fix this!")
424 if fatal_error:
425 bb.fatal("fatal_error detected, unable to print the task list")
426 bb.plain("The tasks present are abc")
427 bb.debug(2, "Finished figuring out the tasklist")
428 }
429 </pre><p>
430 </p></div><div class="section" title="2.3.7.2. Logging With Bash"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div><p>
431 When creating recipes using Bash and inserting code that handles build
432 logs you have the same goals - informative with minimal console output.
433 The syntax you use for recipes written in Bash is similar to that of
434 recipes written in Python described in the previous section.
435 </p><p>
436 Following is an example written in Bash.
437 The code logs the progress of the <code class="filename">do_my_function</code> function.
438 </p><pre class="literallayout">
439 do_my_function() {
440 bbdebug 2 "Running do_my_function"
441 if [ exceptional_condition ]; then
442 bbnote "Hit exceptional_condition"
443 fi
444 bbdebug 2 "Got to point xyz"
445 if [ warning_trigger ]; then
446 bbwarn "Detected warning_trigger, this might cause a problem later."
447 fi
448 if [ recoverable_error ]; then
449 bberror "Hit recoverable_error, correcting"
450 fi
451 if [ fatal_error ]; then
452 bbfatal "fatal_error detected"
453 fi
454 bbdebug 2 "Completed do_my_function"
455 }
456 </pre><p>
457 </p></div></div><div class="section" title="2.3.8. Other Tips"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div><p>
458 Here are some other tips that you might find useful:
459 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>When adding new packages, it is worth watching for
460 undesirable items making their way into compiler command lines.
461 For example, you do not want references to local system files like
462 <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>.
463 </p></li><li class="listitem"><p>If you want to remove the psplash boot splashscreen,
464 add <code class="filename">psplash=false</code> to the kernel command line.
465 Doing so prevents psplash from loading and thus allows you to see the console.
466 It is also possible to switch out of the splashscreen by
467 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
468 </p></li></ul></div><p>
469 </p></div></div><div class="section" title="2.4. Maintaining Build Output Quality"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="maintaining-build-output-quality"></a>2.4. Maintaining Build Output Quality</h2></div></div></div><p>
470 A build's quality can be influenced by many things.
471 For example, if you upgrade a recipe to use a new version of an upstream software
472 package or you experiment with some new configuration options, subtle changes
473 can occur that you might not detect until later.
474 Consider the case where your recipe is using a newer version of an upstream package.
475 In this case, a new version of a piece of software might introduce an optional
476 dependency on another library, which is auto-detected.
477 If that library has already been built when the software is building,
478 then the software will link to the built library and that library will be pulled
479 into your image along with the new software even if you did not want the
480 library.
481 </p><p>
482 The <code class="filename">buildhistory</code> class exists to help you maintain
483 the quality of your build output.
484 You can use the class to highlight unexpected and possibly unwanted
485 changes in the build output.
486 When you enable build history it records information about the contents of
487 each package and image and then commits that information to a local Git
488 repository where you can examine the information.
489 </p><p>
490 The remainder of this section describes the following:
491 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>How you can enable and disable
492 build history</p></li><li class="listitem"><p>How to understand what the build history contains
493 </p></li><li class="listitem"><p>How to limit the information used for build history
494 </p></li><li class="listitem"><p>How to examine the build history from both a
495 command-line and web interface</p></li></ul></div><p>
496 </p><div class="section" title="2.4.1. Enabling and Disabling Build History"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-and-disabling-build-history"></a>2.4.1. Enabling and Disabling Build History</h3></div></div></div><p>
497 Build history is disabled by default.
498 To enable it, add the following statements to the end of your
499 <code class="filename">conf/local.conf</code> file found in the
500 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>:
501 </p><pre class="literallayout">
502 INHERIT += "buildhistory"
503 BUILDHISTORY_COMMIT = "1"
504 </pre><p>
505 Enabling build history as previously described
506 causes the build process to collect build
507 output information and commit it to a local
508 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#git" target="_top">Git</a> repository.
509 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
510 Enabling build history increases your build times slightly,
511 particularly for images, and increases the amount of disk
512 space used during the build.
513 </div><p>
514 </p><p>
515 You can disable build history by removing the previous statements
516 from your <code class="filename">conf/local.conf</code> file.
517 However, you should realize that enabling and disabling
518 build history in this manner can change the
519 <code class="filename">do_package</code> task checksums, which if you
520 are using the OEBasicHash signature generator (the default
521 for many current distro configurations including
522 <code class="filename">DISTRO = "poky"</code> and
523 <code class="filename">DISTRO = ""</code>) will result in the packaging
524 tasks being re-run during the subsequent build.
525 </p><p>
526 To disable the build history functionality without causing the
527 packaging tasks to be re-run, add just this statement to your
528 <code class="filename">conf/local.conf</code> file:
529 </p><pre class="literallayout">
530 BUILDHISTORY_FEATURES = ""
531 </pre><p>
532 </p></div><div class="section" title="2.4.2. Understanding What the Build History Contains"><div class="titlepage"><div><div><h3 class="title"><a id="understanding-what-the-build-history-contains"></a>2.4.2. Understanding What the Build History Contains</h3></div></div></div><p>
533 Build history information is kept in
534 <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">$TMPDIR</code></a><code class="filename">/buildhistory</code>
535 in the Build Directory.
536 The following is an example abbreviated listing:
537 </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/buildhistory.png" align="middle" width="540" /></td></tr></table><p>
538 </p><div class="section" title="2.4.2.1. Build History Package Information"><div class="titlepage"><div><div><h4 class="title"><a id="build-history-package-information"></a>2.4.2.1. Build History Package Information</h4></div></div></div><p>
539 The history for each package contains a text file that has
540 name-value pairs with information about the package.
541 For example, <code class="filename">buildhistory/packages/core2-poky-linux/busybox/busybox/latest</code>
542 contains the following:
543 </p><pre class="literallayout">
544 PV = 1.19.3
545 PR = r3
546 RDEPENDS = update-rc.d eglibc (&gt;= 2.13)
547 RRECOMMENDS = busybox-syslog busybox-udhcpc
548 PKGSIZE = 564701
549 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
550 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
551 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
552 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
553 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
554 </pre><p>
555 Most of these name-value pairs corresponds to variables used
556 to produce the package.
557 The exceptions are <code class="filename">FILELIST</code>, which is the
558 actual list of files in the package, and
559 <code class="filename">PKGSIZE</code>, which is the total size of files
560 in the package in bytes.
561 </p><p>
562 There is also a file corresponding to the recipe from which the
563 package came (e.g.
564 <code class="filename">buildhistory/packages/core2-poky-linux/busybox/latest</code>):
565 </p><pre class="literallayout">
566 PV = 1.19.3
567 PR = r3
568 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
569 virtual/libc update-rc.d-native
570 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
571 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
572 busybox-staticdev busybox-locale
573 </pre><p>
574 </p></div><div class="section" title="2.4.2.2. Build History Image Information"><div class="titlepage"><div><div><h4 class="title"><a id="build-history-image-information"></a>2.4.2.2. Build History Image Information</h4></div></div></div><p>
575 The files produced for each image are as follows:
576 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>build-id:</em></span>
577 Human-readable information about the build configuration
578 and metadata source revisions.</p></li><li class="listitem"><p><span class="emphasis"><em>*.dot:</em></span>
579 Dependency graphs for the image that are
580 compatible with <code class="filename">graphviz</code>.
581 </p></li><li class="listitem"><p><span class="emphasis"><em>files-in-image.txt:</em></span>
582 A list of files in the image with permissions,
583 owner, group, size, and symlink information.
584 </p></li><li class="listitem"><p><span class="emphasis"><em>image-info.txt:</em></span>
585 A text file containing name-value pairs with information
586 about the image.
587 See the following listing example for more information.
588 </p></li><li class="listitem"><p><span class="emphasis"><em>installed-package-names.txt:</em></span>
589 A list of installed packages by name only.</p></li><li class="listitem"><p><span class="emphasis"><em>installed-package-sizes.txt:</em></span>
590 A list of installed packages ordered by size.
591 </p></li><li class="listitem"><p><span class="emphasis"><em>installed-packages.txt:</em></span>
592 A list of installed packages with fuill package
593 filenames.</p></li></ul></div><p>
594 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
595 Installed package information is able to be gathered and
596 produced even if package management is disabled for the final
597 image.
598 </div><p>
599 </p><p>
600 Here is an example of <code class="filename">image-info.txt</code>:
601 </p><pre class="literallayout">
602 DISTRO = poky
603 DISTRO_VERSION = 1.1+snapshot-20120207
604 USER_CLASSES = image-mklibs image-prelink
605 IMAGE_CLASSES = image_types
606 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
607 package-management ssh-server-dropbear package-management
608 IMAGE_LINGUAS = en-us en-gb
609 IMAGE_INSTALL = task-core-boot task-base-extended
610 BAD_RECOMMENDATIONS =
611 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
612 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
613 IMAGESIZE = 171816
614 </pre><p>
615 Other than <code class="filename">IMAGESIZE</code>, which is the
616 total size of the files in the image in Kbytes, the
617 name-value pairs are variables that may have influenced the
618 content of the image.
619 This information is often useful when you are trying to determine
620 why a change in the package or file listings has occurred.
621 </p></div><div class="section" title="2.4.2.3. Using Build History to Gather Image Information Only"><div class="titlepage"><div><div><h4 class="title"><a id="using-build-history-to-gather-image-information-only"></a>2.4.2.3. Using Build History to Gather Image Information Only</h4></div></div></div><p>
622 As you can see, build history produces image information,
623 including dependency graphs, so you can see why something
624 was pulled into the image.
625 If you are just interested in this information and not
626 interested in collecting history or any package information,
627 you can enable writing only image information without
628 any history by adding the following
629 to your <code class="filename">conf/local.conf</code> file found in the
630 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>:
631 </p><pre class="literallayout">
632 INHERIT += "buildhistory"
633 BUILDHISTORY_COMMIT = "0"
634 BUILDHISTORY_FEATURES = "image"
635 </pre><p>
636 </p></div><div class="section" title="2.4.2.4. Examining Build History Information"><div class="titlepage"><div><div><h4 class="title"><a id="examining-build-history-information"></a>2.4.2.4. Examining Build History Information</h4></div></div></div><p>
637 You can examine build history output from the command line or
638 from a web interface.
639 </p><p>
640 To see any changes that have occurred (assuming you have
641 <code class="filename">BUILDHISTORY_COMMIT = "1"</code>), you can simply
642 use any Git command that allows you to view the history of
643 a repository.
644 Here is one method:
645 </p><pre class="literallayout">
646 $ git log -p
647 </pre><p>
648 You need to realize, however, that this method does show
649 changes that are not significant (e.g. a package's size
650 changing by a few bytes).
651 </p><p>
652 A command-line tool called <code class="filename">buildhistory-diff</code>
653 does exist though that queries the Git repository and prints just
654 the differences that might be significant in human-readable form.
655 Here is an example:
656 </p><pre class="literallayout">
657 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
658 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
659 /etc/anotherpkg.conf was added
660 /sbin/anotherpkg was added
661 * (installed-package-names.txt):
662 * anotherpkg was added
663 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
664 anotherpkg was added
665 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
666 * PR changed from "r0" to "r1"
667 * PV changed from "0.1.10" to "0.1.12"
668 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
669 * PR changed from "r0" to "r1"
670 * PV changed from "0.1.10" to "0.1.12"
671 </pre><p>
672 </p><p>
673 To see changes to the build history using a web interface, follow
674 the instruction in the <code class="filename">README</code> file here.
675 <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/</a>.
676 </p><p>
677 Here is a sample screenshot of the interface:
678 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="130%"><tr><td align="center"><img src="figures/buildhistory-web.png" align="middle" height="468" /></td></tr></table><p>
679 </p></div></div></div></div>
680
681 <div class="chapter" title="Chapter 3. Technical Details"><div class="titlepage"><div><div><h2 class="title"><a id="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></div><p>
682 This chapter provides technical details for various parts of the Yocto Project.
683 Currently, topics include Yocto Project components and shared state (sstate) cache.
684 </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div><p>
685 The BitBake task executor together with various types of configuration files form the
686 OpenEmbedded Core.
687 This section overviews the BitBake task executor and the
688 configuration files by describing what they are used for and how they interact.
689 </p><p>
690 BitBake handles the parsing and execution of the data files.
691 The data itself is of various types:
692 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular
693 pieces of software</p></li><li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build
694 information (e.g. how to build a Linux kernel).</p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings,
695 policy decisions, etc.
696 Configuration data acts as the glue to bind everything together.</p></li></ul></div><p>
697 For more information on data, see the
698 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#yocto-project-terms" target="_top">Yocto Project Terms</a>"
699 section in the Yocto Project Development Manual.
700 </p><p>
701 BitBake knows how to combine multiple data sources together and refers to each data source
702 as a layer.
703 For information on layers, see the
704 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and
705 Creating Layers</a>" section of the Yocto Project Development Manual.
706 </p><p>
707 Following are some brief details on these core components.
708 For more detailed information on these components see the
709 "<a class="link" href="#ref-structure" title="Chapter 5. Source Directory Structure">Directory Structure</a>" chapter.
710 </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div><p>
711 BitBake is the tool at the heart of the OpenEmbedded build system and is responsible
712 for parsing the metadata, generating a list of tasks from it,
713 and then executing those tasks.
714 To see a list of the options BitBake supports, use the following help command:
715 </p><pre class="literallayout">
716 $ bitbake --help
717 </pre><p>
718 </p><p>
719 The most common usage for BitBake is <code class="filename">bitbake &lt;packagename&gt;</code>, where
720 <code class="filename">packagename</code> is the name of the package you want to build
721 (referred to as the "target" in this manual).
722 The target often equates to the first part of a <code class="filename">.bb</code> filename.
723 So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you
724 might type the following:
725 </p><pre class="literallayout">
726 $ bitbake matchbox-desktop
727 </pre><p>
728 Several different versions of <code class="filename">matchbox-desktop</code> might exist.
729 BitBake chooses the one selected by the distribution configuration.
730 You can get more details about how BitBake chooses between different
731 target versions and providers in the
732 "<a class="link" href="#ref-bitbake-providers" title="6.2. Preferences and Providers">Preferences and Providers</a>" section.
733 </p><p>
734 BitBake also tries to execute any dependent tasks first.
735 So for example, before building <code class="filename">matchbox-desktop</code>, BitBake
736 would build a cross compiler and <code class="filename">eglibc</code> if they had not already
737 been built.
738 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code>
739 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
740 builds with <code class="filename">eglibc</code>.</div><p>
741 </p><p>
742 A useful BitBake option to consider is the <code class="filename">-k</code> or
743 <code class="filename">--continue</code> option.
744 This option instructs BitBake to try and continue processing the job as much
745 as possible even after encountering an error.
746 When an error occurs, the target that
747 failed and those that depend on it cannot be remade.
748 However, when you use this option other dependencies can still be processed.
749 </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div><p>
750 The <code class="filename">.bb</code> files are usually referred to as "recipes."
751 In general, a recipe contains information about a single piece of software.
752 The information includes the location from which to download the source patches
753 (if any are needed), which special configuration options to apply,
754 how to compile the source files, and how to package the compiled output.
755 </p><p>
756 The term "package" can also be used to describe recipes.
757 However, since the same word is used for the packaged output from the OpenEmbedded
758 build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files),
759 this document avoids using the term "package" when referring to recipes.
760 </p></div><div class="section" title="3.1.3. Classes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div><p>
761 Class files (<code class="filename">.bbclass</code>) contain information that is useful to share
762 between metadata files.
763 An example is the Autotools class, which contains
764 common settings for any application that Autotools uses.
765 The "<a class="link" href="#ref-classes" title="Chapter 7. Classes">Classes</a>" chapter provides details
766 about common classes and how to use them.
767 </p></div><div class="section" title="3.1.4. Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div><p>
768 The configuration files (<code class="filename">.conf</code>) define various configuration variables
769 that govern the OpenEmbedded build process.
770 These files fall into several areas that define machine configuration options,
771 distribution configuration options, compiler tuning options, general common configuration
772 options and user configuration options (<code class="filename">local.conf</code>, which is found
773 in the <a class="ulink" href="build-directory" target="_top">Build Directory</a>).
774 </p></div></div><div class="section" title="3.2. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div><p>
775 By design, the OpenEmbedded build system builds everything from scratch unless
776 BitBake can determine that parts don't need to be rebuilt.
777 Fundamentally, building from scratch is attractive as it means all parts are
778 built fresh and there is no possibility of stale data causing problems.
779 When developers hit problems, they typically default back to building from scratch
780 so they know the state of things from the start.
781 </p><p>
782 Building an image from scratch is both an advantage and a disadvantage to the process.
783 As mentioned in the previous paragraph, building from scratch ensures that
784 everything is current and starts from a known state.
785 However, building from scratch also takes much longer as it generally means
786 rebuilding things that don't necessarily need rebuilt.
787 </p><p>
788 The Yocto Project implements shared state code that supports incremental builds.
789 The implementation of the shared state code answers the following questions that
790 were fundamental roadblocks within the OpenEmbedded incremental build support system:
791 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">What pieces of the system have changed and what pieces have not changed?</li><li class="listitem">How are changed pieces of software removed and replaced?</li><li class="listitem">How are pre-built components that don't need to be rebuilt from scratch
792 used when they are available?</li></ul></div><p>
793 </p><p>
794 For the first question, the build system detects changes in the "inputs" to a given task by
795 creating a checksum (or signature) of the task's inputs.
796 If the checksum changes, the system assumes the inputs have changed and the task needs to be
797 rerun.
798 For the second question, the shared state (sstate) code tracks which tasks add which output
799 to the build process.
800 This means the output from a given task can be removed, upgraded or otherwise manipulated.
801 The third question is partly addressed by the solution for the second question
802 assuming the build system can fetch the sstate objects from remote locations and
803 install them if they are deemed to be valid.
804 </p><p>
805 The rest of this section goes into detail about the overall incremental build
806 architecture, the checksums (signatures), shared state, and some tips and tricks.
807 </p><div class="section" title="3.2.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title"><a id="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div><p>
808 When determining what parts of the system need to be built, BitBake
809 uses a per-task basis and does not use a per-recipe basis.
810 You might wonder why using a per-task basis is preferred over a per-recipe basis.
811 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
812 In this case, <code class="filename">do_install</code> and <code class="filename">do_package</code>
813 output are still valid.
814 However, with a per-recipe approach, the build would not include the
815 <code class="filename">.deb</code> files.
816 Consequently, you would have to invalidate the whole build and rerun it.
817 Rerunning everything is not the best situation.
818 Also in this case, the core must be "taught" much about specific tasks.
819 This methodology does not scale well and does not allow users to easily add new tasks
820 in layers or as external recipes without touching the packaged-staging core.
821 </p></div><div class="section" title="3.2.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title"><a id="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div><p>
822 The shared state code uses a checksum, which is a unique signature of a task's
823 inputs, to determine if a task needs to be run again.
824 Because it is a change in a task's inputs that triggers a rerun, the process
825 needs to detect all the inputs to a given task.
826 For shell tasks, this turns out to be fairly easy because
827 the build process generates a "run" shell script for each task and
828 it is possible to create a checksum that gives you a good idea of when
829 the task's data changes.
830 </p><p>
831 To complicate the problem, there are things that should not be included in
832 the checksum.
833 First, there is the actual specific build path of a given task -
834 the <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
835 It does not matter if the working directory changes because it should not
836 affect the output for target packages.
837 Also, the build process has the objective of making native/cross packages relocatable.
838 The checksum therefore needs to exclude <code class="filename">WORKDIR</code>.
839 The simplistic approach for excluding the working directory is to set
840 <code class="filename">WORKDIR</code> to some fixed value and create the checksum
841 for the "run" script.
842 </p><p>
843 Another problem results from the "run" scripts containing functions that
844 might or might not get called.
845 The incremental build solution contains code that figures out dependencies
846 between shell functions.
847 This code is used to prune the "run" scripts down to the minimum set,
848 thereby alleviating this problem and making the "run" scripts much more
849 readable as a bonus.
850 </p><p>
851 So far we have solutions for shell scripts.
852 What about python tasks?
853 The same approach applies even though these tasks are more difficult.
854 The process needs to figure out what variables a python function accesses
855 and what functions it calls.
856 Again, the incremental build solution contains code that first figures out
857 the variable and function dependencies, and then creates a checksum for the data
858 used as the input to the task.
859 </p><p>
860 Like the <code class="filename">WORKDIR</code> case, situations exist where dependencies
861 should be ignored.
862 For these cases, you can instruct the build process to ignore a dependency
863 by using a line like the following:
864 </p><pre class="literallayout">
865 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
866 </pre><p>
867 This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not
868 depend on the value of <code class="filename">MACHINE</code>, even if it does reference it.
869 </p><p>
870 Equally, there are cases where we need to add dependencies BitBake is not able to find.
871 You can accomplish this by using a line like the following:
872 </p><pre class="literallayout">
873 PACKAGE_ARCHS[vardeps] = "MACHINE"
874 </pre><p>
875 This example explicitly adds the <code class="filename">MACHINE</code> variable as a
876 dependency for <code class="filename">PACKAGE_ARCHS</code>.
877 </p><p>
878 Consider a case with inline python, for example, where BitBake is not
879 able to figure out dependencies.
880 When running in debug mode (i.e. using <code class="filename">-DDD</code>), BitBake
881 produces output when it discovers something for which it cannot figure out
882 dependencies.
883 The Yocto Project team has currently not managed to cover those dependencies
884 in detail and is aware of the need to fix this situation.
885 </p><p>
886 Thus far, this section has limited discussion to the direct inputs into a task.
887 Information based on direct inputs is referred to as the "basehash" in the
888 code.
889 However, there is still the question of a task's indirect inputs - the
890 things that were already built and present in the Build Directory.
891 The checksum (or signature) for a particular task needs to add the hashes
892 of all the tasks on which the particular task depends.
893 Choosing which dependencies to add is a policy decision.
894 However, the effect is to generate a master checksum that combines the basehash
895 and the hashes of the task's dependencies.
896 </p><p>
897 At the code level, there are a variety of ways both the basehash and the
898 dependent task hashes can be influenced.
899 Within the BitBake configuration file, we can give BitBake some extra information
900 to help it construct the basehash.
901 The following statements effectively result in a list of global variable
902 dependency excludes - variables never included in any checksum:
903 </p><pre class="literallayout">
904 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
905 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
906 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
907 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
908 </pre><p>
909 The previous example actually excludes
910 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>
911 since it is actually constructed as a path within
912 <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on
913 the whitelist.
914 </p><p>
915 The rules for deciding which hashes of dependent tasks to include through
916 dependency chains are more complex and are generally accomplished with a
917 python function.
918 The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows two examples
919 of this and also illustrates how you can insert your own policy into the system
920 if so desired.
921 This file defines the two basic signature generators <code class="filename">OE-Core</code>
922 uses: "OEBasic" and "OEBasicHash".
923 By default, there is a dummy "noop" signature handler enabled in BitBake.
924 This means that behavior is unchanged from previous versions.
925 <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default
926 through this setting in the <code class="filename">bitbake.conf</code> file:
927 </p><pre class="literallayout">
928 BB_SIGNATURE_HANDLER ?= "OEBasic"
929 </pre><p>
930 The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the
931 "OEBasic" version but adds the task hash to the stamp files.
932 This results in any metadata change that changes the task hash, automatically
933 causing the task to be run again.
934 This removes the need to bump <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a>
935 values and changes to metadata automatically ripple across the build.
936 Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code>
937 but is the default in <code class="filename">poky</code>.
938 </p><p>
939 It is also worth noting that the end result of these signature generators is to
940 make some dependency and hash information available to the build.
941 This information includes:
942 </p><pre class="literallayout">
943 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
944 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
945 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
946 BB_TASKHASH - the hash of the currently running task
947 </pre><p>
948 </p></div><div class="section" title="3.2.3. Shared State"><div class="titlepage"><div><div><h3 class="title"><a id="shared-state"></a>3.2.3. Shared State</h3></div></div></div><p>
949 Checksums and dependencies, as discussed in the previous section, solve half the
950 problem.
951 The other part of the problem is being able to use checksum information during the build
952 and being able to reuse or rebuild specific components.
953 </p><p>
954 The shared state class (<code class="filename">sstate.bbclass</code>)
955 is a relatively generic implementation of how to "capture" a snapshot of a given task.
956 The idea is that the build process does not care about the source of a task's output.
957 Output could be freshly built or it could be downloaded and unpacked from
958 somewhere - the build process doesn't need to worry about its source.
959 </p><p>
960 There are two types of output, one is just about creating a directory
961 in <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
962 A good example is the output of either <code class="filename">do_install</code> or
963 <code class="filename">do_package</code>.
964 The other type of output occurs when a set of data is merged into a shared directory
965 tree such as the sysroot.
966 </p><p>
967 The Yocto Project team has tried to keep the details of the implementation hidden in
968 <code class="filename">sstate.bbclass</code>.
969 From a user's perspective, adding shared state wrapping to a task
970 is as simple as this <code class="filename">do_deploy</code> example taken from
971 <code class="filename">do_deploy.bbclass</code>:
972 </p><pre class="literallayout">
973 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
974 SSTATETASKS += "do_deploy"
975 do_deploy[sstate-name] = "deploy"
976 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
977 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
978
979 python do_deploy_setscene () {
980 sstate_setscene(d)
981 }
982 addtask do_deploy_setscene
983 </pre><p>
984 In the example, we add some extra flags to the task, a name field ("deploy"), an
985 input directory where the task sends data, and the output
986 directory where the data from the task should eventually be copied.
987 We also add a <code class="filename">_setscene</code> variant of the task and add the task
988 name to the <code class="filename">SSTATETASKS</code> list.
989 </p><p>
990 If you have a directory whose contents you need to preserve, you can do this with
991 a line like the following:
992 </p><pre class="literallayout">
993 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
994 </pre><p>
995 This method, as well as the following example, also works for multiple directories.
996 </p><pre class="literallayout">
997 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
998 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
999 do_package[sstate-lockfile] = "${PACKAGELOCK}"
1000 </pre><p>
1001 These methods also include the ability to take a lockfile when manipulating
1002 shared state directory structures since some cases are sensitive to file
1003 additions or removals.
1004 </p><p>
1005 Behind the scenes, the shared state code works by looking in
1006 <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> and
1007 <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
1008 for shared state files.
1009 Here is an example:
1010 </p><pre class="literallayout">
1011 SSTATE_MIRRORS ?= "\
1012 file://.* http://someserver.tld/share/sstate/PATH \n \
1013 file://.* file:///some/local/dir/sstate/PATH"
1014 </pre><p>
1015 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1016 The shared state directory (<code class="filename">SSTATE_DIR</code>) is
1017 organized into two-character subdirectories, where the subdirectory
1018 names are based on the first two characters of the hash.
1019 If the shared state directory structure for a mirror has the
1020 same structure as <code class="filename">SSTATE_DIR</code>, you must
1021 specify "PATH" as part of the URI to enable the build system
1022 to map to the appropriate subdirectory.
1023 </div><p>
1024 </p><p>
1025 The shared state package validity can be detected just by looking at the
1026 filename since the filename contains the task checksum (or signature) as
1027 described earlier in this section.
1028 If a valid shared state package is found, the build process downloads it
1029 and uses it to accelerate the task.
1030 </p><p>
1031 The build processes uses the <code class="filename">*_setscene</code> tasks
1032 for the task acceleration phase.
1033 BitBake goes through this phase before the main execution code and tries
1034 to accelerate any tasks for which it can find shared state packages.
1035 If a shared state package for a task is available, the shared state
1036 package is used.
1037 This means the task and any tasks on which it is dependent are not
1038 executed.
1039 </p><p>
1040 As a real world example, the aim is when building an IPK-based image,
1041 only the <code class="filename">do_package_write_ipk</code> tasks would have their
1042 shared state packages fetched and extracted.
1043 Since the sysroot is not used, it would never get extracted.
1044 This is another reason why a task-based approach is preferred over a
1045 recipe-based approach, which would have to install the output from every task.
1046 </p></div><div class="section" title="3.2.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title"><a id="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div><p>
1047 The code in the build system that supports incremental builds is not
1048 simple code.
1049 This section presents some tips and tricks that help you work around
1050 issues related to shared state code.
1051 </p><div class="section" title="3.2.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title"><a id="debugging"></a>3.2.4.1. Debugging</h4></div></div></div><p>
1052 When things go wrong, debugging needs to be straightforward.
1053 Because of this, the Yocto Project team included strong debugging
1054 tools:
1055 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Whenever a shared state package is written out, so is a
1056 corresponding <code class="filename">.siginfo</code> file.
1057 This practice results in a pickled python database of all
1058 the metadata that went into creating the hash for a given shared state
1059 package.</p></li><li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code>
1060 (or <code class="filename">-S</code>) option, BitBake dumps out
1061 <code class="filename">.siginfo</code> files in
1062 the stamp directory for every task it would have executed instead of
1063 building the specified target package.</p></li><li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that
1064 can process these <code class="filename">.siginfo</code> files.
1065 If one file is specified, it will dump out the dependency
1066 information in the file.
1067 If two files are specified, it will compare the two files and dump out
1068 the differences between the two.
1069 This allows the question of "What changed between X and Y?" to be
1070 answered easily.</p></li></ul></div><p>
1071 </p></div><div class="section" title="3.2.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title"><a id="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div><p>
1072 The shared state code uses checksums and shared state
1073 cache to avoid unnecessarily rebuilding tasks.
1074 As with all schemes, this one has some drawbacks.
1075 It is possible that you could make implicit changes that are not factored
1076 into the checksum calculation, but do affect a task's output.
1077 A good example is perhaps when a tool changes its output.
1078 Let's say that the output of <code class="filename">rpmdeps</code> needed to change.
1079 The result of the change should be that all the "package", "package_write_rpm",
1080 and "package_deploy-rpm" shared state cache items would become invalid.
1081 But, because this is a change that is external to the code and therefore implicit,
1082 the associated shared state cache items do not become invalidated.
1083 In this case, the build process would use the cached items rather than running the
1084 task again.
1085 Obviously, these types of implicit changes can cause problems.
1086 </p><p>
1087 To avoid these problems during the build, you need to understand the effects of any
1088 change you make.
1089 Note that any changes you make directly to a function automatically are factored into
1090 the checksum calculation and thus, will invalidate the associated area of sstate cache.
1091 You need to be aware of any implicit changes that are not obvious changes to the
1092 code and could affect the output of a given task.
1093 Once you are aware of such a change, you can take steps to invalidate the cache
1094 and force the task to run.
1095 The step to take is as simple as changing a function's comments in the source code.
1096 For example, to invalidate package shared state files, change the comment statements
1097 of <code class="filename">do_package</code> or the comments of one of the functions it calls.
1098 The change is purely cosmetic, but it causes the checksum to be recalculated and
1099 forces the task to be run again.
1100 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1101 For an example of a commit that makes a cosmetic change to invalidate
1102 a shared state, see this
1103 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>.
1104 </div></div></div></div><div class="section" title="3.3. x32"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="x32"></a>3.3. x32</h2></div></div></div><p>
1105 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64.
1106 An ABI defines the calling conventions between functions in a processing environment.
1107 The interface determines what registers are used and what the sizes are for various C data types.
1108 </p><p>
1109 Some processing environments prefer using 32-bit applications even when running
1110 on Intel 64-bit platforms.
1111 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
1112 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
1113 leaving the system underutilized.
1114 Now consider the x86_64 psABI.
1115 This ABI is newer and uses 64-bits for data sizes and program pointers.
1116 The extra bits increase the footprint size of the programs, libraries,
1117 and also increases the memory and file system size requirements.
1118 Executing under the x32 psABI enables user programs to utilize CPU and system resources
1119 more efficiently while keeping the memory footprint of the applications low.
1120 Extra bits are used for registers but not for addressing mechanisms.
1121 </p><div class="section" title="3.3.1. Support"><div class="titlepage"><div><div><h3 class="title"><a id="support"></a>3.3.1. Support</h3></div></div></div><p>
1122 While the x32 psABI specifications are not fully finalized, this Yocto Project
1123 release supports current development specifications of x32 psABI.
1124 As of this release of the Yocto Project, x32 psABI support exists as follows:
1125 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets.
1126 </p></li><li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code>
1127 layer on top of the OE-core/Yocto layer.</p></li><li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer
1128 is used for building x32 psABI program binaries.</p></li><li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li><li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and
1129 <code class="filename">core-image-sato</code> images.</p></li></ul></div><p>
1130 </p></div><div class="section" title="3.3.2. Future Development and Limitations"><div class="titlepage"><div><div><h3 class="title"><a id="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div><p>
1131 As of this Yocto Project release, the x32 psABI kernel and library interfaces
1132 specifications are not finalized.
1133 </p><p>
1134 Future Plans for the x32 psABI in the Yocto Project include the following:
1135 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enhance and fix the few remaining recipes so they
1136 work with and support x32 toolchains.</p></li><li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li><li class="listitem"><p>Support larger images.</p></li><li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from
1137 <code class="filename">experimental/meta-x32</code> into OE-core.</p></li></ul></div><p>
1138 </p></div><div class="section" title="3.3.3. Using x32 Right Now"><div class="titlepage"><div><div><h3 class="title"><a id="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div><p>
1139 Despite the fact the x32 psABI support is in development state for this release of the
1140 Yocto Project, you can follow these steps to use the x32 spABI:
1141 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local
1142 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
1143 You can find the <code class="filename">experimental/meta-x32</code> source repository at
1144 <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>.</p></li><li class="listitem"><p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes
1145 the <code class="filename">meta-x32</code>.
1146 Here is an example:
1147 </p><pre class="literallayout">
1148 BBLAYERS ?= " \
1149 /home/nitin/prj/poky.git/meta \
1150 /home/nitin/prj/poky.git/meta-yocto \
1151 /home/nitin/prj/poky.git/meta-yocto-bsp \
1152 /home/nitin/prj/meta-x32.git \
1153 "
1154 BBLAYERS_NON_REMOVABLE ?= " \
1155 /home/nitin/prj/poky.git/meta \
1156 /home/nitin/prj/poky.git/meta-yocto \
1157 "
1158 </pre></li><li class="listitem"><p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code>
1159 machines by editing the <code class="filename">conf/local.conf</code> like this:
1160 </p><pre class="literallayout">
1161 MACHINE = "qemux86-64"
1162 DEFAULTTUNE = "x86-64-x32"
1163 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
1164 or 'INVALID'), True) or 'lib'}"
1165 #MACHINE = "atom-pc"
1166 #DEFAULTTUNE = "core2-64-x32"
1167 </pre></li><li class="listitem"><p>As usual, use BitBake to build an image that supports the x32 psABI.
1168 Here is an example:
1169 </p><pre class="literallayout">
1170 $ bitake core-image-sato
1171 </pre></li><li class="listitem"><p>As usual, run your image using QEMU:
1172 </p><pre class="literallayout">
1173 $ runqemu qemux86-64 core-image-sato
1174 </pre></li></ul></div><p>
1175 </p></div></div><div class="section" title="3.4. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licenses"></a>3.4. Licenses</h2></div></div></div><p>
1176 This section describes the mechanism by which the OpenEmbedded build system
1177 tracks changes to licensing text.
1178 The section also describes how to enable commercially licensed recipes,
1179 which by default are disabled.
1180 </p><p>
1181 For information that can help you maintain compliance with various open
1182 source licensing during the lifecycle of the product, see the
1183 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/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>" section
1184 in the Yocto Project Development Manual.
1185 </p><div class="section" title="3.4.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div><p>
1186 The license of an upstream project might change in the future.
1187 In order to prevent these changes going unnoticed, the
1188 <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code>
1189 variable tracks changes to the license text. The checksums are validated at the end of the
1190 configure step, and if the checksums do not match, the build will fail.
1191 </p><div class="section" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.4.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div><p>
1192 The <code class="filename">LIC_FILES_CHKSUM</code>
1193 variable contains checksums of the license text in the source code for the recipe.
1194 Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>:
1195 </p><pre class="literallayout">
1196 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1197 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1198 file://licfile2.txt;endline=50;md5=zzzz \
1199 ..."
1200 </pre><p>
1201 </p><p>
1202 The build system uses the
1203 <code class="filename"><a class="link" href="#var-S" title="S">S</a></code> variable as the
1204 default directory used when searching files listed in
1205 <code class="filename">LIC_FILES_CHKSUM</code>.
1206 The previous example employs the default directory.
1207 </p><p>
1208 You can also use relative paths as shown in the following example:
1209 </p><pre class="literallayout">
1210 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
1211 md5=bb14ed3c4cda583abc85401304b5cd4e"
1212 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1213 </pre><p>
1214 </p><p>
1215 In this example, the first line locates a file in
1216 <code class="filename">${S}/src/ls.c</code>.
1217 The second line refers to a file in
1218 <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent
1219 of <code class="filename"><a class="link" href="#var-S" title="S">S</a></code>.
1220 </p><p>
1221 Note that this variable is mandatory for all recipes, unless the
1222 <code class="filename">LICENSE</code> variable is set to "CLOSED".
1223 </p></div><div class="section" title="3.4.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div><p>
1224 As mentioned in the previous section, the
1225 <code class="filename">LIC_FILES_CHKSUM</code> variable lists all the
1226 important files that contain the license text for the source code.
1227 It is possible to specify a checksum for an entire file, or a specific section of a
1228 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1229 parameters, respectively).
1230 The latter is useful for source files with a license notice header,
1231 README documents, and so forth.
1232 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
1233 first line of the file.
1234 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
1235 ends with the last line of the file.
1236 </p><p>
1237 The "md5" parameter stores the md5 checksum of the license text.
1238 If the license text changes in any way as compared to this parameter
1239 then a mismatch occurs.
1240 This mismatch triggers a build failure and notifies the developer.
1241 Notification allows the developer to review and address the license text changes.
1242 Also note that if a mismatch occurs during the build, the correct md5
1243 checksum is placed in the build log and can be easily copied to the recipe.
1244 </p><p>
1245 There is no limit to how many files you can specify using the
1246 <code class="filename">LIC_FILES_CHKSUM</code> variable.
1247 Generally, however, every project requires a few specifications for license tracking.
1248 Many projects have a "COPYING" file that stores the license information for all the source
1249 code files.
1250 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1251 </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
1252 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1253 error and displays the correct "md5" parameter value during the build.
1254 The correct parameter is also captured in the build log.
1255 </div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
1256 If the whole file contains only license text, you do not need to use the "beginline" and
1257 "endline" parameters.
1258 </div></div></div><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div><p>
1259 By default, the OpenEmbedded build system disables
1260 components that have commercial or other special licensing
1261 requirements.
1262 Such requirements are defined on a
1263 recipe-by-recipe basis through the <code class="filename">LICENSE_FLAGS</code> variable
1264 definition in the affected recipe.
1265 For instance, the
1266 <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
1267 recipe contains the following statement:
1268 </p><pre class="literallayout">
1269 LICENSE_FLAGS = "commercial"
1270 </pre><p>
1271 Here is a slightly more complicated example that contains both an
1272 explicit recipe name and version (after variable expansion):
1273 </p><pre class="literallayout">
1274 LICENSE_FLAGS = "license_${PN}_${PV}"
1275 </pre><p>
1276 In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code>
1277 definition to be enabled and included in an image, it
1278 needs to have a matching entry in the global
1279 <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable
1280 typically defined in your <code class="filename">local.conf</code> file.
1281 For example, to enable
1282 the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
1283 package, you could add either the string
1284 "commercial_gst-plugins-ugly" or the more general string
1285 "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>.
1286 See the
1287 "<a class="link" href="#license-flag-matching" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section
1288 for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works.
1289 Here is the example:
1290 </p><pre class="literallayout">
1291 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1292 </pre><p>
1293 Likewise, to additionally enable the package built from the recipe containing
1294 <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming
1295 that the actual recipe name was <code class="filename">emgd_1.10.bb</code>,
1296 the following string would enable that package as well as
1297 the original <code class="filename">gst-plugins-ugly</code> package:
1298 </p><pre class="literallayout">
1299 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1300 </pre><p>
1301 As a convenience, you do not need to specify the complete license string
1302 in the whitelist for every package.
1303 you can use an abbreviated form, which consists
1304 of just the first portion or portions of the license string before
1305 the initial underscore character or characters.
1306 A partial string will match
1307 any license that contains the given string as the first
1308 portion of its license.
1309 For example, the following
1310 whitelist string will also match both of the packages
1311 previously mentioned as well as any other packages that have
1312 licenses starting with "commercial" or "license".
1313 </p><pre class="literallayout">
1314 LICENSE_FLAGS_WHITELIST = "commercial license"
1315 </pre><p>
1316 </p><div class="section" title="3.4.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title"><a id="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div><p>
1317 The definition of 'matching' in reference to a
1318 recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple.
1319 However, some things exist that you should know about in order to
1320 correctly and effectively use it.
1321 </p><p>
1322 Before a flag
1323 defined by a particular recipe is tested against the
1324 contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the
1325 string <code class="filename">_${PN}</code> (with
1326 <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is
1327 appended to the flag, thus automatically making each
1328 <code class="filename">LICENSE_FLAGS</code> value recipe-specific.
1329 That string is
1330 then matched against the whitelist.
1331 So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe
1332 "foo" for example, the string <code class="filename">"commercial_foo"</code>
1333 would normally be what is specified in the whitelist in order for it to
1334 match.
1335 </p><p>
1336 You can broaden the match by
1337 putting any "_"-separated beginning subset of a
1338 <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also
1339 match.
1340 For example, simply specifying "commercial" in
1341 the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code>
1342 definition starting with "commercial" such as
1343 "commercial_foo" and "commercial_bar", which are the
1344 strings that would be automatically generated for
1345 hypothetical "foo" and "bar" recipes assuming those
1346 recipes had simply specified the following:
1347 </p><pre class="literallayout">
1348 LICENSE_FLAGS = "commercial"
1349 </pre><p>
1350 </p><p>
1351 Broadening the match allows for a range of specificity for the items
1352 in the whitelist, from more general to perfectly
1353 specific.
1354 So you have the choice of exhaustively
1355 enumerating each license flag in the whitelist to
1356 allow only those specific recipes into the image, or
1357 of using a more general string to pick up anything
1358 matching just the first component or components of the specified
1359 string.
1360 </p><p>
1361 This scheme works even if the flag already
1362 has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is
1363 redundant, but does not affect the outcome.
1364 For example, a license flag of "commercial_1.2_foo" would
1365 turn into "commercial_1.2_foo_foo" and would match
1366 both the general "commercial" and the specific
1367 "commercial_1.2_foo", as expected.
1368 The flag would also match
1369 "commercial_1.2_foo_foo" and "commercial_1.2", which
1370 does not make much sense regarding use in the whitelist.
1371 </p><p>
1372 For a versioned string, you could instead specify
1373 "commercial_foo_1.2", which would turn into
1374 "commercial_foo_1.2_foo".
1375 And, as expected, this flag allows
1376 you to pick up this package along with
1377 anything else "commercial" when you specify "commercial"
1378 in the whitelist.
1379 Or, the flag allows you to pick up this package along with anything "commercial_foo"
1380 regardless of version when you use "commercial_foo" in the whitelist.
1381 Finally, you can be completely specific about the package and version and specify
1382 "commercial_foo_1.2" package and version.
1383 </p></div><div class="section" title="3.4.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title"><a id="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div><p>
1384 Other helpful variables related to commercial
1385 license handling exist and are defined in the
1386 <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file:
1387 </p><pre class="literallayout">
1388 COMMERCIAL_AUDIO_PLUGINS ?= ""
1389 COMMERCIAL_VIDEO_PLUGINS ?= ""
1390 COMMERCIAL_QT = ""
1391 </pre><p>
1392 If you want to enable these components, you can do so by making sure you have
1393 the following statements in your <code class="filename">local.conf</code> configuration file:
1394 </p><pre class="literallayout">
1395 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1396 gst-plugins-ugly-mpegaudioparse"
1397 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1398 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1399 COMMERCIAL_QT ?= "qmmp"
1400 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1401 </pre><p>
1402 Of course, you could also create a matching whitelist
1403 for those components using the more general "commercial"
1404 in the whitelist, but that would also enable all the
1405 other packages with <code class="filename">LICENSE_FLAGS</code> containing
1406 "commercial", which you may or may not want:
1407 </p><pre class="literallayout">
1408 LICENSE_FLAGS_WHITELIST = "commercial"
1409 </pre><p>
1410 </p><p>
1411 Specifying audio and video plug-ins as part of the
1412 <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and
1413 <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements
1414 or commercial qt components as part of
1415 the <code class="filename">COMMERCIAL_QT</code> statement (along
1416 with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the
1417 plug-ins or components into built images, thus adding
1418 support for media formats or components.
1419 </p></div></div></div></div>
1420
1421 <div class="chapter" title="Chapter 4. Migrating to a Newer Yocto Project Release"><div class="titlepage"><div><div><h2 class="title"><a id="migration"></a>Chapter 4. Migrating to a Newer Yocto Project Release</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#moving-to-the-yocto-project-1.3-release">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt><dd><dl><dt><span class="section"><a href="#1.3-local-configuration">4.1.1. Local Configuration</a></span></dt><dt><span class="section"><a href="#1.3-recipes">4.1.2. Recipes</a></span></dt></dl></dd></dl></div><p>
1422 This chapter provides information you can use to migrate work to a
1423 newer Yocto Project release. You can find the same information in the
1424 release notes for a given release.
1425 </p><div class="section" title="4.1. Moving to the Yocto Project 1.3 Release"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="moving-to-the-yocto-project-1.3-release"></a>4.1. Moving to the Yocto Project 1.3 Release</h2></div></div></div><p>
1426 This section provides migration information for moving to the
1427 Yocto Project 1.3 Release.
1428 </p><div class="section" title="4.1.1. Local Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="1.3-local-configuration"></a>4.1.1. Local Configuration</h3></div></div></div><p>
1429 Differences include changes for
1430 <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
1431 and <code class="filename">bblayers.conf</code>.
1432 </p><div class="section" title="4.1.1.1. SSTATE_MIRRORS"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-sstate-mirrors"></a>4.1.1.1. SSTATE_MIRRORS</h4></div></div></div><p>
1433 The shared state cache (sstate-cache) as pointed to by
1434 <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> by default
1435 now has two-character subdirectories to prevent there being an issue with too
1436 many files in the same directory.
1437 Also, native sstate-cache packages will go into a subdirectory named using
1438 the distro ID string.
1439 If you copy the newly structured sstate-cache to a mirror location
1440 (either local or remote) and then point to it in
1441 <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>,
1442 you need to append "PATH" to the end of the mirror URL so that
1443 the path used by BitBake before the mirror substitution is
1444 appended to the path used to access the mirror.
1445 Here is an example:
1446 </p><pre class="literallayout">
1447 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
1448 </pre><p>
1449 </p></div><div class="section" title="4.1.1.2. bblayers.conf"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-bblayers-conf"></a>4.1.1.2. bblayers.conf</h4></div></div></div><p>
1450 The <code class="filename">meta-yocto</code> layer has been split into
1451 two parts: <code class="filename">meta-yocto</code> and
1452 <code class="filename">meta-yocto-bsp</code>, corresponding to the
1453 Poky reference distro configuration and the reference
1454 hardware Board Support Packages (BSPs), respectively.
1455 When running BitBake or Hob for the first time after upgrading,
1456 your <code class="filename">conf/bblayers.conf</code> file will be
1457 updated to handle this change and you will be asked to
1458 re-run/restart for the changes to take effect.
1459 </p></div></div><div class="section" title="4.1.2. Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="1.3-recipes"></a>4.1.2. Recipes</h3></div></div></div><p>
1460 Differences include changes for the following:
1461 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Python function whitespace</p></li><li class="listitem"><p><code class="filename">proto=</code> in <code class="filename">SRC_URI</code></p></li><li class="listitem"><p><code class="filename">nativesdk</code></p></li><li class="listitem"><p>Task recipes</p></li><li class="listitem"><p><code class="filename">IMAGE_FEATURES</code></p></li><li class="listitem"><p>Removed recipes</p></li></ul></div><p>
1462 </p><div class="section" title="4.1.2.1. Python Function Whitespace"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-python-function-whitespace"></a>4.1.2.1. Python Function Whitespace</h4></div></div></div><p>
1463 All Python functions must now use four spaces for indentation.
1464 Previously, an inconsistent mix of spaces and tabs existed,
1465 which made extending these functions using
1466 <code class="filename">_append</code> or <code class="filename">_prepend</code>
1467 complicated given that Python treats whitespace as
1468 syntactically significant.
1469 If you are defining or extending any Python functions (e.g.
1470 <code class="filename">populate_packages</code>, <code class="filename">do_unpack</code>,
1471 <code class="filename">do_patch</code> and so forth) in custom recipes
1472 or classes, you need to ensure you are using consistent
1473 four-space indentation.
1474 </p></div><div class="section" title="4.1.2.2. proto= in SRC_URI"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-proto=-in-src-uri"></a>4.1.2.2. proto= in SRC_URI</h4></div></div></div><p>
1475 Any use of <code class="filename">proto=</code> in
1476 <a class="link" href="#var-SRC_URI" title="SRC_URI"><code class="filename">SRC_URI</code></a>
1477 needs to be changed to <code class="filename">protocol=</code>.
1478 In particular, this applies to the following URIs:
1479 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">svn://</code></p></li><li class="listitem"><p><code class="filename">bzr://</code></p></li><li class="listitem"><p><code class="filename">hg://</code></p></li><li class="listitem"><p><code class="filename">osc://</code></p></li></ul></div><p>
1480 Other URIs were already using <code class="filename">protocol=</code>.
1481 This change improves consistency.
1482 </p></div><div class="section" title="4.1.2.3. nativesdk"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-nativesdk"></a>4.1.2.3. nativesdk</h4></div></div></div><p>
1483 The suffix <code class="filename">nativesdk</code> is now implemented
1484 as a prefix, which simplifies a lot of the packaging code for
1485 <code class="filename">nativesdk</code> recipes.
1486 All custom <code class="filename">nativesdk</code> recipes and any
1487 references need to be updated to use
1488 <code class="filename">nativesdk-*</code> instead of
1489 <code class="filename">*-nativesdk</code>.
1490 </p></div><div class="section" title="4.1.2.4. Task Recipes"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-task-recipes"></a>4.1.2.4. Task Recipes</h4></div></div></div><p>
1491 "Task" recipes are now known as "Package groups" and have
1492 been renamed from <code class="filename">task-*.bb</code> to
1493 <code class="filename">packagegroup-*.bb</code>.
1494 Existing references to the previous <code class="filename">task-*</code>
1495 names should work in most cases as there is an automatic
1496 upgrade path for most packages.
1497 However, you should update references in your own recipes and
1498 configurations as they could be removed in future releases.
1499 You should also rename any custom <code class="filename">task-*</code>
1500 recipes to <code class="filename">packagegroup-*</code>, and change
1501 them to inherit <code class="filename">packagegroup</code> instead of
1502 <code class="filename">task</code>, as well as taking the opportunity
1503 to remove anything now handled by
1504 <code class="filename">packagegroup.bbclass</code>, such as providing
1505 <code class="filename">-dev</code> and <code class="filename">-dbg</code>
1506 packages, setting
1507 <a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM"><code class="filename">LIC_FILES_CHKSUM</code></a>,
1508 and so forth.
1509 See the
1510 "<a class="link" href="#ref-classes-packagegroup" title="7.12. Package Groups - packagegroup.bbclass">Package Groups - packagegroup.bbclass</a>"
1511 section for further details.
1512 </p></div><div class="section" title="4.1.2.5. IMAGE_FEATURES"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-image-features"></a>4.1.2.5. IMAGE_FEATURES</h4></div></div></div><p>
1513 Image recipes that previously included "apps-console-core"
1514 in <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES"><code class="filename">IMAGE_FEATURES</code></a>
1515 should now include "splash" instead to enable the boot-up
1516 splash screen.
1517 Retaining "apps-console-core" will still include the splash
1518 screen generates a warning.
1519 The "apps-x11-core" and "apps-x11-games"
1520 <code class="filename">IMAGE_FEATURES</code> features have been removed.
1521 </p></div><div class="section" title="4.1.2.6. Removed Recipes"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-removed-recipes"></a>4.1.2.6. Removed Recipes</h4></div></div></div><p>
1522 The following recipes have been removed.
1523 For most of them, it is unlikely that you would have any
1524 references to them in your own metadata.
1525 However, you should check your metadata against this list to be sure:
1526 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">libx11-trim</code></em></span>:
1527 Replaced by <code class="filename">libx11</code>, which has a negligible
1528 size difference with modern Xorg.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-xorg-lite</code></em></span>:
1529 Use <code class="filename">xserver-xorg</code>, which has a negligible
1530 size difference when DRI and GLX modules are not installed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-kdrive</code></em></span>:
1531 Effectively unmaintained for many years.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">mesa-xlib</code></em></span>:
1532 No longer serves any purpose.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">galago</code></em></span>:
1533 Replaced by telepathy.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gail</code></em></span>:
1534 Functionality was integrated into GTK+ 2.13.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">eggdbus</code></em></span>:
1535 No longer needed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gcc-*-intermediate</code></em></span>:
1536 The build has been restructured to avoid the need for
1537 this step.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">libgsmd</code></em></span>:
1538 Unmaintained for many years.
1539 Functionality now provided by
1540 <code class="filename">ofono</code> instead.</p></li><li class="listitem"><p><span class="emphasis"><em>contacts, dates, tasks, eds-tools</em></span>:
1541 Largely unmaintained PIM application suite.
1542 It has been moved to <code class="filename">meta-gnome</code>
1543 in <code class="filename">meta-openembedded</code>.</p></li></ul></div><p>
1544 In addition to the previously listed changes, the
1545 <code class="filename">meta-demoapps</code> directory has also been removed
1546 because the recipes in it were not being maintained and many
1547 had become obsolete or broken.
1548 Additionally, these recipes were not parsed in the default configuration.
1549 Many of these recipes are already provided in an updated and
1550 maintained form within OpenEmbedded community layers such as
1551 <code class="filename">meta-oe</code> and <code class="filename">meta-gnome</code>.
1552 For the remainder, you can now find them in the
1553 <code class="filename">meta-extras</code> repository, which is in the
1554 Yocto Project source repositories.
1555 </p></div></div></div></div>
1556
1557 <div class="chapter" title="Chapter 5. Source Directory Structure"><div class="titlepage"><div><div><h2 class="title"><a id="ref-structure"></a>Chapter 5. Source Directory Structure</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#structure-core">5.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">5.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">5.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">5.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">5.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto-bsp">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-hob">5.1.7. <code class="filename">meta-hob/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">5.1.9. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">5.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">5.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">5.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">5.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">5.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></div><p>
1558 The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> consists of several components.
1559 Understanding them and knowing where they are located is key to using the Yocto Project well.
1560 This chapter describes the Source Directory and gives information about the various
1561 files and directories.
1562</p><p>
1563 For information on how to establish a local Source Directory on your development system, see the
1564 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#getting-setup" target="_top">Getting Set Up</a>"
1565 section in the Yocto Project Development Manual.
1566</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1567 The OpenEmbedded build system does not support file or directory names that
1568 contain spaces.
1569 Be sure that the Source Directory you use does not contain these types
1570 of names.
1571</div><div class="section" title="5.1. Top level core components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-core"></a>5.1. Top level core components</h2></div></div></div><div class="section" title="5.1.1. bitbake/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-bitbake"></a>5.1.1. <code class="filename">bitbake/</code></h3></div></div></div><p>
1572 The <a class="ulink" href="source-directory" target="_top">Source Directory</a>
1573 includes a copy of BitBake for ease of use.
1574 The copy usually matches the current stable BitBake release from the BitBake project.
1575 BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks
1576 defined by that data.
1577 Failures are usually from the metadata and not from BitBake itself.
1578 Consequently, most users do not need to worry about BitBake.
1579 </p><p>
1580 When you run the <code class="filename">bitbake</code> command, the wrapper script in
1581 <code class="filename">scripts/</code> is executed to run the main BitBake executable,
1582 which resides in the <code class="filename">bitbake/bin/</code> directory.
1583 Sourcing the <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>
1584 script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code>
1585 directories (in that order) into the shell's <code class="filename">PATH</code> environment
1586 variable.
1587 </p><p>
1588 For more information on BitBake, see the BitBake documentation
1589 inculded in the <code class="filename">bitbake/doc/manual</code> directory of the
1590 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
1591 </p></div><div class="section" title="5.1.2. build/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-build"></a>5.1.2. <code class="filename">build/</code></h3></div></div></div><p>
1592 This directory contains user configuration files and the output
1593 generated by the OpenEmbedded build system in its standard configuration where
1594 the source tree is combined with the output.
1595 The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
1596 is created initially when you <code class="filename">source</code>
1597 the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>.
1598 </p><p>
1599 It is also possible to place output and configuration
1600 files in a directory separate from the
1601 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
1602 by providing a directory name when you <code class="filename">source</code>
1603 the setup script.
1604 For information on separating output from your local Source Directory files, see <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>.
1605 </p></div><div class="section" title="5.1.3. documentation"><div class="titlepage"><div><div><h3 class="title"><a id="handbook"></a>5.1.3. <code class="filename">documentation</code></h3></div></div></div><p>
1606 This directory holds the source for the Yocto Project documentation
1607 as well as templates and tools that allow you to generate PDF and HTML
1608 versions of the manuals.
1609 Each manual is contained in a sub-folder.
1610 For example, the files for this manual reside in
1611 <code class="filename">ref-manual</code>.
1612 </p></div><div class="section" title="5.1.4. meta/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta"></a>5.1.4. <code class="filename">meta/</code></h3></div></div></div><p>
1613 This directory contains the OpenEmbedded Core metadata.
1614 The directory holds recipes, common classes, and machine
1615 configuration for emulated targets (qemux86, qemuarm,
1616 and so on.)
1617 </p></div><div class="section" title="5.1.5. meta-yocto/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-yocto"></a>5.1.5. <code class="filename">meta-yocto/</code></h3></div></div></div><p>
1618 This directory contains the configuration for the Poky
1619 reference distribution.
1620 </p></div><div class="section" title="5.1.6. meta-yocto-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-yocto-bsp"></a>5.1.6. <code class="filename">meta-yocto-bsp/</code></h3></div></div></div><p>
1621 This directory contains the Yocto Project reference
1622 hardware BSPs.
1623 </p></div><div class="section" title="5.1.7. meta-hob/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-hob"></a>5.1.7. <code class="filename">meta-hob/</code></h3></div></div></div><p>
1624 This directory contains template recipes used by the
1625 <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a>
1626 build UI.
1627 </p></div><div class="section" title="5.1.8. meta-skeleton/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-skeleton"></a>5.1.8. <code class="filename">meta-skeleton/</code></h3></div></div></div><p>
1628 This directory contains template recipes for BSP and kernel development.
1629 </p></div><div class="section" title="5.1.9. scripts/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-scripts"></a>5.1.9. <code class="filename">scripts/</code></h3></div></div></div><p>
1630 This directory contains various integration scripts that implement
1631 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
1632 The <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a> script appends this
1633 directory to the shell's <code class="filename">PATH</code> environment variable.
1634 </p><p>
1635 The <code class="filename">scripts</code> directory has useful scripts that assist contributing
1636 back to the Yocto Project, such as <code class="filename">create_pull_request</code> and
1637 <code class="filename">send_pull_request</code>.
1638 </p></div><div class="section" title="5.1.10. oe-init-build-env"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-script"></a>5.1.10. <code class="filename">oe-init-build-env</code></h3></div></div></div><p>
1639 This script sets up the OpenEmbedded build environment.
1640 Running this script with the <code class="filename">source</code> command in
1641 a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the
1642 current working directory.
1643 You need to run this script before running BitBake commands.
1644 The script uses other scripts within the <code class="filename">scripts</code> directory to do
1645 the bulk of the work.
1646 </p><p>
1647 By default, running this script without a Build Directory argument creates the
1648 <code class="filename">build</code> directory.
1649 If you provide a Build Directory argument when you <code class="filename">source</code>
1650 the script, you direct OpenEmbedded build system to create a
1651 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> of your choice.
1652 For example, the following command creates a Build Directory named
1653 <code class="filename">mybuilds</code> that is outside of the
1654 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>:
1655 </p><pre class="literallayout">
1656 $ source oe-init-build-env ~/mybuilds
1657 </pre><p>
1658 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1659 The OpenEmbedded build system does not support file or directory names that
1660 contain spaces.
1661 If you attempt to run the <code class="filename">oe-init-build-env</code> script
1662 from a Source Directory that contains spaces in either the filenames
1663 or directory names, the script returns an error indicating no such
1664 file or directory.
1665 Be sure to use a Source Directory free of names containing spaces.
1666 </div><p>
1667 </p></div><div class="section" title="5.1.11. LICENSE, README, and README.hardware"><div class="titlepage"><div><div><h3 class="title"><a id="structure-basic-top-level"></a>5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></h3></div></div></div><p>
1668 These files are standard top-level files.
1669 </p></div></div><div class="section" title="5.2. The Build Directory - build/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-build"></a>5.2. The Build Directory - <code class="filename">build/</code></h2></div></div></div><div class="section" title="5.2.1. build/pseudodone"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-pseudodone"></a>5.2.1. <code class="filename">build/pseudodone</code></h3></div></div></div><p>
1670 This tag file indicates that the initial pseudo binary was created.
1671 The file is built the first time BitBake is invoked.
1672 </p></div><div class="section" title="5.2.2. build/conf/local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-local.conf"></a>5.2.2. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p>
1673 This file contains all the local user configuration for your build environment.
1674 If there is no <code class="filename">local.conf</code> present, it is created from
1675 <code class="filename">local.conf.sample</code>.
1676 The <code class="filename">local.conf</code> file contains documentation on the various configuration options.
1677 Any variable set here overrides any variable set elsewhere within the environment unless
1678 that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
1679 Some variables are hard-coded for various reasons but these variables are
1680 relatively rare.
1681 </p><p>
1682 Edit this file to set the <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code>
1683 for which you want to build, which package types you wish to use
1684 (<a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES"><code class="filename">PACKAGE_CLASSES</code></a>),
1685 where you want to downloaded files
1686 (<code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>),
1687 and how you want your host machine to use resources
1688 (<a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS"><code class="filename">BB_NUMBER_THREADS</code></a> and
1689 <a class="link" href="#var-PARALLEL_MAKE" title="PARALLEL_MAKE"><code class="filename">PARALLEL_MAKE</code></a>).
1690 </p></div><div class="section" title="5.2.3. build/conf/bblayers.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-bblayers.conf"></a>5.2.3. <code class="filename">build/conf/bblayers.conf</code></h3></div></div></div><p>
1691 This file defines layers, which are directory trees, traversed (or walked) by BitBake.
1692 If <code class="filename">bblayers.conf</code>
1693 is not present, it is created from <code class="filename">bblayers.conf.sample</code> when
1694 you <code class="filename">source</code> the environment setup script.
1695 </p><p>
1696 The <code class="filename">bblayers.conf</code> file uses the
1697 <a class="link" href="#var-BBLAYERS" title="BBLAYERS"><code class="filename">BBLAYERS</code></a> variable to
1698 list the layers BitBake tries to find.
1699 The file uses the
1700 <a class="link" href="#var-BBLAYERS_NON_REMOVABLE" title="BBLAYERS_NON_REMOVABLE"><code class="filename">BBLAYERS_NON_REMOVABLE</code></a>
1701 variable to list layers that must not be removed.
1702 </p></div><div class="section" title="5.2.4. build/conf/sanity_info"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-sanity_info"></a>5.2.4. <code class="filename">build/conf/sanity_info</code></h3></div></div></div><p>
1703 This file is created during the build to indicate the state of the sanity checks.
1704 </p></div><div class="section" title="5.2.5. build/downloads/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-downloads"></a>5.2.5. <code class="filename">build/downloads/</code></h3></div></div></div><p>
1705 This directory is used for the upstream source tarballs.
1706 The directory can be reused by multiple builds or moved to another location.
1707 You can control the location of this directory through the
1708 <code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable.
1709 </p></div><div class="section" title="5.2.6. build/sstate-cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-sstate-cache"></a>5.2.6. <code class="filename">build/sstate-cache/</code></h3></div></div></div><p>
1710 This directory is used for the shared state cache.
1711 The directory can be reused by multiple builds or moved to another location.
1712 You can control the location of this directory through the
1713 <code class="filename"><a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable.
1714 </p></div><div class="section" title="5.2.7. build/tmp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp"></a>5.2.7. <code class="filename">build/tmp/</code></h3></div></div></div><p>
1715 This directory receives all the OpenEmbedded build system's output.
1716 BitBake creates this directory if it does not exist.
1717 As a last resort, to clean up a build and start it from scratch (other than the downloads),
1718 you can remove everything in the <code class="filename">tmp</code> directory or get rid of the
1719 directory completely.
1720 If you do, you should also completely remove the <code class="filename">build/sstate-cache</code>
1721 directory as well.
1722 </p></div><div class="section" title="5.2.8. build/tmp/buildstats/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-buildstats"></a>5.2.8. <code class="filename">build/tmp/buildstats/</code></h3></div></div></div><p>
1723 This directory stores the build statistics.
1724 </p></div><div class="section" title="5.2.9. build/tmp/cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-cache"></a>5.2.9. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p>
1725 When BitBake parses the metadata, it creates a cache file of the result that can
1726 be used when subsequently running commands.
1727 These results are stored here on a per-machine basis.
1728 </p></div><div class="section" title="5.2.10. build/tmp/deploy/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy"></a>5.2.10. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p>
1729 This directory contains any 'end result' output from the OpenEmbedded build process.
1730 </p></div><div class="section" title="5.2.11. build/tmp/deploy/deb/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-deb"></a>5.2.11. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p>
1731 This directory receives any <code class="filename">.deb</code> packages produced by
1732 the build process.
1733 The packages are sorted into feeds for different architecture types.
1734 </p></div><div class="section" title="5.2.12. build/tmp/deploy/rpm/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-rpm"></a>5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></h3></div></div></div><p>
1735 This directory receives any <code class="filename">.rpm</code> packages produced by
1736 the build process.
1737 The packages are sorted into feeds for different architecture types.
1738 </p></div><div class="section" title="5.2.13. build/tmp/deploy/licenses/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-licenses"></a>5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></h3></div></div></div><p>
1739 This directory receives package licensing information.
1740 For example, the directory contains sub-directories for <code class="filename">bash</code>,
1741 <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn
1742 contain appropriate <code class="filename">COPYING</code> license files with other licensing information.
1743 </p></div><div class="section" title="5.2.14. build/tmp/deploy/images/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-images"></a>5.2.14. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p>
1744 This directory receives complete filesystem images.
1745 If you want to flash the resulting image from a build onto a device, look here for the image.
1746 </p><p>
1747 Be careful when deleting files in this directory.
1748 You can safely delete old images from this directory (e.g.
1749 <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>,
1750 etc.).
1751 However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.),
1752 bootloader and other supplementary files might be deployed here prior to building an
1753 image.
1754 Because these files, however, are not directly produced from the image, if you
1755 delete them they will not be automatically re-created when you build the image again.
1756 </p><p>
1757 If you do accidentally delete files here, you will need to force them to be
1758 re-created.
1759 In order to do that, you will need to know the target that produced them.
1760 For example, these commands rebuild and re-create the kernel files:
1761 </p><pre class="literallayout">
1762 $ bitbake -c clean virtual/kernel
1763 $ bitbake virtual/kernel
1764 </pre><p>
1765 </p></div><div class="section" title="5.2.15. build/tmp/deploy/ipk/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-ipk"></a>5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p>
1766 This directory receives <code class="filename">.ipk</code> packages produced by
1767 the build process.</p></div><div class="section" title="5.2.16. build/tmp/sysroots/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-sysroots"></a>5.2.16. <code class="filename">build/tmp/sysroots/</code></h3></div></div></div><p>
1768 This directory contains shared header files and libraries as well as other shared
1769 data.
1770 Packages that need to share output with other packages do so within this directory.
1771 The directory is subdivided by architecture so multiple builds can run within
1772 the one Build Directory.
1773 </p></div><div class="section" title="5.2.17. build/tmp/stamps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-stamps"></a>5.2.17. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p>
1774 This directory holds information that BitBake uses for accounting purposes
1775 to track what tasks have run and when they have run.
1776 The directory is sub-divided by architecture, package name, and
1777 version.
1778 Following is an example:
1779 </p><pre class="literallayout">
1780 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
1781 </pre><p>
1782 Although the files in the directory are empty of data,
1783 BitBake uses the filenames and timestamps for tracking purposes.
1784 </p></div><div class="section" title="5.2.18. build/tmp/log/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-log"></a>5.2.18. <code class="filename">build/tmp/log/</code></h3></div></div></div><p>
1785 This directory contains general logs that are not otherwise placed using the
1786 package's <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>.
1787 Examples of logs are the output from the <code class="filename">check_pkg</code> or
1788 <code class="filename">distro_check</code> tasks.
1789 Running a build does not necessarily mean this directory is created.
1790 </p></div><div class="section" title="5.2.19. build/tmp/pkgdata/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-pkgdata"></a>5.2.19. <code class="filename">build/tmp/pkgdata/</code></h3></div></div></div><p>
1791 This directory contains intermediate packaging data that is used later in the packaging process.
1792 For more information, see the "<a class="link" href="#ref-classes-package" title="7.13. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section.
1793 </p></div><div class="section" title="5.2.20. build/tmp/work/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-work"></a>5.2.20. <code class="filename">build/tmp/work/</code></h3></div></div></div><p>
1794 This directory contains architecture-specific work sub-directories
1795 for packages built by BitBake.
1796 All tasks execute from the appropriate work directory.
1797 For example, the source for a particular package is unpacked,
1798 patched, configured and compiled all within its own work directory.
1799 Within the work directory, organization is based on the package group
1800 and version for which the source is being compiled
1801 as defined by the
1802 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
1803 </p><p>
1804 It is worth considering the structure of a typical work directory.
1805 As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code>
1806 on the machine <code class="filename">qemux86</code>
1807 built within the Yocto Project.
1808 For this package, a work directory of
1809 <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</code>,
1810 referred to as the
1811 <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created.
1812 Within this directory, the source is unpacked to
1813 <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt
1814 (see the
1815 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#using-a-quilt-workflow" target="_top">Modifying Package
1816 Source Code with Quilt</a>" section in the Yocto Project Development Manual.
1817 Within the <code class="filename">linux-qemux86-standard-build</code> directory,
1818 standard Quilt directories <code class="filename">linux-3.0/patches</code>
1819 and <code class="filename">linux-3.0/.pc</code> are created,
1820 and standard Quilt commands can be used.
1821 </p><p>
1822 There are other directories generated within <code class="filename">WORKDIR</code>.
1823 The most important directory is <code class="filename">WORKDIR/temp/</code>,
1824 which has log files for each task (<code class="filename">log.do_*.pid</code>)
1825 and contains the scripts BitBake runs for each task
1826 (<code class="filename">run.do_*.pid</code>).
1827 The <code class="filename">WORKDIR/image/</code> directory is where "make
1828 install" places its output that is then split into sub-packages
1829 within <code class="filename">WORKDIR/packages-split/</code>.
1830 </p></div></div><div class="section" title="5.3. The Metadata - meta/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-meta"></a>5.3. The Metadata - <code class="filename">meta/</code></h2></div></div></div><p>
1831 As mentioned previously, metadata is the core of the Yocto Project.
1832 Metadata has several important subdivisions:
1833 </p><div class="section" title="5.3.1. meta/classes/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-classes"></a>5.3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p>
1834 This directory contains the <code class="filename">*.bbclass</code> files.
1835 Class files are used to abstract common code so it can be reused by multiple
1836 packages.
1837 Every package inherits the <code class="filename">base.bbclass</code> file.
1838 Examples of other important classes are <code class="filename">autotools.bbclass</code>, which
1839 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
1840 Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions
1841 for working with the Linux kernel.
1842 Functions like image generation or packaging also have their specific class files
1843 such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and
1844 <code class="filename">package*.bbclass</code>.
1845 </p></div><div class="section" title="5.3.2. meta/conf/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf"></a>5.3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p>
1846 This directory contains the core set of configuration files that start from
1847 <code class="filename">bitbake.conf</code> and from which all other configuration
1848 files are included.
1849 See the include statements at the end of the file and you will note that even
1850 <code class="filename">local.conf</code> is loaded from there.
1851 While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override
1852 these by using the (<code class="filename">local.conf</code>) file, machine file or
1853 the distribution configuration file.
1854 </p></div><div class="section" title="5.3.3. meta/conf/machine/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-machine"></a>5.3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p>
1855 This directory contains all the machine configuration files.
1856 If you set <code class="filename">MACHINE="qemux86"</code>,
1857 the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this
1858 directory.
1859 The <code class="filename">include</code> directory contains various data common to multiple machines.
1860 If you want to add support for a new machine to the Yocto Project, look in this directory.
1861 </p></div><div class="section" title="5.3.4. meta/conf/distro/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-distro"></a>5.3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p>
1862 Any distribution-specific configuration is controlled from this directory.
1863 For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here.
1864 This directory includes the versions and the
1865 <code class="filename">SRCDATE</code> definitions for applications that are configured here.
1866 An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>.
1867 Although this file mainly inherits its configuration from Poky.
1868 </p></div><div class="section" title="5.3.5. meta/recipes-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-bsp"></a>5.3.5. <code class="filename">meta/recipes-bsp/</code></h3></div></div></div><p>
1869 This directory contains anything linking to specific hardware or hardware
1870 configuration information such as "u-boot" and "grub".
1871 </p></div><div class="section" title="5.3.6. meta/recipes-connectivity/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-connectivity"></a>5.3.6. <code class="filename">meta/recipes-connectivity/</code></h3></div></div></div><p>
1872 This directory contains libraries and applications related to communication with other devices.
1873 </p></div><div class="section" title="5.3.7. meta/recipes-core/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-core"></a>5.3.7. <code class="filename">meta/recipes-core/</code></h3></div></div></div><p>
1874 This directory contains what is needed to build a basic working Linux image
1875 including commonly used dependencies.
1876 </p></div><div class="section" title="5.3.8. meta/recipes-devtools/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-devtools"></a>5.3.8. <code class="filename">meta/recipes-devtools/</code></h3></div></div></div><p>
1877 This directory contains tools that are primarily used by the build system.
1878 The tools, however, can also be used on targets.
1879 </p></div><div class="section" title="5.3.9. meta/recipes-extended/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-extended"></a>5.3.9. <code class="filename">meta/recipes-extended/</code></h3></div></div></div><p>
1880 This directory contains non-essential applications that add features compared to the
1881 alternatives in core.
1882 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
1883 compliance.
1884 </p></div><div class="section" title="5.3.10. meta/recipes-gnome/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-gnome"></a>5.3.10. <code class="filename">meta/recipes-gnome/</code></h3></div></div></div><p>
1885 This directory contains all things related to the GTK+ application framework.
1886 </p></div><div class="section" title="5.3.11. meta/recipes-graphics/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-graphics"></a>5.3.11. <code class="filename">meta/recipes-graphics/</code></h3></div></div></div><p>
1887 This directory contains X and other graphically related system libraries
1888 </p></div><div class="section" title="5.3.12. meta/recipes-kernel/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-kernel"></a>5.3.12. <code class="filename">meta/recipes-kernel/</code></h3></div></div></div><p>
1889 This directory contains the kernel and generic applications and libraries that
1890 have strong kernel dependencies.
1891 </p></div><div class="section" title="5.3.13. meta/recipes-multimedia/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-multimedia"></a>5.3.13. <code class="filename">meta/recipes-multimedia/</code></h3></div></div></div><p>
1892 This directory contains codecs and support utilities for audio, images and video.
1893 </p></div><div class="section" title="5.3.14. meta/recipes-qt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-qt"></a>5.3.14. <code class="filename">meta/recipes-qt/</code></h3></div></div></div><p>
1894 This directory contains all things related to the Qt application framework.
1895 </p></div><div class="section" title="5.3.15. meta/recipes-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-rt"></a>5.3.15. <code class="filename">meta/recipes-rt/</code></h3></div></div></div><p>
1896 This directory contains package and image recipes for using and testing
1897 the <code class="filename">PREEMPT_RT</code> kernel.
1898 </p></div><div class="section" title="5.3.16. meta/recipes-sato/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-sato"></a>5.3.16. <code class="filename">meta/recipes-sato/</code></h3></div></div></div><p>
1899 This directory contains the Sato demo/reference UI/UX and its associated applications
1900 and configuration data.
1901 </p></div><div class="section" title="5.3.17. meta/recipes-support/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-support"></a>5.3.17. <code class="filename">meta/recipes-support/</code></h3></div></div></div><p>
1902 This directory contains recipes that used by other recipes, but that are not directly
1903 included in images (i.e. dependencies of other recipes).
1904 </p></div><div class="section" title="5.3.18. meta/site/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-site"></a>5.3.18. <code class="filename">meta/site/</code></h3></div></div></div><p>
1905 This directory contains a list of cached results for various architectures.
1906 Because certain "autoconf" test results cannot be determined when cross-compiling due to
1907 the tests not able to run on a live system, the information in this directory is
1908 passed to "autoconf" for the various architectures.
1909 </p></div><div class="section" title="5.3.19. meta/recipes.txt"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-txt"></a>5.3.19. <code class="filename">meta/recipes.txt</code></h3></div></div></div><p>
1910 This file is a description of the contents of <code class="filename">recipes-*</code>.
1911 </p></div></div></div>
1912
1913 <div class="chapter" title="Chapter 6. BitBake"><div class="titlepage"><div><div><h2 class="title"><a id="ref-bitbake"></a>Chapter 6. BitBake</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-bitbake-parsing">6.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">6.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">6.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">6.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">6.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">6.7. Fetchers</a></span></dt></dl></div><p>
1914 BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded
1915 build system.
1916 At some point, developers wonder what actually happens when you enter:
1917 </p><pre class="literallayout">
1918 $ bitbake core-image-sato
1919 </pre><p>
1920 </p><p>
1921 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
1922 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1923 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
1924 As such, it has no real knowledge of what the tasks being executed actually do.
1925 BitBake just considers a list of tasks with dependencies and handles metadata
1926 that consists of variables in a certain format that get passed to the tasks.
1927 </div><div class="section" title="6.1. Parsing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-parsing"></a>6.1. Parsing</h2></div></div></div><p>
1928 BitBake parses configuration files, classes, and <code class="filename">.bb</code> files.
1929 </p><p>
1930 The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file.
1931 This file resides in the
1932 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
1933 within the <code class="filename">meta/conf/</code> directory.
1934 BitBake finds it by examining its
1935 <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment
1936 variable and looking for the <code class="filename">meta/conf/</code>
1937 directory.
1938 </p><p>
1939 The <code class="filename">bitbake.conf</code> file lists other configuration
1940 files to include from a <code class="filename">conf/</code>
1941 directory below the directories listed in <code class="filename">BBPATH</code>.
1942 In general, the most important configuration file from a user's perspective
1943 is <code class="filename">local.conf</code>, which contains a user's customized
1944 settings for the OpenEmbedded build environment.
1945 Other notable configuration files are the distribution
1946 configuration file (set by the
1947 <code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> variable)
1948 and the machine configuration file
1949 (set by the
1950 <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> variable).
1951 The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment
1952 variables are both usually set in
1953 the <code class="filename">local.conf</code> file.
1954 Valid distribution
1955 configuration files are available in the <code class="filename">meta/conf/distro/</code> directory
1956 and valid machine configuration
1957 files in the <code class="filename">meta/conf/machine/</code> directory.
1958 Within the <code class="filename">meta/conf/machine/include/</code>
1959 directory are various <code class="filename">tune-*.inc</code> configuration files that provide common
1960 "tuning" settings specific to and shared between particular architectures and machines.
1961 </p><p>
1962 After the parsing of the configuration files, some standard classes are included.
1963 The <code class="filename">base.bbclass</code> file is always included.
1964 Other classes that are specified in the configuration using the
1965 <code class="filename"><a class="link" href="#var-INHERIT" title="INHERIT">INHERIT</a></code>
1966 variable are also included.
1967 Class files are searched for in a <code class="filename">classes</code> subdirectory
1968 under the paths in <code class="filename">BBPATH</code> in the same way as
1969 configuration files.
1970 </p><p>
1971 After classes are included, the variable
1972 <code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code>
1973 is set, usually in
1974 <code class="filename">local.conf</code>, and defines the list of places to search for
1975 <code class="filename">.bb</code> files.
1976 By default, the <code class="filename">BBFILES</code> variable specifies the
1977 <code class="filename">meta/recipes-*/</code> directory within Poky.
1978 Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of
1979 BitBake layers as described in the
1980 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and
1981 Creating Layers</a>" section of the Yocto Project Development Manual.
1982 </p><p>
1983 BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and
1984 stores the values of various variables.
1985 In summary, for each <code class="filename">.bb</code>
1986 file the configuration plus the base class of variables are set, followed
1987 by the data in the <code class="filename">.bb</code> file
1988 itself, followed by any inherit commands that
1989 <code class="filename">.bb</code> file might contain.
1990 </p><p>
1991 Because parsing <code class="filename">.bb</code> files is a time
1992 consuming process, a cache is kept to speed up subsequent parsing.
1993 This cache is invalid if the timestamp of the <code class="filename">.bb</code>
1994 file itself changes, or if the timestamps of any of the include,
1995 configuration or class files the <code class="filename">.bb</code>
1996 file depends on changes.
1997 </p></div><div class="section" title="6.2. Preferences and Providers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-providers"></a>6.2. Preferences and Providers</h2></div></div></div><p>
1998 Once all the <code class="filename">.bb</code> files have been
1999 parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code>
2000 in the previous section's example) and looks for providers of that target.
2001 Once a provider is selected, BitBake resolves all the dependencies for
2002 the target.
2003 In the case of <code class="filename">core-image-sato</code>, it would lead to
2004 <code class="filename">packagegroup-core-x11-sato</code>,
2005 which in turn leads to recipes like <code class="filename">matchbox-terminal</code>,
2006 <code class="filename">pcmanfm</code> and <code class="filename">gthumb</code>.
2007 These recipes in turn depend on <code class="filename">eglibc</code> and the toolchain.
2008 </p><p>
2009 Sometimes a target might have multiple providers.
2010 A common example is "virtual/kernel", which is provided by each kernel package.
2011 Each machine often selects the best kernel provider by using a line similar to the
2012 following in the machine configuration file:
2013 </p><pre class="literallayout">
2014 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
2015 </pre><p>
2016 The default <code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code>
2017 is the provider with the same name as the target.
2018 </p><p>
2019 Understanding how providers are chosen is made complicated by the fact
2020 that multiple versions might exist.
2021 BitBake defaults to the highest version of a provider.
2022 Version comparisons are made using the same method as Debian.
2023 You can use the
2024 <code class="filename"><a class="link" href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code>
2025 variable to specify a particular version (usually in the distro configuration).
2026 You can influence the order by using the
2027 <code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code>
2028 variable.
2029 By default, files have a preference of "0".
2030 Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the
2031 package unlikely to be used unless it is explicitly referenced.
2032 Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used.
2033 <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting.
2034 <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package
2035 versions until they have undergone sufficient testing to be considered stable.
2036 </p><p>
2037 In summary, BitBake has created a list of providers, which is prioritized, for each target.
2038 </p></div><div class="section" title="6.3. Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-dependencies"></a>6.3. Dependencies</h2></div></div></div><p>
2039 Each target BitBake builds consists of multiple tasks such as
2040 <code class="filename">fetch</code>, <code class="filename">unpack</code>,
2041 <code class="filename">patch</code>, <code class="filename">configure</code>,
2042 and <code class="filename">compile</code>.
2043 For best performance on multi-core systems, BitBake considers each task as an independent
2044 entity with its own set of dependencies.
2045 </p><p>
2046 Dependencies are defined through several variables.
2047 You can find information about variables BitBake uses in the BitBake documentation,
2048 which is found in the <code class="filename">bitbake/doc/manual</code> directory within the
2049 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2050 At a basic level, it is sufficient to know that BitBake uses the
2051 <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and
2052 <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when
2053 calculating dependencies.
2054 </p></div><div class="section" title="6.4. The Task List"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-tasklist"></a>6.4. The Task List</h2></div></div></div><p>
2055 Based on the generated list of providers and the dependency information,
2056 BitBake can now calculate exactly what tasks it needs to run and in what
2057 order it needs to run them.
2058 The build now starts with BitBake forking off threads up to the limit set in the
2059 <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></code> variable.
2060 BitBake continues to fork threads as long as there are tasks ready to run,
2061 those tasks have all their dependencies met, and the thread threshold has not been
2062 exceeded.
2063 </p><p>
2064 It is worth noting that you can greatly speed up the build time by properly setting
2065 the <code class="filename">BB_NUMBER_THREADS</code> variable.
2066 See the
2067 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#building-image" target="_top">Building an Image</a>"
2068 section in the Yocto Project Quick Start for more information.
2069 </p><p>
2070 As each task completes, a timestamp is written to the directory specified by the
2071 <code class="filename"><a class="link" href="#var-STAMP" title="STAMP">STAMP</a></code> variable.
2072 On subsequent runs, BitBake looks within the <code class="filename">/build/tmp/stamps</code>
2073 directory and does not rerun
2074 tasks that are already completed unless a timestamp is found to be invalid.
2075 Currently, invalid timestamps are only considered on a per
2076 <code class="filename">.bb</code> file basis.
2077 So, for example, if the configure stamp has a timestamp greater than the
2078 compile timestamp for a given target, then the compile task would rerun.
2079 Running the compile task again, however, has no effect on other providers
2080 that depend on that target.
2081 This behavior could change or become configurable in future versions of BitBake.
2082 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2083 Some tasks are marked as "nostamp" tasks.
2084 No timestamp file is created when these tasks are run.
2085 Consequently, "nostamp" tasks are always rerun.
2086 </div></div><div class="section" title="6.5. Running a Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-runtask"></a>6.5. Running a Task</h2></div></div></div><p>
2087 Tasks can either be a shell task or a Python task.
2088 For shell tasks, BitBake writes a shell script to
2089 <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> and then executes the script.
2090 The generated shell script contains all the exported variables, and the shell functions
2091 with all variables expanded.
2092 Output from the shell script goes to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
2093 Looking at the expanded shell functions in the run file and the output in the log files
2094 is a useful debugging technique.
2095 </p><p>
2096 For Python tasks, BitBake executes the task internally and logs information to the
2097 controlling terminal.
2098 Future versions of BitBake will write the functions to files similar to the way
2099 shell tasks are handled.
2100 Logging will be handled in way similar to shell tasks as well.
2101 </p><p>
2102 Once all the tasks have been completed BitBake exits.
2103 </p><p>
2104 When running a task, BitBake tightly controls the execution environment
2105 of the build tasks to make sure unwanted contamination from the build machine
2106 cannot influence the build.
2107 Consequently, if you do want something to get passed into the build
2108 task's environment, you must take a few steps:
2109 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Tell BitBake to load what you want from the environment
2110 into the data store.
2111 You can do so through the <code class="filename">BB_ENV_EXTRAWHITE</code>
2112 variable.
2113 For example, assume you want to prevent the build system from
2114 accessing your <code class="filename">$HOME/.ccache</code> directory.
2115 The following command tells BitBake to load
2116 <code class="filename">CCACHE_DIR</code> from the environment into the data
2117 store:
2118 </p><pre class="literallayout">
2119 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
2120 </pre></li><li class="listitem"><p>Tell BitBake to export what you have loaded into the
2121 environment store to the task environment of every running task.
2122 Loading something from the environment into the data store
2123 (previous step) only makes it available in the datastore.
2124 To export it to the task environment of every running task,
2125 use a command similar to the following in your
2126 <code class="filename">local.conf</code> or distro configuration file:
2127 </p><pre class="literallayout">
2128 export CCACHE_DIR
2129 </pre></li></ol></div><p>
2130 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2131 A side effect of the previous steps is that BitBake records the variable
2132 as a dependency of the build process in things like the shared state
2133 checksums.
2134 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
2135 variable so that the shared state code ignores the dependency when it creates
2136 checksums.
2137 For information on this process, see the <code class="filename">BB_HASHBASE_WHITELIST</code>
2138 example in the "<a class="link" href="#checksums" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section.
2139 </div></div><div class="section" title="6.6. BitBake Command Line"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-commandline"></a>6.6. BitBake Command Line</h2></div></div></div><p>
2140 Following is the BitBake help output:
2141 </p><pre class="screen">
2142$ bitbake --help
2143Usage: bitbake [options] [package ...]
2144
2145Executes the specified task (default is 'build') for a given set of BitBake files.
2146It expects that BBFILES is defined, which is a space separated list of files to
2147be executed. BBFILES does support wildcards.
2148Default BBFILES are the .bb files in the current directory.
2149
2150Options:
2151 --version show program's version number and exit
2152 -h, --help show this help message and exit
2153 -b BUILDFILE, --buildfile=BUILDFILE
2154 execute the task against this .bb file, rather than a
2155 package from BBFILES. Does not handle any
2156 dependencies.
2157 -k, --continue continue as much as possible after an error. While the
2158 target that failed, and those that depend on it,
2159 cannot be remade, the other dependencies of these
2160 targets can be processed all the same.
2161 -a, --tryaltconfigs continue with builds by trying to use alternative
2162 providers where possible.
2163 -f, --force force run of specified cmd, regardless of stamp status
2164 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
2165 the specified task for the providee and the packages
2166 it depends on, i.e. 'compile' does not implicitly call
2167 stage for the dependencies (IOW: use only if you know
2168 what you are doing). Depending on the base.bbclass a
2169 listtasks tasks is defined and will show available
2170 tasks
2171 -r PREFILE, --read=PREFILE
2172 read the specified file before bitbake.conf
2173 -R POSTFILE, --postread=POSTFILE
2174 read the specified file after bitbake.conf
2175 -v, --verbose output more chit-chat to the terminal
2176 -D, --debug Increase the debug level. You can specify this more
2177 than once.
2178 -n, --dry-run don't execute, just go through the motions
2179 -S, --dump-signatures
2180 don't execute, just dump out the signature
2181 construction information
2182 -p, --parse-only quit after parsing the BB files (developers only)
2183 -s, --show-versions show current and preferred versions of all packages
2184 -e, --environment show the global or per-package environment (this is
2185 what used to be bbread)
2186 -g, --graphviz emit the dependency trees of the specified packages in
2187 the dot syntax
2188 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
2189 Assume these dependencies don't exist and are already
2190 provided (equivalent to ASSUME_PROVIDED). Useful to
2191 make dependency graphs more appealing
2192 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
2193 Show debug logging for the specified logging domains
2194 -P, --profile profile the command and print a report
2195 -u UI, --ui=UI userinterface to use
2196 -t SERVERTYPE, --servertype=SERVERTYPE
2197 Choose which server to use, none, process or xmlrpc
2198 --revisions-changed Set the exit code depending on whether upstream
2199 floating revisions have changed or not
2200 </pre></div><div class="section" title="6.7. Fetchers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-fetchers"></a>6.7. Fetchers</h2></div></div></div><p>
2201 BitBake also contains a set of "fetcher" modules that allow
2202 retrieval of source code from various types of sources.
2203 For example, BitBake can get source code from a disk with the metadata, from websites,
2204 from remote shell accounts or from Source Code Management (SCM) systems
2205 like <code class="filename">cvs/subversion/git</code>.
2206 </p><p>
2207 Fetchers are usually triggered by entries in
2208 <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>.
2209 You can find information about the options and formats of entries for specific
2210 fetchers in the BitBake manual located in the
2211 <code class="filename">bitbake/doc/manual</code> directory of the
2212 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2213 </p><p>
2214 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
2215 "auto-update" when the upstream SCM changes version.
2216 Since this ability requires certain functionality from the SCM, not all
2217 systems support it.
2218 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
2219 This feature works using the <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code>
2220 variable.
2221 See the
2222 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-srcrev" target="_top">Using an External SCM</a>" section
2223 in the Yocto Project Development Manual for more information.
2224 </p></div></div>
2225
2226 <div class="chapter" title="Chapter 7. Classes"><div class="titlepage"><div><div><h2 class="title"><a id="ref-classes"></a>Chapter 7. Classes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-classes-base">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-packagegroup">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">7.21. Other Classes</a></span></dt></dl></div><p>
2227 Class files are used to abstract common functionality and share it amongst multiple
2228 <code class="filename">.bb</code> files.
2229 Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class
2230 file.
2231 Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed
2232 in a <code class="filename">classes/</code> directory beneath the
2233 <code class="filename">meta*/</code> directory found in the
2234 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2235 Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as
2236 <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory.
2237 Class files are searched for in <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a>
2238 using the same method by which <code class="filename">.conf</code> files are searched.
2239</p><p>
2240 In most cases inheriting the class is enough to enable its features, although
2241 for some classes you might need to set variables or override some of the
2242 default behaviour.
2243</p><div class="section" title="7.1. The base class - base.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-base"></a>7.1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p>
2244 The base class is special in that every <code class="filename">.bb</code>
2245 file inherits it automatically.
2246 This class contains definitions for standard basic
2247 tasks such as fetching, unpacking, configuring (empty by default), compiling
2248 (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging
2249 (empty by default).
2250 These classes are often overridden or extended by other classes
2251 such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>.
2252 The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>.
2253 </p></div><div class="section" title="7.2. Autotooled Packages - autotools.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-autotools"></a>7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p>
2254 Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>,
2255 and <code class="filename">libtool</code>) bring standardization.
2256 This class defines a set of tasks (configure, compile etc.) that
2257 work for all Autotooled packages.
2258 It should usually be enough to define a few standard variables
2259 and then simply <code class="filename">inherit autotools</code>.
2260 This class can also work with software that emulates Autotools.
2261 For more information, see the
2262 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-addpkg-autotools" target="_top">Autotooled Package</a>"
2263 section in the Yocto Project Development Manual.
2264 </p><p>
2265 It's useful to have some idea of how the tasks defined by this class work
2266 and what they do behind the scenes.
2267 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">do_configure</code> ‐ regenerates the
2268 configure script (using <code class="filename">autoreconf</code>) and then launches it
2269 with a standard set of arguments used during cross-compilation.
2270 You can pass additional parameters to <code class="filename">configure</code> through the
2271 <code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable.
2272 </p></li><li class="listitem"><p><code class="filename">do_compile</code> ‐ runs <code class="filename">make</code> with
2273 arguments that specify the compiler and linker.
2274 You can pass additional arguments through
2275 the <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable.
2276 </p></li><li class="listitem"><p><code class="filename">do_install</code> ‐ runs <code class="filename">make install</code>
2277 and passes a DESTDIR option, which takes its value from the standard
2278 <code class="filename"><a class="link" href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable.
2279 </p></li></ul></div><p>
2280 </p></div><div class="section" title="7.3. Alternatives - update-alternatives.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-alternatives"></a>7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p>
2281 Several programs can fulfill the same or similar function and be installed with the same name.
2282 For example, the <code class="filename">ar</code> command is available from the
2283 <code class="filename">busybox</code>, <code class="filename">binutils</code> and
2284 <code class="filename">elfutils</code> packages.
2285 The <code class="filename">update-alternatives.bbclass</code> class handles renaming the
2286 binaries so that multiple packages can be installed without conflicts.
2287 The <code class="filename">ar</code> command still works regardless of which packages are installed
2288 or subsequently removed.
2289 The class renames the conflicting binary in each package and symlinks the highest
2290 priority binary during installation or removal of packages.
2291 </p><p>
2292 Four variables control this class:
2293 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> ‐ The name of the
2294 binary that is replaced (<code class="filename">ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> ‐ The path to
2295 the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> ‐ The path to the
2296 real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> ‐ The priority of
2297 the binary.
2298 The version with the most features should have the highest priority.</p></li></ul></div><p>
2299 </p><p>
2300 Currently, the OpenEmbedded build system supports only one binary per package.
2301 </p></div><div class="section" title="7.4. Initscripts - update-rc.d.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-rc.d"></a>7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p>
2302 This class uses <code class="filename">update-rc.d</code> to safely install an
2303 initialization script on behalf of the package.
2304 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
2305 a package is removed and started when the package is installed.
2306 Three variables control this class:
2307 <code class="filename"><a class="link" href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>,
2308 <code class="filename"><a class="link" href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and
2309 <code class="filename"><a class="link" href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>.
2310 See the variable links for details.
2311 </p></div><div class="section" title="7.5. Binary config scripts - binconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-binconfig"></a>7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p>
2312 Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell
2313 scripts to give information about the libraries and include paths needed
2314 to build software (usually named <code class="filename">LIBNAME-config</code>).
2315 This class assists any recipe using such scripts.
2316 </p><p>
2317 During staging, BitBake installs such scripts into the
2318 <code class="filename">sysroots/</code> directory.
2319 BitBake also changes all paths to point into the <code class="filename">sysroots/</code>
2320 directory so all builds that use the script will use the correct
2321 directories for the cross compiling layout.
2322 </p></div><div class="section" title="7.6. Debian renaming - debian.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-debian"></a>7.6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p>
2323 This class renames packages so that they follow the Debian naming
2324 policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code>
2325 and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>.
2326 </p></div><div class="section" title="7.7. Pkg-config - pkgconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-pkgconfig"></a>7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p>
2327 <code class="filename">pkg-config</code> brought standardization and this class aims to make its
2328 integration smooth for all libraries that make use of it.
2329 </p><p>
2330 During staging, BitBake installs <code class="filename">pkg-config</code> data into the
2331 <code class="filename">sysroots/</code> directory.
2332 By making use of sysroot functionality within <code class="filename">pkg-config</code>,
2333 this class no longer has to manipulate the files.
2334 </p></div><div class="section" title="7.8. Distribution of sources - src_distribute_local.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-src-distribute"></a>7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p>
2335 Many software licenses require that source files be provided along with the binaries.
2336 To simplify this process, two classes were created:
2337 <code class="filename">src_distribute.bbclass</code> and
2338 <code class="filename">src_distribute_local.bbclass</code>.
2339 </p><p>
2340 The results of these classes are <code class="filename">tmp/deploy/source/</code>
2341 subdirs with sources sorted by
2342 <code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a></code> field.
2343 If recipes list few licenses (or have entries like "Bitstream Vera"),
2344 the source archive is placed in each license directory.
2345 </p><p>
2346 This class operates using three modes:
2347 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the
2348 distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the
2349 distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into
2350 the distribute directory and then symlinks them back.</p></li></ul></div><p>
2351 </p></div><div class="section" title="7.9. Perl modules - cpan.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-perl"></a>7.9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p>
2352 Recipes for Perl modules are simple.
2353 These recipes usually only need to point to the source's archive and then inherit the
2354 proper <code class="filename">.bbclass</code> file.
2355 Building is split into two methods depending on which method the module authors used.
2356 </p><p>
2357 Modules that use old <code class="filename">Makefile.PL</code>-based build system require
2358 <code class="filename">cpan.bbclass</code> in their recipes.
2359 </p><p>
2360 Modules that use <code class="filename">Build.PL</code>-based build system require
2361 using <code class="filename">cpan_build.bbclass</code> in their recipes.
2362 </p></div><div class="section" title="7.10. Python extensions - distutils.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-distutils"></a>7.10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p>
2363 Recipes for Python extensions are simple.
2364 These recipes usually only need to point to the source's archive and then inherit
2365 the proper <code class="filename">.bbclass</code> file.
2366 Building is split into two methods dependling on which method the module authors used.
2367 </p><p>
2368 Extensions that use an Autotools-based build system require Autotools and
2369 <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes.
2370 </p><p>
2371 Extensions that use <code class="filename">distutils</code>-based build systems require
2372 <code class="filename">distutils.bbclass</code> in their recipes.
2373 </p></div><div class="section" title="7.11. Developer Shell - devshell.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-devshell"></a>7.11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p>
2374 This class adds the <code class="filename">devshell</code> task.
2375 Distribution policy dictates whether to include this class.
2376 See the
2377 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section
2378 in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>.
2379 </p></div><div class="section" title="7.12. Package Groups - packagegroup.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-packagegroup"></a>7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></h2></div></div></div><p>
2380 This class sets default values appropriate for package group recipes (such as
2381 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>,
2382 <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>,
2383 <code class="filename"><a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">ALLOW_EMPTY</a></code>,
2384 and so forth.
2385 It is highly recommended that all package group recipes inherit this class.
2386 </p><p>
2387 For information on how to use this class, see the
2388 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks" target="_top">Customizing Images Using Custom Package Tasks</a>"
2389 section in the Yocto Project Development Manual.
2390 </p><p>
2391 Previously, this class was named <code class="filename">task.bbclass</code>.
2392 </p></div><div class="section" title="7.13. Packaging - package*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-package"></a>7.13. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p>
2393 The packaging classes add support for generating packages from a build's
2394 output.
2395 The core generic functionality is in <code class="filename">package.bbclass</code>.
2396 The code specific to particular package types is contained in various sub-classes such as
2397 <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>,
2398 and <code class="filename">package_rpm.bbclass</code>.
2399 Most users will want one or more of these classes.
2400 </p><p>
2401 You can control the list of resulting package formats by using the
2402 <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code>
2403 variable defined in the <code class="filename">local.conf</code> configuration file,
2404 which is located in the <code class="filename">conf</code> folder of the
2405 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2406 When defining the variable, you can specify one or more package types.
2407 Since images are generated from packages, a packaging class is
2408 needed to enable image generation.
2409 The first class listed in this variable is used for image generation.
2410 </p><p>
2411 The package class you choose can affect build-time performance and has space
2412 ramifications.
2413 In general, building a package with RPM takes about thirty percent more time as
2414 compared to using IPK to build the same or similar package.
2415 This comparison takes into account a complete build of the package with all
2416 dependencies previously built.
2417 The reason for this discrepancy is because the RPM package manager creates and
2418 processes more metadata than the IPK package manager.
2419 Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code>
2420 to "package_ipk" if you are building smaller systems.
2421 </p><p>
2422 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
2423 the fact that it processes more metadata.
2424 For example, this information includes individual file types, file checksum generation
2425 and evaluation on install, sparse file support, conflict detection and resolution
2426 for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
2427 </p><p>
2428 Another consideration for packages built using the RPM package manager is space.
2429 For smaller systems, the extra space used for the Berkley Database and the amount
2430 of metadata can affect your ability to do on-device upgrades.
2431 </p><p>
2432 You can find additional information on the effects of the package class at these
2433 two Yocto Project mailing list links:
2434 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_top">
2435 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_top">
2436 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li></ul></div><p>
2437 </p></div><div class="section" title="7.14. Building kernels - kernel.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-kernel"></a>7.14. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p>
2438 This class handles building Linux kernels.
2439 The class contains code to build all kernel trees.
2440 All needed headers are staged into the
2441 <code class="filename"><a class="link" href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code>
2442 directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>.
2443 </p><p>
2444 This means that each built kernel module is packaged separately and inter-module
2445 dependencies are created by parsing the <code class="filename">modinfo</code> output.
2446 If all modules are required, then installing the <code class="filename">kernel-modules</code>
2447 package installs all packages with modules and various other kernel packages
2448 such as <code class="filename">kernel-vmlinux</code>.
2449 </p><p>
2450 Various other classes are used by the kernel and module classes internally including
2451 <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>,
2452 <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>.
2453 </p></div><div class="section" title="7.15. Creating images - image.bbclass and rootfs*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-image"></a>7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p>
2454 These classes add support for creating images in several formats.
2455 First, the root filesystem is created from packages using
2456 one of the <code class="filename">rootfs_*.bbclass</code>
2457 files (depending on the package format used) and then the image is created.
2458 </p><p>
2459 The <code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code>
2460 variable controls the types of images to generate.
2461 </p><p>
2462 The <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code>
2463 variable controls the list of packages to install into the image.
2464 </p></div><div class="section" title="7.16. Host System sanity checks - sanity.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-sanity"></a>7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p>
2465 This class checks to see if prerequisite software is present so that
2466 users can be notified of potential problems that might affect their build.
2467 The class also performs basic user configuration checks from
2468 the <code class="filename">local.conf</code> configuration file to
2469 prevent common mistakes that cause build failures.
2470 Distribution policy usually determines whether to include this class.
2471 </p></div><div class="section" title="7.17. Generated output quality assurance checks - insane.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-insane"></a>7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p>
2472 This class adds a step to the package generation process that sanity checks the
2473 packages generated by the OpenEmbedded build system.
2474 A range of checks are performed that check the build's output
2475 for common problems that show up during runtime.
2476 Distribution policy usually dictates whether to include this class.
2477 </p><p>
2478 You can configure the sanity checks so that specific test failures either raise a warning or
2479 an error message.
2480 Typically, failures for new tests generate a warning.
2481 Subsequent failures for the same test would then generate an error message
2482 once the metadata is in a known and good condition.
2483 You use the <code class="filename">WARN_QA</code> variable to specify tests for which you
2484 want to generate a warning message on failure.
2485 You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you
2486 want to generate an error message on failure.
2487 </p><p>
2488 The following list shows the tests you can list with the <code class="filename">WARN_QA</code>
2489 and <code class="filename">ERROR_QA</code> variables:
2490 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span>
2491 Ensures that the binaries were linked with the
2492 <code class="filename">LDFLAGS</code> options provided by the build system.
2493 If this test fails, check that the <code class="filename">LDFLAGS</code> variable
2494 is being passed to the linker command.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span>
2495 Checks for dynamic library load paths (rpaths) in the binaries that
2496 by default on a standard system are searched by the linker (e.g.
2497 <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>).
2498 While these paths will not cause any breakage, they do waste space and
2499 are unnecessary.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span>
2500 Checks for rpaths in the binaries that contain build system paths such
2501 as <code class="filename">TMPDIR</code>.
2502 If this test fails, bad <code class="filename">-rpath</code> options are being
2503 passed to the linker commands and your binaries have potential security
2504 issues.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span>
2505 Checks that the <code class="filename">.so</code> symbolic links are in the
2506 <code class="filename">-dev</code> package and not in any of the other packages.
2507 In general, these symlinks are only useful for development purposes.
2508 Thus, the <code class="filename">-dev</code> package is the correct location for
2509 them.
2510 Some very rare cases do exist for dynamically loaded modules where
2511 these symlinks are needed instead in the main package.
2512 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span>
2513 Checks for <code class="filename">.debug</code> directories in anything but the
2514 <code class="filename">-dbg</code> package.
2515 The debug files should all be in the <code class="filename">-dbg</code> package.
2516 Thus, anything packaged elsewhere is incorrect packaging.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span>
2517 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
2518 of any binaries to ensure it matches the target architecture.
2519 This test fails if any binaries don't match the type since there would be an
2520 incompatibility.
2521 Sometimes software, like bootloaders, might need to bypass this check.
2522 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span>
2523 Checks that <code class="filename">-dbg</code> packages only depend on other
2524 <code class="filename">-dbg</code> packages and not on any other types of packages,
2525 which would cause a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span>
2526 Checks that <code class="filename">-dev</code> packages only depend on other
2527 <code class="filename">-dev</code> packages and not on any other types of packages,
2528 which would be a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span>
2529 Checks <code class="filename">.pc</code> files for any
2530 <code class="filename">TMPDIR/WORKDIR</code> paths.
2531 Any <code class="filename">.pc</code> file containing these paths is incorrect
2532 since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix
2533 when the files are accessed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span>
2534 Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code>
2535 paths.
2536 Any <code class="filename">.la</code> file continaing these paths is incorrect since
2537 <code class="filename">libtool</code> adds the correct sysroot prefix when using the
2538 files automatically itself.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span>
2539 Runs the <code class="filename">desktop-file-validate</code> program against any
2540 <code class="filename">.desktop</code> files to validate their contents against
2541 the specification for <code class="filename">.desktop</code> files.</p></li></ul></div><p>
2542 </p></div><div class="section" title="7.18. Autotools configuration data cache - siteinfo.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-siteinfo"></a>7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p>
2543 Autotools can require tests that must execute on the target hardware.
2544 Since this is not possible in general when cross compiling, site information is
2545 used to provide cached test results so these tests can be skipped over but
2546 still make the correct values available.
2547 The <code class="filename"><a class="link" href="#structure-meta-site" title="5.3.18. meta/site/">meta/site directory</a></code>
2548 contains test results sorted into different categories such as architecture, endianness, and
2549 the <code class="filename">libc</code> used.
2550 Site information provides a list of files containing data relevant to
2551 the current build in the
2552 <code class="filename"><a class="link" href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable
2553 that Autotools automatically picks up.
2554 </p><p>
2555 The class also provides variables like
2556 <code class="filename"><a class="link" href="#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code>
2557 and <code class="filename"><a class="link" href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code>
2558 that can be used elsewhere in the metadata.
2559 </p><p>
2560 Because this class is included from <code class="filename">base.bbclass</code>, it is always active.
2561 </p></div><div class="section" title="7.19. Adding Users - useradd.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-useradd"></a>7.19. Adding Users - <code class="filename">useradd.bbclass</code></h2></div></div></div><p>
2562 If you have packages that install files that are owned by custom users or groups,
2563 you can use this class to specify those packages and associate the users and groups
2564 with those packages.
2565 The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code>
2566 recipe in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
2567 provides a simple exmample that shows how to add three
2568 users and groups to two packages.
2569 See the <code class="filename">useradd-example.bb</code> for more information on how to
2570 use this class.
2571 </p></div><div class="section" title="7.20. Using External Source - externalsrc.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-externalsrc"></a>7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></h2></div></div></div><p>
2572 You can use this class to build software from source code that is external to the
2573 OpenEmbedded build system.
2574 In other words, your source code resides in an external tree outside of the Yocto Project.
2575 Building software from an external source tree means that the normal fetch, unpack, and
2576 patch process is not used.
2577 </p><p>
2578 To use the class, you need to define the
2579 <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> variable to point to the directory that contains the source files.
2580 You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class.
2581 </p><p>
2582 This class expects the source code to support recipe builds that use the
2583 <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable to point to the directory in
2584 which the OpenEmbedded build system places the generated objects built from the recipes.
2585 By default, the <code class="filename">B</code> directory is set to the following, which is separate from the
2586 Source Directory (<code class="filename">S</code>):
2587 </p><pre class="literallayout">
2588 ${WORKDIR}/${BPN}/{PV}/
2589 </pre><p>
2590 See the glossary entries for the
2591 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>,
2592 <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a>,
2593 <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>,
2594 <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>, and
2595 <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> for more information.
2596 </p><p>
2597 You can build object files in the external tree by setting the
2598 <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>.
2599 However, this practice does not work well if you use the source for more than one variant
2600 (i.e., "natives" such as <code class="filename">quilt-native</code>,
2601 or "crosses" such as <code class="filename">gcc-cross</code>).
2602 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
2603 </p><p>
2604 If you do want to build different variants of a recipe, you can use the
2605 <a class="link" href="#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable.
2606 When you do, the <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable must support the
2607 recipe's ability to build variants in different working directories.
2608 Most autotools-based recipes support separating these directories.
2609 The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code>
2610 and some kernel recipes.
2611 Alternatively, you can make sure that separate recipes exist that each
2612 use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant.
2613 The separate recipes can inherit a single target recipe.
2614 </p><p>
2615 For information on how to use this class, see the
2616 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#building-software-from-an-external-source" target="_top">Building
2617 Software from an External Source</a>" section in the Yocto Project Development Manual.
2618 </p></div><div class="section" title="7.21. Other Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-others"></a>7.21. Other Classes</h2></div></div></div><p>
2619 Thus far, this chapter has discussed only the most useful and important
2620 classes.
2621 However, other classes exist within the <code class="filename">meta/classes</code> directory
2622 in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2623 You can examine the <code class="filename">.bbclass</code> files directly for more
2624 information.
2625 </p></div></div>
2626
2627 <div class="chapter" title="Chapter 8. Images"><div class="titlepage"><div><div><h2 class="title"><a id="ref-images"></a>Chapter 8. Images</h2></div></div></div><p>
2628 The OpenEmbedded build process supports several types of images to satisfy different needs.
2629 When you issue the <code class="filename">bitbake</code> command you provide a “top-level” recipe
2630 that essentially begins the build for the type of image you want.
2631 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2632 Building an image without GNU General Public License Version 3 (GPLv3) components
2633 is only supported for minimal and base images.
2634 Furthermore, if you are going to build an image using non-GPLv3 components,
2635 you must make the following changes in the <code class="filename">local.conf</code> file
2636 before using the BitBake command to build the minimal or base image:
2637 <pre class="literallayout">
2638 1. Comment out the EXTRA_IMAGE_FEATURES line
2639 2. Set INCOMPATIBLE_LICENSE = "GPLv3"
2640 </pre></div><p>
2641 From within the <code class="filename">poky</code> Git repository, use the following command to list
2642 the supported images:
2643 </p><pre class="literallayout">
2644 $ ls meta*/recipes*/images/*.bb
2645 </pre><p>
2646 These recipes reside in the <code class="filename">meta/recipes-core/images</code>,
2647 <code class="filename">meta/recipes-extended/images</code>,
2648 <code class="filename">meta/recipes-graphics/images</code>, and
2649 <code class="filename">meta/recipes-sato/images</code> directories
2650 within the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a>.
2651 Although the recipe names are somewhat explanatory, here is a list that describes them:
2652 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span>
2653 A console-only image that fully supports the target device hardware.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span>
2654 A small image just capable of allowing a device to boot.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span>
2655 A <code class="filename">core-image-minimal</code> image suitable for development work
2656 using the host.
2657 The image includes headers and libraries you can use in a host development
2658 environment.
2659 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span>
2660 A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based
2661 Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel,
2662 which allows the system to find the first “init” program more efficiently.
2663 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span>
2664 A <code class="filename">core-image-minimal</code> image that has support
2665 for the Minimal MTD Utilities, which let the user interact with the
2666 MTD subsystem in the kernel to perform operations on flash devices.
2667 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-x11</code>:</em></span>
2668 A very basic X11 image with a terminal.
2669 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span>
2670 A console-only image with more full-featured Linux system
2671 functionality installed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span>
2672 An image that conforms to the Linux Standard Base (LSB) specification.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span>
2673 A <code class="filename">core-image-lsb</code> image that is suitable for development work
2674 using the host.
2675 The image includes headers and libraries you can use in a host development
2676 environment.
2677 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span>
2678 A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain
2679 but also includes development headers and libraries to form a complete standalone SDK.
2680 This image is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span>
2681 An image with support for the Open GL-based toolkit Clutter, which enables development of
2682 rich and animated graphical user interfaces.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span>
2683 An image with Sato support, a mobile environment and visual style that works well
2684 with mobile devices.
2685 The image supports X11 with a Sato theme and applications such as
2686 a terminal, editor, file manager, media player, and so forth.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span>
2687 A <code class="filename">core-image-sato</code> image suitable for development
2688 using the host.
2689 The image includes libraries needed to build applications on the device itself,
2690 testing and profiling tools, and debug symbols.
2691 This image was formerly <code class="filename">core-image-sdk</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span>
2692 A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain.
2693 The image also includes development headers and libraries to form a complete standalone SDK
2694 and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span>
2695 A <code class="filename">core-image-minimal</code> image plus a real-time test suite and
2696 tools appropriate for real-time use.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span>
2697 A <code class="filename">core-image-rt</code> image that includes everything in
2698 <code class="filename">meta-toolchain</code>.
2699 The image also includes development headers and libraries to form a complete
2700 stand-alone SDK and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span>
2701 An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code>
2702 instead of X11.
2703 In order to build, this image requires specific distro configuration that enables
2704 <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span>
2705 An image you can boot and run using either the
2706 <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_top">VMware Player</a>
2707 or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_top">VMware Workstation</a>.
2708 For more information on this image, see the
2709 <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> page on
2710 the Yocto Project website.</p></li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
2711 From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and
2712 <code class="filename">-directdisk</code> images have been replaced by a "live"
2713 option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an
2714 image file that can be
2715 copied directly to a CD or USB device and run as is.
2716 To build a live image, simply add
2717 "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code>
2718 file or wherever appropriate and then build the desired image as normal.
2719 </div></div>
2720
2721 <div class="chapter" title="Chapter 9. Reference: Features"><div class="titlepage"><div><div><h2 class="title"><a id="ref-features"></a>Chapter 9. Reference: Features</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-features-distro">9.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">9.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">9.3. Images</a></span></dt><dt><span class="section"><a href="#ref-features-backfill">9.4. Feature Backfilling</a></span></dt></dl></div><p>
2722 Features provide a mechanism for working out which packages
2723 should be included in the generated images.
2724 Distributions can select which features they want to support through the
2725 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>
2726 variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file.
2727 Machine features are set in the
2728 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>
2729 variable, which is set in the machine configuration file and
2730 specifies the hardware features for a given machine.
2731 </p><p>
2732 These two variables combine to work out which kernel modules,
2733 utilities, and other packages to include.
2734 A given distribution can support a selected subset of features so some machine features might not
2735 be included if the distribution itself does not support them.
2736 </p><p>
2737 One method you can use to determine which recipes are checking to see if a
2738 particular feature is contained or not is to <code class="filename">grep</code> through
2739 the metadata for the feature.
2740 Here is an example that discovers the recipes whose build is potentially
2741 changed based on a given feature:
2742 </p><pre class="literallayout">
2743 $ cd $HOME/poky
2744 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
2745 </pre><p>
2746 </p><p>
2747 This chapter provides a reference of shipped machine and distro features
2748 you can include as part of the image, a reference on image types you can
2749 build, and a reference on feature backfilling.
2750 </p><div class="section" title="9.1. Distro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-distro"></a>9.1. Distro</h2></div></div></div><p>
2751 The items below are features you can use with
2752 <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>.
2753 Features do not have a one-to-one correspondence to packages, and they can
2754 go beyond simply controlling the installation of a package or packages.
2755 Sometimes a feature can influence how certain recipes are built.
2756 For example, a feature might determine whether a particular configure option
2757 is specified within <code class="filename">do_configure</code> for a particular
2758 recipe.
2759 </p><p>
2760 This list only represents features as shipped with the Yocto Project metadata:
2761 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility
2762 kernel modules will be installed if available).</p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only)
2763 </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal
2764 HDD/Microdrive for storing files (instead of Flash only devices)
2765 </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support
2766 </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be
2767 loaded during boot).
2768 </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support
2769 </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support
2770 </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB
2771 networking/serial/storage)
2772 </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external
2773 keyboard, mouse, storage, network etc)
2774 </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only)
2775 </p></li><li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support
2776 </p></li><li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support
2777 </p></li><li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support
2778 </p></li><li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on
2779 device)</p></li><li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li><li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting
2780 Samba/Microsoft Windows shares on device)</p></li></ul></div><p>
2781 </p></div><div class="section" title="9.2. Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-machine"></a>9.2. Machine</h2></div></div></div><p>
2782 The items below are features you can use with
2783 <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>.
2784 Features do not have a one-to-one correspondence to packages, and they can
2785 go beyond simply controlling the installation of a package or packages.
2786 Sometimes a feature can influence how certain recipes are built.
2787 For example, a feature might determine whether a particular configure option
2788 is specified within <code class="filename">do_configure</code> for a particular
2789 recipe.
2790 </p><p>
2791 This feature list only represents features as shipped with the Yocto Project metadata:
2792 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only)
2793 </p></li><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers
2794 </p></li><li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation)
2795 </p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT
2796 </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive
2797 </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support
2798 </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard
2799 </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus
2800 </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets
2801 </p></li><li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen
2802 </p></li><li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232)
2803 </p></li><li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen
2804 </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable
2805 </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable
2806 </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi
2807 </p></li></ul></div><p>
2808 </p></div><div class="section" title="9.3. Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-image"></a>9.3. Images</h2></div></div></div><p>
2809 The contents of images generated by the OpenEmbedded build system can be controlled by the
2810 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>
2811 and <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code>
2812 variables that you typically configure in your image recipes.
2813 Through these variables you can add several different
2814 predefined packages such as development utilities or packages with debug
2815 information needed to investigate application problems or profile applications.
2816 </p><p>
2817 Current list of
2818 <code class="filename">IMAGE_FEATURES</code> contains the following:
2819 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>splash:</em></span> Enables showing a splash screen during boot.
2820 By default, this screen is provided by <code class="filename">psplash</code>, which does
2821 allow customization.
2822 If you prefer to use an alternative splash screen package, you can do so by
2823 setting the <code class="filename">SPLASH</code> variable
2824 to a different package name (or names) within the image recipe or at the distro
2825 configuration level.</p></li><li class="listitem"><p><span class="emphasis"><em>ssh-server-dropbear:</em></span> Installs the Dropbear minimal
2826 SSH server.
2827 </p></li><li class="listitem"><p><span class="emphasis"><em>ssh-server-openssh:</em></span> Installs the OpenSSH SSH server,
2828 which is more full-featured than Dropbear.
2829 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
2830 are present in <code class="filename">IMAGE_FEATURES</code>, then OpenSSH will take
2831 precedence and Dropbear will not be installed.</p></li><li class="listitem"><p><span class="emphasis"><em>x11:</em></span> Installs the X server</p></li><li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> Installs the X server with a
2832 minimal environment.</p></li><li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> Installs the OpenedHand Sato environment.
2833 </p></li><li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> Installs a full SDK that runs on the device.
2834 </p></li><li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Installs debugging tools such as
2835 <code class="filename">strace</code> and <code class="filename">gdb</code>.
2836 </p></li><li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Installs profiling tools such as
2837 <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and
2838 <code class="filename">LTTng</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Installs device testing tools (e.g.
2839 touchscreen debugging).</p></li><li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> Installs an NFS server.</p></li><li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Installs development packages (headers and
2840 extra library links) for all packages installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>staticdev-pkgs:</em></span> Installs static development
2841 packages (i.e. static libraries containing <code class="filename">*.a</code> files) for all
2842 packages installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Installs debug symbol packages for all packages
2843 installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>doc-pkgs:</em></span> Installs documentation packages for all packages
2844 installed in a given image.</p></li></ul></div><p>
2845 </p></div><div class="section" title="9.4. Feature Backfilling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-backfill"></a>9.4. Feature Backfilling</h2></div></div></div><p>
2846 Sometimes it is necessary in the OpenEmbedded build system to extend
2847 <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>
2848 or <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>
2849 to control functionality that was previously enabled and not able
2850 to be disabled.
2851 For these cases, we need to add an
2852 additional feature item to appear in one of these variables,
2853 but we do not want to force developers who have existing values
2854 of the variables in their configuration to add the new feature
2855 in order to retain the same overall level of functionality.
2856 Thus, the OpenEmbedded build system has a mechanism to
2857 automatically "backfill" these added features into existing
2858 distro or machine configurations.
2859 You can see the list of features for which this is done by
2860 finding the
2861 <a class="link" href="#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL"><code class="filename">DISTRO_FEATURES_BACKFILL</code></a>
2862 and <a class="link" href="#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL"><code class="filename">MACHINE_FEATURES_BACKFILL</code></a>
2863 variables in the <code class="filename">meta/conf/bitbake.conf</code> file.
2864 </p><p>
2865 Because such features are backfilled by default into all
2866 configurations as described in the previous paragraph, developers
2867 who wish to disable the new features need to be able to selectively
2868 prevent the backfilling from occurring.
2869 They can do this by adding the undesired feature or features to the
2870 <a class="link" href="#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED"><code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code></a>
2871 or <a class="link" href="#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED"><code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code></a>
2872 variables for distro features and machine features respectively.
2873 </p><p>
2874 Here are two examples to help illustrate feature backfilling:
2875 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The "pulseaudio" distro feature option</em></span>:
2876 Previously, PulseAudio support was enabled within the Qt and
2877 GStreamer frameworks.
2878 Because of this, the feature is backfilled and thus
2879 enabled for all distros through the
2880 <code class="filename">DISTRO_FEATURES_BACKFILL</code>
2881 variable in the <code class="filename">meta/conf/bitbake.conf</code> file.
2882 However, your distro needs to disable the feature.
2883 You can disable the feature without affecting
2884 other existing distro configurations that need PulseAudio support
2885 by adding "pulseaudio" to
2886 <code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code>
2887 in your distro's <code class="filename">.conf</code> file.
2888 Adding the feature to this variable when it also
2889 exists in the <code class="filename">DISTRO_FEATURES_BACKFILL</code>
2890 variable prevents the build system from adding the feature to
2891 your configuration's <code class="filename">DISTRO_FEATURES</code>, effectively disabling
2892 the feature for that particular distro.</p></li><li class="listitem"><p><span class="emphasis"><em>The "rtc" machine feature option</em></span>:
2893 Previously, real time clock (RTC) support was enabled for all
2894 target devices.
2895 Because of this, the feature is backfilled and thus enabled
2896 for all machines through the <code class="filename">MACHINE_FEATURES_BACKFILL</code>
2897 variable in the <code class="filename">meta/conf/bitbake.conf</code> file.
2898 However, your target device does not have this capability.
2899 You can disable RTC support for your device without
2900 affecting other machines that need RTC support
2901 by adding the feature to your machine's
2902 <code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code>
2903 list in the machine's <code class="filename">.conf</code> file.
2904 Adding the feature to this variable when it also
2905 exists in the <code class="filename">MACHINE_FEATURES_BACKFILL</code>
2906 variable prevents the build system from adding the feature to
2907 your configuration's <code class="filename">MACHINE_FEATURES</code>, effectively
2908 disabling RTC support for that particular machine.</p></li></ul></div><p>
2909 </p></div></div>
2910
2911 <div class="chapter" title="Chapter 10. Variables Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glos"></a>Chapter 10. Variables Glossary</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p>
2912 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
2913 of their function and contents.
2914</p><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glossary"></a>Glossary</h2></div></div></div><p>
2915 <a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a>
2916 <a class="link" href="#var-B" title="B">B</a>
2917 <a class="link" href="#var-CFLAGS" title="CFLAGS">C</a>
2918 <a class="link" href="#var-D" title="D">D</a>
2919 <a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a>
2920 <a class="link" href="#var-FILES" title="FILES">F</a>
2921
2922 <a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">H</a>
2923 <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a>
2924
2925 <a class="link" href="#var-KBRANCH" title="KBRANCH">K</a>
2926 <a class="link" href="#var-LAYERDIR" title="LAYERDIR">L</a>
2927 <a class="link" href="#var-MACHINE" title="MACHINE">M</a>
2928
2929 <a class="link" href="#var-OE_TERMINAL" title="OE_TERMINAL">O</a>
2930 <a class="link" href="#var-P" title="P">P</a>
2931
2932 <a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">R</a>
2933 <a class="link" href="#var-S" title="S">S</a>
2934 <a class="link" href="#var-T" title="T">T</a>
2935
2936
2937 <a class="link" href="#var-WORKDIR" title="WORKDIR">W</a>
2938
2939
2940
2941 </p><div class="glossdiv" title="A"><h3 class="title">A</h3><dl><dt><a id="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt><dd><p>
2942 Specifies if an output package should still be produced if it is empty.
2943 By default, BitBake does not produce empty packages.
2944 This default behavior can cause issues when there is an
2945 <a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or
2946 some other runtime hard-requirement on the existence of the package.
2947 </p><p>
2948 Like all package-controlling variables, you must always use them in
2949 conjunction with a package name override.
2950 Here is an example:
2951 </p><pre class="literallayout">
2952 ALLOW_EMPTY_${PN} = "1"
2953 </pre><p>
2954 </p></dd><dt><a id="var-AUTHOR"></a>AUTHOR</dt><dd><p>The email address used to contact the original author or authors in
2955 order to send patches, forward bugs, etc.</p></dd><dt><a id="var-AUTOREV"></a>AUTOREV</dt><dd><p>When <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code>
2956 is set to the value of this variable, it specifies that the latest
2957 source revision in the repository should be used. Here is an example:
2958 </p><pre class="literallayout">
2959 SRCREV = "${AUTOREV}"
2960 </pre><p>
2961 </p></dd></dl></div><div class="glossdiv" title="B"><h3 class="title">B</h3><dl><dt><a id="var-B"></a>B</dt><dd><p>
2962 The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
2963 The OpenEmbedded build system places generated objects into the Build Directory
2964 during a recipe's build process.
2965 By default, this directory is the same as the <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>
2966 directory:
2967 </p><pre class="literallayout">
2968 B = ${WORKDIR}/${BPN}/{PV}/
2969 </pre><p>
2970 You can separate the (<code class="filename">S</code>) directory and the directory pointed to
2971 by the <code class="filename">B</code> variable.
2972 Most autotools-based recipes support separating these directories.
2973 The build system defaults to using separate directories for <code class="filename">gcc</code>
2974 and some kernel recipes.
2975 </p></dd><dt><a id="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt><dd><p>
2976 A list of packages not to install despite being recommended by a recipe.
2977 Support for this variable exists only when using the
2978 <code class="filename">ipk</code> packaging backend.
2979 </p></dd><dt><a id="var-BB_DISKMON_DIRS"></a>BB_DISKMON_DIRS</dt><dd><p>
2980 Monitors disk space and available inodes during the build
2981 and allows you to control the build based on these
2982 parameters.
2983 </p><p>
2984 Disk space monitoring is disabled by default.
2985 To enable monitoring, add the <code class="filename">BB_DISKMON_DIRS</code>
2986 variable to your <code class="filename">conf/local.conf</code> file found in the
2987 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
2988 Use the following form:
2989 </p><pre class="literallayout">
2990 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
2991
2992 where:
2993
2994 &lt;action&gt; is:
2995 ABORT: Immediately abort the build when
2996 a threshold is broken.
2997 STOPTASKS: Stop the build after the currently
2998 executing tasks have finished when
2999 a threshold is broken.
3000 WARN: Issue a warning but continue the
3001 build when a threshold is broken.
3002 Subsequent warnings are issued as
3003 defined by the
3004 <a class="link" href="#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL">BB_DISKMON_WARNINTERVAL</a> variable,
3005 which must be defined in the
3006 conf/local.conf file.
3007
3008 &lt;dir&gt; is:
3009 Any directory you choose. You can specify one or
3010 more directories to monitor by separating the
3011 groupings with a space. If two directories are
3012 on the same device, only the first directory
3013 is monitored.
3014
3015 &lt;threshold&gt; is:
3016 Either the minimum available disk space,
3017 the minimum number of free inodes, or
3018 both. You must specify at least one. To
3019 omit one or the other, simply omit the value.
3020 Specify the threshold using G, M, K for Gbytes,
3021 Mbytes, and Kbytes, respectively. If you do
3022 not specify G, M, or K, Kbytes is assumed by
3023 default. Do not use GB, MB, or KB.
3024 </pre><p>
3025 </p><p>
3026 Here are some examples:
3027 </p><pre class="literallayout">
3028 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
3029 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
3030 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
3031 </pre><p>
3032 The first example works only if you also provide
3033 the <a class="link" href="#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL"><code class="filename">BB_DISKMON_WARNINTERVAL</code></a> variable
3034 in the <code class="filename">conf/local.conf</code>.
3035 This example causes the build system to immediately
3036 abort when either the disk space in <code class="filename">${TMPDIR}</code> drops
3037 below 1 Gbyte or the available free inodes drops below
3038 100 Kbytes.
3039 Because two directories are provided with the variable, the
3040 build system also issue a
3041 warning when the disk space in the
3042 <code class="filename">${SSTATE_DIR}</code> directory drops
3043 below 1 Gbyte or the number of free inodes drops
3044 below 100 Kbytes.
3045 Subsequent warnings are issued during intervals as
3046 defined by the <code class="filename">BB_DISKMON_WARNINTERVAL</code>
3047 variable.
3048 </p><p>
3049 The second example stops the build after all currently
3050 executing tasks complete when the minimum disk space
3051 in the <code class="filename">${TMPDIR}</code> directory drops
3052 below 1 Gbyte.
3053 No disk monitoring occurs for the free inodes in this case.
3054 </p><p>
3055 The final example immediately aborts the build when the
3056 number of free inodes in the <code class="filename">${TMPDIR}</code> directory
3057 drops below 100 Kbytes.
3058 No disk space monitoring for the directory itself occurs
3059 in this case.
3060 </p></dd><dt><a id="var-BB_DISKMON_WARNINTERVAL"></a>BB_DISKMON_WARNINTERVAL</dt><dd><p>
3061 Defines the disk space and free inode warning intervals.
3062 To set these intervals, define the variable in your
3063 <code class="filename">conf/local.conf</code> file in the
3064 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3065 </p><p>
3066 If you are going to use the
3067 <code class="filename">BB_DISKMON_WARNINTERVAL</code> variable, you must
3068 also use the
3069 <a class="link" href="#var-BB_DISKMON_DIRS" title="BB_DISKMON_DIRS"><code class="filename">BB_DISKMON_DIRS</code></a> variable
3070 and define its action as "WARN".
3071 During the build, subsequent warnings are issued each time
3072 disk space or number of free inodes further reduces by
3073 the respective interval.
3074 </p><p>
3075 If you do not provide a <code class="filename">BB_DISKMON_WARNINTERVAL</code>
3076 variable and you do use <code class="filename">BB_DISKMON_DIRS</code> with
3077 the "WARN" action, the disk monitoring interval defaults to
3078 the following:
3079 </p><pre class="literallayout">
3080 BB_DISKMON_WARNINTERVAL = "50M,5K"
3081 </pre><p>
3082 </p><p>
3083 When specifying the variable in your configuration file,
3084 use the following form:
3085 </p><pre class="literallayout">
3086 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
3087
3088 where:
3089
3090 &lt;disk_space_interval&gt; is:
3091 An interval of memory expressed in either
3092 G, M, or K for Gbytes, Mbytes, or Kbytes,
3093 respectively. You cannot use GB, MB, or KB.
3094
3095 &lt;disk_inode_interval&gt; is:
3096 An interval of free inodes expressed in either
3097 G, M, or K for Gbytes, Mbytes, or Kbytes,
3098 respectively. You cannot use GB, MB, or KB.
3099 </pre><p>
3100 </p><p>
3101 Here is an example:
3102 </p><pre class="literallayout">
3103 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
3104 BB_DISKMON_WARNINTERVAL = "50M,5K"
3105 </pre><p>
3106 These variables cause the OpenEmbedded build system to
3107 issue subsequent warnings each time the available
3108 disk space further reduces by 50 Mbytes or the number
3109 of free inodes further reduces by 5 Kbytes in the
3110 <code class="filename">${SSTATE_DIR}</code> directory.
3111 Subsequent warnings based on the interval occur each time
3112 a respective interval is reached beyond the intial warning
3113 (i.e. 1 Gbytes and 100 Kbytes).
3114 </p></dd><dt><a id="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt><dd><p>
3115 Allows you to extend a recipe so that it builds variants of the software.
3116 Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>,
3117 which is a copy of quilt built to run on the build system;
3118 "crosses" such as <code class="filename">gcc-cross</code>,
3119 which is a compiler built to run on the build machine but produces binaries
3120 that run on the target <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>;
3121 "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>;
3122 and "mulitlibs" in the form "<code class="filename">multilib:&lt;multilib_name&gt;</code>".
3123 </p><p>
3124 To build a different variant of the recipe with a minimal amount of code, it usually
3125 is as simple as adding the following to your recipe:
3126 </p><pre class="literallayout">
3127 BBCLASSEXTEND =+ "native nativesdk"
3128 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
3129 </pre><p>
3130 </p></dd><dt><a id="var-BBMASK"></a>BBMASK</dt><dd><p>Prevents BitBake from processing recipes and recipe append files.
3131 You can use the <code class="filename">BBMASK</code> variable to "hide"
3132 these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files.
3133 BitBake ignores any recipe or recipe append files that match the expression.
3134 It is as if BitBake does not see them at all.
3135 Consequently, matching files are not parsed or otherwise used by
3136 BitBake.</p><p>The value you provide is passed to python's regular expression compiler.
3137 For complete syntax information, see python's documentation at
3138 <a class="ulink" href="http://docs.python.org/release/2.3/lib/re-syntax.html" target="_top">http://docs.python.org/release/2.3/lib/re-syntax.html</a>.
3139 The expression is compared against the full paths to the files.
3140 For example, the following uses a complete regular expression to tell
3141 BitBake to ignore all recipe and recipe append files in the
3142 <code class="filename">.*/meta-ti/recipes-misc/</code> directory:
3143 </p><pre class="literallayout">
3144 BBMASK = ".*/meta-ti/recipes-misc/"
3145 </pre><p>Use the <code class="filename">BBMASK</code> variable from within the
3146 <code class="filename">conf/local.conf</code> file found
3147 in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.</p></dd><dt><a id="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>The maximum number of tasks BitBake should run in parallel at any one time.
3148 If your host development system supports multiple cores a good rule of thumb
3149 is to set this variable to twice the number of cores.</p></dd><dt><a id="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt><dd><p>Lists the names of configured layers.
3150 These names are used to find the other <code class="filename">BBFILE_*</code>
3151 variables.
3152 Typically, each layer will append its name to this variable in its
3153 <code class="filename">conf/layer.conf</code> file.
3154 </p></dd><dt><a id="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt><dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer.
3155 This variable is used in the <code class="filename">conf/layer.conf</code> file and must
3156 be suffixed with the name of the specific layer (e.g.
3157 <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd><dt><a id="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt><dd><p>Assigns the priority for recipe files in each layer.</p><p>This variable is useful in situations where the same recipe appears in
3158 more than one layer.
3159 Setting this variable allows you to prioritize a
3160 layer against other layers that contain the same recipe - effectively
3161 letting you control the precedence for the multiple layers.
3162 The precedence established through this variable stands regardless of a
3163 recipe's version (<code class="filename">PV</code> variable).
3164 For example, a layer that has a recipe with a higher <code class="filename">PV</code> value but for
3165 which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a
3166 lower precedence.</p><p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher
3167 precedence.
3168 For example, the value 6 has a higher precedence than the value 5.
3169 If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer
3170 dependencies (see the
3171 <code class="filename"><a class="link" href="#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for
3172 more information.
3173 The default priority, if unspecified
3174 for a layer with no dependencies, is the lowest defined priority + 1
3175 (or 1 if no priorities are defined).</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
3176 You can use the command <code class="filename">bitbake-layers show_layers</code> to list
3177 all configured layers along with their priorities.
3178 </div></dd><dt><a id="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipe files used by BitBake to build software</p></dd><dt><a id="var-BBPATH"></a>BBPATH</dt><dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files.
3179 This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd><dt><a id="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd><dt><a id="var-BBLAYERS"></a>BBLAYERS</dt><dd><p>Lists the layers to enable during the build.
3180 This variable is defined in the <code class="filename">bblayers.conf</code> configuration
3181 file in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3182 Here is an example:
3183 </p><pre class="literallayout">
3184 BBLAYERS = " \
3185 /home/scottrif/poky/meta \
3186 /home/scottrif/poky/meta-yocto \
3187 /home/scottrif/poky/meta-yocto-bsp \
3188 /home/scottrif/poky/meta-mykernel \
3189 "
3190
3191 BBLAYERS_NON_REMOVABLE ?= " \
3192 /home/scottrif/poky/meta \
3193 /home/scottrif/poky/meta-yocto \
3194 "
3195 </pre><p>
3196 This example enables four layers, one of which is a custom, user-defined layer
3197 named <code class="filename">meta-mykernel</code>.
3198 </p></dd><dt><a id="var-BBLAYERS_NON_REMOVABLE"></a>BBLAYERS_NON_REMOVABLE</dt><dd><p>Lists core layers that cannot be removed from the
3199 <code class="filename">bblayers.conf</code> file.
3200 In order for BitBake to build your image, your
3201 <code class="filename">bblayers.conf</code> file must include the
3202 <code class="filename">meta</code> and <code class="filename">meta-yocto</code>
3203 core layers.
3204 Here is an example that shows these two layers listed in
3205 the <code class="filename">BBLAYERS_NON_REMOVABLE</code> statement:
3206 </p><pre class="literallayout">
3207 BBLAYERS = " \
3208 /home/scottrif/poky/meta \
3209 /home/scottrif/poky/meta-yocto \
3210 /home/scottrif/poky/meta-yocto-bsp \
3211 /home/scottrif/poky/meta-mykernel \
3212 "
3213
3214 BBLAYERS_NON_REMOVABLE ?= " \
3215 /home/scottrif/poky/meta \
3216 /home/scottrif/poky/meta-yocto \
3217 "
3218 </pre><p>
3219 </p></dd><dt><a id="var-BP"></a>BP</dt><dd><p>The base recipe name and version but without any special
3220 recipe name suffix (i.e. <code class="filename">-native</code>, <code class="filename">lib64-</code>,
3221 and so forth).
3222 <code class="filename">BP</code> is comprised of the following:
3223 </p><pre class="literallayout">
3224 ${BPN}-${PV}
3225 </pre></dd><dt><a id="var-BPN"></a>BPN</dt><dd><p>The bare name of the recipe.
3226 This variable is a version of the <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> variable
3227 but removes common suffixes such as "-native" and "-cross" as well
3228 as removes common prefixes such as multilib's "lib64-" and "lib32-".
3229 The exact list of suffixes removed is specified by the
3230 <a class="link" href="#var-SPECIAL_PKGSUFFIX" title="SPECIAL_PKGSUFFIX"><code class="filename">SPECIAL_PKGSUFFIX</code></a> variable.
3231 The exact list of prefixes removed is specified by the
3232 <a class="link" href="#var-MLPREFIX" title="MLPREFIX"><code class="filename">MLPREFIX</code></a> variable.
3233 Prefixes are removed for multilib and nativesdk cases.</p></dd></dl></div><div class="glossdiv" title="C"><h3 class="title">C</h3><dl><dt><a id="var-CFLAGS"></a>CFLAGS</dt><dd><p>
3234 Flags passed to C compiler for the target system.
3235 This variable evaluates to the same as
3236 <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>.
3237 </p></dd><dt><a id="var-COMBINED_FEATURES"></a>COMBINED_FEATURES</dt><dd><p>A set of features common between
3238 <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>
3239 and <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>.
3240 See the glossary descriptions for these variables for more information.</p></dd><dt><a id="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt><dd><p>A regular expression which evaluates to match the machines the recipe
3241 works with.
3242 It stops recipes being run on machines for which they are not compatible.
3243 This is particularly useful with kernels.
3244 It also helps to increase parsing speed as further parsing of the recipe is skipped
3245 if it is found the current machine is not compatible.</p></dd><dt><a id="var-CONFFILES"></a>CONFFILES</dt><dd><p>
3246 Identifies editable or configurable files that are part of a package.
3247 If the Package Management System (PMS) is being used to update
3248 packages on the target system, it is possible that
3249 configuration files you have changed after the original installation
3250 and that you now want to remain unchanged are overwritten.
3251 In other words, editable files might exist in the package that you do not
3252 want reset as part of the package update process.
3253 You can use the <code class="filename">CONFFILES</code> variable to list the files in the
3254 package that you wish to prevent the PMS from overwriting during this update process.
3255 </p><p>
3256 To use the <code class="filename">CONFFILES</code> variable, provide a package name
3257 override that identifies the resulting package.
3258 Then, provide a space-separated list of files.
3259 Here is an example:
3260 </p><pre class="literallayout">
3261 CONFFILES_${PN} += "${sysconfdir}/file1 \
3262 ${sysconfdir}/file2 ${sysconfdir}/file3"
3263 </pre><p>
3264 </p><p>
3265 A relationship exists between the <code class="filename">CONFFILES</code> and
3266 <code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a></code> variables.
3267 The files listed within <code class="filename">CONFFILES</code> must be a subset of
3268 the files listed within <code class="filename">FILES</code>.
3269 Because the configuration files you provide with <code class="filename">CONFFILES</code>
3270 are simply being identified so that the PMS will not overwrite them,
3271 it makes sense that
3272 the files must already be included as part of the package through the
3273 <code class="filename">FILES</code> variable.
3274 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3275 When specifying paths as part of the <code class="filename">CONFFILES</code> variable,
3276 it is good practice to use appropriate path variables.
3277 For example, <code class="filename">${sysconfdir}</code> rather than
3278 <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather
3279 than <code class="filename">/usr/bin</code>.
3280 You can find a list of these variables at the top of the
3281 <code class="filename">/meta/conf/bitbake.conf</code> file in the
3282 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
3283 </div></dd><dt><a id="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p>
3284 A list of files that contains <code class="filename">autoconf</code> test results relevant
3285 to the current build.
3286 This variable is used by the Autotools utilities when running
3287 <code class="filename">configure</code>.
3288 </p></dd><dt><a id="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt><dd><p>
3289 Specifies the list of packages to be added to the image.
3290 This variable should only be set in the <code class="filename">local.conf</code>
3291 configuration file found in the
3292 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3293 </p><p>
3294 This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported.
3295 </p></dd></dl></div><div class="glossdiv" title="D"><h3 class="title">D</h3><dl><dt><a id="var-D"></a>D</dt><dd><p>The destination directory.</p></dd><dt><a id="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p>
3296 Specifies to build packages with debugging information.
3297 This influences the value of the
3298 <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code>
3299 variable.
3300 </p></dd><dt><a id="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p>
3301 The options to pass in
3302 <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>
3303 and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling
3304 a system for debugging.
3305 This variable defaults to "-O -fno-omit-frame-pointer -g".
3306 </p></dd><dt><a id="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Specifies the priority of recipes.</p></dd><dt><a id="var-DEPENDS"></a>DEPENDS</dt><dd><p>
3307 Lists a recipe's build-time dependencies
3308 (i.e. other recipe files).
3309 The system ensures that all the dependencies listed
3310 have been built and have their contents in the appropriate
3311 sysroots before the recipe's configure task is executed.
3312 </p></dd><dt><a id="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>The package description used by package managers.
3313 If not set, <code class="filename">DESCRIPTION</code> takes
3314 the value of the
3315 <a class="link" href="#var-SUMMARY" title="SUMMARY"><code class="filename">SUMMARY</code></a>
3316 variable.
3317 </p></dd><dt><a id="var-DESTDIR"></a>DESTDIR</dt><dd><p>the destination directory.</p></dd><dt><a id="var-DISTRO"></a>DISTRO</dt><dd><p>
3318 The short name of the distribution.
3319 This variable corresponds to a file with the
3320 extension <code class="filename">.conf</code>
3321 located in a <code class="filename">conf/distro</code> directory
3322 within the metadata that contains the distribution configuration.
3323 The
3324 value must not contain spaces, and is typically all lower-case.
3325 </p><p>
3326 If the variable is blank, a set of default configuration
3327 will be used, which is specified
3328 within <code class="filename">meta/conf/distro/defaultsetup.conf</code>.
3329 </p></dd><dt><a id="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt><dd><p>
3330 Specifies a list of distro-specific packages to add to all images.
3331 This variable takes affect through
3332 <code class="filename">packagegroup-base</code> so the
3333 variable only really applies to the more full-featured
3334 images that include <code class="filename">packagegroup-base</code>.
3335 You can use this variable to keep distro policy out of
3336 generic images.
3337 As with all other distro variables, you set this variable
3338 in the distro <code class="filename">.conf</code> file.
3339 </p></dd><dt><a id="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p>
3340 Specifies a list of distro-specific packages to add to all images
3341 if the packages exist.
3342 The packages might not exist or be empty (e.g. kernel modules).
3343 The list of packages are automatically installed but can be
3344 removed by the user.
3345 </p></dd><dt><a id="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>The features enabled for the distribution.
3346 For a list of features supported by the Yocto Project as shipped,
3347 see the "<a class="link" href="#ref-features-distro" title="9.1. Distro">Distro</a>"
3348 section.
3349 </p></dd><dt><a id="var-DISTRO_FEATURES_BACKFILL"></a>DISTRO_FEATURES_BACKFILL</dt><dd><p>Features to be added to
3350 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>
3351 if not also present in
3352 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED">DISTRO_FEATURES_BACKFILL_CONSIDERED</a></code>.
3353 </p><p>
3354 This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file.
3355 It is not intended to be user-configurable.
3356 It is best to just reference the variable to see which distro features are
3357 being backfilled for all distro configurations.
3358 See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for
3359 more information.
3360 </p></dd><dt><a id="var-DISTRO_FEATURES_BACKFILL_CONSIDERED"></a>DISTRO_FEATURES_BACKFILL_CONSIDERED</dt><dd><p>Features from
3361 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL">DISTRO_FEATURES_BACKFILL</a></code>
3362 that should not backfilled (i.e. added to
3363 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>)
3364 during the build.
3365 See the "<a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature Backfilling</a>" section for
3366 more information.
3367 </p></dd><dt><a id="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>The long name of the distribution.</p></dd><dt><a id="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt><dd><p>Alias names used for the recipe in various Linux distributions.</p><p>See the
3368 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-configuring-DISTRO_PN_ALIAS" target="_top">Handling
3369 a Package Name Alias</a>" section in the Yocto Project Development
3370 Manual for more information.</p></dd><dt><a id="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>the version of the distribution.</p></dd><dt><a id="var-DL_DIR"></a>DL_DIR</dt><dd><p>
3371 The central download directory used by the build process to store downloads.
3372 You can set this directory by defining the <code class="filename">DL_DIR</code>
3373 variable in the <code class="filename">/conf/local.conf</code> file.
3374 This directory is self-maintaining and you should not have
3375 to touch it.
3376 By default, the directory is <code class="filename">downloads</code> in the
3377 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3378 </p><pre class="literallayout">
3379 #DL_DIR ?= "${TOPDIR}/downloads"
3380 </pre><p>
3381 To specify a different download directory, simply uncomment the line
3382 and provide your directory.
3383 </p><p>
3384 During a first build, the system downloads many different source code
3385 tarballs from various upstream projects.
3386 Downloading can take a while, particularly if your network
3387 connection is slow.
3388 Tarballs are all stored in the directory defined by
3389 <code class="filename">DL_DIR</code> and the build system looks there first
3390 to find source tarballs.
3391 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3392 When wiping and rebuilding, you can preserve this directory to speed
3393 up this part of subsequent builds.
3394 </div><p>
3395 </p><p>
3396 You can safely share this directory between multiple builds on the
3397 same development machine.
3398 For additional information on how the build process gets source files
3399 when working behind a firewall or proxy server, see the
3400 "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server">FAQ</a>"
3401 chapter.
3402 </p></dd></dl></div><div class="glossdiv" title="E"><h3 class="title">E</h3><dl><dt><a id="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p></p><p>Variable that controls which locales for <code class="filename">eglibc</code> are
3403 to be generated during the build (useful if the target device has 64Mbytes
3404 of RAM or less).</p></dd><dt><a id="var-EXTENDPE"></a>EXTENDPE</dt><dd><p>
3405 Used with file and pathnames to create a prefix for a recipe's
3406 version based on the recipe's
3407 <a class="link" href="#var-PE" title="PE"><code class="filename">PE</code></a> value.
3408 If <code class="filename">PE</code> is set and greater than zero for a recipe,
3409 <code class="filename">EXTENDPE</code> becomes that value (e.g if
3410 <code class="filename">PE</code> is equal to "1" then <code class="filename">EXTENDPE</code>
3411 becomes "1_").
3412 If a recipe's <code class="filename">PE</code> is not set (the default) or is equal to
3413 zero, <code class="filename">EXTENDPE</code> becomes "".</p><p>See the <a class="link" href="#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a>
3414 variable for an example.
3415 </p></dd><dt><a id="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt><dd><p>Allows extra packages to be added to the generated images.
3416 You set this variable in the <code class="filename">local.conf</code>
3417 configuration file.
3418 Note that some image features are also added using the
3419 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>
3420 variable generally configured in image recipes.
3421 You can use this variable to add more features in addition to those.
3422 Here are some examples of features you can add:</p><pre class="literallayout">
3423"dbg-pkgs" - Adds -dbg packages for all installed packages
3424 including symbol information for debugging and
3425 profiling.
3426
3427"dev-pkgs" - Adds -dev packages for all installed packages.
3428 This is useful if you want to develop against
3429 the libraries in the image.
3430
3431"tools-sdk" - Adds development tools such as gcc, make,
3432 pkgconfig and so forth.
3433
3434"tools-debug" - Adds debugging tools such as gdb and
3435 strace.
3436
3437"tools-profile" - Adds profiling tools such as oprofile,
3438 exmap, lttng and valgrind (x86 only).
3439
3440"tools-testapps" - Adds useful testing tools such as
3441 ts_print, aplay, arecord and so
3442 forth.
3443
3444"debug-tweaks" - Makes an image suitable for development.
3445 For example, ssh root access has a blank
3446 password. You should remove this feature
3447 before you produce a production image.
3448 </pre><p>There are other valid features too, see the
3449 <a class="link" href="#ref-features-image" title="9.3. Images">Images</a>
3450 section for more details.</p></dd><dt><a id="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt><dd><p>A list of recipes to be built that do not provide packages to be installed in
3451 the root filesystem.
3452 </p><p>Sometimes a recipe is required to build the final image but is not
3453 needed in the root filesystem.
3454 You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to
3455 list these recipes and thus, specify the dependencies.
3456 A typical example is a required bootloader in a machine configuration.
3457 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3458 To add packages to the root filesystem, see the various
3459 <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code>
3460 variables.
3461 </div></dd><dt><a id="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt><dd><p>Additional <code class="filename">cmake</code> options.</p></dd><dt><a id="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional <code class="filename">configure</code> script options.</p></dd><dt><a id="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU <code class="filename">make</code> options.</p></dd></dl></div><div class="glossdiv" title="F"><h3 class="title">F</h3><dl><dt><a id="var-FILES"></a>FILES</dt><dd><p>
3462 The list of directories or files that are placed in packages.
3463 </p><p>
3464 To use the <code class="filename">FILES</code> variable, provide a package name
3465 override that identifies the resulting package.
3466 Then, provide a space-separated list of files or paths that identifies the
3467 files you want included as part of the resulting package.
3468 Here is an example:
3469 </p><pre class="literallayout">
3470 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
3471 </pre><p>
3472 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3473 When specifying paths as part of the <code class="filename">FILES</code> variable,
3474 it is good practice to use appropriate path variables.
3475 For example, <code class="filename">${sysconfdir}</code> rather than
3476 <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather
3477 than <code class="filename">/usr/bin</code>.
3478 You can find a list of these variables at the top of the
3479 <code class="filename">/meta/conf/bitbake.conf</code> file in the
3480 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
3481 </div><p>
3482 If some of the files you provide with the <code class="filename">FILES</code> variable
3483 are editable and you know they should not be
3484 overwritten during the package update process by the Package Management
3485 System (PMS), you can identify these files so that the PMS will not
3486 overwrite them.
3487 See the <code class="filename"><a class="link" href="#var-CONFFILES" title="CONFFILES">CONFFILES</a></code>
3488 variable for information on how to identify these files to the PMS.
3489 </p></dd><dt><a id="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt><dd><p>
3490 Extends the search path the OpenEmbedded build system uses when
3491 looking for files and patches as it processes recipes.
3492 The directories BitBake uses when it processes recipes is defined by the
3493 <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable.
3494 You can add directories to the search path by defining the
3495 <code class="filename">FILESEXTRAPATHS</code> variable.
3496 </p><p>
3497 To add paths to the search order, provide a list of directories and separate
3498 each path using a colon character as follows:
3499 </p><pre class="literallayout">
3500 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
3501 </pre><p>
3502 Typically, you want your directories searched first.
3503 To make sure that happens, use <code class="filename">_prepend</code> and
3504 the immediate expansion (<code class="filename">:=</code>) operator as shown in the
3505 previous example.
3506 Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable,
3507 you must include the appropriate beginning or ending (as needed) colon character.
3508 </p><p>
3509 The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in
3510 <code class="filename">.bbappend</code> files to include any additional files provided in that layer.
3511 You typically accomplish this with the following:
3512 </p><pre class="literallayout">
3513 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
3514 </pre><p>
3515 </p></dd><dt><a id="var-FILESPATH"></a>FILESPATH</dt><dd><p>
3516 The default set of directories the OpenEmbedded build system uses
3517 when searching for patches and files.
3518 During the build process, BitBake searches each directory in
3519 <code class="filename">FILESPATH</code> in the specified order when looking for
3520 files and patches specified by each <code class="filename">file://</code> URI in a recipe.
3521 </p><p>
3522 The default value for the <code class="filename">FILESPATH</code> variable is defined
3523 in the <code class="filename">base.bbclass</code> class found in
3524 <code class="filename">meta/classes</code> in the
3525 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>:
3526 </p><pre class="literallayout">
3527FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
3528 "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
3529 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
3530 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
3531 </pre><p>
3532 Do not hand-edit the <code class="filename">FILESPATH</code> variable.
3533 If you want to extend the set of pathnames that BitBake uses when searching for
3534 files and patches, use the
3535 <a class="link" href="#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable.
3536 </p></dd><dt><a id="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt><dd><p>Allows you to define your own file permissions settings table as part of
3537 your configuration for the packaging process.
3538 For example, suppose you need a consistent set of custom permissions for
3539 a set of groups and users across an entire work project.
3540 It is best to do this in the packages themselves but this is not always
3541 possible.
3542 </p><p>
3543 By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which
3544 is located in the <code class="filename">meta/files</code> folder in the
3545 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
3546 If you create your own file permissions setting table, you should place it in your
3547 layer or the distros layer.
3548 </p><p>
3549 You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the
3550 <code class="filename">conf/local.conf</code> file, which is found in the
3551 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>, to
3552 point to your custom <code class="filename">fs-perms.txt</code>.
3553 You can specify more than a single file permissions setting table.
3554 The paths you specify to these files must be defined within the
3555 <code class="filename">BBPATH</code> variable.
3556 </p><p>
3557 For guidance on how to create your own file permissions settings table file,
3558 examine the existing <code class="filename">fs-perms.txt</code>.
3559 </p></dd><dt><a id="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p>
3560 The options to pass in
3561 <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>
3562 and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>
3563 when compiling an optimized system.
3564 This variable defaults to
3565 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
3566 </p></dd></dl></div><div class="glossdiv" title="H"><h3 class="title">H</h3><dl><dt><a id="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more information about the software the recipe is building
3567 can be found.</p></dd></dl></div><div class="glossdiv" title="I"><h3 class="title">I</h3><dl><dt><a id="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p>The list of features to include in an image.
3568 Typically, you configure this variable in an image recipe.
3569 Note that you can also add extra features to the image by using the
3570 <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> variable.
3571 See the "<a class="link" href="#ref-features-image" title="9.3. Images">Images</a>" section for the
3572 full list of features that can be included in images built by the
3573 OpenEmbedded build system.</p></dd><dt><a id="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of root filesystem images that you want to have created.</p></dd><dt><a id="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p>
3574 Specifies the packages to install into an image.
3575 The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image
3576 recipe and you should use it with care to avoid ordering issues.
3577 </p><p>
3578 Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the
3579 packages to install into an image through <code class="filename">image.bbclass</code>.
3580 Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>,
3581 that can take
3582 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists
3583 and turn these into auto-generated entries in
3584 <code class="filename">IMAGE_INSTALL</code> in addition to its default contents.
3585 </p><p>
3586 Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code>
3587 operator from the <code class="filename">/conf/local.conf</code> file or from within
3588 an image recipe is not recommended as it can cause ordering issues.
3589 Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code>
3590 to a default value using the <code class="filename">?=</code> operator, using a
3591 <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code>
3592 will result in unexpected behavior when used in
3593 <code class="filename">/conf/local.conf</code>.
3594 Furthermore, the same operation from with an image recipe may or may not
3595 succeed depending on the specific situation.
3596 In both these cases, the behavior is contrary to how most users expect
3597 the <code class="filename">+=</code> operator to work.
3598 </p><p>
3599 When you use this variable, it is best to use it as follows:
3600 </p><pre class="literallayout">
3601 IMAGE_INSTALL_append = " package-name"
3602 </pre><p>
3603 Be sure to include the space between the quotation character and the start of the
3604 package name.
3605 </p></dd><dt><a id="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt><dd><p>
3606 Defines a multiplier that the build system applies to the initial image
3607 size for cases when the multiplier times the returned disk usage value
3608 for the image is greater than the sum of
3609 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>
3610 and
3611 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>.
3612 The result of the multiplier applied to the initial image size creates
3613 free disk space in the image as overhead.
3614 By default, the build process uses a multiplier of 1.3 for this variable.
3615 This default value results in 30% free disk space added to the image when this
3616 method is used to determine the final generated image size.
3617 You should be aware that post install scripts and the package management
3618 system uses disk space inside this overhead area.
3619 Consequently, the multiplier does not produce an image with
3620 all the theoretical free disk space.
3621 See <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>
3622 for information on how the build system determines the overall image size.
3623 </p><p>
3624 The default 30% free disk space typically gives the image enough room to boot
3625 and allows for basic post installs while still leaving a small amount of
3626 free disk space.
3627 If 30% free space is inadequate, you can increase the default value.
3628 For example, the following setting gives you 50% free space added to the image:
3629 </p><pre class="literallayout">
3630 IMAGE_OVERHEAD_FACTOR = "1.5"
3631 </pre><p>
3632 </p><p>
3633 Alternatively, you can ensure a specific amount of free disk space is added
3634 to the image by using
3635 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>
3636 the variable.
3637 </p></dd><dt><a id="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt><dd><p>
3638 Defines additional free disk space created in the image in Kbytes.
3639 By default, this variable is set to "0".
3640 This free disk space is added to the image after the build system determines
3641 the image size as described in
3642 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>.
3643 </p><p>
3644 This variable is particularly useful when you want to ensure that a
3645 specific amount of free disk space is available on a device after an image
3646 is installed and running.
3647 For example, to be sure 5 Gbytes of free disk space is available, set the
3648 variable as follows:
3649 </p><pre class="literallayout">
3650 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3651 </pre><p>
3652 </p></dd><dt><a id="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt><dd><p>
3653 Defines the size in Kbytes for the generated image.
3654 The OpenEmbedded build system determines the final size for the generated
3655 image using an algorithm that takes into account the initial disk space used
3656 for the generated image, a requested size for the image, and requested
3657 additional free disk space to be added to the image.
3658 Programatically, the build system determines the final size of the
3659 generated image as follows:
3660 </p><pre class="literallayout">
3661 if (image-du * overhead) &lt; rootfs-size:
3662 internal-rootfs-size = rootfs-size + xspace
3663 else:
3664 internal-rootfs-size = (image-du * overhead) + xspace
3665
3666 where:
3667
3668 image-du = Returned value of the du command on
3669 the image.
3670
3671 overhead = IMAGE_OVERHEAD_FACTOR
3672
3673 rootfs-size = IMAGE_ROOTFS_SIZE
3674
3675 internal-rootfs-size = Initial root filesystem
3676 size before any modifications.
3677
3678 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3679 </pre><p>
3680
3681 </p></dd><dt><a id="var-INC_PR"></a>INC_PR</dt><dd><p>Helps define the recipe revision for recipes that share
3682 a common <code class="filename">include</code> file.
3683 You can think of this variable as part of the recipe revision
3684 as set from within an include file.</p><p>Suppose, for example, you have a set of recipes that
3685 are used across several projects.
3686 And, within each of those recipes the revision
3687 (its <code class="filename">PR</code> value) is set accordingly.
3688 In this case, when the revision of those recipes changes
3689 the burden is on you to find all those recipes and
3690 be sure that they get changed to reflect the updated
3691 version of the recipe.
3692 In this scenario, it can get complicated when recipes
3693 used in many places and that provide common functionality
3694 are upgraded to a new revision.</p><p>A more efficient way of dealing with this situation is
3695 to set the <code class="filename">INC_PR</code> variable inside
3696 the <code class="filename">include</code> files that the recipes
3697 share and then expand the <code class="filename">INC_PR</code>
3698 variable within the recipes to help
3699 define the recipe revision.
3700 </p><p>
3701 The following provides an example that shows how to use
3702 the <code class="filename">INC_PR</code> variable
3703 given a common <code class="filename">include</code> file that
3704 defines the variable.
3705 Once the variable is defined in the
3706 <code class="filename">include</code> file, you can use the
3707 variable to set the <code class="filename">PR</code> values in
3708 each recipe.
3709 You will notice that when you set a recipe's
3710 <code class="filename">PR</code> you can provide more granular
3711 revisioning by appending values to the
3712 <code class="filename">INC_PR</code> variable:
3713 </p><pre class="literallayout">
3714recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3715recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3716recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3717recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3718 </pre><p>
3719 The first line of the example establishes the baseline
3720 revision to be used for all recipes that use the
3721 <code class="filename">include</code> file.
3722 The remaining lines in the example are from individual
3723 recipes and show how the <code class="filename">PR</code> value
3724 is set.</p></dd><dt><a id="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p>
3725 Causes the build to not strip binaries in resulting packages.
3726 </p></dd><dt><a id="var-INHERIT"></a>INHERIT</dt><dd><p>
3727 Causes the named class to be inherited at
3728 this point during parsing.
3729 The variable is only valid in configuration files.
3730 </p></dd><dt><a id="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p>
3731 A list of the packages that contain initscripts.
3732 If multiple packages are specified, you need to append the package name
3733 to the other <code class="filename">INITSCRIPT_*</code> as an override.</p><p>
3734 This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>.
3735 The variable is optional and defaults to the <code class="filename">PN</code> variable.
3736 </p></dd><dt><a id="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p>
3737 The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>.
3738 </p><p>
3739 This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>.
3740 The variable is Mandatory.
3741 </p></dd><dt><a id="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p>
3742 Specifies the options to pass to <code class="filename">update-rc.d</code>.
3743 An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a
3744 runlevel of 99, starts the script in initlevels 2 and 5, and
3745 stops the script in levels 0, 1 and 6.
3746 </p><p>
3747 The variable is mandatory and is used in recipes when using
3748 <code class="filename">update-rc.d.bbclass</code>.
3749 </p></dd></dl></div><div class="glossdiv" title="K"><h3 class="title">K</h3><dl><dt><a id="var-KBRANCH"></a>KBRANCH</dt><dd><p>
3750 A regular expression used by the build process to explicitly identify the kernel
3751 branch that is validated, patched and configured during a build.
3752 The <code class="filename">KBRANCH</code> variable is optional.
3753 You can use it to trigger checks to ensure the exact kernel branch you want is
3754 being used by the build process.
3755 </p><p>
3756 Values for this variable are set in the kernel's recipe file and the kernel's
3757 append file.
3758 For example, if you are using the Yocto Project kernel that is based on the
3759 Linux 3.4 kernel, the kernel recipe file is the
3760 <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.4.bb</code> file.
3761 Following is the default value for <code class="filename">KBRANCH</code> and the default
3762 override for the architectures the Yocto Project supports:
3763 </p><pre class="literallayout">
3764 KBRANCH_DEFAULT = "standard/base"
3765 KBRANCH = "${KBRANCH_DEFAULT}"
3766 </pre><p>
3767 This branch exists in the <code class="filename">linux-yocto-3.4</code> kernel Git
3768 repository <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads</a>.
3769 </p><p>
3770 This variable is also used from the kernel's append file to identify the kernel
3771 branch specific to a particular machine or target hardware.
3772 The kernel's append file is located in the BSP layer for a given machine.
3773 For example, the kernel append file for the Crown Bay BSP is in the
3774 <code class="filename">meta-intel</code> Git repository and is named
3775 <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</code>.
3776 Here are the related statements from the append file:
3777 </p><pre class="literallayout">
3778 COMPATIBLE_MACHINE_crownbay = "crownbay"
3779 KMACHINE_crownbay = "crownbay"
3780 KBRANCH_crownbay = "standard/crownbay"
3781
3782 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
3783 KMACHINE_crownbay-noemgd = "crownbay"
3784 KBRANCH_crownbay-noemgd = "standard/crownbay"
3785 </pre><p>
3786 The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to
3787 use when building for the Crown Bay BSP.
3788 In this case there are two identical statements: one for each type of
3789 Crown Bay machine.
3790 </p></dd><dt><a id="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt><dd><p>Includes additional metadata from the Yocto Project kernel Git repository.
3791 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
3792 metadata is provided through
3793 the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables.
3794 You can use the <code class="filename">KERNEL_FEATURES</code> variable to further
3795 add metadata for all BSPs.</p><p>The metadata you add through this variable includes config fragments and
3796 features descriptions,
3797 which usually includes patches as well as config fragments.
3798 You typically override the <code class="filename">KERNEL_FEATURES</code> variable
3799 for a specific machine.
3800 In this way, you can provide validated, but optional, sets of kernel
3801 configurations and features.</p><p>For example, the following adds <code class="filename">netfilter</code> to all
3802 the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code>
3803 machine:
3804 </p><pre class="literallayout">
3805 # Add netfilter to all linux-yocto kernels
3806 KERNEL_FEATURES="features/netfilter"
3807
3808 # Add sound support to the qemux86 machine
3809 KERNEL_FEATURES_append_qemux86=" cfg/sound"
3810 </pre></dd><dt><a id="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the
3811 machine configuration files and defaults to "zImage".
3812 This variable is used
3813 when building the kernel and is passed to <code class="filename">make</code> as the target to
3814 build.</p></dd><dt><a id="var-KMACHINE"></a>KMACHINE</dt><dd><p>
3815 The machine as known by the kernel.
3816 Sometimes the machine name used by the kernel does not match the machine name
3817 used by the OpenEmbedded build system.
3818 For example, the machine name that the OpenEmbedded build system understands as
3819 <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel.
3820 The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>.
3821 For cases like these, the <code class="filename">KMACHINE</code> variable maps the
3822 kernel machine name to the OpenEmbedded build system machine name.
3823 </p><p>
3824 Kernel machine names are initially defined in the
3825 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">Yocto Linux Kernel</a> in
3826 the <code class="filename">meta</code> branch.
3827 From the <code class="filename">meta</code> branch, look in
3828 the <code class="filename">meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</code> file.
3829 For example, from the <code class="filename">meta</code> branch in the
3830 <code class="filename">linux-yocto-3.0</code> kernel, the
3831 <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file
3832 has the following:
3833 </p><pre class="literallayout">
3834 define KMACHINE cedartrail
3835 define KTYPE standard
3836 define KARCH i386
3837
3838 include ktypes/standard
3839 branch cedartrail
3840
3841 include cedartrail.scc
3842 </pre><p>
3843 You can see that the kernel understands the machine name for the Cedar Trail BSP as
3844 <code class="filename">cedartrail</code>.
3845 </p><p>
3846 If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source
3847 repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>,
3848 you will find the following statements among others:
3849 </p><pre class="literallayout">
3850 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
3851 KMACHINE_cedartrail = "cedartrail"
3852 KBRANCH_cedartrail = "yocto/standard/cedartrail"
3853 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
3854 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
3855
3856 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
3857 KMACHINE_cedartrail-nopvr = "cedartrail"
3858 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
3859 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
3860 </pre><p>
3861 The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that
3862 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
3863 names.
3864 </p><p>
3865 This append file uses two <code class="filename">KMACHINE</code> statements.
3866 The first is not really necessary but does ensure that the machine known to the
3867 OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine
3868 in the kernel also known as <code class="filename">cedartrail</code>:
3869 </p><pre class="literallayout">
3870 KMACHINE_cedartrail = "cedartrail"
3871 </pre><p>
3872 </p><p>
3873 The second statement is a good example of why the <code class="filename">KMACHINE</code> variable
3874 is needed.
3875 In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code>
3876 machine name to refer to the Cedar Trail BSP that does not support the propriatory
3877 PowerVR driver.
3878 The kernel, however, uses the machine name <code class="filename">cedartrail</code>.
3879 Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to
3880 the kernel's <code class="filename">cedartrail</code> name:
3881 </p><pre class="literallayout">
3882 KMACHINE_cedartrail-nopvr = "cedartrail"
3883 </pre><p>
3884 </p><p>
3885 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
3886 Project kernel machine names and the OpenEmbedded machine names.
3887 Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine
3888 name you use is different than that used in the kernel.
3889 </p></dd></dl></div><div class="glossdiv" title="L"><h3 class="title">L</h3><dl><dt><a id="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt><dd><p>Lists the layers that this recipe depends upon, separated by spaces.
3890 Optionally, you can specify a specific layer version for a dependency
3891 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
3892 to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case).
3893 An error will be produced if any dependency is missing or
3894 the version numbers do not match exactly (if specified).
3895 This variable is used in the <code class="filename">conf/layer.conf</code> file
3896 and must be suffixed with the name of the specific layer (e.g.
3897 <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd><dt><a id="var-LAYERDIR"></a>LAYERDIR</dt><dd><p>When used inside the <code class="filename">layer.conf</code> configuration
3898 file, this variable provides the path of the current layer.
3899 This variable requires immediate expansion
3900 (see the BitBake manual) as lazy expansion can result in
3901 the expansion happening in the wrong directory and therefore
3902 giving the wrong value.</p></dd><dt><a id="var-LAYERVERSION"></a>LAYERVERSION</dt><dd><p>Optionally specifies the version of a layer as a single number.
3903 You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to
3904 depend on a specific version of the layer.
3905 This variable is used in the <code class="filename">conf/layer.conf</code> file
3906 and must be suffixed with the name of the specific layer (e.g.
3907 <code class="filename">LAYERVERSION_mylayer</code>).</p></dd><dt><a id="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt><dd><p>Checksums of the license text in the recipe source code.</p><p>This variable tracks changes in license text of the source
3908 code files.
3909 If the license text is changed, it will trigger a build
3910 failure, which gives the developer an opportunity to review any
3911 license change.</p><p>
3912 This variable must be defined for all recipes (unless <code class="filename">LICENSE</code>
3913 is set to "CLOSED")</p><p>For more information, see the
3914 <a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" title="3.4.1. Tracking License Changes">
3915 Tracking License Changes</a> section</p></dd><dt><a id="var-LICENSE"></a>LICENSE</dt><dd><p>
3916 The list of source licenses for the recipe.
3917 Follow these rules:
3918 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Do not use spaces within individual
3919 license names.</p></li><li class="listitem"><p>Separate license names using
3920 | (pipe) when there is a choice between licenses.
3921 </p></li><li class="listitem"><p>Separate license names using
3922 &amp; (ampersand) when multiple licenses exist
3923 that cover different parts of the source.
3924 </p></li><li class="listitem"><p>You can use spaces between license
3925 names.</p></li></ul></div><p>
3926 </p><p>
3927 Here are some examples:
3928 </p><pre class="literallayout">
3929 LICENSE = "LGPLv2.1 | GPLv3"
3930 LICENSE = "MPL-1 &amp; LGPLv2.1"
3931 LICENSE = "GPLv2+"
3932 </pre><p>
3933 The first example is from the recipes for Qt, which the user
3934 may choose to distribute under either the LGPL version
3935 2.1 or GPL version 3.
3936 The second example is from Cairo where two licenses cover
3937 different parts of the source code.
3938 The final example is from <code class="filename">sysstat</code>,
3939 which presents a single license.
3940 </p></dd><dt><a id="var-LICENSE_PATH"></a>LICENSE_PATH</dt><dd><p>Path to additional licenses used during the build.
3941 By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code>
3942 to define the directory that holds common license text used during the build.
3943 The <code class="filename">LICENSE_PATH</code> variable allows you to extend that
3944 location to other areas that have additional licenses:
3945 </p><pre class="literallayout">
3946 LICENSE_PATH += "/path/to/additional/common/licenses"
3947 </pre></dd></dl></div><div class="glossdiv" title="M"><h3 class="title">M</h3><dl><dt><a id="var-MACHINE"></a>MACHINE</dt><dd><p>
3948 Specifies the target device for which the image is built.
3949 You define <code class="filename">MACHINE</code> in the
3950 <code class="filename">local.conf</code> file found in the
3951 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3952 By default, <code class="filename">MACHINE</code> is set to
3953 "qemux86", which is an x86-based architecture machine to
3954 be emulated using QEMU:
3955 </p><pre class="literallayout">
3956 MACHINE ?= "qemux86"
3957 </pre><p>
3958 The variable corresponds to a machine configuration file of the
3959 same name, through which machine-specific configurations are set.
3960 Thus, when <code class="filename">MACHINE</code> is set to "qemux86" there
3961 exists the corresponding <code class="filename">qemux86.conf</code> machine
3962 configuration file, which can be found in the
3963 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
3964 in <code class="filename">meta/conf/machine</code>.
3965 </p><p>
3966 The list of machines supported by the Yocto Project as
3967 shipped include the following:
3968 </p><pre class="literallayout">
3969 MACHINE ?= "qemuarm"
3970 MACHINE ?= "qemumips"
3971 MACHINE ?= "qemuppc"
3972 MACHINE ?= "qemux86"
3973 MACHINE ?= "qemux86-64"
3974 MACHINE ?= "atom-pc"
3975 MACHINE ?= "beagleboard"
3976 MACHINE ?= "mpc8315e-rdb"
3977 MACHINE ?= "routerstationpro"
3978 </pre><p>
3979 The last four are Yocto Project reference hardware boards, which
3980 are provided in the <code class="filename">meta-yocto-bsp</code> layer.
3981 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Adding additional Board Support Package (BSP) layers
3982 to your configuration adds new possible settings for
3983 <code class="filename">MACHINE</code>.
3984 </div><p>
3985 </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt><dd><p></p><p>
3986 A list of required machine-specific packages to install as part of
3987 the image being built.
3988 The build process depends on these packages being present.
3989 Furthermore, because this is a "machine essential" variable, the list of
3990 packages are essential for the machine to boot.
3991 The impact of this variable affects images based on
3992 <code class="filename">packagegroup-core-boot</code>,
3993 including the <code class="filename">core-image-minimal</code> image.
3994 </p><p>
3995 This variable is similar to the
3996 <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code>
3997 variable with the exception that the image being built has a build
3998 dependency on the variable's list of packages.
3999 In other words, the image will not build if a file in this list is not found.
4000 </p><p>
4001 As an example, suppose the machine for which you are building requires
4002 <code class="filename">example-init</code> to be run during boot to initialize the hardware.
4003 In this case, you would use the following in the machine's
4004 <code class="filename">.conf</code> configuration file:
4005 </p><pre class="literallayout">
4006 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4007 </pre><p>
4008 </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt><dd><p></p><p>
4009 A list of recommended machine-specific packages to install as part of
4010 the image being built.
4011 The build process does not depend on these packages being present.
4012 However, because this is a "machine essential" variable, the list of
4013 packages are essential for the machine to boot.
4014 The impact of this variable affects images based on
4015 <code class="filename">packagegroup-core-boot</code>,
4016 including the <code class="filename">core-image-minimal</code> image.
4017 </p><p>
4018 This variable is similar to the
4019 <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS</a></code>
4020 variable with the exception that the image being built does not have a build
4021 dependency on the variable's list of packages.
4022 In other words, the image will still build if a package in this list is not found.
4023 Typically, this variable is used to handle essential kernel modules, whose
4024 functionality may be selected to be built into the kernel rather than as a module,
4025 in which case a package will not be produced.
4026 </p><p>
4027 Consider an example where you have a custom kernel where a specific touchscreen
4028 driver is required for the machine to be usable.
4029 However, the driver can be built as a module or
4030 into the kernel depending on the kernel configuration.
4031 If the driver is built as a module, you want it to be installed.
4032 But, when the driver is built into the kernel, you still want the
4033 build to succeed.
4034 This variable sets up a "recommends" relationship so that in the latter case,
4035 the build will not fail due to the missing package.
4036 To accomplish this, assuming the package for the module was called
4037 <code class="filename">kernel-module-ab123</code>, you would use the
4038 following in the machine's <code class="filename">.conf</code> configuration
4039 file:
4040 </p><pre class="literallayout">
4041 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4042 </pre><p>
4043 </p><p>
4044 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4045 or touchscreen drivers (depending on the machine).
4046 </p></dd><dt><a id="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p>
4047 A list of machine-specific packages to install as part of the
4048 image being built that are not essential for the machine to boot.
4049 However, the build process for more fully-featured images
4050 depends on the packages being present.
4051 </p><p>
4052 This variable affects all images based on
4053 <code class="filename">packagegroup-base</code>, which does not include the
4054 <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code>
4055 images.
4056 </p><p>
4057 The variable is similar to the
4058 <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code>
4059 variable with the exception that the image being built has a build
4060 dependency on the variable's list of packages.
4061 In other words, the image will not build if a file in this list is not found.
4062 </p><p>
4063 An example is a machine that has WiFi capability but is not essential
4064 For the machine to boot the image.
4065 However, if you are building a more fully-featured image, you want to enable
4066 the WiFi.
4067 The package containing the firmware for the WiFi hardware is always
4068 expected to exist, so it is acceptable for the build process to depend upon
4069 finding the package.
4070 In this case, assuming the package for the firmware was called
4071 <code class="filename">wifidriver-firmware</code>, you would use the following in the
4072 <code class="filename">.conf</code> file for the machine:
4073 </p><pre class="literallayout">
4074 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4075 </pre><p>
4076 </p></dd><dt><a id="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt><dd><p></p><p>
4077 A list of machine-specific packages to install as part of the
4078 image being built that are not essential for booting the machine.
4079 The image being built has no build dependency on this list of packages.
4080 </p><p>
4081 This variable affects only images based on
4082 <code class="filename">packagegroup-base</code>, which does not include the
4083 <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code>
4084 images.
4085 </p><p>
4086 This variable is similar to the
4087 <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code>
4088 variable with the exception that the image being built does not have a build
4089 dependency on the variable's list of packages.
4090 In other words, the image will build if a file in this list is not found.
4091 </p><p>
4092 An example is a machine that has WiFi capability but is not essential
4093 For the machine to boot the image.
4094 However, if you are building a more fully-featured image, you want to enable
4095 WiFi.
4096 In this case, the package containing the WiFi kernel module will not be produced
4097 if the WiFi driver is built into the kernel, in which case you still want the
4098 build to succeed instead of failing as a result of the package not being found.
4099 To accomplish this, assuming the package for the module was called
4100 <code class="filename">kernel-module-examplewifi</code>, you would use the
4101 following in the <code class="filename">.conf</code> file for the machine:
4102 </p><pre class="literallayout">
4103 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4104 </pre><p>
4105 </p></dd><dt><a id="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>Specifies the list of hardware features the
4106 <a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a> supports.
4107 For example, including the "bluetooth" feature causes the
4108 <code class="filename">bluez</code> bluetooth daemon to be built and
4109 added to the image.
4110 It also causes the <code class="filename">connman</code> recipe
4111 to look at <code class="filename">MACHINE_FEATURES</code> and when it
4112 finds "bluetooth" there it enables the bluetooth
4113 support in ConnMan.
4114 </p><p>
4115 For a list of features supported by the Yocto Project as shipped,
4116 see the "<a class="link" href="#ref-features-machine" title="9.2. Machine">Machine</a>" section.
4117 </p></dd><dt><a id="var-MACHINE_FEATURES_BACKFILL"></a>MACHINE_FEATURES_BACKFILL</dt><dd><p>Features to be added to
4118 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>
4119 if not also present in
4120 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED">MACHINE_FEATURES_BACKFILL_CONSIDERED</a></code>.
4121 </p><p>
4122 This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file.
4123 It is not intended to be user-configurable.
4124 It is best to just reference the variable to see which machine features are
4125 being backfilled for all machine configurations.
4126 See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for
4127 more information.
4128 </p></dd><dt><a id="var-MACHINE_FEATURES_BACKFILL_CONSIDERED"></a>MACHINE_FEATURES_BACKFILL_CONSIDERED</dt><dd><p>Features from
4129 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL">MACHINE_FEATURES_BACKFILL</a></code>
4130 that should not be backfilled (i.e. added to
4131 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>)
4132 during the build.
4133 See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for
4134 more information.
4135 </p></dd><dt><a id="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>The email address of the distribution maintainer.</p></dd><dt><a id="var-MLPREFIX"></a>MLPREFIX</dt><dd><p>
4136 Specifies a prefix has been added to
4137 <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> to create a special version
4138 of a recipe or package, such as a multilib version.
4139 The variable is used in places where the prefix needs to be
4140 added to or removed from a the name (e.g. the
4141 <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable).
4142 <code class="filename">MLPREFIX</code> gets set when a prefix has been
4143 added to <code class="filename">PN</code>.
4144 </p></dd><dt><a id="var-MULTIMACH_TARGET_SYS"></a>MULTIMACH_TARGET_SYS</dt><dd><p>
4145 Separates files for different machines such that you can build
4146 for multiple target machines using the same output directories.
4147 See the <a class="link" href="#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> variable
4148 for an example.
4149 </p></dd></dl></div><div class="glossdiv" title="O"><h3 class="title">O</h3><dl><dt><a id="var-OE_TERMINAL"></a>OE_TERMINAL</dt><dd><p>
4150 Controls how the OpenEmbedded build system spawns
4151 interactive terminals on the host development system
4152 (e.g. using the BitBake command with the
4153 <code class="filename">-c devshell</code> command-line option).
4154 For more information, see the
4155 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section
4156 in the Yocto Project Development Manual.
4157 </p><p>
4158 You can use the following values for the
4159 <code class="filename">OE_TERMINAL</code> variable:
4160 </p><pre class="literallayout">
4161 auto
4162 gnome
4163 xfce
4164 rxvt
4165 screen
4166 konsole
4167 none
4168 </pre><p>
4169 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Konsole support only works for KDE 3.x.
4170 Also, "auto" is the default behavior for
4171 <code class="filename">OE_TERMINAL</code></div><p>
4172 </p></dd></dl></div><div class="glossdiv" title="P"><h3 class="title">P</h3><dl><dt><a id="var-P"></a>P</dt><dd><p>The recipe name and version.
4173 <code class="filename">P</code> is comprised of the following:
4174 </p><pre class="literallayout">
4175 ${PN}-${PV}
4176 </pre></dd><dt><a id="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>The architecture of the resulting package or packages.</p></dd><dt><a id="var-PACKAGE_BEFORE_PN"></a>PACKAGE_BEFORE_PN</dt><dd><p>Enables easily adding packages to
4177 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
4178 before <code class="filename">${PN}</code> so that the packages can pick
4179 up files that would normally be included in the default package.</p></dd><dt><a id="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>This variable, which is set in the <code class="filename">local.conf</code> configuration
4180 file found in the <code class="filename">conf</code> folder of the
4181 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>,
4182 specifies the package manager to use when packaging data.
4183 You can provide one or more arguments for the variable with the first
4184 argument being the package manager used to create images:
4185 </p><pre class="literallayout">
4186 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
4187 </pre><p>
4188 For information on build performance effects as a result of the
4189 package manager use, see
4190 <a class="link" href="#ref-classes-package" title="7.13. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a>
4191 in this manual.
4192 </p></dd><dt><a id="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>Specifies the list of architectures compatible with the device CPU.
4193 This variable is useful when you build for several different devices that use
4194 miscellaneous processors such as XScale and ARM926-EJS).</p></dd><dt><a id="var-PACKAGECONFIG"></a>PACKAGECONFIG</dt><dd><p>
4195 This variable provides a means of enabling or disabling
4196 features of a recipe on a per-recipe basis.
4197 The <code class="filename">PACKAGECONFIG</code>
4198 variable itself specifies a space-separated list of the
4199 features to enable.
4200 The features themselves are specified as flags on the
4201 <code class="filename">PACKAGECONFIG</code> variable.
4202 You can provide up to four arguments, which are separated by
4203 commas, to determine the behavior of each feature
4204 when it is enabled or disabled.
4205 You can omit any argument you like but must retain the
4206 separating commas.
4207 The arguments specify the following:
4208 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Extra arguments
4209 that should be added to the configure script argument list
4210 (<a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF"><code class="filename">EXTRA_OECONF</code></a>)
4211 if the feature is enabled.</p></li><li class="listitem"><p>Extra arguments
4212 that should be added to <code class="filename">EXTRA_OECONF</code>
4213 if the feature is disabled.
4214 </p></li><li class="listitem"><p>Additional build dependencies
4215 (<a class="link" href="#var-DEPENDS" title="DEPENDS"><code class="filename">DEPENDS</code></a>)
4216 that should be added if the feature is enabled.
4217 </p></li><li class="listitem"><p>Additional runtime dependencies
4218 (<a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a>)
4219 that should be added if the feature is enabled.
4220 </p></li></ol></div><p>
4221 </p><p>
4222 Consider the following example taken from the
4223 <code class="filename">librsvg</code> recipe.
4224 In this example the feature is <code class="filename">croco</code>, which
4225 has three arguments that determine the feature's behavior.
4226 </p><pre class="literallayout">
4227 PACKAGECONFIG ??= "croco"
4228 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
4229 </pre><p>
4230 The <code class="filename">--with-croco</code> and
4231 <code class="filename">libcroco</code> arguments apply only if
4232 the feature is enabled.
4233 In this case, <code class="filename">--with-croco</code> is
4234 added to the configure script argument list and
4235 <code class="filename">libcroco</code> is added to
4236 <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code>.
4237 On the other hand, if the feature is disabled say through
4238 a <code class="filename">.bbappend</code> file in another layer, then
4239 the second argument <code class="filename">--without-croco</code> is
4240 added to the configure script rather than
4241 <code class="filename">--with-croco</code>.
4242 </p></dd><dt><a id="var-PACKAGES"></a>PACKAGES</dt><dd><p>The list of packages to be created from the recipe.
4243 The default value is the following:
4244 </p><pre class="literallayout">
4245 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
4246 </pre></dd><dt><a id="var-PACKAGES_DYNAMIC"></a>PACKAGES_DYNAMIC</dt><dd><p>
4247 A promise that your recipe satisfies runtime dependencies
4248 for optional modules that are found in other recipes.
4249 <code class="filename">PACKAGES_DYNAMIC</code>
4250 does not actually satisfy the dependencies, it only states that
4251 they should be satisfied.
4252 For example, if a hard, runtime dependency
4253 (<code class="filename">RDEPENDS</code>) of another package is satisfied
4254 at build time through the <code class="filename">PACKAGES_DYNAMIC</code>
4255 variable, but a package with the module name is never actually
4256 produced, then the other package will be broken.
4257 Thus, if you attempt to include that package in an image,
4258 you will get a dependency failure from the packaging system
4259 during <code class="filename">do_rootfs</code>.
4260 Typically, if there is a chance that such a situation can
4261 occur and the package that is not created is valid
4262 without the dependency being satisfied, then you should use
4263 <code class="filename">RRECOMMENDS</code> (a soft runtime dependency)
4264 instead of <code class="filename">RDEPENDS</code>.
4265 </p><p>
4266 For an example of how to use the <code class="filename">PACKAGES_DYNAMIC</code>
4267 variable when you are splitting packages, see the
4268 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#handling-optional-module-packaging" target="_top">Handling Optional Module Packaging</a>" section
4269 in the Yocto Project Development Manual.
4270 </p></dd><dt><a id="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt><dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the
4271 compile tasks.
4272 This variable is usually in the form <code class="filename">-j 4</code>, where the number
4273 represents the maximum number of parallel threads make can run.
4274 If you development host supports multiple cores a good rule of thumb is to set
4275 this variable to twice the number of cores on the host.</p></dd><dt><a id="var-PF"></a>PF</dt><dd><p>Specifies the recipe or package name and includes all version and revision
4276 numbers (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and
4277 <code class="filename">bash-4.2-r1/</code>).
4278 This variable is comprised of the following:
4279 </p><pre class="literallayout">
4280 ${PN}-${EXTENDPE}${PV}-${PR}
4281 </pre></dd><dt><a id="var-PN"></a>PN</dt><dd><p>This variable can have two separate functions depending on the context: a recipe
4282 name or a resulting package name.</p><p><code class="filename">PN</code> refers to a recipe name in the context of a file used
4283 by the OpenEmbedded build system as input to create a package.
4284 The name is normally extracted from the recipe file name.
4285 For example, if the recipe is named
4286 <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PN</code>
4287 will be "expat".</p><p>
4288 The variable refers to a package name in the context of a file created or produced by the
4289 OpenEmbedded build system.</p><p>If applicable, the <code class="filename">PN</code> variable also contains any special
4290 suffix or prefix.
4291 For example, using <code class="filename">bash</code> to build packages for the native
4292 machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>.
4293 Using <code class="filename">bash</code> to build packages for the target and for Multilib,
4294 <code class="filename">PN</code> would be <code class="filename">bash</code> and
4295 <code class="filename">lib64-bash</code>, respectively.
4296 </p></dd><dt><a id="var-PR"></a>PR</dt><dd><p>The revision of the recipe.
4297 The default value for this variable is "r0".
4298 </p></dd><dt><a id="var-PRINC"></a>PRINC</dt><dd><p>Causes the <code class="filename">PR</code> variable of
4299 <code class="filename">.bbappend</code> files to dynamically increment.
4300 This increment minimizes the impact of layer ordering.</p><p>In order to ensure multiple <code class="filename">.bbappend</code> files can co-exist,
4301 <code class="filename">PRINC</code> should be self referencing.
4302 This variable defaults to 0.</p><p>Following is an example that increments <code class="filename">PR</code> by two:
4303 </p><pre class="literallayout">
4304 PRINC := "${@int(PRINC) + 2}"
4305 </pre><p>
4306 It is adviseable not to use strings such as ".= '.1'" with the variable because
4307 this usage is very sensitive to layer ordering.
4308 Explicit assignments should be avoided as they cannot adequately represent multiple
4309 <code class="filename">.bbappend</code> files.</p></dd><dt><a id="var-PV"></a>PV</dt><dd><p>The version of the recipe.
4310 The version is normally extracted from the recipe filename.
4311 For example, if the recipe is named
4312 <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PV</code>
4313 will be "2.0.1".
4314 <code class="filename">PV</code> is generally not overridden within
4315 a recipe unless it is building an unstable (i.e. development) version from a source code repository
4316 (e.g. Git or Subversion).
4317 </p></dd><dt><a id="var-PE"></a>PE</dt><dd><p>
4318 the epoch of the recipe.
4319 The default value is "0".
4320 The field is used to make upgrades possible when the versioning scheme changes in
4321 some backwards incompatible way.
4322 </p></dd><dt><a id="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p>
4323 If multiple recipes provide an item, this variable
4324 determines which recipe should be given preference.
4325 The variable must always be suffixed with the name of the
4326 provided item, and should be set to the
4327 <code class="filename">PN</code> of the recipe
4328 to which you want to give precedence.
4329 Here is an example:
4330 </p><pre class="literallayout">
4331 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
4332 </pre><p>
4333 </p></dd><dt><a id="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p>
4334 If there are multiple versions of recipes available, this
4335 variable determines which recipe should be given preference.
4336 The variable must always be suffixed with the <code class="filename">PN</code>
4337 for which to select, and should be set to the
4338 <code class="filename">PV</code> to which you want to give precedence.
4339 You can use the "<code class="filename">%</code>" character as a wildcard
4340 to match any number of characters, which can be useful when
4341 specifying versions that contain long revision number that could
4342 potentially change.
4343 Here are two examples:
4344 </p><pre class="literallayout">
4345 PREFERRED_VERSION_python = "2.6.6"
4346 PREFERRED_VERSION_linux-yocto = "3.0+git%"
4347 </pre><p>
4348 </p></dd></dl></div><div class="glossdiv" title="R"><h3 class="title">R</h3><dl><dt><a id="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>The list of packages that conflict with a package.
4349 Note that the package will not be installed if the conflicting packages are not
4350 first removed.</p><p>
4351 Like all package-controlling variables, you must always use them in
4352 conjunction with a package name override.
4353 Here is an example:
4354 </p><pre class="literallayout">
4355 RCONFLICTS_${PN} = "another-conflicting-package-name"
4356 </pre><p>
4357 </p></dd><dt><a id="var-RDEPENDS"></a>RDEPENDS</dt><dd><p>
4358 Lists a package's run-time dependencies (i.e. other packages)
4359 that must be installed for the package to be built.
4360 In other words, in order for the package to be built and
4361 run correctly, it depends on the listed packages.
4362 If a package in this list cannot be found, it is probable
4363 that a dependency error would occur before the build.
4364 </p><p>
4365 The names of the variables you list with
4366 <code class="filename">RDEPENDS</code> must be the names of other
4367 packages as listed in the
4368 <a class="link" href="#var-PACKAGES" title="PACKAGES"><code class="filename">PACKAGES</code></a>
4369 variable.
4370 You should not list recipe names (<code class="filename">PN</code>).
4371 </p><p>
4372 Because the <code class="filename">RDEPENDS</code> variable applies
4373 to packages being built, you should
4374 always attach a package name to the variable to specify the
4375 particular run-time package that has the dependency.
4376 For example, suppose you are building a development package
4377 that depends on the <code class="filename">perl</code> package.
4378 In this case, you would use the following
4379 <code class="filename">RDEPENDS</code> statement:
4380 </p><pre class="literallayout">
4381 RDEPENDS_${PN}-dev += "perl"
4382 </pre><p>
4383 In the example, the package name
4384 (<code class="filename">${PN}-dev</code>) must appear as it would
4385 in the
4386 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
4387 namespace before any renaming of the output package by
4388 classes like <code class="filename">debian.bbclass</code>.
4389 </p><p>
4390 In many cases you do not need to explicitly add dependencies
4391 to <code class="filename">RDEPENDS</code> since some automatic
4392 handling occurs:
4393 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If
4394 a run-time package contains a shared library
4395 (<code class="filename">.so</code>), the build
4396 processes the library in order to determine other
4397 libraries to which it is dynamically linked.
4398 The build process adds these libraries to
4399 <code class="filename">RDEPENDS</code> when creating the run-time
4400 package.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If
4401 the package ships a <code class="filename">pkg-config</code>
4402 information file, the build process uses this file
4403 to add items to the <code class="filename">RDEPENDS</code>
4404 variable to create the run-time packages.
4405 </p></li></ul></div><p>
4406 </p></dd><dt><a id="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p>
4407 A list of packages that extend the usability of a package being
4408 built.
4409 The package being built does not depend on this list of packages in
4410 order to successfully build, but needs them for the extended usability.
4411 To specify runtime dependencies for packages, see the
4412 <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable.
4413 </p><p>
4414 The OpenEmbedded build process automatically installs the list of packages
4415 as part of the built package.
4416 However, you can remove them later if you want.
4417 If, during the build, a package from the list cannot be found, the build
4418 process continues without an error.
4419 </p><p>
4420 Because the <code class="filename">RRECOMMENDS</code> variable applies to packages
4421 being built, you should
4422 always attach an override to the variable to specify the particular package
4423 whose usability is being extended.
4424 For example, suppose you are building a development package that is extended
4425 to support wireless functionality.
4426 In this case, you would use the following:
4427 </p><pre class="literallayout">
4428 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
4429 </pre><p>
4430 In the example, the package name (<code class="filename">${PN}-dev</code>) must
4431 appear as it would in the
4432 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any
4433 renaming of the output package by classes like <code class="filename">debian.bbclass</code>.
4434 </p></dd><dt><a id="var-RREPLACES"></a>RREPLACES</dt><dd><p>The list of packages that are replaced with this package.</p></dd></dl></div><div class="glossdiv" title="S"><h3 class="title">S</h3><dl><dt><a id="var-S"></a>S</dt><dd><p>
4435 The location in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
4436 where unpacked package source code resides.
4437 This location is within the working directory
4438 (<code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which
4439 is not static.
4440 The unpacked source location depends on the package name
4441 (<code class="filename"><a class="link" href="#var-PN" title="PN">PN</a></code>) and
4442 package version (<code class="filename"><a class="link" href="#var-PV" title="PV">PV</a></code>) as
4443 follows:
4444 </p><pre class="literallayout">
4445 ${WORKDIR}/${PN}/${PV}
4446 </pre><p>
4447 As an example, assume a
4448 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> top-level
4449 folder named <code class="filename">poky</code>
4450 and a default <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
4451 at <code class="filename">poky/build</code>.
4452 In this case, the working directory the build system uses to build
4453 the <code class="filename">db</code> package is the following:
4454 </p><pre class="literallayout">
4455 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
4456 </pre><p>
4457 </p></dd><dt><a id="var-SDKIMAGE_FEATURES"></a>SDKIMAGE_FEATURES</dt><dd><p>Equivalent to
4458 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>.
4459 However, this variable applies to the SDK generated from an image using
4460 <code class="filename">bitbake -c populate_sdk imagename</code>).
4461 </p></dd><dt><a id="var-SECTION"></a>SECTION</dt><dd><p>The section in which packages should be categorized.
4462 Package management utilities can make use of this variable.</p></dd><dt><a id="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p>
4463 The variable takes the value of
4464 <code class="filename"><a class="link" href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code>
4465 unless <code class="filename"><a class="link" href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1".
4466 In this case the value of
4467 <code class="filename"><a class="link" href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used.
4468 </p></dd><dt><a id="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>The speed and device for the serial port used to attach the serial console.
4469 This variable is given to the kernel as the "console"
4470 parameter and after booting occurs <code class="filename">getty</code> is started on that port
4471 so remote login is possible.</p></dd><dt><a id="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt><dd><p>
4472 Specifies the endian byte order of the target system.
4473 The value should be either "le" for little-endian or "be" for big-endian.
4474 </p></dd><dt><a id="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p>
4475 Specifies the number of bits for the target system CPU.
4476 The value should be either "32" or "64".
4477 </p></dd><dt><a id="var-SPECIAL_PKGSUFFIX"></a>SPECIAL_PKGSUFFIX</dt><dd><p>
4478 A list of prefixes for <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> used by the
4479 OpenEmbedded build system to create variants of recipes or packages.
4480 The list specifies the prefixes to strip off during certain circumstances
4481 such as the generation of the <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable.
4482 </p></dd><dt><a id="var-SRC_URI"></a>SRC_URI</dt><dd><p>The list of source files - local or remote.
4483 This variable tells the OpenEmbedded build system which bits to pull
4484 in for the build and how to pull them in.
4485 For example, if the recipe only needs to fetch a tarball from the
4486 internet, the recipe uses a single <code class="filename">SRC_URI</code> entry.
4487 On the other hand, if the recipe needs to fetch a tarball, apply
4488 two patches, and include a custom file, the recipe would include four
4489 instances of the variable.</p><p>The following list explains the available URI protocols:
4490 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">file://</code> -</em></span> Fetches files, which is usually
4491 a file shipped with the metadata, from the local machine.
4492 The path is relative to the
4493 <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a>
4494 variable.
4495 Thus, the build system searches, in order, from the following directories,
4496 which are assumed to be a subdirectories of the directory in which the
4497 recipe file resides:
4498 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em><code class="filename">${PN}</code> -</em></span> The recipe name
4499 with any special suffix or prefix, if applicable.
4500 For example, using <code class="filename">bash</code> to build for the native
4501 machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>.
4502 Using <code class="filename">bash</code> to build for the target and for Multilib,
4503 <code class="filename">PN</code> would be <code class="filename">bash</code> and
4504 <code class="filename">lib64-bash</code>, respectively.
4505 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${PF}</code> - </em></span>
4506 <code class="filename">${PN}-${EXTENDPE}${PV}-${PR}</code>.
4507 The recipe name including all version and revision numbers
4508 (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and
4509 <code class="filename">bash-4.2-r1/</code>).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${P}</code> -</em></span>
4510 <code class="filename">${PN}-${PV}</code>.
4511 The recipe name and version (i.e. <code class="filename">bash-4.2</code>).
4512 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${BPN}</code> -</em></span> The
4513 base recipe name without any special suffix or version numbers.
4514 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${BP}</code> -</em></span>
4515 <code class="filename">${BPN}-${PV}</code>.
4516 The base recipe name and version but without any special
4517 package name suffix.</p></li><li class="listitem"><p><span class="emphasis"><em>Files -</em></span> Files beneath the directory in which the recipe
4518 resides.</p></li><li class="listitem"><p><span class="emphasis"><em>Directory -</em></span> The directory itself in which the recipe
4519 resides.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">bzr://</code> -</em></span> Fetches files from a
4520 Bazaar revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git://</code> -</em></span> Fetches files from a
4521 Git revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">osc://</code> -</em></span> Fetches files from
4522 an OSC (OpenSuse Build service) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">repo://</code> -</em></span> Fetches files from
4523 a repo (Git) repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">svk://</code> -</em></span> Fetches files from
4524 an SVK revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">http://</code> -</em></span> Fetches files from
4525 the Internet using <code class="filename">http</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">https://</code> -</em></span> Fetches files
4526 from the Internet using <code class="filename">https</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">ftp://</code> -</em></span> Fetches files
4527 from the Internet using <code class="filename">ftp</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">cvs://</code> -</em></span> Fetches files from
4528 a CVS revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">hg://</code> -</em></span> Fetches files from
4529 a Mercurial (<code class="filename">hg</code>) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">p4://</code> -</em></span> Fetches files from
4530 a Perforce (<code class="filename">p4</code>) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">ssh://</code> -</em></span> Fetches files from
4531 a secure shell.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">svn://</code> -</em></span> Fetches files from
4532 a Subversion (<code class="filename">svn</code>) revision control repository.</p></li></ul></div><p>
4533 </p><p>Standard and recipe-specific options for <code class="filename">SRC_URI</code> exist.
4534 Here are standard options:
4535 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">apply</code> -</em></span> Whether to apply
4536 the patch or not.
4537 The default action is to apply the patch.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">striplevel</code> -</em></span> Which
4538 striplevel to use when applying the patch.
4539 The default level is 1.</p></li></ul></div><p>
4540 </p><p>Here are options specific to recipes building code from a revision control system:
4541 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">mindate</code> -</em></span> Only applies
4542 the patch if <a class="link" href="#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a>
4543 is equal to or greater than <code class="filename">mindate</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">maxdate</code> -</em></span> Only applies
4544 the patch if <a class="link" href="#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a>
4545 is not later than <code class="filename">mindate</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">minrev</code> -</em></span> Only applies
4546 the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4547 is equal to or greater than <code class="filename">minrev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">maxrev</code> -</em></span> Only applies
4548 the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4549 is not later than <code class="filename">maxrev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rev</code> -</em></span> Only applies the
4550 patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4551 is equal to <code class="filename">rev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">notrev</code> -</em></span> Only applies
4552 the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4553 is not equal to <code class="filename">rev</code>.</p></li></ul></div><p>
4554 </p><p>Here are some additional options worth mentioning:
4555 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">unpack</code> -</em></span> Controls
4556 whether or not to unpack the file if it is an archive.
4557 The default action is to upack the file.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">subdir</code> -</em></span> Places the file
4558 (or extracts its contents) into the specified
4559 subdirectory of <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
4560 This option is useful for unusual tarballs or other archives that
4561 don't have their files already in a subdirectory within the archive.
4562 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">name</code> -</em></span> Specifies a
4563 name to be used for association with <code class="filename">SRC_URI</code> checksums
4564 when you have more than one file specified in <code class="filename">SRC_URI</code>.
4565 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">downloadfilename</code> -</em></span> Specifies
4566 the filename used when storing the downloaded file.</p></li></ul></div><p>
4567 </p></dd><dt><a id="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p></p><p>
4568 By default, the OpenEmbedded build system automatically detects whether
4569 <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>
4570 contains files that are machine-specific.
4571 If so, the build system automatically changes
4572 <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>.
4573 Setting this variable to "0" disables this behavior.
4574 </p></dd><dt><a id="var-SRCDATE"></a>SRCDATE</dt><dd><p>
4575 The date of the source code used to build the package.
4576 This variable applies only if the source was fetched from a Source Code Manager (SCM).
4577 </p></dd><dt><a id="var-SRCREV"></a>SRCREV</dt><dd><p>
4578 The revision of the source code used to build the package.
4579 This variable applies to Subversion, Git, Mercurial and Bazaar
4580 only.
4581 Note that if you wish to build a fixed revision and you wish
4582 to avoid performing a query on the remote repository every time
4583 BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a
4584 full revision identifier and not just a tag.
4585 </p></dd><dt><a id="var-SSTATE_DIR"></a>SSTATE_DIR</dt><dd><p>The directory for the shared state.</p></dd><dt><a id="var-SSTATE_MIRRORS"></a>SSTATE_MIRRORS</dt><dd><p>
4586 Configures the OpenEmbedded build system to search other
4587 mirror locations for prebuilt cache data objects before
4588 building out the data.
4589 This variable works like fetcher
4590 <code class="filename">MIRRORS</code>/<code class="filename">PREMIRRORS</code>
4591 and points to the cache locations to check for the shared
4592 objects.
4593 </p><p>
4594 You can specify a filesystem directory or a remote URL such
4595 as HTTP or FTP.
4596 The locations you specify need to contain the shared state
4597 cache (sstate-cache) results from previous builds.
4598 The sstate-cache you point to can also be from builds on
4599 other machines.
4600 </p><p>
4601 If a mirror uses the same structure as
4602 <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a>,
4603 you need to add
4604 "PATH" at the end as shown in the examples below.
4605 The build system substitues the correct path within the
4606 directory structure.
4607 </p><pre class="literallayout">
4608 SSTATE_MIRRORS ?= "\
4609 file://.* http://someserver.tld/share/sstate/PATH \n \
4610 file://.* file:///some/local/dir/sstate/PATH"
4611 </pre><p>
4612 </p></dd><dt><a id="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p>
4613 The directory with kernel headers that are required to build out-of-tree
4614 modules.
4615 </p></dd><dt><a id="var-STAMP"></a>STAMP</dt><dd><p>
4616 Specifies the base path used to create recipe stamp files.
4617 The path to an actual stamp file is constructed by evaluating this
4618 string and then appending additional information.
4619 Currently, the default assignment for <code class="filename">STAMP</code>
4620 as set in the <code class="filename">meta/conf/bitbake.conf</code> file
4621 is:
4622 </p><pre class="literallayout">
4623 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
4624 </pre><p>
4625 See <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>,
4626 <a class="link" href="#var-MULTIMACH_TARGET_SYS" title="MULTIMACH_TARGET_SYS"><code class="filename">MULTIMACH_TARGET_SYS</code></a>,
4627 <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a>,
4628 <a class="link" href="#var-EXTENDPE" title="EXTENDPE"><code class="filename">EXTENDPE</code></a>,
4629 <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>, and
4630 <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> for related variable
4631 information.
4632 </p></dd><dt><a id="var-SUMMARY"></a>SUMMARY</dt><dd><p>The short (72 characters or less) summary of the binary package for packaging
4633 systems such as <code class="filename">opkg</code>, <code class="filename">rpm</code> or
4634 <code class="filename">dpkg</code>.
4635 By default, <code class="filename">SUMMARY</code> is used to define
4636 the <a class="link" href="#var-DESCRIPTION" title="DESCRIPTION"><code class="filename">DESCRIPTION</code></a>
4637 variable if <code class="filename">DESCRIPTION</code> is not set
4638 in the recipe.
4639 </p></dd></dl></div><div class="glossdiv" title="T"><h3 class="title">T</h3><dl><dt><a id="var-T"></a>T</dt><dd><p>This variable points to a directory were Bitbake places temporary
4640 files when building a particular package.
4641 It is typically set as follows:
4642 </p><pre class="literallayout">
4643 T = ${WORKDIR}/temp
4644 </pre><p>
4645 The <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>
4646 is the directory into which Bitbake unpacks and builds the package.
4647 The default <code class="filename">bitbake.conf</code> file sets this variable.</p><p>The <code class="filename">T</code> variable is not to be confused with
4648 the <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> variable,
4649 which points to the root of the directory tree where Bitbake
4650 places the output of an entire build.
4651 </p></dd><dt><a id="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device being built.
4652 While a number of values are possible, the OpenEmbedded build system primarily supports
4653 <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd><dt><a id="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p>
4654 Flags passed to the C compiler for the target system.
4655 This variable evaluates to the same as
4656 <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>.
4657 </p></dd><dt><a id="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Specifies the method for handling FPU code.
4658 For FPU-less targets, which include most ARM CPUs, the variable must be
4659 set to "soft".
4660 If not, the kernel emulation gets used, which results in a performance penalty.</p></dd><dt><a id="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Specifies the target's operating system.
4661 The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and
4662 to "linux-uclibc" for <code class="filename">uclibc</code>.
4663 For ARM/EABI targets, there are also "linux-gnueabi" and
4664 "linux-uclibc-gnueabi" values possible.</p></dd><dt><a id="var-TCLIBC"></a>TCLIBC</dt><dd><p>
4665 Specifies which variant of the GNU standard C library (<code class="filename">libc</code>)
4666 to use during the build process.
4667 This variable replaces <code class="filename">POKYLIBC</code>, which is no longer
4668 supported.
4669 </p><p>
4670 You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>.
4671 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
4672 This release of the Yocto Project does not support the
4673 <code class="filename">glibc</code> implementation of <code class="filename">libc</code>.
4674 </div><p>
4675 </p></dd><dt><a id="var-TCMODE"></a>TCMODE</dt><dd><p>
4676 The toolchain selector.
4677 This variable replaces <code class="filename">POKYMODE</code>, which is no longer
4678 supported.
4679 </p><p>
4680 The <code class="filename">TCMODE</code> variable selects the external toolchain
4681 built using the OpenEmbedded build system or a few supported combinations of
4682 the upstream GCC or CodeSourcery Labs toolchain.
4683 The variable identifies the <code class="filename">tcmode-*</code> files used in
4684 the <code class="filename">meta/conf/distro/include</code> directory, which is found in the
4685 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
4686 </p><p>
4687 By default, <code class="filename">TCMODE</code> is set to "default", which
4688 chooses the <code class="filename">tcmode-default.inc</code> file.
4689 The variable is similar to
4690 <a class="link" href="#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls
4691 the variant of the GNU standard C library (<code class="filename">libc</code>)
4692 used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>.
4693 </p></dd><dt><a id="var-TMPDIR"></a>TMPDIR</dt><dd><p>
4694 This variable is the temporary directory the OpenEmbedded build system
4695 uses when it does its work building images.
4696 By default, the <code class="filename">TMPDIR</code> variable is named
4697 <code class="filename">tmp</code> within the
4698 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
4699 </p><p>
4700 If you want to establish this directory in a location other than the
4701 default, you can uncomment the following statement in the
4702 <code class="filename">conf/local.conf</code> file in the
4703 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>:
4704 </p><pre class="literallayout">
4705 #TMPDIR = "${TOPDIR}/tmp"
4706 </pre><p>
4707 </p></dd><dt><a id="var-TOPDIR"></a>TOPDIR</dt><dd><p>
4708 This variable is the
4709 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
4710 BitBake automatically sets this variable.
4711 The OpenEmbedded build system uses the Build Directory when building images.
4712 </p></dd></dl></div><div class="glossdiv" title="W"><h3 class="title">W</h3><dl><dt><a id="var-WORKDIR"></a>WORKDIR</dt><dd><p>
4713 The pathname of the working directory in which the OpenEmbedded build system
4714 builds a recipe.
4715 This directory is located within the
4716 <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes
4717 as different packages are built.
4718 </p><p>
4719 The actual <code class="filename">WORKDIR</code> directory depends on several things:
4720 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The temporary directory - <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a></li><li class="listitem">The package architecture - <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH"><code class="filename">PACKAGE_ARCH</code></a></li><li class="listitem">The target machine - <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a></li><li class="listitem">The target operating system - <a class="link" href="#var-TARGET_OS" title="TARGET_OS"><code class="filename">TARGET_OS</code></a></li><li class="listitem">The recipe name - <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a></li><li class="listitem">The recipe version - <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a></li><li class="listitem">The recipe revision - <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a></li></ul></div><p>
4721 </p><p>
4722 For packages that are not dependent on a particular machine,
4723 <code class="filename">WORKDIR</code> is defined as follows:
4724 </p><pre class="literallayout">
4725 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
4726 </pre><p>
4727 As an example, assume a
4728 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> top-level
4729 folder name <code class="filename">poky</code> and a default
4730 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
4731 at <code class="filename">poky/build</code>.
4732 In this case, the working directory the build system uses to build
4733 the <code class="filename">v86d</code> package is the following:
4734 </p><pre class="literallayout">
4735 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
4736 </pre><p>
4737 </p><p>
4738 For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code>
4739 is defined slightly different:
4740 </p><pre class="literallayout">
4741 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
4742 </pre><p>
4743 As an example, again assume a Source Directory top-level folder
4744 named <code class="filename">poky</code> and a default Build Directory
4745 at <code class="filename">poky/build</code>.
4746 In this case, the working directory the build system uses to build
4747 the <code class="filename">acl</code> recipe, which is being built for a
4748 MIPS-based device, is the following:
4749 </p><pre class="literallayout">
4750 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
4751 </pre><p>
4752 </p></dd></dl></div></div></div>
4753
4754 <div class="chapter" title="Chapter 11. Variable Context"><div class="titlepage"><div><div><h2 class="title"><a id="ref-varlocality"></a>Chapter 11. Variable Context</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-varlocality-configuration">11.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">11.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">11.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">11.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">11.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">11.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">11.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">11.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">11.2.4. Extra Build Information</a></span></dt></dl></dd></dl></div><p>
4755 While most variables can be used in almost any context such as
4756 <code class="filename">.conf</code>, <code class="filename">.bbclass</code>,
4757 <code class="filename">.inc</code>, and <code class="filename">.bb</code> files,
4758 some variables are often associated with a particular locality or context.
4759 This chapter describes some common associations.
4760 </p><div class="section" title="11.1. Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-configuration"></a>11.1. Configuration</h2></div></div></div><p>
4761 The following subsections provide lists of variables whose context is
4762 configuration: distribution, machine, and local.
4763 </p><div class="section" title="11.1.1. Distribution (Distro)"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-distro"></a>11.1.1. Distribution (Distro)</h3></div></div></div><p>
4764 This section lists variables whose context is the distribution, or distro.
4765 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></code>
4766 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a>
4767 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code>
4768 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a>
4769 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></code>
4770 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></code>
4771 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code>
4772 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCLIBC" title="TCLIBC">TCLIBC</a></code>
4773 </p></li></ul></div><p>
4774 </p></div><div class="section" title="11.1.2. Machine"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-machine"></a>11.1.2. Machine</h3></div></div></div><p>
4775 This section lists variables whose context is the machine.
4776 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></code>
4777 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a>
4778 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a>
4779 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a>
4780 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a>
4781 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS
4782 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS
4783 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS
4784 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">
4785 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li></ul></div><p>
4786 </p></div><div class="section" title="11.1.3. Local"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-local"></a>11.1.3. Local</h3></div></div></div><p>
4787 This section lists variables whose context is the local configuration through the
4788 <code class="filename">local.conf</code> file.
4789 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code>
4790 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code>
4791 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>
4792 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code>
4793 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES
4794 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a>
4795 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a>
4796 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a>
4797 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">
4798 ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li></ul></div><p>
4799 </p></div></div><div class="section" title="11.2. Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-recipes"></a>11.2. Recipes</h2></div></div></div><p>
4800 The following subsections provide lists of variables whose context is
4801 recipes: required, dependencies, path, and extra build information.
4802 </p><div class="section" title="11.2.1. Required"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-required"></a>11.2.1. Required</h3></div></div></div><p>
4803 This section lists variables that are required for recipes.
4804 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a>
4805 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a>
4806 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> - used
4807 in recipes that fetch local or remote files.
4808 </p></li></ul></div><p>
4809 </p></div><div class="section" title="11.2.2. Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-dependencies"></a>11.2.2. Dependencies</h3></div></div></div><p>
4810 This section lists variables that define recipe dependencies.
4811 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a>
4812 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a>
4813 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a>
4814 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a>
4815 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RREPLACES" title="RREPLACES">RREPLACES</a>
4816 </code></p></li></ul></div><p>
4817 </p></div><div class="section" title="11.2.3. Paths"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-paths"></a>11.2.3. Paths</h3></div></div></div><p>
4818 This section lists variables that define recipe paths.
4819 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a>
4820 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-S" title="S">S</a>
4821 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a>
4822 </code></p></li></ul></div><p>
4823 </p></div><div class="section" title="11.2.4. Extra Build Information"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-build"></a>11.2.4. Extra Build Information</h3></div></div></div><p>
4824 This section lists variables that define extra build information for recipes.
4825 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a>
4826 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a>
4827 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a>
4828 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
4829 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE
4830 </a></code></p></li></ul></div><p>
4831 </p></div></div></div>
4832
4833 <div class="chapter" title="Chapter 12. FAQ"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Chapter 12. FAQ</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><a id="idm975296"></a><dl><dt>12.1. <a href="#idm974832">
4834 How does Poky differ from OpenEmbedded?
4835 </a></dt><dt>12.2. <a href="#idp1801248">
4836 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
4837 Can I still use the Yocto Project?
4838 </a></dt><dt>12.3. <a href="#idm1781424">
4839 How can you claim Poky / OpenEmbedded-Core is stable?
4840 </a></dt><dt>12.4. <a href="#idm1777456">
4841 How do I get support for my board added to the Yocto Project?
4842 </a></dt><dt>12.5. <a href="#idm345792">
4843 Are there any products built using the OpenEmbedded build system?
4844 </a></dt><dt>12.6. <a href="#idm343136">
4845 What does the OpenEmbedded build system produce as output?
4846 </a></dt><dt>12.7. <a href="#idm341840">
4847 How do I add my package to the Yocto Project?
4848 </a></dt><dt>12.8. <a href="#idp1600368">
4849 Do I have to reflash my entire board with a new Yocto Project image when recompiling
4850 a package?
4851 </a></dt><dt>12.9. <a href="#idp1603824">
4852 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
4853 </a></dt><dt>12.10. <a href="#idp1605872">
4854 I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'.
4855 What is wrong?
4856 </a></dt><dt>12.11. <a href="#idp1662416">
4857 How do I make the Yocto Project work in RHEL/CentOS?
4858 </a></dt><dt>12.12. <a href="#idp562304">
4859 I see lots of 404 responses for files on
4860 http://www.yoctoproject.org/sources/*. Is something wrong?
4861 </a></dt><dt>12.13. <a href="#idp179952">
4862 I have machine-specific data in a package for one machine only but the package is
4863 being marked as machine-specific in all cases, how do I prevent this?
4864 </a></dt><dt>12.14. <a href="#idp184672">
4865 I'm behind a firewall and need to use a proxy server. How do I do that?
4866 </a></dt><dt>12.15. <a href="#idp1585952">
4867 What’s the difference between foo and foo-native?
4868 </a></dt><dt>12.16. <a href="#idp3269536">
4869 I'm seeing random build failures. Help?!
4870 </a></dt><dt>12.17. <a href="#idp3271104">
4871 What do we need to ship for license compliance?
4872 </a></dt><dt>12.18. <a href="#idp3272560">
4873 How do I disable the cursor on my touchscreen device?
4874 </a></dt><dt>12.19. <a href="#idp3244640">
4875 How do I make sure connected network interfaces are brought up by default?
4876 </a></dt><dt>12.20. <a href="#idp3248256">
4877 How do I create images with more free space?
4878 </a></dt><dt>12.21. <a href="#idp348464">
4879 Why don't you support directories with spaces in the pathnames?
4880 </a></dt><dt>12.22. <a href="#idp350512">
4881 How do I use an external toolchain?
4882 </a></dt><dt>12.23. <a href="#idm184288">
4883 How does the OpenEmbedded build system obtain source code and will it work behind my
4884 firewall or proxy server?
4885 </a></dt><dt>12.24. <a href="#idm1036560">
4886 Can I get rid of build output so I can start over?
4887 </a></dt></dl><table border="0" width="100%" summary="Q and A Set"><col align="left" width="1%" /><col /><tbody><tr class="question" title="12.1."><td align="left" valign="top"><a id="idm974832"></a><a id="idm974704"></a><p><strong>12.1.</strong></p></td><td align="left" valign="top"><p>
4888 How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>?
4889 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4890 The term "Poky" refers to the specific reference build system that
4891 the Yocto Project provides.
4892 Poky is based on <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#oe-core" target="_top">OE-Core</a>
4893 and BitBake.
4894 Thus, the generic term used here for the build system is
4895 the "OpenEmbedded build system."
4896 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
4897 changes always being merged to OE-Core or BitBake first before being pulled back
4898 into Poky.
4899 This practice benefits both projects immediately.
4900 For a fuller description of the term "Poky", see the
4901 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">poky</a> term in the Yocto Project
4902 Development Manual.
4903 </p></td></tr><tr class="question" title="12.2."><td align="left" valign="top"><a id="idp1801248"></a><a id="idp1801376"></a><p><strong>12.2.</strong></p></td><td align="left" valign="top"><p>
4904 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
4905 Can I still use the Yocto Project?
4906 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4907 You can use a stand-alone tarball to provide Python 2.6.
4908 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
4909 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2" target="_top">32-bit tarball</a></p></li><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2" target="_top">64-bit tarball</a></p></li></ul></div><p>
4910 </p><p>
4911 These tarballs are self-contained with all required libraries and should work
4912 on most Linux systems.
4913 To use the tarballs extract them into the root
4914 directory and run the appropriate command:
4915 </p><pre class="literallayout">
4916 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
4917 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
4918 </pre><p>
4919 </p><p>
4920 Once you run the command, BitBake uses Python 2.6.
4921 </p></td></tr><tr class="question" title="12.3."><td align="left" valign="top"><a id="idm1781424"></a><a id="idm1781296"></a><p><strong>12.3.</strong></p></td><td align="left" valign="top"><p>
4922 How can you claim Poky / OpenEmbedded-Core is stable?
4923 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4924 There are three areas that help with stability;
4925 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Yocto Project team keeps
4926 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#oe-core" target="_top">OE-Core</a> small
4927 and focused, containing around 830 recipes as opposed to the thousands
4928 available in other OpenEmbedded community layers.
4929 Keeping it small makes it easy to test and maintain.</p></li><li class="listitem"><p>The Yocto Project team runs manual and automated tests
4930 using a small, fixed set of reference hardware as well as emulated
4931 targets.</p></li><li class="listitem"><p>The Yocto Project uses an an autobuilder,
4932 which provides continuous build and integration tests.</p></li></ul></div><p>
4933 </p></td></tr><tr class="question" title="12.4."><td align="left" valign="top"><a id="idm1777456"></a><a id="idm1777328"></a><p><strong>12.4.</strong></p></td><td align="left" valign="top"><p>
4934 How do I get support for my board added to the Yocto Project?
4935 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4936 Support for an additional board is added by creating a BSP layer for it.
4937 For more information on how to create a BSP layer, see the
4938 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>.
4939 </p><p>
4940 Usually, if the board is not completely exotic, adding support in
4941 the Yocto Project is fairly straightforward.
4942 </p></td></tr><tr class="question" title="12.5."><td align="left" valign="top"><a id="idm345792"></a><a id="idm345664"></a><p><strong>12.5.</strong></p></td><td align="left" valign="top"><p>
4943 Are there any products built using the OpenEmbedded build system?
4944 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4945 The software running on the <a class="ulink" href="http://vernier.com/labquest/" target="_top">Vernier LabQuest</a>
4946 is built using the OpenEmbedded build system.
4947 See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_top">Vernier LabQuest</a>
4948 website for more information.
4949 There are a number of pre-production devices using the OpenEmbedded build system
4950 and the Yocto Project team
4951 announces them as soon as they are released.
4952 </p></td></tr><tr class="question" title="12.6."><td align="left" valign="top"><a id="idm343136"></a><a id="idm343008"></a><p><strong>12.6.</strong></p></td><td align="left" valign="top"><p>
4953 What does the OpenEmbedded build system produce as output?
4954 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4955 Because the same set of recipes can be used to create output of various formats, the
4956 output of an OpenEmbedded build depends on how it was started.
4957 Usually, the output is a flashable image ready for the target device.
4958 </p></td></tr><tr class="question" title="12.7."><td align="left" valign="top"><a id="idm341840"></a><a id="idm341712"></a><p><strong>12.7.</strong></p></td><td align="left" valign="top"><p>
4959 How do I add my package to the Yocto Project?
4960 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4961 To add a package, you need to create a BitBake recipe.
4962 For information on how to add a package, see the section
4963 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-addpkg" target="_top">Adding a Package</a>"
4964 in the Yocto Project Development Manual.
4965 </p></td></tr><tr class="question" title="12.8."><td align="left" valign="top"><a id="idp1600368"></a><a id="idp1600496"></a><p><strong>12.8.</strong></p></td><td align="left" valign="top"><p>
4966 Do I have to reflash my entire board with a new Yocto Project image when recompiling
4967 a package?
4968 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4969 The OpenEmbedded build system can build packages in various formats such as
4970 <code class="filename">ipk</code> for <code class="filename">opkg</code>,
4971 Debian package (<code class="filename">.deb</code>), or RPM.
4972 The packages can then be upgraded using the package tools on the device, much like
4973 on a desktop distribution such as Ubuntu or Fedora.
4974 </p></td></tr><tr class="question" title="12.9."><td align="left" valign="top"><a id="idp1603824"></a><a id="idp1603952"></a><p><strong>12.9.</strong></p></td><td align="left" valign="top"><p>
4975 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
4976 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4977 GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_top">GNOME</a>
4978 platform targeted at mobile and embedded devices.
4979 The the main difference between GNOME Mobile and standard GNOME is that
4980 desktop-orientated libraries have been removed, along with deprecated libraries,
4981 creating a much smaller footprint.
4982 </p></td></tr><tr class="question" title="12.10."><td align="left" valign="top"><a id="idp1605872"></a><a id="idp1606000"></a><p><strong>12.10.</strong></p></td><td align="left" valign="top"><p>
4983 I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'.
4984 What is wrong?
4985 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4986 You are probably running the build on an NTFS filesystem.
4987 Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead.
4988 </p></td></tr><tr class="question" title="12.11."><td align="left" valign="top"><a id="idp1662416"></a><a id="idp1662544"></a><p><strong>12.11.</strong></p></td><td align="left" valign="top"><p>
4989 How do I make the Yocto Project work in RHEL/CentOS?
4990 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4991 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
4992 install some required packages.
4993 The standard CentOS packages needed are:
4994 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>"Development tools" (selected during installation)</p></li><li class="listitem"><p><code class="filename">texi2html</code></p></li><li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li></ul></div><p>
4995 On top of these, you need the following external packages:
4996 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">python-sqlite2</code> from
4997 <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG repository</a>
4998 </p></li><li class="listitem"><p><code class="filename">help2man</code> from
4999 <a class="ulink" href="http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html" target="_top">Karan repository</a></p></li></ul></div><p>
5000 </p><p>
5001 Once these packages are installed, the OpenEmbedded build system will be able
5002 to build standard images.
5003 However, there might be a problem with the QEMU emulator segfaulting.
5004 You can either disable the generation of binary locales by setting
5005 <code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a>
5006 </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code>
5007 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
5008 </p></td></tr><tr class="question" title="12.12."><td align="left" valign="top"><a id="idp562304"></a><a id="idp562432"></a><p><strong>12.12.</strong></p></td><td align="left" valign="top"><p>
5009 I see lots of 404 responses for files on
5010 <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong?
5011 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5012 Nothing is wrong.
5013 The OpenEmbedded build system checks any configured source mirrors before downloading
5014 from the upstream sources.
5015 The build system does this searching for both source archives and
5016 pre-checked out versions of SCM managed software.
5017 These checks help in large installations because it can reduce load on the SCM servers
5018 themselves.
5019 The address above is one of the default mirrors configured into the
5020 build system.
5021 Consequently, if an upstream source disappears, the team
5022 can place sources there so builds continue to work.
5023 </p></td></tr><tr class="question" title="12.13."><td align="left" valign="top"><a id="idp179952"></a><a id="idp180080"></a><p><strong>12.13.</strong></p></td><td align="left" valign="top"><p>
5024 I have machine-specific data in a package for one machine only but the package is
5025 being marked as machine-specific in all cases, how do I prevent this?
5026 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5027 Set <code class="filename"><a class="link" href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a>
5028 </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is
5029 manually marked as
5030 machine-specific in the case that needs it.
5031 The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>.
5032 </p></td></tr><tr class="question" title="12.14."><td align="left" valign="top"><a id="idp184672"></a><a id="idp1581568"></a><p><strong>12.14.</strong></p></td><td align="left" valign="top"><p>
5033 I'm behind a firewall and need to use a proxy server. How do I do that?
5034 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5035 Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code>
5036 and you therefore need to specify the proxy settings in a
5037 <code class="filename">.wgetrc</code> file in your home directory.
5038 Example settings in that file would be
5039 </p><pre class="literallayout">
5040 http_proxy = http://proxy.yoyodyne.com:18023/
5041 ftp_proxy = http://proxy.yoyodyne.com:18023/
5042 </pre><p>
5043 The Yocto Project also includes a <code class="filename">site.conf.sample</code>
5044 file that shows how to configure CVS and Git proxy servers
5045 if needed.
5046 </p></td></tr><tr class="question" title="12.15."><td align="left" valign="top"><a id="idp1585952"></a><a id="idp1586080"></a><p><strong>12.15.</strong></p></td><td align="left" valign="top"><p>
5047 What’s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>?
5048 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5049 The <code class="filename">*-native</code> targets are designed to run on the system
5050 being used for the build.
5051 These are usually tools that are needed to assist the build in some way such as
5052 <code class="filename">quilt-native</code>, which is used to apply patches.
5053 The non-native version is the one that runs on the target device.
5054 </p></td></tr><tr class="question" title="12.16."><td align="left" valign="top"><a id="idp3269536"></a><a id="idp3269664"></a><p><strong>12.16.</strong></p></td><td align="left" valign="top"><p>
5055 I'm seeing random build failures. Help?!
5056 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5057 If the same build is failing in totally different and random ways,
5058 the most likely explanation is that either the hardware you're running the
5059 build on has some problem, or, if you are running the build under virtualisation,
5060 the virtualisation probably has bugs.
5061 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
5062 CPU activity and is sensitive to even single bit failures in any of these areas.
5063 True random failures have always been traced back to hardware or virtualisation issues.
5064 </p></td></tr><tr class="question" title="12.17."><td align="left" valign="top"><a id="idp3271104"></a><a id="idp3271232"></a><p><strong>12.17.</strong></p></td><td align="left" valign="top"><p>
5065 What do we need to ship for license compliance?
5066 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5067 This is a difficult question and you need to consult your lawyer for the answer
5068 for your specific case.
5069 It is worth bearing in mind that for GPL compliance there needs to be enough
5070 information shipped to allow someone else to rebuild the same end result
5071 you are shipping.
5072 This means sharing the source code, any patches applied to it, and also any
5073 configuration information about how that package was configured and built.
5074 </p></td></tr><tr class="question" title="12.18."><td align="left" valign="top"><a id="idp3272560"></a><a id="idp3272688"></a><p><strong>12.18.</strong></p></td><td align="left" valign="top"><p>
5075 How do I disable the cursor on my touchscreen device?
5076 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5077 You need to create a form factor file as described in the
5078 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>"
5079 section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows:
5080 </p><pre class="literallayout">
5081 HAVE_TOUCHSCREEN=1
5082 </pre><p>
5083 </p></td></tr><tr class="question" title="12.19."><td align="left" valign="top"><a id="idp3244640"></a><a id="idp3244768"></a><p><strong>12.19.</strong></p></td><td align="left" valign="top"><p>
5084 How do I make sure connected network interfaces are brought up by default?
5085 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5086 The default interfaces file provided by the netbase recipe does not
5087 automatically bring up network interfaces.
5088 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
5089 file.
5090 See the "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>"
5091 section for information on creating these types of miscellaneous recipe files.
5092 </p><p>
5093 For example, add the following files to your layer:
5094 </p><pre class="literallayout">
5095 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
5096 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
5097 </pre><p>
5098 </p></td></tr><tr class="question" title="12.20."><td align="left" valign="top"><a id="idp3248256"></a><a id="idp3248384"></a><p><strong>12.20.</strong></p></td><td align="left" valign="top"><p>
5099 How do I create images with more free space?
5100 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5101 Images are created to be 1.2 times the size of the populated root filesystem.
5102 To modify this ratio so that there is more free space available, you need to
5103 set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>.
5104 For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets
5105 the image size ratio to one and a half times the size of the populated
5106 root filesystem.
5107 </p><pre class="literallayout">
5108 IMAGE_OVERHEAD_FACTOR = "1.5"
5109 </pre><p>
5110 </p></td></tr><tr class="question" title="12.21."><td align="left" valign="top"><a id="idp348464"></a><a id="idp348592"></a><p><strong>12.21.</strong></p></td><td align="left" valign="top"><p>
5111 Why don't you support directories with spaces in the pathnames?
5112 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5113 The Yocto Project team has tried to do this before but too many of the tools
5114 the OpenEmbedded build system depends on such as <code class="filename">autoconf</code>
5115 break when they find spaces in pathnames.
5116 Until that situation changes, the team will not support spaces in pathnames.
5117 </p></td></tr><tr class="question" title="12.22."><td align="left" valign="top"><a id="idp350512"></a><a id="idp350640"></a><p><strong>12.22.</strong></p></td><td align="left" valign="top"><p>
5118 How do I use an external toolchain?
5119 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5120 The toolchain configuration is very flexible and customizable.
5121 It is primarily controlled with the
5122 <code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> variable.
5123 This variable controls which <code class="filename">tcmode-*.inc</code> file to include
5124 from the <code class="filename">meta/conf/distro/include</code> directory within the
5125 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a>.
5126 </p><p>
5127 The default value of <code class="filename">TCMODE</code> is "default"
5128 (i.e. <code class="filename">tcmode-default.inc</code>).
5129 However, other patterns are accepted.
5130 In particular, "external-*" refers to external toolchains of which there are some
5131 basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>).
5132 You can use your own custom toolchain definition in your own layer
5133 (or as defined in the <code class="filename">local.conf</code> file) at the location
5134 <code class="filename">conf/distro/include/tcmode-*.inc</code>.
5135 </p><p>
5136 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
5137 This recipe file needs to package up any pre-built objects in the toolchain such as
5138 <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>,
5139 any locales, and <code class="filename">libc</code>.
5140 An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located
5141 in <code class="filename">meta/recipes-core/meta/</code> within the source directory.
5142 </p></td></tr><tr class="question" title="12.23."><td align="left" valign="top"><a id="idm184288"></a><a id="idm1835680"></a><p><strong>12.23.</strong></p></td><td align="left" valign="top"><p><a id="how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server"></a>
5143 How does the OpenEmbedded build system obtain source code and will it work behind my
5144 firewall or proxy server?
5145 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5146 The way the build system obtains source code is highly configurable.
5147 You can setup the build system to get source code in most environments if
5148 HTTP transport is available.
5149 </p><p>
5150 When the build system searches for source code, it first tries the local download directory.
5151 If that location fails, Poky tries PREMIRRORS, the upstream source,
5152 and then MIRRORS in that order.
5153 </p><p>
5154 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
5155 for SCM-based sources,
5156 upstreams for normal tarballs, and then falls back to a number of other mirrors
5157 including the Yocto Project source mirror if those fail.
5158 </p><p>
5159 As an example, you could add a specific server for Poky to attempt before any
5160 others by adding something like the following to the <code class="filename">local.conf</code>
5161 configuration file:
5162 </p><pre class="literallayout">
5163 PREMIRRORS_prepend = "\
5164 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5165 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5166 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5167 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5168 </pre><p>
5169 </p><p>
5170 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
5171 requests and direct them to the <code class="filename">http://</code> sources mirror.
5172 You can use <code class="filename">file://</code> URLs to point to local directories
5173 or network shares as well.
5174 </p><p>
5175 Aside from the previous technique, these options also exist:
5176 </p><pre class="literallayout">
5177 BB_NO_NETWORK = "1"
5178 </pre><p>
5179 This statement tells BitBake to throw an error instead of trying to access the
5180 Internet.
5181 This technique is useful if you want to ensure code builds only from local sources.
5182 </p><p>
5183 Here is another technique:
5184 </p><pre class="literallayout">
5185 BB_FETCH_PREMIRRORONLY = "1"
5186 </pre><p>
5187 This statement limits Poky to pulling source from the PREMIRRORS only.
5188 Again, this technique is useful for reproducing builds.
5189 </p><p>
5190 Here is another technique:
5191 </p><pre class="literallayout">
5192 BB_GENERATE_MIRROR_TARBALLS = "1"
5193 </pre><p>
5194 This statement tells Poky to generate mirror tarballs.
5195 This technique is useful if you want to create a mirror server.
5196 If not, however, the technique can simply waste time during the build.
5197 </p><p>
5198 Finally, consider an example where you are behind an HTTP-only firewall.
5199 You could make the following changes to the <code class="filename">local.conf</code>
5200 configuration file as long as the PREMIRROR server is up to date:
5201 </p><pre class="literallayout">
5202 PREMIRRORS_prepend = "\
5203 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5204 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5205 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5206 BB_FETCH_PREMIRRORONLY = "1"
5207 </pre><p>
5208 These changes would cause Poky to successfully fetch source over HTTP and
5209 any network accesses to anything other than the PREMIRROR would fail.
5210 </p><p>
5211 The build system also honors the standard shell environment variables
5212 <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>,
5213 <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code>
5214 to redirect requests through proxy servers.
5215 </p></td></tr><tr class="question" title="12.24."><td align="left" valign="top"><a id="idm1036560"></a><a id="idm1036432"></a><p><strong>12.24.</strong></p></td><td align="left" valign="top"><p>
5216 Can I get rid of build output so I can start over?
5217 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5218 Yes - you can easily do this.
5219 When you use BitBake to build an image, all the build output goes into the
5220 directory created when you source the <code class="filename">oe-init-build-env</code>
5221 setup file.
5222 By default, this <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">build directory</a>
5223 is named <code class="filename">build</code> but can be named
5224 anything you want.
5225 </p><p>
5226 Within the build directory is the <code class="filename">tmp</code> directory.
5227 To remove all the build output yet preserve any source code or downloaded files
5228 from previous builds, simply remove the <code class="filename">tmp</code> directory.
5229 </p></td></tr></tbody></table></div></div>
5230
5231 <div class="chapter" title="Chapter 13. Contributing to the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="resources"></a>Chapter 13. Contributing to the Yocto Project</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#resources-intro">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">13.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">13.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">13.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">13.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">13.6. Contributions</a></span></dt></dl></div><div class="section" title="13.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-intro"></a>13.1. Introduction</h2></div></div></div><p>
5232 The Yocto Project team is happy for people to experiment with the Yocto Project.
5233 A number of places exist to find help if you run into difficulties or find bugs.
5234 To find out how to download source code,
5235 see the "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#local-yp-release" target="_top">Yocto Project Release</a>"
5236 list item in the Yocto Project Development Manual.
5237 </p></div><div class="section" title="13.2. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-bugtracker"></a>13.2. Tracking Bugs</h2></div></div></div><p>
5238 If you find problems with the Yocto Project, you should report them using the
5239 Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>.
5240 </p></div><div class="section" title="13.3. Mailing lists"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-mailinglist"></a>13.3. Mailing lists</h2></div></div></div><p>
5241 There are a number of mailing lists maintained by the Yocto Project as well as
5242 related OpenEmbedded mailing lists for discussion, patch submission and announcements.
5243 To subscribe to one of the following mailing lists, click on the appropriate URL
5244 in the following list and follow the instructions:
5245 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> -
5246 General Yocto Project discussion mailing list. </p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core</a> -
5247 Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel</a> -
5248 Discussion mailing list about OpenEmbedded.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel</a> -
5249 Discussion mailing list about the BitBake build tool.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> -
5250 Discussion mailing list about Poky.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> -
5251 Mailing list to receive official Yocto Project release and milestone
5252 announcements.</p></li></ul></div><p>
5253 </p></div><div class="section" title="13.4. Internet Relay Chat (IRC)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-irc"></a>13.4. Internet Relay Chat (IRC)</h2></div></div></div><p>
5254 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
5255 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">#yocto</code></p></li><li class="listitem"><p><code class="filename">#poky</code></p></li></ul></div><p>
5256 </p></div><div class="section" title="13.5. Links"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-links"></a>13.5. Links</h2></div></div></div><p>
5257 Following is a list of resources you will find helpful:
5258 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_top">The Yocto Project website</a>:
5259 </em></span> The home site for the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span>
5260 The company who acquired OpenedHand in 2008 and began development on the
5261 Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span>
5262 The upstream, generic, embedded distribution used as the basis for the build system in the
5263 Yocto Project.
5264 Poky derives from and contributes back to the OpenEmbedded project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top">
5265 BitBake</a>:</em></span> The tool used to process metadata.</p></li><li class="listitem"><p><span class="emphasis"><em>BitBake User Manual:</em></span>
5266 A comprehensive guide to the BitBake tool.
5267 You can find the BitBake User Manual in the <code class="filename">bitbake/doc/manual</code>
5268 directory, which is found in the
5269 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
5270 </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>:
5271 </em></span> An open source machine emulator and virtualizer.</p></li></ul></div><p>
5272 </p></div><div class="section" title="13.6. Contributions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-contributions"></a>13.6. Contributions</h2></div></div></div><p>
5273 The Yocto Project gladly accepts contributions.
5274 You can submit changes to the project either by creating and sending pull requests,
5275 or by submitting patches through email.
5276 For information on how to do both, see the
5277 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">How to Submit a Change</a>"
5278 section in the Yocto Project Development Manual.
5279 </p></div></div>
5280
5281
5282
5283</div></body></html>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 20:23:26 +0000