Yocto 2.5
Move OpenBMC to Yocto 2.5(sumo)
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78
diff --git a/import-layers/yocto-poky/documentation/Makefile b/import-layers/yocto-poky/documentation/Makefile
index 9891095..e41d5a0 100644
--- a/import-layers/yocto-poky/documentation/Makefile
+++ b/import-layers/yocto-poky/documentation/Makefile
@@ -48,7 +48,7 @@
# Examples:
#
# make DOC=bsp-guide
-# make html DOC=yocto-project-qs
+# make html DOC=brief-yoctoprojectqs
# make pdf DOC=ref-manual
# make DOC=dev-manual BRANCH=edison
# make DOC=mega-manual BRANCH=denzil
@@ -56,7 +56,7 @@
# The first example generates the HTML and Eclipse help versions of the BSP Guide.
# The second example generates the HTML version only of the Quick Start. Note
# that the Quick Start only has an HTML version available. So, the
-# 'make DOC=yocto-project-qs' command would be equivalent. The third example
+# 'make DOC=brief-yoctoprojectqs' command would be equivalent. The third example
# generates just the PDF version of the Yocto Project Reference Manual.
# The fourth example generates the HTML 'edison' version and (if available)
# the Eclipse help version of the YP Development Tasks Manual. The last example
@@ -84,6 +84,40 @@
# for the 'denzil' branch.
#
+ifeq ($(DOC),brief-yoctoprojectqs)
+XSLTOPTS = --stringparam html.stylesheet brief-yoctoprojectqs-style.css \
+ --stringparam chapter.autolabel 0 \
+ --stringparam section.autolabel 0 \
+ --stringparam section.label.includes.component.label 0 \
+ --xinclude
+ALLPREQ = html eclipse tarball
+TARFILES = brief-yoctoprojectqs-style.css brief-yoctoprojectqs.html figures/bypqs-title.png \
+ figures/yocto-project-transp.png
+MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+
+endif
+
+ifeq ($(DOC),overview-manual)
+XSLTOPTS = --xinclude
+ALLPREQ = html eclipse tarball
+TARFILES = overview-manual-style.css overview-manual.html figures/overview-manual-title.png \
+ figures/git-workflow.png figures/source-repos.png figures/index-downloads.png \
+ figures/yp-download.png figures/YP-flow-diagram.png figures/key-dev-elements.png \
+ figures/poky-reference-distribution.png figures/cross-development-toolchains.png \
+ figures/user-configuration.png figures/layer-input.png figures/source-input.png \
+ figures/package-feeds.png figures/patching.png figures/source-fetching.png \
+ figures/configuration-compile-autoreconf.png figures/analysis-for-package-splitting.png \
+ figures/image-generation.png figures/sdk-generation.png figures/images.png \
+ figures/sdk.png \
+ eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+
+endif
+
ifeq ($(DOC),bsp-guide)
XSLTOPTS = --xinclude
ALLPREQ = html eclipse tarball
@@ -128,8 +162,8 @@
figures/source-repos.png figures/yp-download.png \
figures/wip.png
else
-TARFILES = dev-style.css dev-manual.html \
- figures/dev-title.png \
+TARFILES = dev-style.css dev-manual.html figures/buildhistory-web.png \
+ figures/dev-title.png figures/buildhistory.png \
figures/recipe-workflow.png figures/bitbake-build-flow.png \
eclipse
endif
@@ -140,17 +174,6 @@
endif
-ifeq ($(DOC),yocto-project-qs)
-XSLTOPTS = --xinclude
-ALLPREQ = html eclipse tarball
-TARFILES = yocto-project-qs.html qs-style.css \
- figures/yocto-project-transp.png \
- eclipse
-MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
ifeq ($(DOC),mega-manual)
XSLTOPTS = --stringparam html.stylesheet mega-style.css \
--stringparam chapter.autolabel 1 \
@@ -191,7 +214,7 @@
figures/wip.png
else
TARFILES = mega-manual.html mega-style.css \
- figures/building-an-image.png figures/YP-flow-diagram.png \
+ figures/YP-flow-diagram.png \
figures/using-a-pre-built-image.png \
figures/poky-title.png figures/buildhistory.png \
figures/buildhistory-web.png \
@@ -229,22 +252,23 @@
figures/sched-wakeup-profile.png figures/sysprof-callers.png \
figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \
figures/cross-development-toolchains.png \
- figures/yocto-environment-ref.png figures/user-configuration.png \
+ figures/user-configuration.png \
figures/source-input.png figures/package-feeds.png \
figures/layer-input.png figures/images.png figures/sdk.png \
figures/source-fetching.png figures/patching.png \
figures/configuration-compile-autoreconf.png \
figures/analysis-for-package-splitting.png \
- figures/image-generation.png \
+ figures/image-generation.png figures/key-dev-elements.png\
figures/sdk-generation.png figures/recipe-workflow.png \
figures/build-workspace-directory.png figures/mega-title.png \
figures/toaster-title.png figures/hosted-service.png \
- figures/simple-configuration.png \
+ figures/simple-configuration.png figures/poky-reference-distribution.png \
figures/compatible-layers.png figures/import-layer.png figures/new-project.png \
figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \
figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \
- figures/sdk-devtool-upgrade-flow.png figures/bitbake-build-flow.png
+ figures/sdk-devtool-upgrade-flow.png figures/bitbake-build-flow.png figures/bypqs-title.png \
+ figures/overview-manual-title.png figures/sdk-autotools-flow.png figures/sdk-makefile-flow.png
endif
MANUALS = $(DOC)/$(DOC).html
@@ -256,17 +280,9 @@
ifeq ($(DOC),ref-manual)
XSLTOPTS = --xinclude
ALLPREQ = html eclipse tarball
-TARFILES = ref-manual.html ref-style.css figures/poky-title.png figures/YP-flow-diagram.png \
- figures/buildhistory.png figures/buildhistory-web.png eclipse \
- figures/cross-development-toolchains.png figures/layer-input.png \
- figures/package-feeds.png figures/source-input.png \
- figures/user-configuration.png figures/yocto-environment-ref.png \
- figures/images.png figures/sdk.png figures/source-fetching.png \
- figures/patching.png figures/configuration-compile-autoreconf.png \
- figures/analysis-for-package-splitting.png figures/image-generation.png \
- figures/sdk-generation.png figures/building-an-image.png \
- figures/build-workspace-directory.png figures/source-repos.png \
- figures/index-downloads.png figures/yp-download.png figures/git-workflow.png
+TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
+ figures/build-workspace-directory.png \
+ eclipse
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
FIGURES = figures
STYLESHEET = $(DOC)/*.css
@@ -279,7 +295,7 @@
figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
figures/sdk-installed-extensible-sdk-directory.png figures/sdk-devtool-add-flow.png \
figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \
- figures/sdk-devtool-upgrade-flow.png \
+ figures/sdk-devtool-upgrade-flow.png figures/sdk-autotools-flow.png figures/sdk-makefile-flow.png \
eclipse
MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
FIGURES = figures
@@ -355,9 +371,9 @@
all: $(ALLPREQ)
pdf:
-ifeq ($(DOC),yocto-project-qs)
+ifeq ($(DOC),brief-yoctoprojectqs)
@echo " "
- @echo "ERROR: You cannot generate a yocto-project-qs PDF file."
+ @echo "ERROR: You cannot generate a PDF file for brief-yoctoprojectqs."
@echo " "
else ifeq ($(DOC),mega-manual)
@@ -401,17 +417,18 @@
.PHONY : eclipse-generate eclipse-resolve-links
eclipse-generate:
-ifeq ($(filter $(DOC), sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual yocto-project-qs),)
+ifeq ($(filter $(DOC), overview-manual sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual brief-yoctoprojectqs),)
@echo " "
@echo "ERROR: You can only create eclipse documentation"
@echo " of the following documentation parts:"
+ @echo " - overview-manual"
@echo " - sdk-manual"
@echo " - bsp-guide"
@echo " - dev-manual"
@echo " - kernel-dev"
@echo " - profile-manual"
@echo " - ref-manual"
- @echo " - yocto-project-qs"
+ @echo " - brief-yoctoprojectqs"
@echo " "
else
@echo " "
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-customization.xsl b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-customization.xsl
similarity index 85%
rename from import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-customization.xsl
rename to import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-customization.xsl
index dcc02dd..0d57424 100644
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-customization.xsl
+++ b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-customization.xsl
@@ -11,7 +11,7 @@
-->
- <xsl:import href="yocto-project-qs-titlepage.xsl"/>
+ <xsl:import href="brief-yoctoprojectqs-titlepage.xsl"/>
<xsl:include href="../template/permalinks.xsl"/>
<xsl:include href="../template/section.title.xsl"/>
@@ -20,5 +20,5 @@
<xsl:include href="../template/formal.object.heading.xsl"/>
<xsl:param name="generate.toc" select="'article nop'"></xsl:param>
- <xsl:param name="html.stylesheet" select="'qs-style.css'" />
+ <xsl:param name="html.stylesheet" select="'brief-yoctoprojectqs-style.css'" />
</xsl:stylesheet>
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-eclipse-customization.xsl
similarity index 89%
rename from import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl
rename to import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-eclipse-customization.xsl
index 50e6830..fbb3b57 100644
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl
+++ b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-eclipse-customization.xsl
@@ -16,13 +16,13 @@
-->
- <xsl:import href="yocto-project-qs-titlepage.xsl"/>
+ <xsl:import href="brief-yoctoprojectqs-titlepage.xsl"/>
<xsl:param name="chunker.output.indent" select="'yes'"/>
<xsl:param name="chunk.quietly" select="1"/>
<xsl:param name="use.id.as.filename" select="1"/>
<xsl:param name="ulink.target" select="'_self'" />
- <xsl:param name="base.dir" select="'html/yocto-project-qs/'"/>
+ <xsl:param name="base.dir" select="'html/brief-yoctoprojectqs/'"/>
<xsl:param name="chunk.section.depth" select="0"/>
<xsl:param name="html.stylesheet" select="'../book.css'"/>
<xsl:param name="eclipse.manifest" select="0"/>
@@ -32,3 +32,4 @@
<xsl:param name="generate.toc" select="'article nop'"></xsl:param>
<xsl:param name="html.stylesheet" select="'style.css'" />
</xsl:stylesheet>
+
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/qs-style.css b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-style.css
similarity index 97%
copy from import-layers/yocto-poky/documentation/yocto-project-qs/qs-style.css
copy to import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-style.css
index 948f1be..386841d 100644
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/qs-style.css
+++ b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-style.css
@@ -118,12 +118,13 @@
background-color: transparent;
background-repeat: no-repeat;
padding-top: 256px;
- background-position: top;
+ background-image: url("figures/bypqs-title.png");
+ background-position: left top;
margin-top: -256px;
padding-right: 50px;
- margin-left: 50px;
- text-align: center;
- width: 600px;
+ margin-left: 0px;
+ text-align: right;
+ width: 740px;
}
h3.author {
@@ -791,9 +792,9 @@
div.preface .titlepage .title,
div.colophon .title,
-div.chapter .titlepage .title,
-div.article .titlepage .title
-{
+div.chapter .titlepage .title {
+ background-position: bottom;
+ background-repeat: repeat-x;
}
div.section div.section .titlepage .title,
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-titlepage.xsl
similarity index 100%
rename from import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl
rename to import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-titlepage.xsl
diff --git a/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
new file mode 100644
index 0000000..62c4964f
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml
@@ -0,0 +1,491 @@
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<article id='brief-yocto-project-qs-intro'>
+ <articleinfo>
+ <title>Yocto Project Quick Build</title>
+
+ <copyright>
+ <year>©RIGHT_YEAR;</year>
+ <holder>Linux Foundation</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.
+ </para>
+ </legalnotice>
+
+
+ <abstract>
+ <imagedata fileref="figures/yocto-project-transp.png"
+ width="6in" depth="1in"
+ align="right" scale="25" />
+ </abstract>
+ </articleinfo>
+
+ <section id='brief-welcome'>
+ <title>Welcome!</title>
+
+ <para>
+ Welcome!
+ This short document steps you through the process for a typical
+ image build using the Yocto Project.
+ The document also introduces how to configure a build for specific
+ hardware.
+ You will use Yocto Project to build a reference embedded OS
+ called Poky.
+ <note>
+ The examples in this paper assume you are using a native Linux
+ system running a recent Ubuntu Linux distribution.
+ If the machine you want to use
+ Yocto Project on to build an image is not a native Linux
+ system, you can still perform these steps by using CROss
+ PlatformS (CROPS) and setting up a Poky container.
+ See the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
+ section in the Yocto Project Development Tasks Manual for more
+ information.
+ </note>
+ </para>
+
+ <para>
+ If you want more conceptual or background information on the
+ Yocto Project, see the
+ <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
+ </para>
+ </section>
+
+ <section id='brief-compatible-distro'>
+ <title>Compatible Linux Distribution</title>
+
+ <para>
+ Make sure your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+ meets the following requirements:
+ <itemizedlist>
+ <listitem><para>
+ 50 Gbytes of free disk space
+ </para></listitem>
+ <listitem><para>
+ Runs a supported Linux distribution (i.e. recent releases of
+ Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of
+ Linux distributions that support the Yocto Project, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para></listitem>
+ <listitem><para>
+ <itemizedlist>
+ <listitem><para>
+ Git 1.8.3.1 or greater
+ </para></listitem>
+ <listitem><para>
+ tar 1.27 or greater
+ </para></listitem>
+ <listitem><para>
+ Python 3.4.0 or greater.
+ </para></listitem>
+ </itemizedlist>
+ If your build host does not meet any of these three listed
+ version requirements, you can take steps to prepare the
+ system so that you can still use the Yocto Project.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
+ section in the Yocto Project Reference Manual for information.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='brief-build-system-packages'>
+ <title>Build Host Packages</title>
+
+ <para>
+ You must install essential host packages on your
+ build host.
+ The following command installs the host packages based on an
+ Ubuntu distribution:
+ <note>
+ For host package requirements on all supported Linux
+ distributions, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
+ section in the Yocto Project Reference Manual.
+ </note>
+ <literallayout class='monospaced'>
+ $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='brief-use-git-to-clone-poky'>
+ <title>Use Git to Clone Poky</title>
+
+ <para>
+ Once you complete the setup instructions for your machine,
+ you need to get a copy of the Poky repository on your build
+ host.
+ Use the following commands to clone the Poky
+ repository and then checkout the &DISTRO_REL_TAG; release:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/poky
+ Cloning into 'poky'...
+ remote: Counting objects: 361782, done.
+ remote: Compressing objects: 100% (87100/87100), done.
+ remote: Total 361782 (delta 268619), reused 361439 (delta 268277)
+ Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.
+ Resolving deltas: 100% (268619/268619), done.
+ Checking connectivity... done.
+ $ git checkout tags/yocto-2.5 -b my-yocto-2.5
+ </literallayout>
+ The previous Git checkout command creates a local branch
+ named my-&DISTRO_REL_TAG;. The files available to you in that
+ branch exactly match the repository's files in the
+ "&DISTRO_NAME_NO_CAP;" development branch at the time of the
+ Yocto Project &DISTRO; release.
+ </para>
+
+ <para>
+ For more options and information about accessing Yocto
+ Project related repositories, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
+
+ <section id='brief-building-your-image'>
+ <title>Building Your Image</title>
+
+ <para>
+ Use the following steps to build your image.
+ The build process creates an entire Linux distribution, including
+ the toolchain, from source.
+ <note>
+ <itemizedlist>
+ <listitem><para>
+ If you are working behind a firewall and your build
+ host is not set up for proxies, you could encounter
+ problems with the build process when fetching source
+ code (e.g. fetcher failures or Git failures).
+ </para></listitem>
+ <listitem><para>
+ If you do not know your proxy settings, consult your
+ local network infrastructure resources and get that
+ information.
+ A good starting point could also be to check your
+ web browser settings.
+ Finally, you can find more information on the
+ "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
+ page of the Yocto Project Wiki.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ Run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ environment setup script to define Yocto Project's
+ build environment on your build host.
+ <literallayout class='monospaced'>
+ $ source &OE_INIT_FILE;
+ </literallayout>
+ Among other things, the script creates the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is <filename>build</filename> in this case
+ and is located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ After the script runs, your current working directory
+ is set to the Build Directory.
+ Later, when the build completes, the Build Directory
+ contains all the files created during the build.
+ </para></listitem>
+ <listitem><para id='conf-file-step'>
+ <emphasis>Examine Your Local Configuration File:</emphasis>
+ When you set up the build environment, a local
+ configuration file named
+ <filename>local.conf</filename> becomes available in
+ a <filename>conf</filename> subdirectory of the
+ Build Directory.
+ For this example, the defaults are set to build
+ for a <filename>qemux86</filename> target, which is
+ suitable for emulation.
+ The package manager used is set to the RPM package
+ manager.
+ <tip>
+ You can significantly speed up your build and guard
+ against fetcher failures by using mirrors.
+ To use mirrors, add these lines to your
+ <filename>local.conf</filename> file in the Build
+ directory:
+ <literallayout class='monospaced'>
+ SSTATE_MIRRORS = "\
+ file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
+ file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \
+ file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \
+ "
+ </literallayout>
+ The previous examples showed how to add sstate
+ paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,
+ &YOCTO_DOC_VERSION;, and a development area.
+ For a complete index of sstate locations, see
+ <ulink url='http://sstate.yoctoproject.org/'></ulink>.
+ </tip>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Start the Build:</emphasis>
+ Continue with the following command to build an OS image
+ for the target, which is
+ <filename>core-image-sato</filename> in this example:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-sato
+ </literallayout>
+ For information on using the
+ <filename>bitbake</filename> command, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
+ section in the Yocto Project Overview and Concepts Manual,
+ or see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
+ section in the BitBake User Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Simulate Your Image Using QEMU:</emphasis>
+ Once this particular image is built, you can start
+ QEMU, which is a Quick EMUlator that ships with
+ the Yocto Project:
+ <literallayout class='monospaced'>
+ $ runqemu qemux86
+ </literallayout>
+ If you want to learn more about running QEMU, see the
+ "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
+ chapter in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Exit QEMU:</emphasis>
+ Exit QEMU by either clicking on the shutdown icon or by
+ typing <filename>Ctrl-C</filename> in the QEMU
+ transcript window from which you evoked QEMU.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='customizing-your-build-for-specific-hardware'>
+ <title>Customizing Your Build for Specific Hardware</title>
+
+ <para>
+ So far, all you have done is quickly built an image suitable
+ for emulation only.
+ This section shows you how to customize your build for specific
+ hardware by adding a hardware layer into the Yocto Project
+ development environment.
+ </para>
+
+ <para>
+ In general, layers are repositories that contain related sets of
+ instructions and configurations that tell the Yocto Project what
+ to do.
+ Isolating related metadata into functionally specific layers
+ facilitates modular development and makes it easier to reuse the
+ layer metadata.
+ <note>
+ By convention, layer names start with the string "meta-".
+ </note>
+ </para>
+
+ <para>
+ Follow these steps to add a hardware layer:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Find a Layer:</emphasis>
+ Lots of hardware layers exist.
+ The Yocto Project
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
+ has many hardware layers.
+ This example adds the
+ <ulink url='https://github.com/kraj/meta-altera'>meta-altera</ulink>
+ hardware layer.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the Layer</emphasis>
+ Use Git to make a local copy of the layer on your machine.
+ You can put the copy in the top level of the copy of the
+ Poky repository created earlier:
+ <literallayout class='monospaced'>
+ $ cd ~/poky
+ $ git clone https://github.com/kraj/meta-altera.git
+ Cloning into 'meta-altera'...
+ remote: Counting objects: 25170, done.
+ remote: Compressing objects: 100% (350/350), done.
+ remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
+ Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
+ Resolving deltas: 100% (13385/13385), done.
+ Checking connectivity... done.
+ </literallayout>
+ The hardware layer now exists with other layers inside
+ the Poky reference repository on your build host as
+ <filename>meta-altera</filename> and contains all the
+ metadata needed to support hardware from Altera, which
+ is owned by Intel.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Change the Configuration to Build for a Specific Machine:</emphasis>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable in the <filename>local.conf</filename> file
+ specifies the machine for the build.
+ For this example, set the <filename>MACHINE</filename>
+ variable to "cyclone5".
+ These configurations are used:
+ <ulink url='https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf'></ulink>.
+ <note>
+ See the
+ "<link linkend='conf-file-step'>Examine Your Local Configuration File</link>"
+ step earlier for more information on configuring the
+ build.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Add Your Layer to the Layer Configuration File:</emphasis>
+ Before you can use a layer during a build, you must add it
+ to your <filename>bblayers.conf</filename> file, which
+ is found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
+ <filename>conf</filename> directory.</para>
+
+ <para>Use the <filename>bitbake-layers add-layer</filename>
+ command to add the layer to the configuration file:
+ <literallayout class='monospaced'>
+ $ cd ~/poky/build
+ $ bitbake-layers add-layer ../meta-altera
+ NOTE: Starting bitbake server...
+ Parsing recipes: 100% |##################################################################| Time: 0:00:32
+ Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 123 skipped, 0 masked, 0 errors.
+ </literallayout>
+ You can find more information on adding layers in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section.
+ </para></listitem>
+ </orderedlist>
+ Completing these steps has added the
+ <filename>meta-altera</filename> layer to your Yocto Project
+ development environment and configured it to build for the
+ "cyclone5" machine.
+ <note>
+ The previous steps are for demonstration purposes only.
+ If you were to attempt to build an image for the
+ "cyclone5" build, you should read the Altera
+ <filename>README</filename>.
+ </note>
+ </para>
+ </section>
+
+ <section id='creating-your-own-general-layer'>
+ <title>Creating Your Own General Layer</title>
+
+ <para>
+ Maybe you have an application or specific set of behaviors you
+ need to isolate.
+ You can create your own general layer using the
+ <filename>bitbake-layers create-layer</filename> command.
+ The tool automates layer creation by setting up a
+ subdirectory with a <filename>layer.conf</filename>
+ configuration file, a <filename>recipes-example</filename>
+ subdirectory that contains an <filename>example.bb</filename>
+ recipe, a licensing file, and a <filename>README</filename>.
+ </para>
+
+ <para>
+ The following commands run the tool to create a layer named
+ <filename>meta-mylayer</filename> in the
+ <filename>poky</filename> directory:
+ <literallayout class='monospaced'>
+ $ cd ~/poky
+ $ bitbake-layers create-layer meta-mylayer
+ NOTE: Starting bitbake server...
+ Add your new layer with 'bitbake-layers add-layer meta-mylayer'
+ </literallayout>
+ For more information on layers and how to create them, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
+
+ <section id='brief-where-to-go-next'>
+ <title>Where To Go Next</title>
+
+ <para>
+ Now that you have experienced using the Yocto Project, you might
+ be asking yourself "What now?"
+ The Yocto Project has many sources of information including
+ the website, wiki pages, and user manuals:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Website:</emphasis>
+ The
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+ provides background information, the latest builds,
+ breaking news, full development documentation, and
+ access to a rich Yocto Project Development Community
+ into which you can tap.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Developer Screencast:</emphasis>
+ The
+ <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
+ provides a 30-minute video created for users unfamiliar
+ with the Yocto Project but familiar with Linux build
+ hosts.
+ While this screencast is somewhat dated, the
+ introductory and fundamental concepts are useful for
+ the beginner.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Yocto Project Overview and Concepts Manual:</emphasis>
+ The
+ <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>
+ is a great place to start to learn about the
+ Yocto Project.
+ This manual introduces you to the Yocto Project and its
+ development environment.
+ The manual also provides conceptual information for
+ various aspects of the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Yocto Project Wiki:</emphasis>
+ The
+ <ulink url='&YOCTO_WIKI_URL;'>Yocto Project Wiki</ulink>
+ provides additional information on where to go next
+ when ramping up with the Yocto Project, release
+ information, project planning, and QA information.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Yocto Project Mailing Lists:</emphasis>
+ Related mailing lists provide a forum for discussion,
+ patch submission and announcements.
+ Several mailing lists exist and are grouped according
+ to areas of concern.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
+ section in the Yocto Project Reference Manual for a
+ complete list of Yocto Project mailing lists.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Comprehensive List of Links and Other Documentation:</emphasis>
+ The
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
+ section in the Yocto Project Reference Manual provides a
+ comprehensive list of all related links and other
+ user documentation.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</article>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/figures/bypqs-title.png b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/figures/bypqs-title.png
new file mode 100644
index 0000000..9e0a5ce
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/figures/bypqs-title.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/figures/yocto-project-transp.png b/import-layers/yocto-poky/documentation/brief-yoctoprojectqs/figures/yocto-project-transp.png
similarity index 100%
rename from import-layers/yocto-poky/documentation/yocto-project-qs/figures/yocto-project-transp.png
rename to import-layers/yocto-poky/documentation/brief-yoctoprojectqs/figures/yocto-project-transp.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml
index 576ed18..7ca4c5d 100644
--- a/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml
+++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml
@@ -117,14 +117,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -142,28 +137,40 @@
<itemizedlist>
<listitem><para>
This version of the
- <emphasis>Yocto Project Board Support Package Developer's Guide</emphasis>
+ <emphasis>Yocto Project Board Support Package (BSP) Developer's Guide</emphasis>
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
</legalnotice>
diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp-style.css b/import-layers/yocto-poky/documentation/bsp-guide/bsp-style.css
index e407ca4..0c8689b 100644
--- a/import-layers/yocto-poky/documentation/bsp-guide/bsp-style.css
+++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp-style.css
@@ -730,6 +730,9 @@
border-color: black;
}
+.writernotes {
+ color: red;
+}
/*********** /
/ graphics /
diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml
index d7b6f15..00a28b0 100644
--- a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml
+++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml
@@ -4,371 +4,428 @@
<chapter id='bsp'>
- <title>Board Support Packages (BSP) - Developer's Guide</title>
+<title>Board Support Packages (BSP) - Developer's Guide</title>
- <para>
- A Board Support Package (BSP) is a collection of information that
- defines how to support a particular hardware device, set of devices, or
- hardware platform.
- The BSP includes information about the hardware features
- present on the device and kernel configuration information along with any
- additional hardware drivers required.
- The BSP also lists any additional software
- components required in addition to a generic Linux software stack for both
- essential and optional platform features.
- </para>
+<para>
+ A Board Support Package (BSP) is a collection of information that
+ defines how to support a particular hardware device, set of devices, or
+ hardware platform.
+ The BSP includes information about the hardware features
+ present on the device and kernel configuration information along with any
+ additional hardware drivers required.
+ The BSP also lists any additional software
+ components required in addition to a generic Linux software stack for both
+ essential and optional platform features.
+</para>
- <para>
- This guide presents information about BSP Layers, defines a structure for components
- so that BSPs follow a commonly understood layout, discusses how to customize
- a recipe for a BSP, addresses BSP licensing, and provides information that
- shows you how to create and manage a
- <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
- <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
- </para>
+<para>
+ This guide presents information about BSP Layers, defines a structure for components
+ so that BSPs follow a commonly understood layout, discusses how to customize
+ a recipe for a BSP, addresses BSP licensing, and provides information that
+ shows you how to create a
+ <link linkend='bsp-layers'>BSP Layer</link> using the
+ <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link>
+ tool.
+</para>
- <section id='bsp-layers'>
- <title>BSP Layers</title>
+<section id='bsp-layers'>
+ <title>BSP Layers</title>
- <para>
- A BSP consists of a file structure inside a base directory.
- Collectively, you can think of the base directory, its file structure,
- and the contents as a BSP Layer.
- Although not a strict requirement, layers in the Yocto Project use the
- following well-established naming convention:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>
- </literallayout>
- The string "meta-" is prepended to the machine or platform name, which is
- <replaceable>bsp_name</replaceable> in the above form.
- <note><title>Tip</title>
- Because the BSP layer naming convention is well-established,
- it is advisable to follow it when creating layers.
- Technically speaking, a BSP layer name does not need to
- start with <filename>meta-</filename>.
- However, you might run into situations where obscure
- scripts assume this convention.
- </note>
- </para>
+ <para>
+ A BSP consists of a file structure inside a base directory.
+ Collectively, you can think of the base directory, its file structure,
+ and the contents as a BSP Layer.
+ Although not a strict requirement, BSP layers in the Yocto Project
+ use the following well-established naming convention:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>
+ </literallayout>
+ The string "meta-" is prepended to the machine or platform name, which is
+ <replaceable>bsp_root_name</replaceable> in the above form.
+ <note><title>Tip</title>
+ Because the BSP layer naming convention is well-established,
+ it is advisable to follow it when creating layers.
+ Technically speaking, a BSP layer name does not need to
+ start with <filename>meta-</filename>.
+ However, various scripts and tools in the Yocto Project
+ development environment assume this convention.
+ </note>
+ </para>
- <para>
- To help understand the BSP layer concept, consider the BSPs that the
- Yocto Project supports and provides with each release.
- You can see the layers in the
- <ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
- through a web interface at
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
- If you go to that interface, you will find near the bottom of the list
- under "Yocto Metadata Layers" several BSP layers all of which are
- supported by the Yocto Project (e.g. <filename>meta-raspberrypi</filename> and
- <filename>meta-intel</filename>).
- Each of these layers is a repository unto itself and clicking on a
- layer reveals information that includes two links from which you can choose
- to set up a clone of the layer's repository on your local host system.
- Here is an example that clones the Raspberry Pi BSP layer:
- <literallayout class='monospaced'>
+ <para>
+ To help understand the BSP layer concept, consider the BSPs that the
+ Yocto Project supports and provides with each release.
+ You can see the layers in the
+ <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
+ through a web interface at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ If you go to that interface, you will find a list of repositories
+ under "Yocto Metadata Layers".
+ <note>
+ Layers that are no longer actively supported as part of the
+ Yocto Project appear under the heading "Yocto Metadata Layer
+ Archive."
+ </note>
+ Each repository is a BSP layer supported by the Yocto Project
+ (e.g. <filename>meta-raspberrypi</filename> and
+ <filename>meta-intel</filename>).
+ Each of these layers is a repository unto itself and clicking on a
+ layer reveals information that includes two links from which you can choose
+ to set up a clone of the layer's repository on your local host system.
+ Here is an example that clones the Raspberry Pi BSP layer:
+ <literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/meta-raspberrypi
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- In addition to BSP layers near the bottom of that referenced
- Yocto Project Source Repository, the
- <filename>meta-yocto-bsp</filename> layer is part of the
- shipped <filename>poky</filename> repository.
- The <filename>meta-yocto-bsp</filename> layer maintains several
- BSPs such as the Beaglebone, EdgeRouter, and generic versions of
- both 32 and 64-bit IA machines.
- </para>
+ <para>
+ In addition to BSP layers, the
+ <filename>meta-yocto-bsp</filename> layer is part of the
+ shipped <filename>poky</filename> repository.
+ The <filename>meta-yocto-bsp</filename> layer maintains several
+ BSPs such as the Beaglebone, EdgeRouter, and generic versions of
+ both 32-bit and 64-bit IA machines.
+ </para>
- <para>
- For information on the BSP development workflow, see the
- "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
- section.
- For more information on how to set up a local copy of source files
- from a Git repository, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
- section also in the Yocto Project Development Tasks Manual.
- </para>
+ <para>
+ For information on the BSP development workflow, see the
+ "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>"
+ section.
+ For more information on how to set up a local copy of source files
+ from a Git repository, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
- <para>
- The layer's base directory
- (<filename>meta-<replaceable>bsp_name</replaceable></filename>)
- is the root of the BSP Layer.
- This root is what you add to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
- variable in the <filename>conf/bblayers.conf</filename> file found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
- which is established after you run the OpenEmbedded build environment
- setup script (i.e.
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
- Adding the root allows the OpenEmbedded build system to recognize the BSP
- definition and from it build an image.
- Here is an example:
- <literallayout class='monospaced'>
+ <para>
+ The layer's base directory
+ (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>)
+ is the root directory of the BSP Layer.
+ This directory is what you add to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
+ variable in the <filename>conf/bblayers.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is established after you run the OpenEmbedded build environment
+ setup script (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
+ Adding the root directory allows the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ to recognize the BSP layer and from it build an image.
+ Here is an example:
+ <literallayout class='monospaced'>
BBLAYERS ?= " \
/usr/local/src/yocto/meta \
/usr/local/src/yocto/meta-poky \
/usr/local/src/yocto/meta-yocto-bsp \
/usr/local/src/yocto/meta-mylayer \
"
- </literallayout>
- </para>
+ </literallayout>
+ <note><title>Tip</title>
+ Ordering and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
+ for the layers listed in <filename>BBLAYERS</filename>
+ matter.
+ For example, if multiple layers define a machine
+ configuration, the OpenEmbedded build system uses
+ the last layer searched given similar layer
+ priorities.
+ The build system works from the top-down through
+ the layers listed in <filename>BBLAYERS</filename>.
+ </note>
+ </para>
- <para>
- Some BSPs require additional layers on
- top of the BSP's root layer in order to be functional.
- For these cases, you also need to add those layers to the
- <filename>BBLAYERS</filename> variable in order to build the BSP.
- You must also specify in the "Dependencies" section of the BSP's
- <filename>README</filename> file any requirements for additional
- layers and, preferably, any
- build instructions that might be contained elsewhere
- in the <filename>README</filename> file.
- </para>
+ <para>
+ Some BSPs require or depend on additional layers
+ beyond the BSP's root layer in order to be functional.
+ In this case, you need to specify these layers in the
+ <filename>README</filename> "Dependencies" section of the
+ BSP's root layer.
+ Additionally, if any build instructions exist for the
+ BSP, you must add them to the "Dependencies" section.
+ </para>
- <para>
- Some layers function as a layer to hold other BSP layers.
- An example of this type of layer is the <filename>meta-intel</filename> layer,
- which contains a number of individual BSP sub-layers, as well as a directory
- named <filename>common/</filename> full of common content across those layers.
- Another example is the <filename>meta-yocto-bsp</filename> layer mentioned
- earlier.
- </para>
+ <para>
+ Some layers function as a layer to hold other BSP layers.
+ These layers are knows as
+ "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>".
+ An example of this type of layer is the
+ <filename>meta-intel</filename> layer.
+ This layer contains BSP layers for the Intel-core2-32
+ <trademark class='registered'>Intel</trademark> Common Core
+ (Intel-core2-32) and the Intel-corei7-64
+ <trademark class='registered'>Intel</trademark> Common Core
+ (Intel-corei7-64).
+ the <filename>meta-intel</filename> layer also contains
+ the <filename>common/</filename> directory, which contains
+ common content across those layers.
+ </para>
- <para>
- For more detailed information on layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section of the Yocto Project Development Tasks Manual.
- </para>
- </section>
+ <para>
+ For more information on layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </para>
+</section>
- <section id='preparing-your-build-host-to-work-with-bsp-layers'>
- <title>Preparing Your Build Host to Work With BSP Layers</title>
+<section id='preparing-your-build-host-to-work-with-bsp-layers'>
+ <title>Preparing Your Build Host to Work With BSP Layers</title>
- <para>
- This section describes how to get your build host ready
- to work with BSP layers.
- Once you have the host set up, you can create the layer
- as described in the
- "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</link>"
- section.
- <note>
- For structural information on BSPs, see the
- <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
- section.
- </note>
+ <para>
+ This section describes how to get your build host ready
+ to work with BSP layers.
+ Once you have the host set up, you can create the layer
+ as described in the
+ "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section.
+ <note>
+ For structural information on BSPs, see the
+ <link linkend='bsp-filelayout'>Example Filesystem Layout</link>
+ section.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set Up the Build Environment:</emphasis>
+ Be sure you are set up to use BitBake in a shell.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
+ section in the Yocto Project Development Tasks Manual for information
+ on how to get a build host ready that is either a native
+ Linux machine or a machine that uses CROPS.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
+ You need to have a local copy of the Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (i.e. a local <filename>poky</filename> repository).
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
+ and possibly the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
+ or
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
+ sections all in the Yocto Project Development Tasks Manual for
+ information on how to clone the <filename>poky</filename>
+ repository and check out the appropriate branch for your work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Determine the BSP Layer You Want:</emphasis>
+ The Yocto Project supports many BSPs, which are maintained in
+ their own layers or in layers designed to contain several
+ BSPs.
+ To get an idea of machine support through BSP layers, you can
+ look at the
+ <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
+ for the release.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Clone the
+ <filename>meta-intel</filename> BSP Layer:</emphasis>
+ If your hardware is based on current Intel CPUs and devices,
+ you can leverage this BSP layer.
+ For details on the <filename>meta-intel</filename> BSP layer,
+ see the layer's
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
+ file.
<orderedlist>
<listitem><para>
- <emphasis>Set Up the Build Environment:</emphasis>
- Be sure you are set up to use BitBake in a shell.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
- section in the Yocto Project Development Tasks Manual for information
- on how to get a build host ready that is either a native
- Linux machine or a machine that uses CROPS.
- </para></listitem>
- <listitem><para>
- <emphasis>Clone the <filename>poky</filename> Repository:</emphasis>
- You need to have a local copy of the Yocto Project
+ <emphasis>Navigate to Your Source Directory:</emphasis>
+ Typically, you set up the
+ <filename>meta-intel</filename> Git repository
+ inside the
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (i.e. a local <filename>poky</filename> repository).
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
- and possibly the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>"
- sections all in the Yocto Project Development Tasks Manual for
- information on how to clone the <filename>poky</filename>
- repository and check out the appropriate branch for your work.
+ (e.g. <filename>poky</filename>).
+ <literallayout class='monospaced'>
+ $ cd /home/<replaceable>you</replaceable>/poky
+ </literallayout>
</para></listitem>
<listitem><para>
- <emphasis>Determine the BSP Layer You Want:</emphasis>
- The Yocto Project supports many BSPs, which are maintained in
- their own layers or in layers designed to contain several
- BSPs.
- To get an idea of machine support through BSP layers, you can
- look at the
- <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
- for the release.
- </para></listitem>
- <listitem><para>
- <emphasis>Optionally Clone the
- <filename>meta-intel</filename> BSP Layer:</emphasis>
- If your hardware is based on current Intel CPUs and devices,
- you can leverage this BSP layer.
- For details on the <filename>meta-intel</filename> BSP layer,
- see the layer's
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
- file.
- <orderedlist>
- <listitem><para>
- <emphasis>Navigate to Your Source Directory:</emphasis>
- Typically, you set up the
- <filename>meta-intel</filename> Git repository
- inside the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (e.g. <filename>poky</filename>).
- </para></listitem>
- <listitem><para>
- <emphasis>Clone the Layer:</emphasis>
- <literallayout class='monospaced'>
+ <emphasis>Clone the Layer:</emphasis>
+ <literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/meta-intel.git
Cloning into 'meta-intel'...
- remote: Counting objects: 14224, done.
- remote: Compressing objects: 100% (4591/4591), done.
- remote: Total 14224 (delta 8245), reused 13985 (delta 8006)
- Receiving objects: 100% (14224/14224), 4.29 MiB | 2.90 MiB/s, done.
- Resolving deltas: 100% (8245/8245), done.
- Checking connectivity... done.
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Check Out the Proper Branch:</emphasis>
- The branch you check out for
- <filename>meta-intel</filename> must match the same
- branch you are using for the Yocto Project release
- (e.g. &DISTRO_NAME_NO_CAP;):
- <literallayout class='monospaced'>
- $ git checkout <replaceable>branch_name</replaceable>
- </literallayout>
- For an example on how to discover branch names and
- checkout on a branch, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- </orderedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
- If your hardware can be more closely leveraged to an
- existing BSP not within the <filename>meta-intel</filename>
- BSP layer, you can clone that BSP layer.</para>
-
- <para>The process is identical to the process used for the
- <filename>meta-intel</filename> layer except for the layer's
- name.
- For example, if you determine that your hardware most
- closely matches the <filename>meta-minnow</filename>,
- clone that layer:
- <literallayout class='monospaced'>
- $ git clone git://git.yoctoproject.org/meta-minnow
- Cloning into 'meta-minnow'...
- remote: Counting objects: 456, done.
- remote: Compressing objects: 100% (283/283), done.
- remote: Total 456 (delta 163), reused 384 (delta 91)
- Receiving objects: 100% (456/456), 96.74 KiB | 0 bytes/s, done.
- Resolving deltas: 100% (163/163), done.
+ remote: Counting objects: 15585, done.
+ remote: Compressing objects: 100% (5056/5056), done.
+ remote: Total 15585 (delta 9123), reused 15329 (delta 8867)
+ Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done.
+ Resolving deltas: 100% (9123/9123), done.
Checking connectivity... done.
</literallayout>
</para></listitem>
<listitem><para>
- <emphasis>Initialize the Build Environment:</emphasis>
- While in the root directory of the Source Directory (i.e.
- <filename>poky</filename>), run the
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- environment setup script to define the OpenEmbedded
- build environment on your build host.
+ <emphasis>Check Out the Proper Branch:</emphasis>
+ The branch you check out for
+ <filename>meta-intel</filename> must match the same
+ branch you are using for the Yocto Project release
+ (e.g. &DISTRO_NAME_NO_CAP;):
<literallayout class='monospaced'>
- $ source &OE_INIT_FILE;
+ $ cd meta-intel
+ $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
+ Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
+ Switched to a new branch '&DISTRO_NAME_NO_CAP;'
</literallayout>
- Among other things, the script creates the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
- which is <filename>build</filename> in this case
- and is located in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- After the script runs, your current working directory
- is set to the <filename>build</filename> directory.
+ <note>
+ To see the available branch names in a cloned repository,
+ use the <filename>git branch -al</filename> command.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for more information.
+ </note>
</para></listitem>
</orderedlist>
- </para>
- </section>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
+ If your hardware can be more closely leveraged to an
+ existing BSP not within the <filename>meta-intel</filename>
+ BSP layer, you can clone that BSP layer.</para>
- <section id="bsp-filelayout">
- <title>Example Filesystem Layout</title>
-
- <para>
- Defining a common BSP directory structure allows end-users to understand and
- become familiar with that structure.
- A common format also encourages standardization of software support of hardware.
- </para>
-
- <para>
- The proposed form does have elements that are specific to the
- OpenEmbedded build system.
- It is intended that this information can be
- used by other build systems besides the OpenEmbedded build system
- and that it will be simple
- to extract information and convert it to other formats if required.
- The OpenEmbedded build system, through its standard layers mechanism, can directly
- accept the format described as a layer.
- The BSP captures all
- the hardware-specific details in one place in a standard format, which is
- useful for any person wishing to use the hardware platform regardless of
- the build system they are using.
- </para>
-
- <para>
- The BSP specification does not include a build system or other tools -
- it is concerned with the hardware-specific components only.
- At the end-distribution point, you can ship the BSP combined with a build system
- and other tools.
- However, it is important to maintain the distinction that these
- are separate components that happen to be combined in certain end products.
- </para>
-
- <para>
- Before looking at the common form for the file structure inside a BSP Layer,
- you should be aware that some requirements do exist in order for a BSP to
- be considered compliant with the Yocto Project.
- For that list of requirements, see the
- "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
- section.
- </para>
-
- <para>
- Below is the common form for the file structure inside a BSP Layer.
- While you can use this basic form for the standard, realize that the actual structures
- for specific BSPs could differ.
-
+ <para>The process is identical to the process used for the
+ <filename>meta-intel</filename> layer except for the layer's
+ name.
+ For example, if you determine that your hardware most
+ closely matches the <filename>meta-raspberrypi</filename>,
+ clone that layer:
<literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/
- meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
- meta-<replaceable>bsp_name</replaceable>/README
- meta-<replaceable>bsp_name</replaceable>/README.sources
- meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
- meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
- meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
- meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
- meta-<replaceable>bsp_name</replaceable>/recipes-core/*
- meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
- meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
+ $ git clone git://git.yoctoproject.org/meta-raspberrypi
+ Cloning into 'meta-raspberrypi'...
+ remote: Counting objects: 4743, done.
+ remote: Compressing objects: 100% (2185/2185), done.
+ remote: Total 4743 (delta 2447), reused 4496 (delta 2258)
+ Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done.
+ Resolving deltas: 100% (2447/2447), done.
+ Checking connectivity... done.
</literallayout>
- </para>
-
- <para>
- Below is an example of the Raspberry Pi BSP:
-
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ While in the root directory of the Source Directory (i.e.
+ <filename>poky</filename>), run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+ environment setup script to define the OpenEmbedded
+ build environment on your build host.
<literallayout class='monospaced'>
+ $ source &OE_INIT_FILE;
+ </literallayout>
+ Among other things, the script creates the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
+ which is <filename>build</filename> in this case
+ and is located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ After the script runs, your current working directory
+ is set to the <filename>build</filename> directory.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id="bsp-filelayout">
+ <title>Example Filesystem Layout</title>
+
+ <para>
+ Defining a common BSP directory structure allows
+ end-users to understand and become familiar with
+ that standard.
+ A common format also encourages standardization
+ of software support for hardware.
+ </para>
+
+ <para>
+ The proposed form described in this section does
+ have elements that are specific to the OpenEmbedded
+ build system.
+ It is intended that developers can use this structure
+ with other build systems besides the OpenEmbedded build
+ system.
+ It is also intended that it will be be simple to extract
+ information and convert it to other formats if required.
+ The OpenEmbedded build system, through its standard
+ <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
+ can directly accept the format described as a layer.
+ The BSP layer captures all the hardware-specific details
+ in one place using a standard format, which is useful
+ for any person wishing to use the hardware platform
+ regardless of the build system they are using.
+ </para>
+
+ <para>
+ The BSP specification does not include a build system
+ or other tools - the specification is concerned with
+ the hardware-specific components only.
+ At the end-distribution point, you can ship the BSP
+ layer combined with a build system and other tools.
+ Realize that it is important to maintain the distinction
+ that the BSP layer, a build system, and tools are
+ separate components that could to be combined in
+ certain end products.
+ </para>
+
+ <para>
+ Before looking at the common form for the file structure
+ inside a BSP Layer, you should be aware that some
+ requirements do exist in order for a BSP layer to
+ be considered compliant with the Yocto Project.
+ For that list of requirements, see the
+ "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
+ section.
+ </para>
+
+ <para>
+ Below is the common form for the file structure
+ inside a BSP Layer.
+ While this basic form represents the standard,
+ realize that the actual file structures for specific
+ BSPs could differ.
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/
+ meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
+ meta-<replaceable>bsp_root_name</replaceable>/README
+ meta-<replaceable>bsp_root_name</replaceable>/README.sources
+ meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
+ meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
+ meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-core/*
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend
+ </literallayout>
+ </para>
+
+ <para>
+ Below is an example of the Raspberry Pi BSP
+ layer that is available from the
+ <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>:
+ <literallayout class='monospaced'>
meta-raspberrypi/COPYING.MIT
- meta-raspberrypi/README
+ meta-raspberrypi/README.md
meta-raspberrypi/classes
- meta-raspberrypi/classes/linux-raspberrypi-base.bbclass
meta-raspberrypi/classes/sdcard_image-rpi.bbclass
meta-raspberrypi/conf/
meta-raspberrypi/conf/layer.conf
meta-raspberrypi/conf/machine/
+ meta-raspberrypi/conf/machine/raspberrypi-cm.conf
+ meta-raspberrypi/conf/machine/raspberrypi-cm3.conf
meta-raspberrypi/conf/machine/raspberrypi.conf
+ meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf
meta-raspberrypi/conf/machine/raspberrypi0.conf
meta-raspberrypi/conf/machine/raspberrypi2.conf
+ meta-raspberrypi/conf/machine/raspberrypi3-64.conf
meta-raspberrypi/conf/machine/raspberrypi3.conf
meta-raspberrypi/conf/machine/include
meta-raspberrypi/conf/machine/include/rpi-base.inc
meta-raspberrypi/conf/machine/include/rpi-default-providers.inc
meta-raspberrypi/conf/machine/include/rpi-default-settings.inc
meta-raspberrypi/conf/machine/include/rpi-default-versions.inc
- meta-raspberrypi/conf/machine/include/rpi-tune-arm1176jzf-s.inc
+ meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc
+ meta-raspberrypi/docs
+ meta-raspberrypi/docs/Makefile
+ meta-raspberrypi/docs/conf.py
+ meta-raspberrypi/docs/contributing.md
+ meta-raspberrypi/docs/extra-apps.md
+ meta-raspberrypi/docs/extra-build-config.md
+ meta-raspberrypi/docs/index.rst
+ meta-raspberrypi/docs/layer-contents.md
+ meta-raspberrypi/docs/readme.md
meta-raspberrypi/files
meta-raspberrypi/files/custom-licenses
meta-raspberrypi/files/custom-licenses/Broadcom
@@ -378,12 +435,26 @@
meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb
meta-raspberrypi/recipes-bsp/common
meta-raspberrypi/recipes-bsp/common/firmware.inc
- meta-raspberrypi/recipes-bsp/formfactor_00.bbappend
- meta-raspberrypi/recipes-bsp/formfactor/raspberrypi/machconfig
- meta-raspberrypi/recipes-bsp/rpi-mkimage_git.bb
- meta-raspberrypi/recipes-bsp/rpi-mkimage/License
- meta-raspberrypi/recipes-bsp/rpi-mkimage/open-files-relative-to-script.patch
- meta-raspberrypi/recipes-bsp/u-boot/u-boot-rpi_git.bb
+ meta-raspberrypi/recipes-bsp/formfactor
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig
+ meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in
+ meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb
+ meta-raspberrypi/recipes-bsp/u-boot
+ meta-raspberrypi/recipes-bsp/u-boot/u-boot
+ meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch
+ meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend
+ meta-raspberrypi/recipes-connectivity
+ meta-raspberrypi/recipes-connectivity/bluez5
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service
+ meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend
meta-raspberrypi/recipes-core
meta-raspberrypi/recipes-core/images
meta-raspberrypi/recipes-core/images/rpi-basic-image.bb
@@ -393,37 +464,41 @@
meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb
meta-raspberrypi/recipes-core/psplash
meta-raspberrypi/recipes-core/psplash/files
- meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h
+ meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend
+ meta-raspberrypi/recipes-core/udev
+ meta-raspberrypi/recipes-core/udev/udev-rules-rpi
+ meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules
+ meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb
meta-raspberrypi/recipes-devtools
meta-raspberrypi/recipes-devtools/bcm2835
- meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.46.bb
+ meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb
meta-raspberrypi/recipes-devtools/pi-blaster
meta-raspberrypi/recipes-devtools/pi-blaster/files
- meta-raspberrypi/recipes-devtools/pi-blaster/*.patch
- meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster.inc
+ meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch
meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb
meta-raspberrypi/recipes-devtools/python
meta-raspberrypi/recipes-devtools/python/python-rtimu
meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch
meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb
- meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.1.0.bb
+ meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb
meta-raspberrypi/recipes-devtools/python/rpi-gpio
meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch
- meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.1.bb
+ meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb
meta-raspberrypi/recipes-devtools/python/rpio
meta-raspberrypi/recipes-devtools/python/rpio/*.patch
meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb
meta-raspberrypi/recipes-devtools/wiringPi
meta-raspberrypi/recipes-devtools/wiringPi/files
meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch
- meta-raspberrypi/recipes-devtools/wiringPi/wiringpi
- meta-raspberrypi/recipes-devtools/wiringPi/wiringpi/*.patch
meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb
meta-raspberrypi/recipes-graphics
meta-raspberrypi/recipes-graphics/eglinfo
meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend
meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend
+ meta-raspberrypi/recipes-graphics/mesa
+ meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend
+ meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend
meta-raspberrypi/recipes-graphics/userland
meta-raspberrypi/recipes-graphics/userland/userland
meta-raspberrypi/recipes-graphics/userland/userland/*.patch
@@ -437,194 +512,204 @@
meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc
meta-raspberrypi/recipes-graphics/wayland
meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend
- meta-raspberrypi/recipes-graphics/weston
- meta-raspberrypi/recipes-graphics/weston/weston_%.bbappend
meta-raspberrypi/recipes-graphics/xorg-xserver
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf
- meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-pitft.conf
+ meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf
+ meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf
meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
+ meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend
meta-raspberrypi/recipes-kernel
meta-raspberrypi/recipes-kernel/linux-firmware
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/LICENSE.broadcom_brcm80211
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.bin
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.txt
- meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_git.bbappend
+ meta-raspberrypi/recipes-kernel/linux-firmware/files
+ meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin
+ meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt
+ meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend
meta-raspberrypi/recipes-kernel/linux
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14/*.patch
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18/*.patch
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1/*.patch
+ meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb
meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi/defconfig
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.14.bb
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.18.bb
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.1.bb
- meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.4.bb
- meta-raspberrypi/recipes-kernel/linux/linux.inc
+ meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb
+ meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb
meta-raspberrypi/recipes-multimedia
meta-raspberrypi/recipes-multimedia/gstreamer
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend
meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend
+ meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12
+ meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch
meta-raspberrypi/recipes-multimedia/omxplayer
meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer
meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch
meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb
- meta-raspberrypi/scripts
- meta-raspberrypi/scripts/lib
- meta-raspberrypi/scripts/lib/image
- meta-raspberrypi/scripts/lib/image/canned-wks
- meta-raspberrypi/scripts/lib/image/canned-wks/sdimage-raspberrypi.wks
- </literallayout>
- </para>
+ meta-raspberrypi/recipes-multimedia/x264
+ meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend
+ meta-raspberrypi/wic
+ meta-raspberrypi/wic/sdimage-raspberrypi.wks
+ </literallayout>
+ </para>
- <para>
- The following sections describe each part of the proposed BSP format.
- </para>
+ <para>
+ The following sections describe each part of the proposed
+ BSP format.
+ </para>
- <section id="bsp-filelayout-license">
- <title>License Files</title>
+ <section id="bsp-filelayout-license">
+ <title>License Files</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable>
+ </literallayout>
+ </para>
- <para>
- These optional files satisfy licensing requirements for the BSP.
- The type or types of files here can vary depending on the licensing requirements.
- For example, in the Raspberry Pi BSP all licensing requirements are handled with the
- <filename>COPYING.MIT</filename> file.
- </para>
+ <para>
+ These optional files satisfy licensing requirements
+ for the BSP.
+ The type or types of files here can vary depending
+ on the licensing requirements.
+ For example, in the Raspberry Pi BSP all licensing
+ requirements are handled with the
+ <filename>COPYING.MIT</filename> file.
+ </para>
- <para>
- Licensing files can be MIT, BSD, GPLv*, and so forth.
- These files are recommended for the BSP but are optional and totally up to the BSP developer.
- </para>
- </section>
+ <para>
+ Licensing files can be MIT, BSD, GPLv*, and so forth.
+ These files are recommended for the BSP but are
+ optional and totally up to the BSP developer.
+ For information on how to maintain license
+ compliance, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para>
+ </section>
- <section id="bsp-filelayout-readme">
- <title>README File</title>
+ <section id="bsp-filelayout-readme">
+ <title>README File</title>
- <para>
- You can find this file in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/README
- </literallayout>
- </para>
+ <para>
+ You can find this file in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/README
+ </literallayout>
+ </para>
- <para>
- This file provides information on how to boot the live images that are optionally
- included in the <filename>binary/</filename> directory.
- The <filename>README</filename> file also provides special information needed for
- building the image.
- </para>
+ <para>
+ This file provides information on how to boot the live
+ images that are optionally included in the
+ <filename>binary/</filename> directory.
+ The <filename>README</filename> file also provides
+ information needed for building the image.
+ </para>
- <para>
- At a minimum, the <filename>README</filename> file must
- contain a list of dependencies, such as the names of
- any other layers on which the BSP depends and the name of
- the BSP maintainer with his or her contact information.
- </para>
- </section>
+ <para>
+ At a minimum, the <filename>README</filename> file must
+ contain a list of dependencies, such as the names of
+ any other layers on which the BSP depends and the name of
+ the BSP maintainer with his or her contact information.
+ </para>
+ </section>
- <section id="bsp-filelayout-readme-sources">
- <title>README.sources File</title>
+ <section id="bsp-filelayout-readme-sources">
+ <title>README.sources File</title>
- <para>
- You can find this file in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/README.sources
- </literallayout>
- </para>
+ <para>
+ You can find this file in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/README.sources
+ </literallayout>
+ </para>
- <para>
- This file provides information on where to locate the BSP
- source files used to build the images (if any) that reside in
- <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
- Images in the <filename>binary</filename> would be images
- released with the BSP.
- The information in the <filename>README.sources</filename>
- file also helps you find the
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
- used to generate the images that ship with the BSP.
- <note>
- If the BSP's <filename>binary</filename> directory is
- missing or the directory has no images, an existing
- <filename>README.sources</filename> file is
- meaningless.
- </note>
- </para>
- </section>
+ <para>
+ This file provides information on where to locate the BSP
+ source files used to build the images (if any) that
+ reside in
+ <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>.
+ Images in the <filename>binary</filename> would be images
+ released with the BSP.
+ The information in the <filename>README.sources</filename>
+ file also helps you find the
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ used to generate the images that ship with the BSP.
+ <note>
+ If the BSP's <filename>binary</filename> directory is
+ missing or the directory has no images, an existing
+ <filename>README.sources</filename> file is
+ meaningless and usually does not exist.
+ </note>
+ </para>
+ </section>
- <section id="bsp-filelayout-binary">
- <title>Pre-built User Binaries</title>
+ <section id="bsp-filelayout-binary">
+ <title>Pre-built User Binaries</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
+ </literallayout>
+ </para>
- <para>
- This optional area contains useful pre-built kernels and
- user-space filesystem images released with the BSP that are
- appropriate to the target system.
- This directory typically contains graphical (e.g. Sato) and
- minimal live images when the BSP tarball has been created and
- made available in the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
- You can use these kernels and images to get a system running
- and quickly get started on development tasks.
- </para>
+ <para>
+ This optional area contains useful pre-built kernels
+ and user-space filesystem images released with the
+ BSP that are appropriate to the target system.
+ This directory typically contains graphical (e.g. Sato)
+ and minimal live images when the BSP tarball has been
+ created and made available in the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
+ website.
+ You can use these kernels and images to get a system
+ running and quickly get started on development tasks.
+ </para>
- <para>
- The exact types of binaries present are highly
- hardware-dependent.
- The <filename>README</filename> file should be present in the
- BSP Layer and it will explain how to use the images with the
- target hardware.
- Additionally, the <filename>README.sources</filename> file
- should be present to locate the sources used to build the
- images and provide information on the Metadata.
- </para>
- </section>
+ <para>
+ The exact types of binaries present are highly
+ hardware-dependent.
+ The
+ <link linkend='bsp-filelayout-readme'><filename>README</filename></link>
+ file should be present in the BSP Layer and it
+ explains how to use the images with the target hardware.
+ Additionally, the
+ <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link>
+ file should be present to locate the sources used to
+ build the images and provide information on the
+ Metadata.
+ </para>
+ </section>
- <section id='bsp-filelayout-layer'>
- <title>Layer Configuration File</title>
+ <section id='bsp-filelayout-layer'>
+ <title>Layer Configuration File</title>
- <para>
- You can find this file in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
- </literallayout>
- </para>
+ <para>
+ You can find this file in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf
+ </literallayout>
+ </para>
- <para>
- The <filename>conf/layer.conf</filename> file identifies the file structure as a
- layer, identifies the
- contents of the layer, and contains information about how the build
- system should use it.
- Generally, a standard boilerplate file such as the following works.
- In the following example, you would replace "<replaceable>bsp</replaceable>" and
- "<replaceable>_bsp</replaceable>" with the actual name
- of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
- </para>
+ <para>
+ The <filename>conf/layer.conf</filename> file
+ identifies the file structure as a layer,
+ identifies the contents of the layer, and
+ contains information about how the build system should
+ use it.
+ Generally, a standard boilerplate file such as the
+ following works.
+ In the following example, you would replace
+ <replaceable>bsp</replaceable> with the actual
+ name of the BSP (i.e.
+ <replaceable>bsp_root_name</replaceable> from the example
+ template).
+ </para>
- <para>
- <literallayout class='monospaced'>
+ <para>
+ <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -637,13 +722,14 @@
BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- To illustrate the string substitutions, here are the corresponding statements
- from the Raspberry Pi <filename>conf/layer.conf</filename> file:
- <literallayout class='monospaced'>
+ <para>
+ To illustrate the string substitutions, here are
+ the corresponding statements from the Raspberry
+ Pi <filename>conf/layer.conf</filename> file:
+ <literallayout class='monospaced'>
# We have a conf and classes directory, append to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -657,1265 +743,1527 @@
# Additional license directories.
LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
- </literallayout>
- </para>
+ .
+ .
+ .
+ </literallayout>
+ </para>
- <para>
- This file simply makes
- <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
- aware of the recipes and configuration directories.
- The file must exist so that the OpenEmbedded build system can recognize the BSP.
- </para>
- </section>
+ <para>
+ This file simply makes
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ aware of the recipes and configuration directories.
+ The file must exist so that the OpenEmbedded build system
+ can recognize the BSP.
+ </para>
+ </section>
- <section id="bsp-filelayout-machine">
- <title>Hardware Configuration Options</title>
+ <section id="bsp-filelayout-machine">
+ <title>Hardware Configuration Options</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf
+ </literallayout>
+ </para>
- <para>
- The machine files bind together all the information contained elsewhere
- in the BSP into a format that the build system can understand.
- If the BSP supports multiple machines, multiple machine configuration files
- can be present.
- These filenames correspond to the values to which users have set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
- </para>
+ <para>
+ The machine files bind together all the information
+ contained elsewhere in the BSP into a format that
+ the build system can understand.
+ Each BSP Layer requires at least one machine file.
+ If the BSP supports multiple machines, multiple
+ machine configuration files can exist.
+ These filenames correspond to the values to which
+ users have set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
+ </para>
- <para>
- These files define things such as the kernel package to use
- (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
- of virtual/kernel), the hardware drivers to
- include in different types of images, any special software components
- that are needed, any bootloader information, and also any special image
- format requirements.
- </para>
+ <para>
+ These files define things such as the kernel package
+ to use
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+ of
+ <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>),
+ the hardware drivers to include in different types
+ of images, any special software components that are
+ needed, any bootloader information, and also any
+ special image format requirements.
+ </para>
- <para>
- Each BSP Layer requires at least one machine file.
- However, you can supply more than one file.
- </para>
+ <para>
+ This configuration file could also include a hardware
+ "tuning" file that is commonly used to define the
+ package architecture and specify optimization flags,
+ which are carefully chosen to give best performance
+ on a given processor.
+ </para>
- <para>
- This configuration file could also include a hardware "tuning"
- file that is commonly used to define the package architecture
- and specify optimization flags, which are carefully chosen
- to give best performance on a given processor.
- </para>
+ <para>
+ Tuning files are found in the
+ <filename>meta/conf/machine/include</filename>
+ directory within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ For example, many <filename>tune-*</filename> files
+ (e.g. <filename>tune-arm1136jf-s.inc</filename>,
+ <filename>tun-1586-nlp.inc</filename>, and so forth)
+ reside in the
+ <filename>poky/meta/conf/machine/include</filename>
+ directory.
+ </para>
- <para>
- Tuning files are found in the <filename>meta/conf/machine/include</filename>
- directory within the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- For example, the <filename>ia32-base.inc</filename> file resides in the
- <filename>meta/conf/machine/include</filename> directory.
- </para>
+ <para>
+ To use an include file, you simply include them in the
+ machine configuration file.
+ For example, the Raspberry Pi BSP
+ <filename>raspberrypi3.conf</filename> contains the
+ following statement:
+ <literallayout class='monospaced'>
+ include conf/machine/include/rpi-base.inc
+ </literallayout>
+ </para>
+ </section>
- <para>
- To use an include file, you simply include them in the
- machine configuration file.
- For example, the Raspberry Pi BSP
- <filename>raspberrypi3.conf</filename> contains the
- following statement:
- <literallayout class='monospaced'>
- include conf/machine/raspberrypi2.conf
- </literallayout>
- </para>
- </section>
+ <section id='bsp-filelayout-misc-recipes'>
+ <title>Miscellaneous BSP-Specific Recipe Files</title>
- <section id='bsp-filelayout-misc-recipes'>
- <title>Miscellaneous BSP-Specific Recipe Files</title>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/*
+ </literallayout>
+ </para>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
- </literallayout>
- </para>
-
- <para>
- This optional directory contains miscellaneous recipe files for
- the BSP.
- Most notably would be the formfactor files.
- For example, in the Raspberry Pi BSP there is the
- <filename>formfactor_0.0.bbappend</filename> file, which is an
- append file used to augment the recipe that starts the build.
- Furthermore, there are machine-specific settings used during
- the build that are defined by the
- <filename>machconfig</filename> file further down in the
- directory.
- Here is the <filename>machconfig</filename>
- file for the Raspberry Pi BSP:
- <literallayout class='monospaced'>
+ <para>
+ This optional directory contains miscellaneous recipe
+ files for the BSP.
+ Most notably would be the formfactor files.
+ For example, in the Raspberry Pi BSP there is the
+ <filename>formfactor_0.0.bbappend</filename> file,
+ which is an append file used to augment the recipe
+ that starts the build.
+ Furthermore, there are machine-specific settings used
+ during the build that are defined by the
+ <filename>machconfig</filename> file further down in
+ the directory.
+ Here is the <filename>machconfig</filename> file for
+ the Raspberry Pi BSP:
+ <literallayout class='monospaced'>
HAVE_TOUCHSCREEN=0
HAVE_KEYBOARD=1
DISPLAY_CAN_ROTATE=0
DISPLAY_ORIENTATION=0
DISPLAY_DPI=133
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <note><para>
- If a BSP does not have a formfactor entry, defaults are established according to
- the formfactor configuration file that is installed by the main
- formfactor recipe
- <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
- which is found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- </para></note>
- </section>
+ <note><para>
+ If a BSP does not have a formfactor entry, defaults
+ are established according to the formfactor
+ configuration file that is installed by the main
+ formfactor recipe
+ <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
+ which is found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ </para></note>
+ </section>
- <section id='bsp-filelayout-recipes-graphics'>
- <title>Display Support Files</title>
+ <section id='bsp-filelayout-recipes-graphics'>
+ <title>Display Support Files</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/*
+ </literallayout>
+ </para>
- <para>
- This optional directory contains recipes for the BSP if it has
- special requirements for graphics support.
- All files that are needed for the BSP to support a display are
- kept here.
- </para>
- </section>
+ <para>
+ This optional directory contains recipes for the
+ BSP if it has special requirements for graphics
+ support.
+ All files that are needed for the BSP to support
+ a display are kept here.
+ </para>
+ </section>
- <section id='bsp-filelayout-kernel'>
- <title>Linux Kernel Configuration</title>
+ <section id='bsp-filelayout-kernel'>
+ <title>Linux Kernel Configuration</title>
- <para>
- You can find these files in the BSP Layer at:
- <literallayout class='monospaced'>
- meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
- </literallayout>
- </para>
+ <para>
+ You can find these files in the BSP Layer at:
+ <literallayout class='monospaced'>
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend
+ meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb
+ </literallayout>
+ </para>
- <para>
- These files append machine-specific changes to the main
- kernel recipe you are using.
- </para>
+ <para>
+ Append files (<filename>*.bbappend</filename>) modify
+ the main kernel recipe being used to build the image.
+ The <filename>*.bb</filename> files would be a
+ developer-supplied kernel recipe.
+ This area of the BSP hierarchy can contain both these
+ types of files, although in practice, it is likely that
+ you would have one or the other.
+ </para>
- <para>
- For your BSP, you typically want to use an existing Yocto
- Project kernel recipe found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- at <filename>meta/recipes-kernel/linux</filename>.
- You can append machine-specific changes to the kernel recipe
- by using a similarly named append file, which is located in
- the BSP Layer for your target device (e.g. the
- <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
- </para>
+ <para>
+ For your BSP, you typically want to use an existing Yocto
+ Project kernel recipe found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ at <filename>meta/recipes-kernel/linux</filename>.
+ You can append machine-specific changes to the
+ kernel recipe by using a similarly named append
+ file, which is located in the BSP Layer for your
+ target device (e.g. the
+ <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory).
+ </para>
- <para>
- Suppose you are using the <filename>linux-yocto_4.4.bb</filename>
- recipe to build the kernel.
- In other words, you have selected the kernel in your
- <replaceable>bsp_name</replaceable><filename>.conf</filename>
- file by adding
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
- statements as follows:
- <literallayout class='monospaced'>
+ <para>
+ Suppose you are using the
+ <filename>linux-yocto_4.4.bb</filename> recipe to
+ build the kernel.
+ In other words, you have selected the kernel in your
+ <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ file by adding
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
+ statements as follows:
+ <literallayout class='monospaced'>
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_VERSION_linux-yocto ?= "4.4%"
- </literallayout>
- <note>
- When the preferred provider is assumed by default, the
- <filename>PREFERRED_PROVIDER</filename>
- statement does not appear in the
- <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
- </note>
- You would use the <filename>linux-yocto_4.4.bbappend</filename>
- file to append specific BSP settings to the kernel, thus
- configuring the kernel for your particular BSP.
- </para>
+ </literallayout>
+ <note>
+ When the preferred provider is assumed by
+ default, the
+ <filename>PREFERRED_PROVIDER</filename>
+ statement does not appear in the
+ <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file.
+ </note>
+ You would use the
+ <filename>linux-yocto_4.4.bbappend</filename>
+ file to append specific BSP settings to the kernel,
+ thus configuring the kernel for your particular BSP.
+ </para>
- <para>
- You can find more information on what your append file
- should contain in the
- "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
- section in the Yocto Project Linux Kernel Development
- Manual.
- </para>
- </section>
- </section>
+ <para>
+ You can find more information on what your append file
+ should contain in the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>"
+ section in the Yocto Project Linux Kernel Development
+ Manual.
+ </para>
- <section id='developing-a-board-support-package-bsp'>
- <title>Developing a Board Support Package (BSP)</title>
+ <para>
+ An alternate scenario is when you create your own
+ kernel recipe for the BSP.
+ A good example of this is the Raspberry Pi BSP.
+ If you examine the
+ <filename>recipes-kernel/linux</filename> directory
+ you see the following:
+ <literallayout class='monospaced'>
+ linux-raspberrypi-dev.bb
+ linux-raspberrypi.inc
+ linux-raspberrypi_4.14.bb
+ linux-raspberrypi_4.9.bb
+ </literallayout>
+ The directory contains three kernel recipes and a
+ common include file.
+ </para>
+ </section>
+</section>
- <para>
- This section contains the high-level procedure you can follow
- to create a BSP using the Yocto Project's
- <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
- Although not required for BSP creation, the
- <filename>meta-intel</filename> repository, which contains
- many BSPs supported by the Yocto Project, is part of the
- example.
- </para>
+<section id='developing-a-board-support-package-bsp'>
+ <title>Developing a Board Support Package (BSP)</title>
- <para>
- For an example that shows how to create a new layer using
- the tools, see the
- "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
- section.
- </para>
+ <para>
+ This section contains the high-level procedure you can
+ follow to create a BSP.
+ Although not required for BSP creation, the
+ <filename>meta-intel</filename> repository, which
+ contains many BSPs supported by the Yocto Project,
+ is part of the example.
+ </para>
- <para>
- The following illustration and list summarize the BSP
- creation general workflow.
- </para>
+ <para>
+ For an example that shows how to create a new
+ layer using the tools, see the
+ "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section.
+ </para>
- <para>
- <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
- </para>
+ <para>
+ The following illustration and list summarize the BSP
+ creation general workflow.
+ </para>
- <para>
- <orderedlist>
- <listitem><para>
- <emphasis>Set up Your Host Development System to Support
- Development Using the Yocto Project</emphasis>:
- See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
- section in the Yocto Project Quick Start for options on how
- to get a build host ready to use the Yocto Project.
- </para></listitem>
- <listitem><para>
- <emphasis>Establish the <filename>meta-intel</filename>
- Repository on Your System:</emphasis>
- Having local copies of these supported BSP layers on
- your system gives you access to layers you might be able
- to build on or modify to create your BSP.
- For information on how to get these files, see the
- "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Create Your Own BSP Layer Using the
- <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></link>
- script:</emphasis>
- Layers are ideal for isolating and storing work for a
- given piece of hardware.
- A layer is really just a location or area in which you
- place the recipes and configurations for your BSP.
- In fact, a BSP is, in itself, a special type of layer.
- The simplest way to create a new BSP layer that is
- compliant with the Yocto Project is to use the
- <filename>yocto-bsp</filename> script.
- For information about that script, see the
- "<link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</link>"
- section.</para>
+ <para>
+ <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" />
+ </para>
- <para>Another example that illustrates a layer
- is an application.
- Suppose you are creating an application that has
- library or other dependencies in order for it to
- compile and run.
- The layer, in this case, would be where all the
- recipes that define those dependencies are kept.
- The key point for a layer is that it is an isolated
- area that contains all the relevant information for
- the project that the OpenEmbedded build system knows
- about.
- For more information on layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks Manual.
- For more information on BSP layers, see the
- "<link linkend='bsp-layers'>BSP Layers</link>"
- section.
- <note><title>Notes</title>
- <para>Five BSPs exist that are part of the Yocto
- Project release:
- <filename>beaglebone</filename> (ARM),
- <filename>mpc8315e</filename> (PowerPC),
- and <filename>edgerouter</filename> (MIPS).
- The recipes and configurations for these five BSPs
- are located and dispersed within the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- </para>
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set up Your Host Development System
+ to Support Development Using the Yocto
+ Project</emphasis>:
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for options on how to get a system ready
+ to use the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Establish the
+ <filename>meta-intel</filename>
+ Repository on Your System:</emphasis>
+ Having local copies of these supported BSP layers
+ on your system gives you access to layers you
+ might be able to leverage when creating your BSP.
+ For information on how to get these files, see the
+ "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create Your Own BSP Layer Using the
+ <filename>bitbake-layers</filename>
+ Script:</emphasis>
+ Layers are ideal for isolating and storing work
+ for a given piece of hardware.
+ A layer is really just a location or area in which you
+ place the recipes and configurations for your BSP.
+ In fact, a BSP is, in itself, a special type of layer.
+ The simplest way to create a new BSP layer that is
+ compliant with the Yocto Project is to use the
+ <filename>bitbake-layers</filename> script.
+ For information about that script, see the
+ "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section.</para>
- <para>Three core Intel BSPs exist as part of the Yocto
- Project release in the
+ <para>Another example that illustrates a layer
+ is an application.
+ Suppose you are creating an application that has
+ library or other dependencies in order for it to
+ compile and run.
+ The layer, in this case, would be where all the
+ recipes that define those dependencies are kept.
+ The key point for a layer is that it is an
+ isolated area that contains all the relevant
+ information for the project that the
+ OpenEmbedded build system knows about.
+ For more information on layers, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual.
+ You can also reference the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ For more information on BSP layers, see the
+ "<link linkend='bsp-layers'>BSP Layers</link>"
+ section.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Five hardware reference BSPs exist
+ that are part of the Yocto Project release
+ and are located in the
+ <filename>poky/meta-yocto-bsp</filename> BSP
+ layer:
+ <itemizedlist>
+ <listitem><para>
+ Texas Instruments Beaglebone
+ (<filename>beaglebone-yocto</filename>)
+ </para></listitem>
+ <listitem><para>
+ Freescale MPC8315E-RDB
+ (<filename>mpc8315e-rdb</filename>)
+ </para></listitem>
+ <listitem><para>
+ Ubiquiti Networks EdgeRouter Lite
+ (<filename>edgerouter</filename>)
+ </para></listitem>
+ <listitem><para>
+ Two general IA platforms
+ (<filename>genericx86</filename> and
+ <filename>genericx86-64</filename>)
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ Three core Intel BSPs exist as part of
+ the Yocto Project release in the
<filename>meta-intel</filename> layer:
<itemizedlist>
<listitem><para>
<filename>intel-core2-32</filename>,
- which is a BSP optimized for the Core2 family of CPUs
- as well as all CPUs prior to the Silvermont core.
+ which is a BSP optimized for the Core2
+ family of CPUs as well as all CPUs
+ prior to the Silvermont core.
</para></listitem>
<listitem><para>
<filename>intel-corei7-64</filename>,
- which is a BSP optimized for Nehalem and later
- Core and Xeon CPUs as well as Silvermont and later
- Atom CPUs, such as the Baytrail SoCs.
+ which is a BSP optimized for Nehalem
+ and later Core and Xeon CPUs as well
+ as Silvermont and later Atom CPUs,
+ such as the Baytrail SoCs.
</para></listitem>
<listitem><para>
<filename>intel-quark</filename>,
- which is a BSP optimized for the Intel Galileo
- gen1 & gen2 development boards.
+ which is a BSP optimized for the
+ Intel Galileo gen1 & gen2
+ development boards.
</para></listitem>
- </itemizedlist></para>
- </note></para>
-
- <para>When you set up a layer for a new BSP, you should
- follow a standard layout.
- This layout is described in the
- "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
- section.
- In the standard layout, you will notice a suggested
- structure for recipes and configuration information.
- You can see the standard layout for a BSP by examining
- any supported BSP found in the
- <filename>meta-intel</filename> layer inside the Source
- Directory.
- </para></listitem>
- <listitem><para>
- <emphasis>Make Configuration Changes to Your New BSP
- Layer:</emphasis>
- The standard BSP layer structure organizes the files
- you need to edit in <filename>conf</filename> and
- several <filename>recipes-*</filename>
- directories within the BSP layer.
- Configuration changes identify where your new layer
- is on the local system and identify which kernel you
- are going to use.
- When you run the <filename>yocto-bsp</filename> script,
- you are able to interactively configure many things for
- the BSP (e.g. keyboard, touchscreen, and so forth).
- </para></listitem>
- <listitem><para>
- <emphasis>Make Recipe Changes to Your New BSP
- Layer:</emphasis>
- Recipe changes include altering recipes
- (<filename>.bb</filename> files), removing recipes you
- do not use, and adding new recipes or append files
- (<filename>.bbappend</filename>) that you need to
- support your hardware.
- </para></listitem>
- <listitem><para>
- <emphasis>Prepare for the Build:</emphasis>
- Once you have made all the changes to your BSP layer,
- there remains a few things you need to do for the
- OpenEmbedded build system in order for it to create
- your image.
- You need to get the build environment ready by
- sourcing an environment setup script
- (i.e. <filename>oe-init-build-env</filename>)
- and you need to be sure two key configuration
- files are configured appropriately: the
- <filename>conf/local.conf</filename> and the
- <filename>conf/bblayers.conf</filename> file.
- You must make the OpenEmbedded build system aware
- of your new layer.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual
- for information on how to let the build system
- know about your new layer.</para>
-
- <para>The entire process for building an image is
- overviewed in the section
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section
- of the Yocto Project Quick Start.
- You might want to reference this information.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Image:</emphasis>
- The OpenEmbedded build system uses the BitBake tool
- to build images based on the type of image you want to
- create.
- You can find more information about BitBake in the
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
- </para>
-
- <para>The build process supports several types of
- images to satisfy different needs.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
- chapter in the Yocto Project Reference Manual for
- information on supported images.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='requirements-and-recommendations-for-released-bsps'>
- <title>Requirements and Recommendations for Released BSPs</title>
-
- <para>
- Certain requirements exist for a released BSP to be considered
- compliant with the Yocto Project.
- Additionally, recommendations also exist.
- This section describes the requirements and recommendations for
- released BSPs.
- </para>
-
- <section id='released-bsp-requirements'>
- <title>Released BSP Requirements</title>
-
- <para>
- Before looking at BSP requirements, you should consider the following:
- <itemizedlist>
- <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
- layer that can be added to the Yocto Project.
- For guidelines on creating a layer that meets these base requirements, see the
- "<link linkend='bsp-layers'>BSP Layers</link>" and the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
- and Creating Layers"</ulink> in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>The requirements in this section apply regardless of how you
- package a BSP.
- You should consult the packaging and distribution guidelines for your
- specific release process.
- For an example of packaging and distribution requirements, see the
- "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
- wiki page.
- </para></listitem>
- <listitem><para>The requirements for the BSP as it is made available to a developer
- are completely independent of the released form of the BSP.
- For example, the BSP Metadata can be contained within a Git repository
- and could have a directory structure completely different from what appears
- in the officially released BSP layer.
- </para></listitem>
- <listitem><para>It is not required that specific packages or package
- modifications exist in the BSP layer, beyond the requirements for general
- compliance with the Yocto Project.
- For example, no requirement exists dictating that a specific kernel or
- kernel version be used in a given BSP.
+ </itemizedlist>
</para></listitem>
</itemizedlist>
+ </note></para>
+
+ <para>When you set up a layer for a new BSP,
+ you should follow a standard layout.
+ This layout is described in the
+ "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>"
+ section.
+ In the standard layout, notice the suggested
+ structure for recipes and configuration
+ information.
+ You can see the standard layout for a BSP
+ by examining any supported BSP found in the
+ <filename>meta-intel</filename> layer inside
+ the Source Directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Configuration Changes to Your New
+ BSP Layer:</emphasis>
+ The standard BSP layer structure organizes the
+ files you need to edit in
+ <filename>conf</filename> and several
+ <filename>recipes-*</filename> directories
+ within the BSP layer.
+ Configuration changes identify where your new
+ layer is on the local system and identifies the
+ kernel you are going to use.
+ When you run the
+ <filename>bitbake-layers</filename> script,
+ you are able to interactively configure many
+ things for the BSP (e.g. keyboard, touchscreen,
+ and so forth).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Recipe Changes to Your New BSP
+ Layer:</emphasis>
+ Recipe changes include altering recipes
+ (<filename>*.bb</filename> files), removing
+ recipes you do not use, and adding new recipes
+ or append files (<filename>.bbappend</filename>)
+ that support your hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Prepare for the Build:</emphasis>
+ Once you have made all the changes to your BSP
+ layer, there remains a few things you need to
+ do for the OpenEmbedded build system in order
+ for it to create your image.
+ You need to get the build environment ready by
+ sourcing an environment setup script
+ (i.e. <filename>oe-init-build-env</filename>)
+ and you need to be sure two key configuration
+ files are configured appropriately: the
+ <filename>conf/local.conf</filename> and the
+ <filename>conf/bblayers.conf</filename> file.
+ You must make the OpenEmbedded build system aware
+ of your new layer.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
+ section in the Yocto Project Development Tasks Manual
+ for information on how to let the build system
+ know about your new layer.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Image:</emphasis>
+ The OpenEmbedded build system uses the BitBake tool
+ to build images based on the type of image you want to
+ create.
+ You can find more information about BitBake in the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</para>
- <para>
- Following are the requirements for a released BSP that conform to the
- Yocto Project:
+ <para>The build process supports several types of
+ images to satisfy different needs.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual for
+ information on supported images.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='requirements-and-recommendations-for-released-bsps'>
+ <title>Requirements and Recommendations for Released BSPs</title>
+
+ <para>
+ Certain requirements exist for a released BSP to be
+ considered compliant with the Yocto Project.
+ Additionally, recommendations also exist.
+ This section describes the requirements and
+ recommendations for released BSPs.
+ </para>
+
+ <section id='released-bsp-requirements'>
+ <title>Released BSP Requirements</title>
+
+ <para>
+ Before looking at BSP requirements, you should consider
+ the following:
+ <itemizedlist>
+ <listitem><para>
+ The requirements here assume the BSP layer
+ is a well-formed, "legal" layer that can be
+ added to the Yocto Project.
+ For guidelines on creating a layer that meets
+ these base requirements, see the
+ "<link linkend='bsp-layers'>BSP Layers</link>"
+ section in this manual and the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para></listitem>
+ <listitem><para>
+ The requirements in this section apply
+ regardless of how you package a BSP.
+ You should consult the packaging and distribution
+ guidelines for your specific release process.
+ For an example of packaging and distribution
+ requirements, see the
+ "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
+ wiki page.
+ </para></listitem>
+ <listitem><para>
+ The requirements for the BSP as it is made
+ available to a developer are completely
+ independent of the released form of the BSP.
+ For example, the BSP Metadata can be contained
+ within a Git repository and could have a directory
+ structure completely different from what appears
+ in the officially released BSP layer.
+ </para></listitem>
+ <listitem><para>
+ It is not required that specific packages or
+ package modifications exist in the BSP layer,
+ beyond the requirements for general
+ compliance with the Yocto Project.
+ For example, no requirement exists dictating
+ that a specific kernel or kernel version be
+ used in a given BSP.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Following are the requirements for a released BSP
+ that conform to the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Layer Name:</emphasis>
+ The BSP must have a layer name that follows
+ the Yocto Project standards.
+ For information on BSP layer names, see the
+ "<link linkend='bsp-layers'>BSP Layers</link>" section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>File System Layout:</emphasis>
+ When possible, use the same directory names
+ in your BSP layer as listed in the
+ <filename>recipes.txt</filename> file, which
+ is found in <filename>poky/meta</filename>
+ directory of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ or in the OpenEmbedded-Core Layer
+ (<filename>openembedded-core</filename>) at
+ <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
+ </para>
+
+ <para>You should place recipes
+ (<filename>*.bb</filename> files) and recipe
+ modifications (<filename>*.bbappend</filename>
+ files) into <filename>recipes-*</filename>
+ subdirectories by functional area as outlined
+ in <filename>recipes.txt</filename>.
+ If you cannot find a category in
+ <filename>recipes.txt</filename> to fit a
+ particular recipe, you can make up your own
+ <filename>recipes-*</filename> subdirectory.
+ </para>
+
+ <para>Within any particular
+ <filename>recipes-*</filename> category, the
+ layout should match what is found in the
+ OpenEmbedded-Core Git repository
+ (<filename>openembedded-core</filename>)
+ or the Source Directory (<filename>poky</filename>).
+ In other words, make sure you place related
+ files in appropriately related
+ <filename>recipes-*</filename> subdirectories
+ specific to the recipe's function, or within
+ a subdirectory containing a set of closely-related
+ recipes.
+ The recipes themselves should follow the general
+ guidelines for recipes used in the Yocto Project
+ found in the
+ "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>License File:</emphasis>
+ You must include a license file in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ This license covers the BSP Metadata as a whole.
+ You must specify which license to use since no
+ default license exists when one not specified.
+ See the
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
+ file for the Raspberry Pi BSP in the
+ <filename>meta-raspberrypi</filename> BSP layer
+ as an example.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>README File:</emphasis>
+ You must include a <filename>README</filename>
+ file in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ See the
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink>
+ file for the Raspberry Pi BSP in the
+ <filename>meta-raspberrypi</filename> BSP layer
+ as an example.</para>
+
+ <para>At a minimum, the <filename>README</filename>
+ file should contain the following:
<itemizedlist>
- <listitem><para><emphasis>Layer Name:</emphasis>
- The BSP must have a layer name that follows the Yocto
- Project standards.
- For information on BSP layer names, see the
- "<link linkend='bsp-layers'>BSP Layers</link>" section.
+ <listitem><para>
+ A brief description about the hardware the BSP
+ targets.
</para></listitem>
- <listitem><para><emphasis>File System Layout:</emphasis>
- When possible, use the same directory names in your
- BSP layer as listed in the <filename>recipes.txt</filename> file.
- In particular, you should place recipes
- (<filename>.bb</filename> files) and recipe
- modifications (<filename>.bbappend</filename> files) into
- <filename>recipes-*</filename> subdirectories by functional area
- as outlined in <filename>recipes.txt</filename>.
- If you cannot find a category in <filename>recipes.txt</filename>
- to fit a particular recipe, you can make up your own
- <filename>recipes-*</filename> subdirectory.
- You can find <filename>recipes.txt</filename> in the
- <filename>meta</filename> directory of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- or in the OpenEmbedded Core Layer
- (<filename>openembedded-core</filename>) found at
- <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
- </para>
- <para>Within any particular <filename>recipes-*</filename> category, the layout
- should match what is found in the OpenEmbedded Core
- Git repository (<filename>openembedded-core</filename>)
- or the Source Directory (<filename>poky</filename>).
- In other words, make sure you place related files in appropriately
- related <filename>recipes-*</filename> subdirectories specific to the
- recipe's function, or within a subdirectory containing a set of closely-related
- recipes.
- The recipes themselves should follow the general guidelines
- for recipes used in the Yocto Project found in the
- "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>".
+ <listitem><para>
+ A list of all the dependencies
+ on which a BSP layer depends.
+ These dependencies are typically a list
+ of required layers needed to build the
+ BSP.
+ However, the dependencies should also
+ contain information regarding any other
+ dependencies the BSP might have.
</para></listitem>
- <listitem><para><emphasis>License File:</emphasis>
- You must include a license file in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This license covers the BSP Metadata as a whole.
- You must specify which license to use since there is no
- default license if one is not specified.
- See the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
- file for the Raspberry Pi BSP in the
- <filename>meta-raspberrypi</filename> BSP layer as an example.
+ <listitem><para>
+ Any required special licensing information.
+ For example, this information includes
+ information on special variables needed
+ to satisfy a EULA, or instructions on
+ information needed to build or distribute
+ binaries built from the BSP Metadata.
</para></listitem>
- <listitem><para><emphasis>README File:</emphasis>
- You must include a <filename>README</filename> file in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- See the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
- file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer
- as an example.</para>
- <para>At a minimum, the <filename>README</filename> file should
- contain the following:
- <itemizedlist>
- <listitem><para>A brief description about the hardware the BSP
- targets.</para></listitem>
- <listitem><para>A list of all the dependencies
- on which a BSP layer depends.
- These dependencies are typically a list of required layers needed
- to build the BSP.
- However, the dependencies should also contain information regarding
- any other dependencies the BSP might have.</para></listitem>
- <listitem><para>Any required special licensing information.
- For example, this information includes information on
- special variables needed to satisfy a EULA,
- or instructions on information needed to build or distribute
- binaries built from the BSP Metadata.</para></listitem>
- <listitem><para>The name and contact information for the
- BSP layer maintainer.
- This is the person to whom patches and questions should
- be sent.
- For information on how to find the right person, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>Instructions on how to build the BSP using the BSP
- layer.</para></listitem>
- <listitem><para>Instructions on how to boot the BSP build from
- the BSP layer.</para></listitem>
- <listitem><para>Instructions on how to boot the binary images
- contained in the <filename>binary</filename> directory,
- if present.</para></listitem>
- <listitem><para>Information on any known bugs or issues that users
- should know about when either building or booting the BSP
- binaries.</para></listitem>
- </itemizedlist></para></listitem>
- <listitem><para><emphasis>README.sources File:</emphasis>
- You must include a <filename>README.sources</filename> in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This file specifies exactly where you can find the sources used to
- generate the binary images contained in the
- <filename>binary</filename> directory, if present.
+ <listitem><para>
+ The name and contact information for the
+ BSP layer maintainer.
+ This is the person to whom patches and
+ questions should be sent.
+ For information on how to find the right
+ person, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
+ section in the Yocto Project Development
+ Tasks Manual.
</para></listitem>
- <listitem><para><emphasis>Layer Configuration File:</emphasis>
- You must include a <filename>conf/layer.conf</filename> in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename>
- BSP layer as a layer to the build system.</para></listitem>
- <listitem><para><emphasis>Machine Configuration File:</emphasis>
- You must include one or more
- <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename>
- files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- These configuration files define machine targets that can be built
- using the BSP layer.
- Multiple machine configuration files define variations of machine
- configurations that are supported by the BSP.
- If a BSP supports multiple machine variations, you need to
- adequately describe each variation in the BSP
- <filename>README</filename> file.
- Do not use multiple machine configuration files to describe disparate
- hardware.
- If you do have very different targets, you should create separate
- BSP layers for each target.
- <note>It is completely possible for a developer to structure the
- working repository as a conglomeration of unrelated BSP
- files, and to possibly generate BSPs targeted for release
- from that directory using scripts or some other mechanism
- (e.g. <filename>meta-yocto-bsp</filename> layer).
- Such considerations are outside the scope of this document.</note>
+ <listitem><para>
+ Instructions on how to build the BSP using
+ the BSP layer.
+ </para></listitem>
+ <listitem><para>
+ Instructions on how to boot the BSP build
+ from the BSP layer.
+ </para></listitem>
+ <listitem><para>
+ Instructions on how to boot the binary
+ images contained in the
+ <filename>binary</filename> directory,
+ if present.
+ </para></listitem>
+ <listitem><para>
+ Information on any known bugs or issues
+ that users should know about when either
+ building or booting the BSP binaries.
</para></listitem>
</itemizedlist>
- </para>
- </section>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>README.sources File:</emphasis>
+ If you BSP contains binary images in the
+ <filename>binary</filename> directory, you must
+ include a <filename>README.sources</filename>
+ file in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ This file specifies exactly where you can find
+ the sources used to generate the binary images.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Layer Configuration File:</emphasis>
+ You must include a
+ <filename>conf/layer.conf</filename> file in
+ the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ This file identifies the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ BSP layer as a layer to the build system.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Machine Configuration File:</emphasis>
+ You must include one or more
+ <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ files in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ These configuration files define machine targets
+ that can be built using the BSP layer.
+ Multiple machine configuration files define
+ variations of machine configurations that the
+ BSP supports.
+ If a BSP supports multiple machine variations,
+ you need to adequately describe each variation
+ in the BSP <filename>README</filename> file.
+ Do not use multiple machine configuration files
+ to describe disparate hardware.
+ If you do have very different targets, you should
+ create separate BSP layers for each target.
+ <note>
+ It is completely possible for a developer to
+ structure the working repository as a
+ conglomeration of unrelated BSP files, and to
+ possibly generate BSPs targeted for release
+ from that directory using scripts or some
+ other mechanism
+ (e.g. <filename>meta-yocto-bsp</filename> layer).
+ Such considerations are outside the scope of
+ this document.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
- <section id='released-bsp-recommendations'>
- <title>Released BSP Recommendations</title>
+ <section id='released-bsp-recommendations'>
+ <title>Released BSP Recommendations</title>
- <para>
- Following are recommendations for a released BSP that conforms to the
- Yocto Project:
- <itemizedlist>
- <listitem><para><emphasis>Bootable Images:</emphasis>
- BSP releases
- can contain one or more bootable images.
- Including bootable images allows users to easily try out the BSP
- on their own hardware.</para>
- <para>In some cases, it might not be convenient to include a
- bootable image.
- In this case, you might want to make two versions of the
- BSP available: one that contains binary images, and one
- that does not.
- The version that does not contain bootable images avoids
- unnecessary download times for users not interested in the images.
- </para>
- <para>If you need to distribute a BSP and include bootable images or build kernel and
- filesystems meant to allow users to boot the BSP for evaluation
- purposes, you should put the images and artifacts within a
- <filename>binary/</filename> subdirectory located in the
- <filename>meta-<replaceable>bsp_name</replaceable></filename> directory.
- <note>If you do include a bootable image as part of the BSP and the image
- was built by software covered by the GPL or other open source licenses,
- it is your responsibility to understand
- and meet all licensing requirements, which could include distribution
- of source files.</note></para></listitem>
- <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
- Kernel recipes in the BSP should be based on a Yocto Linux kernel.
- Basing your recipes on these kernels reduces the costs for maintaining
- the BSP and increases its scalability.
- See the <filename>Yocto Linux Kernel</filename> category in the
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
- for these kernels.</para></listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
+ <para>
+ Following are recommendations for released BSPs that
+ conform to the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Bootable Images:</emphasis>
+ Released BSPs can contain one or more bootable
+ images.
+ Including bootable images allows users to easily
+ try out the BSP using their own hardware.</para>
- <section id='customizing-a-recipe-for-a-bsp'>
- <title>Customizing a Recipe for a BSP</title>
+ <para>In some cases, it might not be convenient
+ to include a bootable image.
+ If so, you might want to make two versions of the
+ BSP available: one that contains binary images, and
+ one that does not.
+ The version that does not contain bootable images
+ avoids unnecessary download times for users not
+ interested in the images.</para>
- <para>
- If you plan on customizing a recipe for a particular BSP, you need to do the
- following:
- <itemizedlist>
- <listitem><para>Create a <filename>.bbappend</filename>
- file for the modified recipe.
- For information on using append files, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>
- Ensure your directory structure in the BSP layer
- that supports your machine is such that it can be found
- by the build system.
- See the example later in this section for more information.
- </para></listitem>
- <listitem><para>
- Put the append file in a directory whose name matches
- the machine's name and is located in an appropriate
- sub-directory inside the BSP layer (i.e.
- <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>,
- <filename>recipes-core</filename>, and so forth).
- </para></listitem>
- <listitem><para>Place the BSP-specific files in the proper directory
- inside the BSP layer.
- How expansive the layer is affects where you must place these files.
- For example, if your layer supports several different machine types,
- you need to be sure your layer's directory structure includes hierarchy
- that separates the files out according to machine.
- If your layer does not support multiple machines, the layer would not
- have that additional hierarchy and the files would obviously not be
- able to reside in a machine-specific directory.
- </para></listitem>
- </itemizedlist>
- </para>
+ <para>If you need to distribute a BSP and include
+ bootable images or build kernel and filesystems
+ meant to allow users to boot the BSP for evaluation
+ purposes, you should put the images and artifacts
+ within a
+ <filename>binary/</filename> subdirectory located
+ in the
+ <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
+ directory.
+ <note>
+ If you do include a bootable image as part
+ of the BSP and the image was built by software
+ covered by the GPL or other open source licenses,
+ it is your responsibility to understand
+ and meet all licensing requirements, which could
+ include distribution of source files.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use a Yocto Linux Kernel:</emphasis>
+ Kernel recipes in the BSP should be based on a
+ Yocto Linux kernel.
+ Basing your recipes on these kernels reduces
+ the costs for maintaining the BSP and increases
+ its scalability.
+ See the <filename>Yocto Linux Kernel</filename>
+ category in the
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
+ for these kernels.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
- <para>
- Following is a specific example to help you better understand the process.
- Consider an example that customizes a recipe by adding
- a BSP-specific configuration file named <filename>interfaces</filename> to the
- <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the
- BSP layer also supports several other machines.
- Do the following:
- <orderedlist>
- <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
- contains the following:
- <literallayout class='monospaced'>
+<section id='customizing-a-recipe-for-a-bsp'>
+ <title>Customizing a Recipe for a BSP</title>
+
+ <para>
+ If you plan on customizing a recipe for a particular BSP,
+ you need to do the following:
+ <itemizedlist>
+ <listitem><para>
+ Create a <filename>*.bbappend</filename> file for
+ the modified recipe.
+ For information on using append files, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para></listitem>
+ <listitem><para>
+ Ensure your directory structure in the BSP layer
+ that supports your machine is such that the
+ OpenEmbedded build system can find it.
+ See the example later in this section for more
+ information.
+ </para></listitem>
+ <listitem><para>
+ Put the append file in a directory whose name matches
+ the machine's name and is located in an appropriate
+ sub-directory inside the BSP layer (i.e.
+ <filename>recipes-bsp</filename>,
+ <filename>recipes-graphics</filename>,
+ <filename>recipes-core</filename>, and so forth).
+ </para></listitem>
+ <listitem><para>
+ Place the BSP-specific files in the proper
+ directory inside the BSP layer.
+ How expansive the layer is affects where you must
+ place these files.
+ For example, if your layer supports several
+ different machine types, you need to be sure your
+ layer's directory structure includes hierarchy
+ that separates the files according to machine.
+ If your layer does not support multiple machines,
+ the layer would not have that additional hierarchy
+ and the files would obviously not be able to reside
+ in a machine-specific directory.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Following is a specific example to help you better understand
+ the process.
+ This example customizes customizes a recipe by adding a
+ BSP-specific configuration file named
+ <filename>interfaces</filename> to the
+ <filename>init-ifupdown_1.0.bb</filename> recipe for machine
+ "xyz" where the BSP layer also supports several other
+ machines:
+ <orderedlist>
+ <listitem><para>
+ Edit the
+ <filename>init-ifupdown_1.0.bbappend</filename> file
+ so that it contains the following:
+ <literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
- </literallayout>
- The append file needs to be in the
- <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
- </para></listitem>
- <listitem><para>Create and place the new <filename>interfaces</filename>
- configuration file in the BSP's layer here:
- <literallayout class='monospaced'>
+ </literallayout>
+ The append file needs to be in the
+ <filename>meta-xyz/recipes-core/init-ifupdown</filename>
+ directory.
+ </para></listitem>
+ <listitem><para>
+ Create and place the new
+ <filename>interfaces</filename> configuration file in
+ the BSP's layer here:
+ <literallayout class='monospaced'>
meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
- </literallayout>
- <note>
- If the <filename>meta-xyz</filename> layer did not support
- multiple machines, you would place the
- <filename>interfaces</filename> configuration file in the
- layer here:
- <literallayout class='monospaced'>
+ </literallayout>
+ <note>
+ If the <filename>meta-xyz</filename> layer did
+ not support multiple machines, you would place
+ the <filename>interfaces</filename> configuration
+ file in the layer here:
+ <literallayout class='monospaced'>
meta-xyz/recipes-core/init-ifupdown/files/interfaces
- </literallayout>
- </note>
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
- variable in the append files extends the search path
- the build system uses to find files during the build.
- Consequently, for this example you need to have the
- <filename>files</filename> directory in the same location
- as your append file.</para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='bsp-licensing-considerations'>
- <title>BSP Licensing Considerations</title>
-
- <para>
- In some cases, a BSP contains separately licensed Intellectual Property (IP)
- for a component or components.
- For these cases, you are required to accept the terms of a commercial or other
- type of license that requires some kind of explicit End User License Agreement (EULA).
- Once the license is accepted, the OpenEmbedded build system can then build and
- include the corresponding component in the final BSP image.
- If the BSP is available as a pre-built image, you can download the image after
- agreeing to the license or EULA.
- </para>
-
- <para>
- You could find that some separately licensed components that are essential
- for normal operation of the system might not have an unencumbered (or free)
- substitute.
- Without these essential components, the system would be non-functional.
- Then again, you might find that other licensed components that are simply
- 'good-to-have' or purely elective do have an unencumbered, free replacement
- component that you can use rather than agreeing to the separately licensed component.
- Even for components essential to the system, you might find an unencumbered component
- that is not identical but will work as a less-capable version of the
- licensed version in the BSP recipe.
- </para>
-
- <para>
- For cases where you can substitute a free component and still
- maintain the system's functionality, the "Downloads" page from the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
- makes available de-featured BSPs
- that are completely free of any IP encumbrances.
- For these cases, you can use the substitution directly and
- without any further licensing requirements.
- If present, these fully de-featured BSPs are named appropriately
- different as compared to the names of the respective
- encumbered BSPs.
- If available, these substitutions are your
- simplest and most preferred options.
- Use of these substitutions of course assumes the resulting functionality meets
- system requirements.
- </para>
-
- <para>
- If however, a non-encumbered version is unavailable or
- it provides unsuitable functionality or quality, you can use an encumbered
- version.
- </para>
-
- <para>
- A couple different methods exist within the OpenEmbedded build system to
- satisfy the licensing requirements for an encumbered BSP.
- The following list describes them in order of preference:
- <orderedlist>
- <listitem><para><emphasis>Use the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
- variable to define the recipes that have commercial or other
- types of specially-licensed packages:</emphasis>
- For each of those recipes, you can
- specify a matching license string in a
- <filename>local.conf</filename> variable named
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
- Specifying the matching license string signifies that you agree to the license.
- Thus, the build system can build the corresponding recipe and include
- the component in the image.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
- Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
- Manual for details on how to use these variables.</para>
- <para>If you build as you normally would, without
- specifying any recipes in the
- <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
- provides you with the list of recipes that you have
- tried to include in the image that need entries in
- the <filename>LICENSE_FLAGS_WHITELIST</filename>.
- Once you enter the appropriate license flags into the whitelist,
- restart the build to continue where it left off.
- During the build, the prompt will not appear again
- since you have satisfied the requirement.</para>
- <para>Once the appropriate license flags are on the white list
- in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
- can build the encumbered image with no change at all
- to the normal build process.</para></listitem>
- <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
- You can get this type of BSP by visiting the
- "Downloads" page of the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
- You can download BSP tarballs that contain proprietary components
- after agreeing to the licensing
- requirements of each of the individually encumbered
- packages as part of the download process.
- Obtaining the BSP this way allows you to access an encumbered
- image immediately after agreeing to the
- click-through license agreements presented by the
- website.
- Note that if you want to build the image
- yourself using the recipes contained within the BSP
- tarball, you will still need to create an
- appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
- encumbered recipes in the BSP.</para></listitem>
- </orderedlist>
- </para>
-
- <note>
- Pre-compiled images are bundled with
- a time-limited kernel that runs for a
- predetermined amount of time (10 days) before it forces
- the system to reboot.
- This limitation is meant to discourage direct redistribution
- of the image.
- You must eventually rebuild the image if you want to remove this restriction.
- </note>
- </section>
-
- <section id='using-the-yocto-projects-bsp-tools'>
- <title>Using the Yocto Project's BSP Tools</title>
-
- <para>
- The Yocto Project includes a couple of tools that enable
- you to create a <link linkend='bsp-layers'>BSP layer</link>
- from scratch and do basic configuration and maintenance
- of the kernel without ever looking at a Metadata file.
- These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
- respectively.
- </para>
-
- <para>
- The following sections describe the common location and help features as well
- as provide details for the
- <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
- </para>
-
- <section id='common-features'>
- <title>Common Features</title>
-
- <para>
- Designed to have a command interface somewhat like
- <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, each
- tool is structured as a set of sub-commands under a
- top-level command.
- The top-level command (<filename>yocto-bsp</filename>
- or <filename>yocto-kernel</filename>) itself does
- nothing but invoke or provide help on the sub-commands
- it supports.
- </para>
-
- <para>
- Both tools reside in the <filename>scripts/</filename> subdirectory
- of the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- Consequently, to use the scripts, you must <filename>source</filename> the
- environment just as you would when invoking a build:
- <literallayout class='monospaced'>
- $ source oe-init-build-env <replaceable>build_dir</replaceable>
</literallayout>
+ </note>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+ variable in the append files extends the search path
+ the build system uses to find files during the build.
+ Consequently, for this example you need to have the
+ <filename>files</filename> directory in the same
+ location as your append file.
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='bsp-licensing-considerations'>
+ <title>BSP Licensing Considerations</title>
+
+ <para>
+ In some cases, a BSP contains separately licensed
+ Intellectual Property (IP) for a component or components.
+ For these cases, you are required to accept the terms
+ of a commercial or other type of license that requires
+ some kind of explicit End User License Agreement (EULA).
+ Once you accept the license, the OpenEmbedded build system
+ can then build and include the corresponding component
+ in the final BSP image.
+ If the BSP is available as a pre-built image, you can
+ download the image after agreeing to the license or EULA.
+ </para>
+
+ <para>
+ You could find that some separately licensed components
+ that are essential for normal operation of the system might
+ not have an unencumbered (or free) substitute.
+ Without these essential components, the system would be
+ non-functional.
+ Then again, you might find that other licensed components
+ that are simply 'good-to-have' or purely elective do have
+ an unencumbered, free replacement component that you can
+ use rather than agreeing to the separately licensed
+ component.
+ Even for components essential to the system, you might
+ find an unencumbered component that is not identical but
+ will work as a less-capable version of the licensed version
+ in the BSP recipe.
+ </para>
+
+ <para>
+ For cases where you can substitute a free component and
+ still maintain the system's functionality, the "DOWNLOADS"
+ selection from the "SOFTWARE" tab on the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>
+ makes available de-featured BSPs that are completely free
+ of any IP encumbrances.
+ For these cases, you can use the substitution directly and
+ without any further licensing requirements.
+ If present, these fully de-featured BSPs are named
+ appropriately different as compared to the names of their
+ respective encumbered BSPs.
+ If available, these substitutions are your simplest and
+ most preferred options.
+ Obviously, use of these substitutions assumes the resulting
+ functionality meets system requirements.
+ <note>
+ If however, a non-encumbered version is unavailable or
+ it provides unsuitable functionality or quality, you can
+ use an encumbered version.
+ </note>
+ </para>
+
+ <para>
+ A couple different methods exist within the OpenEmbedded
+ build system to satisfy the licensing requirements for an
+ encumbered BSP.
+ The following list describes them in order of preference:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ Variable to Define the Recipes that Have Commercial
+ or Other Types of Specially-Licensed Packages:</emphasis>
+ For each of those recipes, you can specify a
+ matching license string in a
+ <filename>local.conf</filename> variable named
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>.
+ Specifying the matching license string signifies
+ that you agree to the license.
+ Thus, the build system can build the corresponding
+ recipe and include the component in the image.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for details on how to use these variables.
</para>
- <para>
- The most immediately useful function is to get help on both tools.
- The built-in help system makes it easy to drill down at
- any time and view the syntax required for any specific command.
- Simply enter the name of the command with the <filename>help</filename>
- switch:
- <literallayout class='monospaced'>
- $ yocto-bsp help
- Usage:
+ <para>If you build as you normally would, without
+ specifying any recipes in the
+ <filename>LICENSE_FLAGS_WHITELIST</filename>, the
+ build stops and provides you with the list of recipes
+ that you have tried to include in the image that
+ need entries in the
+ <filename>LICENSE_FLAGS_WHITELIST</filename>.
+ Once you enter the appropriate license flags into
+ the whitelist, restart the build to continue where
+ it left off.
+ During the build, the prompt will not appear again
+ since you have satisfied the requirement.</para>
- Create a customized Yocto BSP layer.
+ <para>Once the appropriate license flags are on the
+ white list in the
+ <filename>LICENSE_FLAGS_WHITELIST</filename> variable,
+ you can build the encumbered image with no change
+ at all to the normal build process.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Get a Pre-Built Version of the BSP:</emphasis>
+ You can get this type of BSP by selecting the
+ "DOWNLOADS" item from the "SOFTWARE" tab on the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
+ You can download BSP tarballs that contain
+ proprietary components after agreeing to the
+ licensing requirements of each of the individually
+ encumbered packages as part of the download process.
+ Obtaining the BSP this way allows you to access an
+ encumbered image immediately after agreeing to the
+ click-through license agreements presented by the
+ website.
+ If you want to build the image yourself using
+ the recipes contained within the BSP tarball,
+ you will still need to create an appropriate
+ <filename>LICENSE_FLAGS_WHITELIST</filename>
+ to match the encumbered recipes in the BSP.
+ </para></listitem>
+ </orderedlist>
+ <note>
+ Pre-compiled images are bundled with a time-limited
+ kernel that runs for a predetermined amount of time
+ (10 days) before it forces the system to reboot.
+ This limitation is meant to discourage direct
+ redistribution of the image.
+ You must eventually rebuild the image if you want
+ to remove this restriction.
+ </note>
+ </para>
+</section>
- usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
+<section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>
+ <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
- Current 'yocto-bsp' commands are:
- create Create a new Yocto BSP
- list List available values for options and BSP properties
+ <para>
+ The <filename>bitbake-layers create-layer</filename> script
+ automates creating a BSP layer.
+ What makes a layer a "BSP layer", is the presence of a machine
+ configuration file.
+ Additionally, a BSP layer usually has a kernel recipe
+ or an append file that leverages off an existing kernel recipe.
+ The primary requirement, however, is the machine configuration.
+ </para>
- See 'yocto-bsp help COMMAND' for more information on a specific command.
+ <para>
+ Use these steps to create a BSP layer:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create a General Layer:</emphasis>
+ Use the <filename>bitbake-layers</filename> script with the
+ <filename>create-layer</filename> subcommand to create a
+ new general layer.
+ For instructions on how to create a general layer using the
+ <filename>bitbake-layers</filename> script, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Layer Configuration File:</emphasis>
+ Every layer needs a layer configuration file.
+ This configuration file establishes locations for the
+ layer's recipes, priorities for the layer, and so forth.
+ You can find examples of <filename>layer.conf</filename>
+ files in the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+ To get examples of what you need in your configuration
+ file, locate a layer (e.g. "meta-ti") and examine the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
+ file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Machine Configuration File:</emphasis>
+ Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ file.
+ See
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
+ for sample
+ <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+ files.
+ Other samples such as
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
+ and
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
+ exist from other vendors that have more specific machine
+ and tuning examples.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Kernel Recipe:</emphasis>
+ Create a kernel recipe in <filename>recipes-kernel/linux</filename>
+ by either using a kernel append file or a new custom kernel
+ recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
+ The BSP layers mentioned in the previous step also contain different
+ kernel examples.
+ See the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
+ section in the Yocto Project Linux Kernel Development Manual
+ for information on how to create a custom kernel.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The remainder of this section provides a description of
+ the Yocto Project reference BSP for Beaglebone, which
+ resides in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>Container Layer</ulink>
+ (i.e.
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>).
+ </para>
- Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -D, --debug output debug information
- </literallayout>
- </para>
+ <section id='bsp-layer-configuration-example'>
+ <title>BSP Layer Configuration Example</title>
- <para>
- Similarly, entering just the name of a sub-command shows the detailed usage
- for that sub-command:
- <literallayout class='monospaced'>
- $ yocto-bsp create
- ERROR:root:Wrong number of arguments, exiting
+ <para>
+ The layer's <filename>conf</filename> directory
+ contains the <filename>layer.conf</filename>
+ configuration file.
+ In this example, the
+ <filename>conf/layer.conf</filename> is the
+ following:
+ <literallayout class='monospaced'>
+ # We have a conf and classes directory, add to BBPATH
+ BBPATH .= ":${LAYERDIR}"
- Usage:
+ # We have recipes-* directories, add to BBFILES
+ BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+ ${LAYERDIR}/recipes-*/*/*.bbappend"
- Create a new Yocto BSP
+ BBFILE_COLLECTIONS += "yoctobsp"
+ BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
+ BBFILE_PRIORITY_yoctobsp = "5"
+ LAYERVERSION_yoctobsp = "4"
+ LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
+ </literallayout>
+ The variables used in this file configure the
+ layer.
+ A good way to learn about layer configuration
+ files is to examine various files for BSP from
+ the
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+ </para>
- usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
- [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
+ <para>
+ For a detailed description of this particular
+ layer configuration file, see
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
+ in the discussion that describes how to create
+ layers in the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
- This command creates a Yocto BSP based on the specified parameters.
- The new BSP will be a new Yocto BSP layer contained by default within
- the top-level directory specified as 'meta-bsp-name'. The -o option
- can be used to place the BSP layer in a directory with a different
- name and location.
+ <section id='bsp-machine-configuration-example'>
+ <title>BSP Machine Configuration Example</title>
- The value of the 'karch' parameter determines the set of files that
- will be generated for the BSP, along with the specific set of
- 'properties' that will be used to fill out the BSP-specific portions
- of the BSP. The possible values for the 'karch' parameter can be
- listed via 'yocto-bsp list karch'.
+ <para>
+ As mentioned earlier in this section, the existence
+ of a machine configuration file is what makes a
+ layer a BSP layer as compared to a general or
+ kernel layer.
+ </para>
- ...
- </literallayout>
- </para>
+ <para>
+ Machine configuration files exist in the
+ <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
+ directory of the layer:
+ <literallayout class='monospaced'>
+ <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename>
+ </literallayout>
+ For example, the machine configuration file for the
+ <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
+ is located in the container layer
+ <filename>poky/meta-yocto-bsp/conf/machine</filename>
+ and is named <filename>beaglebone-yocto.conf</filename>:
+ <literallayout class='monospaced'>
+ #@TYPE: Machine
+ #@NAME: Beaglebone-yocto machine
+ #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
- <para>
- For any sub-command, you can use the word "help" option just before the
- sub-command to get more extensive documentation:
- <literallayout class='monospaced'>
- $ yocto-bsp help create
+ PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
+ XSERVER ?= "xserver-xorg \
+ xf86-video-modesetting \
+ "
- NAME
- yocto-bsp create - Create a new Yocto BSP
+ MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
- SYNOPSIS
- yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
- [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
+ EXTRA_IMAGEDEPENDS += "u-boot"
- DESCRIPTION
- This command creates a Yocto BSP based on the specified
- parameters. The new BSP will be a new Yocto BSP layer contained
- by default within the top-level directory specified as
- 'meta-bsp-name'. The -o option can be used to place the BSP layer
- in a directory with a different name and location.
+ DEFAULTTUNE ?= "cortexa8hf-neon"
+ include conf/machine/include/tune-cortexa8.inc
- ...
- </literallayout>
- </para>
+ IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
+ EXTRA_IMAGECMD_jffs2 = "-lnp "
+ WKS_FILE ?= "beaglebone-yocto.wks"
+ IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
+ do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
- <para>
- Now that you know where these two commands reside and how to access information
- on them, you should find it relatively straightforward to discover the commands
- necessary to create a BSP and perform basic kernel maintenance on that BSP using
- the tools.
- <note>
- You can also use the <filename>bitbake-layers</filename> script to create
- a "generic" layer.
- For information on using this script to create a layer, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
- section in the Yocto Project Development Tasks Manual.
+ SERIAL_CONSOLES = "115200;ttyO0"
+
+ PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+ PREFERRED_VERSION_linux-yocto ?= "4.12%"
+
+ KERNEL_IMAGETYPE = "zImage"
+ KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
+ KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
+
+ SPL_BINARY = "MLO"
+ UBOOT_SUFFIX = "img"
+ UBOOT_MACHINE = "am335x_boneblack_config"
+ UBOOT_ENTRYPOINT = "0x80008000"
+ UBOOT_LOADADDRESS = "0x80008000"
+
+ MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
+
+ IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO"
+ </literallayout>
+ The variables used to configure the machine define
+ machine-specific properties.
+ For example, machine-dependent packages, machine
+ tunings, the type of kernel to build, and
+ U-Boot configurations.
+ </para>
+
+ <para>
+ The following list provides some explanation
+ for the statements found in the example reference
+ machine configuration file for the BeagleBone
+ development boards.
+ Realize that much more can be defined as part of
+ a machines configuration file.
+ In general, you can learn about related variables
+ that this example does not have by locating the
+ variables in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
+ in the Yocto Project Reference Manual.
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
+ The recipe that provides "virtual/xserver" when
+ more than one provider is found.
+ In this case, the recipe that provides
+ "virtual/xserver" is "xserver-xorg", which
+ exists in
+ <filename>poky/meta/recipes-graphics/xserver-xorg</filename>.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
+ The packages that should be installed to provide
+ an X server and drivers for the machine.
+ In this example, the "xserver-xorg" and
+ "xf86-video-modesetting" are installed.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
+ A list of machine-dependent packages
+ not essential for booting the image.
+ Thus, the build does not fail if the packages
+ do not exist.
+ However, the packages are required for a
+ fully-featured image.
+ <note><title>Tip</title>
+ Many <filename>MACHINE*</filename> variables
+ exist that help you configure a particular
+ piece of hardware.
</note>
- </para>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
+ Recipes to build that do not provide packages
+ for installing into the root filesystem
+ but building the image depends on the
+ recipes.
+ Sometimes a recipe is required to build
+ the final image but is not needed in the
+ root filesystem.
+ In this case, the U-Boot recipe must be
+ built for the image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
+ Machines use tunings to optimize machine,
+ CPU, and application performance.
+ These features, which are collectively known
+ as "tuning features", exist in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
+ layer (e.g.
+ <filename>poky/meta/conf/machine/include</filename>).
+ In this example, the default tunning file is
+ "cortexa8hf-neon".
+ <note>
+ The <filename>include</filename> statement
+ that pulls in the
+ <filename>conf/machine/include/tune-cortexa8.inc</filename>
+ file provides many tuning possibilities.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
+ The formats the OpenEmbedded build system
+ uses during the build when creating the
+ root filesystem.
+ In this example, four types of images are
+ supported.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
+ Specifies additional options for image
+ creation commands.
+ In this example, the "-lnp " option is used
+ when creating the
+ <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
+ image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
+ The location of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
+ file used by the OpenEmbedded build system to
+ create a partitioned image (image.wic).
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+ Specifies packages to install into an image
+ through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+ class.
+ Recipes use the <filename>IMAGE_INSTALL</filename>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <filename>do_image_wic[depends]</filename>:
+ A task that is constructed during the build.
+ In this example, the task depends on specific tools
+ in order to create the sysroot when buiding a Wic
+ image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>:
+ Defines a serial console (TTY) to enable using
+ getty.
+ In this case, the baud rate is "115200" and the
+ device name is "ttyO0".
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
+ Specifies the recipe that provides
+ "virtual/kernel" when more than one provider
+ is found.
+ In this case, the recipe that provides
+ "virtual/kernel" is "linux-yocto", which
+ exists in the layer's
+ <filename>recipes-kernel/linux</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
+ Defines the version of the recipe used
+ to build the kernel, which is "4.12" in this
+ case.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
+ The type of kernel to build for the device.
+ In this case, the OpenEmbedded build system
+ creates a "zImage" image type.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
+ The name of the generated Linux kernel device
+ tree (i.e. the <filename>.dtb</filename>) file.
+ All the device trees for the various BeagleBone
+ devices are included.
+<!--
+ You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
+ I don't see where these are being provided.
+-->
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
+ Additional <filename>make</filename>
+ command-line arguments the OpenEmbedded build
+ system passes on when compiling the kernel.
+ In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
+ is passed as a command-line argument.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
+ Defines the Secondary Program Loader (SPL) binary
+ type.
+ In this case, the SPL binary is set to
+ "MLO", which stands for Multimedia card LOader.
+ </para>
- <para>
- The next sections provide a concrete starting point to expand on a few points that
- might not be immediately obvious or that could use further explanation.
- </para>
- </section>
-
-
- <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
- <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
-
- <para>
- The <filename>yocto-bsp</filename> script creates a new
- <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
- by the Yocto Project, as well as QEMU versions of the same.
- The default mode of the script's operation is to prompt you for information needed
- to generate the BSP layer.
- </para>
-
- <para>
- For the current set of BSPs, the script prompts you for various important
- parameters such as:
+ <para>The BeagleBone development board requires an
+ SPL to boot and that SPL file type must be MLO.
+ Consequently, the machine configuration needs to
+ define <filename>SPL_BINARY</filename> as "MLO".
+ <note>
+ For more information on how the SPL variables
+ are used, see the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
+ include file.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
+ Defines various U-Boot configurations needed
+ to build a U-Boot image.
+ In this example, a U-Boot image is required
+ to boot the BeagleBone device.
+ See the following variables for more information:
<itemizedlist>
- <listitem><para>The kernel to use</para></listitem>
- <listitem><para>The branch of that kernel to use (or re-use)</para></listitem>
- <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem>
- <listitem><para>Whether to turn on SMP</para></listitem>
- <listitem><para>Whether the BSP has a keyboard</para></listitem>
- <listitem><para>Whether the BSP has a touchscreen</para></listitem>
- <listitem><para>Remaining configurable items associated with the BSP</para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
+ Points to the generated U-Boot extension.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
+ Specifies the value passed on the make command line when building a U-Boot image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
+ Specifies the entry point for the U-Boot image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
+ Specifies the load address for the U-Boot image.
+ </para></listitem>
</itemizedlist>
- </para>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
+ Specifies the list of hardware features the
+ BeagleBone device is capable of supporting.
+ In this case, the device supports
+ "usbgadget usbhost vfat alsa".
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
+ Files installed into the device's boot partition
+ when preparing the image using the Wic tool
+ with the <filename>bootimg-partition</filename>
+ source plugin.
+ In this case, the "u-boot.${UBOOT_SUFFIX}" and
+ "MLO" files are installed.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
- <para>
- You use the <filename>yocto-bsp create</filename> sub-command to create
- a new BSP layer.
- This command requires you to specify a particular kernel architecture
- (<filename>karch</filename>) on which to base the BSP.
- Assuming you have sourced the environment, you can use the
- <filename>yocto-bsp list karch</filename> sub-command to list the
- architectures available for BSP creation as follows:
- <literallayout class='monospaced'>
- $ yocto-bsp list karch
- Architectures available:
- powerpc
- x86_64
- i386
- arm
- qemu
- mips
- mips64
- </literallayout>
- </para>
+ <section id='bsp-kernel-recipe-example'>
+ <title>BSP Kernel Recipe Example</title>
- <para>
- The remainder of this section presents an example that uses
- <filename>myarm</filename> as the machine name and <filename>qemu</filename>
- as the machine architecture.
- Of the available architectures, <filename>qemu</filename> is the only architecture
- that causes the script to prompt you further for an actual architecture.
- In every other way, this architecture is representative of how creating a BSP for
- an actual machine would work.
- The reason the example uses this architecture is because it is an emulated architecture
- and can easily be followed without requiring actual hardware.
- </para>
+ <para>
+ The kernel recipe used to build the kernel image
+ for the BeagleBone device was established in the
+ machine configuration:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+ PREFERRED_VERSION_linux-yocto ?= "4.12%"
+ </literallayout>
+ The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
+ directory in the layer contains metadata used
+ to build the kernel.
+ In this case, a kernel append file is used to
+ override an established kernel recipe, which is
+ located in
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>
+ and named
+ <filename>linux-yocto_4.12.bb</filename>.
+ </para>
- <para>
- As the <filename>yocto-bsp create</filename> command runs, default values for
- the prompts appear in brackets.
- Pressing enter without supplying anything on the command line or pressing enter
- with an invalid response causes the script to accept the default value.
- Once the script completes, the new <filename>meta-myarm</filename> BSP layer
- is created in the current working directory.
- This example assumes you have sourced the
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- setup script.
- </para>
+ <para>
+ Following is the contents of the append file:
+ <literallayout class='monospaced'>
+ KBRANCH_genericx86 = "standard/base"
+ KBRANCH_genericx86-64 = "standard/base"
- <para>
- Following is the complete example:
- <literallayout class='monospaced'>
- $ yocto-bsp create myarm qemu
- Checking basic git connectivity...
- Done.
+ KMACHINE_genericx86 ?= "common-pc"
+ KMACHINE_genericx86-64 ?= "common-pc-64"
+ KBRANCH_edgerouter = "standard/edgerouter"
+ KBRANCH_beaglebone-yocto = "standard/beaglebone"
+ KMACHINE_beaglebone-yocto = "beaglebone"
+ KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
- Which qemu architecture would you like to use? [default: i386]
- 1) i386 (32-bit)
- 2) x86_64 (64-bit)
- 3) ARM (32-bit)
- 4) PowerPC (32-bit)
- 5) MIPS (32-bit)
- 6) MIPS64 (64-bit)
- 3
- Would you like to use the default (4.8) kernel? (y/n) [default: y]
- Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
- Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-4.8.git...
- Please choose a machine branch to base this BSP on: [default: standard/base]
- 1) standard/arm-versatile-926ejs
- 2) standard/base
- 3) standard/beaglebone
- 4) standard/edgerouter
- 5) standard/fsl-mpc8315e-rdb
- 6) standard/mti-malta32
- 7) standard/mti-malta64
- 8) standard/qemuarm64
- 9) standard/qemuppc
- 1
- Would you like SMP support? (y/n) [default: y]
- Does your BSP have a touchscreen? (y/n) [default: n]
- Does your BSP have a keyboard? (y/n) [default: y]
-
- New qemu BSP created in meta-myarm
- </literallayout>
- Take a closer look at the example now:
- <orderedlist>
- <listitem><para>For the QEMU architecture,
- the script first prompts you for which emulated architecture to use.
- In the example, we use the ARM architecture.
- </para></listitem>
- <listitem><para>The script then prompts you for the kernel.
- The default 4.8 kernel is acceptable.
- So, the example accepts the default.
- If you enter 'n', the script prompts you to further enter the kernel
- you do want to use.</para></listitem>
- <listitem><para>Next, the script asks whether you would like to have a new
- branch created especially for your BSP in the local
- Linux Yocto Kernel Git repository .
- If not, then the script re-uses an existing branch.</para>
- <para>In this example, the default (or "yes") is accepted.
- Thus, a new branch is created for the BSP rather than using a common, shared
- branch.
- The new branch is the branch committed to for any patches you might later add.
- The reason a new branch is the default is that typically
- new BSPs do require BSP-specific patches.
- The tool thus assumes that most of time a new branch is required.
- </para></listitem>
- <listitem><para>Regardless of which choice you make in the previous step,
- you are now given the opportunity to select a particular machine branch on
- which to base your new BSP-specific machine branch
- (or to re-use if you had elected to not create a new branch).
- Because this example is generating an ARM-based BSP, the example
- uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch.
- </para></listitem>
- <listitem><para>The remainder of the prompts are routine.
- Defaults are accepted for each.</para></listitem>
- <listitem><para>By default, the script creates the new BSP Layer in the
- current working directory of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- (i.e. <filename>poky/build</filename>).
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- Once the BSP Layer is created, you must add it to your
- <filename>bblayers.conf</filename> file.
- Here is an example:
- <literallayout class='monospaced'>
- BBLAYERS = ? " \
- /usr/local/src/yocto/meta \
- /usr/local/src/yocto/meta-poky \
- /usr/local/src/yocto/meta-yocto-bsp \
- /usr/local/src/yocto/meta-myarm \
- "
- </literallayout>
- Adding the layer to this file allows the build system to build the BSP and
- the <filename>yocto-kernel</filename> tool to be able to find the layer and
- other Metadata it needs on which to operate.
- </para>
- </section>
-
- <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
- <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
-
- <para>
- Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
- <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
- <filename>yocto-bsp</filename></link> and you added it to your
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
- variable in the <filename>bblayers.conf</filename> file, you can now use
- the <filename>yocto-kernel</filename> script to add patches and configuration
- items to the BSP's kernel.
- </para>
-
- <para>
- The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
- and kernel config settings to a BSP's kernel
- <filename>.bbappend</filename> file.
- All you need to do is use the appropriate sub-command.
- Recall that the easiest way to see exactly what sub-commands are available
- is to use the <filename>yocto-kernel</filename> built-in help as follows:
- <literallayout class='monospaced'>
- $ yocto-kernel --help
- Usage:
-
- Modify and list Yocto BSP kernel config items and patches.
-
- usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
-
- Current 'yocto-kernel' commands are:
- config list List the modifiable set of bare kernel config options for a BSP
- config add Add or modify bare kernel config options for a BSP
- config rm Remove bare kernel config options from a BSP
- patch list List the patches associated with a BSP
- patch add Patch the Yocto kernel for a BSP
- patch rm Remove patches from a BSP
- feature list List the features used by a BSP
- feature add Have a BSP use a feature
- feature rm Have a BSP stop using a feature
- features list List the features available to BSPs
- feature describe Describe a particular feature
- feature create Create a new BSP-local feature
- feature destroy Remove a BSP-local feature
-
- See 'yocto-kernel help COMMAND' for more information on a specific command.
+ SRCREV_machine_genericx86 ?= "1c4ad569af3e23a77994235435040e322908687f"
+ SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f"
+ SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483"
+ SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483"
+ SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1"
+ COMPATIBLE_MACHINE_genericx86 = "genericx86"
+ COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
+ COMPATIBLE_MACHINE_edgerouter = "edgerouter"
+ COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
+ COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
- Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -D, --debug output debug information
- </literallayout>
- </para>
+ LINUX_VERSION_genericx86 = "4.12.20"
+ LINUX_VERSION_genericx86-64 = "4.12.20"
+ LINUX_VERSION_edgerouter = "4.12.19"
+ LINUX_VERSION_beaglebone-yocto = "4.12.19"
+ LINUX_VERSION_mpc8315e-rdb = "4.12.19"
+ </literallayout>
+ This particular append file works for all the
+ machines that are part of the
+ <filename>meta-yocto-bsp</filename> container
+ layer.
+ The relevant statements are appended with
+ the "beaglebone-yocto" string.
+ The OpenEmbedded build system uses these
+ statements to override similar statements
+ in the kernel recipe:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
+ Identifies the kernel branch that is validated,
+ patched, and configured during the build.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
+ Identifies the machine name as known by the
+ kernel, which is sometimes a different name
+ than what is known by the OpenEmbedded build
+ system.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
+ Identifies the revision of the source code used
+ to build the image.
+<!--
+ You find out about that point in the kernel source tree by
+ doing the following command:
- <para>
- The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
- patch to a BSP.
- The following example adds two patches to the <filename>myarm</filename> BSP:
- <literallayout class='monospaced'>
- $ yocto-kernel patch add myarm ~/test.patch
- Added patches:
- test.patch
+ git log ‐‐decorate 257f843ea367744620f1d92910afd2f454e31483
- $ yocto-kernel patch add myarm ~/yocto-testmod.patch
- Added patches:
- yocto-testmod.patch
- </literallayout>
- <note>Although the previous example adds patches one at a time, it is possible
- to add multiple patches at the same time.</note>
- </para>
-
- <para>
- You can verify patches have been added by using the
- <filename>yocto-kernel patch list</filename> sub-command.
- Here is an example:
- <literallayout class='monospaced'>
- $ yocto-kernel patch list myarm
- The current set of machine-specific patches for myarm is:
- 1) test.patch
- 2) yocto-testmod.patch
- </literallayout>
- </para>
-
- <para>
- You can also use the <filename>yocto-kernel</filename> script to
- remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
- Here is an example:
- <literallayout class='monospaced'>
- $ yocto-kernel patch rm myarm
- Specify the patches to remove:
- 1) test.patch
- 2) yocto-testmod.patch
- 1
- Removed patches:
- test.patch
- </literallayout>
- </para>
-
- <para>
- Again, using the <filename>yocto-kernel patch list</filename> sub-command,
- you can verify that the patch was in fact removed:
- <literallayout class='monospaced'>
- $ yocto-kernel patch list myarm
- The current set of machine-specific patches for myarm is:
- 1) yocto-testmod.patch
- </literallayout>
- </para>
-
- <para>
- In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
- sub-command to add one or more kernel config item settings to a BSP.
- The following commands add a couple of config items to the
- <filename>myarm</filename> BSP:
- <literallayout class='monospaced'>
- $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
- Added item:
- CONFIG_MISC_DEVICES=y
-
- $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
- Added item:
- CONFIG_YOCTO_TESTMOD=y
- </literallayout>
- <note>
- Although the previous example adds config items one at a time, it is possible
- to add multiple config items at the same time.
- </note>
- </para>
-
- <para>
- You can list the config items now associated with the BSP.
- Doing so shows you the config items you added as well as others associated
- with the BSP:
- <literallayout class='monospaced'>
- $ yocto-kernel config list myarm
- The current set of machine-specific kernel config items for myarm is:
- 1) CONFIG_MISC_DEVICES=y
- 2) CONFIG_YOCTO_TESTMOD=y
- </literallayout>
- </para>
-
- <para>
- Finally, you can remove one or more config items using the
- <filename>yocto-kernel config rm</filename> sub-command in a manner
- completely analogous to <filename>yocto-kernel patch rm</filename>.
- </para>
- </section>
- </section>
+ Returns information about the commit, which is usually
+ that it is a merge point for a stable kernel release.
+-->
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
+ A regular expression that resolves to one or
+ more target machines with which the recipe
+ is compatible.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
+ The Linux version from kernel.org used by
+ the OpenEmbedded build system to build the
+ kernel image.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
</chapter>
diff --git a/import-layers/yocto-poky/documentation/bsp-guide/figures/bsp-dev-flow.png b/import-layers/yocto-poky/documentation/bsp-guide/figures/bsp-dev-flow.png
index 0f82a1f..2ca1fec 100644
--- a/import-layers/yocto-poky/documentation/bsp-guide/figures/bsp-dev-flow.png
+++ b/import-layers/yocto-poky/documentation/bsp-guide/figures/bsp-dev-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml
index 0081738..fe1bfba 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -22,90 +22,24 @@
multiple layers.
Layers allow you to isolate different types of customizations from
each other.
- You might find it tempting to keep everything in one layer when
- working on a single project.
- However, the more modular your Metadata, the easier
- it is to cope with future changes.
+ For introductory information on the Yocto Project Layer Model,
+ see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
- <para>
- To illustrate how layers are used to keep things modular, consider
- machine customizations.
- These types of customizations typically reside in a special layer,
- rather than a general layer, called a Board Support Package (BSP)
- Layer.
- Furthermore, the machine customizations should be isolated from
- recipes and Metadata that support a new GUI environment,
- for example.
- This situation gives you a couple of layers: one for the machine
- configurations, and one for the GUI environment.
- It is important to understand, however, that the BSP layer can
- still make machine-specific additions to recipes within the GUI
- environment layer without polluting the GUI layer itself
- with those machine-specific changes.
- You can accomplish this through a recipe that is a BitBake append
- (<filename>.bbappend</filename>) file, which is described later
- in this section.
- <note>
- For general information on BSP layer structure, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>.
- </note>
- </para>
-
- <para>
- </para>
-
- <section id='yocto-project-layers'>
- <title>Layers</title>
-
- <para>
- The <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- contains both general layers and BSP
- layers right out of the box.
- You can easily identify layers that ship with a
- Yocto Project release in the Source Directory by their
- folder names.
- Folders that represent layers typically have names that begin with
- the string <filename>meta-</filename>.
- <note>
- It is not a requirement that a layer name begin with the
- prefix <filename>meta-</filename>, but it is a commonly
- accepted standard in the Yocto Project community.
- </note>
- For example, when you set up the Source Directory structure,
- you will see several layers:
- <filename>meta</filename>,
- <filename>meta-skeleton</filename>,
- <filename>meta-selftest</filename>,
- <filename>meta-poky</filename>, and
- <filename>meta-yocto-bsp</filename>.
- Each of these folders represents a distinct layer.
- </para>
-
- <para>
- As another example, if you set up a local copy of the
- <filename>meta-intel</filename> Git repository
- and then explore the folder of that general layer,
- you will discover many Intel-specific BSP layers inside.
- For more information on BSP layers, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
- section in the Yocto Project Board Support Package (BSP)
- Developer's Guide.
- </para>
- </section>
-
<section id='creating-your-own-layer'>
<title>Creating Your Own Layer</title>
<para>
It is very easy to create your own layers to use with the
OpenEmbedded build system.
- The Yocto Project ships with scripts that speed up creating
- general layers and BSP layers.
+ The Yocto Project ships with tools that speed up creating
+ layers.
This section describes the steps you perform by hand to create
- a layer so that you can better understand them.
- For information about the layer-creation scripts, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+ layers so that you can better understand them.
+ For information about the layer-creation tools, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
section in the Yocto Project Board Support Package (BSP)
Developer's Guide and the
"<link linkend='creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</link>"
@@ -113,40 +47,70 @@
</para>
<para>
- Follow these general steps to create your layer without the aid of a script:
+ Follow these general steps to create your layer without using
+ tools:
<orderedlist>
- <listitem><para><emphasis>Check Existing Layers:</emphasis>
+ <listitem><para>
+ <emphasis>Check Existing Layers:</emphasis>
Before creating a new layer, you should be sure someone
has not already created a layer containing the Metadata
you need.
You can see the
- <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
+ <ulink url='http://layers.openembedded.org/layerindex/layers/'>OpenEmbedded Metadata Index</ulink>
for a list of layers from the OpenEmbedded community
that can be used in the Yocto Project.
+ You could find a layer that is identical or close to
+ what you need.
</para></listitem>
- <listitem><para><emphasis>Create a Directory:</emphasis>
+ <listitem><para>
+ <emphasis>Create a Directory:</emphasis>
Create the directory for your layer.
- While not strictly required, prepend the name of the
- folder with the string <filename>meta-</filename>.
+ When you create the layer, be sure to create the
+ directory in an area not associated with the
+ Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (e.g. the cloned <filename>poky</filename> repository).
+ </para>
+
+ <para>While not strictly required, prepend the name of
+ the directory with the string "meta-".
For example:
<literallayout class='monospaced'>
meta-mylayer
meta-GUI_xyz
meta-mymachine
</literallayout>
+ With rare exceptions, a layer's name follows this
+ form:
+ <literallayout class='monospaced'>
+ meta-<replaceable>root_name</replaceable>
+ </literallayout>
+ Following this layer naming convention can
+ save you trouble later when tools, components, or
+ variables "assume" your layer name begins with "meta-".
+ A notable example is in configuration files as
+ shown in the following step where layer names without
+ the "meta-" string are appended
+ to several variables used in the configuration.
</para></listitem>
- <listitem><para><emphasis>Create a Layer Configuration
- File:</emphasis>
- Inside your new layer folder, you need to create a
- <filename>conf/layer.conf</filename> file.
- It is easiest to take an existing layer configuration
- file and copy that to your layer's
- <filename>conf</filename> directory and then modify the
- file as needed.</para>
- <para>The
- <filename>meta-yocto-bsp/conf/layer.conf</filename> file
- demonstrates the required syntax:
- <literallayout class='monospaced'>
+ <listitem><para id='dev-layer-config-file-description'>
+ <emphasis>Create a Layer Configuration File:</emphasis>
+ Inside your new layer folder, you need to create a
+ <filename>conf/layer.conf</filename> file.
+ It is easiest to take an existing layer configuration
+ file and copy that to your layer's
+ <filename>conf</filename> directory and then modify the
+ file as needed.</para>
+
+ <para>The
+ <filename>meta-yocto-bsp/conf/layer.conf</filename> file
+ in the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink>
+ demonstrates the required syntax.
+ For your layer, you need to replace "yoctobsp" with
+ a unique identifier for your layer (e.g. "machinexyz"
+ for a layer named "meta-machinexyz"):
+ <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -157,75 +121,82 @@
BBFILE_COLLECTIONS += "yoctobsp"
BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
BBFILE_PRIORITY_yoctobsp = "5"
- LAYERVERSION_yoctobsp = "3"
- </literallayout></para>
- <para>Here is an explanation of the example:
+ LAYERVERSION_yoctobsp = "4"
+ LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
+ </literallayout>
+ Following is an explanation of the layer configuration
+ file:
<itemizedlist>
- <listitem><para>The configuration and
- classes directory is appended to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
- <note>
- All non-distro layers, which include all BSP
- layers, are expected to append the layer
- directory to the
- <filename>BBPATH</filename>.
- On the other hand, distro layers, such as
- <filename>meta-poky</filename>, can choose
- to enforce their own precedence over
- <filename>BBPATH</filename>.
- For an example of that syntax, see the
- <filename>layer.conf</filename> file for
- the <filename>meta-poky</filename> layer.
- </note></para></listitem>
- <listitem><para>The recipes for the layers are
- appended to
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>:
+ Adds the layer's root directory to BitBake's
+ search path.
+ Through the use of the
+ <filename>BBPATH</filename> variable, BitBake
+ locates class files
+ (<filename>.bbclass</filename>),
+ configuration files, and files that are
+ included with <filename>include</filename> and
+ <filename>require</filename> statements.
+ For these cases, BitBake uses the first file
+ that matches the name found in
+ <filename>BBPATH</filename>.
+ This is similar to the way the
+ <filename>PATH</filename> variable is used for
+ binaries.
+ It is recommended, therefore, that you use
+ unique class and configuration filenames in
+ your custom layer.
</para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
- variable is then appended with the layer name.
- </para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
- variable is set to a regular expression and is
- used to match files from
- <filename>BBFILES</filename> into a particular
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>:
+ Defines the location for all recipes in the
layer.
- In this case,
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
- is used to make <filename>BBFILE_PATTERN</filename> match within the
- layer's path.</para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
- variable then assigns a priority to the layer.
- Applying priorities is useful in situations
- where the same recipe might appear in multiple
- layers and allows you to choose the layer
- that takes precedence.</para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
- variable optionally specifies the version of a
- layer as a single number.</para></listitem>
- </itemizedlist></para>
- <para>Note the use of the
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
- variable, which expands to the directory of the current
- layer.</para>
- <para>Through the use of the <filename>BBPATH</filename>
- variable, BitBake locates class files
- (<filename>.bbclass</filename>),
- configuration files, and files that are included
- with <filename>include</filename> and
- <filename>require</filename> statements.
- For these cases, BitBake uses the first file that
- matches the name found in <filename>BBPATH</filename>.
- This is similar to the way the <filename>PATH</filename>
- variable is used for binaries.
- It is recommended, therefore, that you use unique
- class and configuration
- filenames in your custom layer.</para></listitem>
- <listitem><para><emphasis>Add Content:</emphasis> Depending
- on the type of layer, add the content.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>:
+ Establishes the current layer through a
+ unique identifier that is used throughout the
+ OpenEmbedded build system to refer to the layer.
+ In this example, the identifier "yoctobsp" is
+ the representation for the container layer
+ named "meta-yocto-bsp".
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>:
+ Expands immediately during parsing to
+ provide the directory of the layer.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>:
+ Establishes a priority to use for
+ recipes in the layer when the OpenEmbedded build
+ finds recipes of the same name in different
+ layers.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>:
+ Establishes a version number for the layer.
+ You can use this version number to specify this
+ exact version of the layer as a dependency when
+ using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>:
+ Lists the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Yocto Project</ulink>
+ releases for which the current version is
+ compatible.
+ This variable is a good way to indicate how
+ up-to-date your particular layer is.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Add Content:</emphasis>
+ Depending on the type of layer, add the content.
If the layer adds support for a machine, add the machine
configuration in a <filename>conf/machine/</filename>
file within the layer.
@@ -235,9 +206,13 @@
If the layer introduces new recipes, put the recipes
you need in <filename>recipes-*</filename>
subdirectories within the layer.
- <note>In order to be compliant with the Yocto Project,
- a layer must contain a
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
+ <note>
+ For an explanation of layer hierarchy that
+ is compliant with the Yocto Project, see
+ the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
+ section in the Yocto Project Board
+ Support Package (BSP) Developer's Guide.
</note>
</para></listitem>
<listitem><para>
@@ -492,7 +467,7 @@
acceptable explanation for any questions answered "No".
</para></listitem>
<listitem><para>
- You need to be a Yocto Project Member Organization.
+ Be a Yocto Project Member Organization.
</para></listitem>
</itemizedlist>
</para>
@@ -562,7 +537,7 @@
</para>
<para>
- The script divides tests into three areas: COMMON, BSD,
+ The script divides tests into three areas: COMMON, BSP,
and DISTRO.
For example, given a distribution layer (DISTRO), the
layer must pass both the COMMON and DISTRO related tests.
@@ -646,23 +621,26 @@
The following example shows how to enable a layer named
<filename>meta-mylayer</filename>:
<literallayout class='monospaced'>
- LCONF_VERSION = "6"
+ # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
+ # changes incompatibly
+ POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
- $HOME/poky/meta \
- $HOME/poky/meta-poky \
- $HOME/poky/meta-yocto-bsp \
- $HOME/poky/meta-mylayer \
+ /home/<replaceable>user</replaceable>/poky/meta \
+ /home/<replaceable>user</replaceable>/poky/meta-poky \
+ /home/<replaceable>user</replaceable>/poky/meta-yocto-bsp \
+ /home/<replaceable>user</replaceable>/poky/meta-mylayer \
"
</literallayout>
</para>
<para>
BitBake parses each <filename>conf/layer.conf</filename> file
- as specified in the <filename>BBLAYERS</filename> variable
+ from the top down as specified in the
+ <filename>BBLAYERS</filename> variable
within the <filename>conf/bblayers.conf</filename> file.
During the processing of each
<filename>conf/layer.conf</filename> file, BitBake adds the
@@ -840,8 +818,7 @@
<para>
To specify the layer's priority manually, use the
<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
- variable.
- For example:
+ variable and append the layer's root name:
<literallayout class='monospaced'>
BBFILE_PRIORITY_mylayer = "1"
</literallayout>
@@ -862,7 +839,8 @@
<title>Managing Layers</title>
<para>
- You can use the BitBake layer management tool to provide a view
+ You can use the BitBake layer management tool
+ <filename>bitbake-layers</filename> to provide a view
into the structure of recipes across a multi-layer project.
Being able to generate output that reports on configured layers
with their paths and priorities and on
@@ -871,42 +849,88 @@
</para>
<para>
- Use the following form when running the layer management tool.
+ For help on the BitBake layer management tool, use the
+ following command:
<literallayout class='monospaced'>
- $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>]
+ $ bitbake-layers --help
+ NOTE: Starting bitbake server...
+ usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ...
+
+ BitBake layers utility
+
+ optional arguments:
+ -d, --debug Enable debug output
+ -q, --quiet Print only errors
+ -F, --force Force add without recipe parse verification
+ --color COLOR Colorize output (where COLOR is auto, always, never)
+ -h, --help show this help message and exit
+
+ subcommands:
+ <subcommand>
+ show-layers show current configured layers.
+ show-overlayed list overlayed recipes (where the same recipe exists
+ in another layer)
+ show-recipes list available recipes, showing the layer they are
+ provided by
+ show-appends list bbappend files and recipe files they apply to
+ show-cross-depends Show dependencies between recipes that cross layer
+ boundaries.
+ add-layer Add one or more layers to bblayers.conf.
+ remove-layer Remove one or more layers from bblayers.conf.
+ flatten flatten layer configuration into a separate output
+ directory.
+ layerindex-fetch Fetches a layer from a layer index along with its
+ dependent layers, and adds them to conf/bblayers.conf.
+ layerindex-show-depends
+ Find layer dependencies from layer index.
+ create-layer Create a basic layer
+
+ Use bitbake-layers <subcommand> --help to get help on a specific command
</literallayout>
+ </para>
+
+ <para>
The following list describes the available commands:
<itemizedlist>
- <listitem><para><filename><emphasis>help:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>help:</filename></emphasis>
Displays general help or help on a specified command.
</para></listitem>
- <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-layers:</filename></emphasis>
Shows the current configured layers.
</para></listitem>
- <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
- Lists available recipes and the layers that provide them.
- </para></listitem>
- <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-overlayed:</filename></emphasis>
Lists overlayed recipes.
A recipe is overlayed when a recipe with the same name
exists in another layer that has a higher layer
priority.
</para></listitem>
- <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-recipes:</filename></emphasis>
+ Lists available recipes and the layers that provide them.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>show-appends:</filename></emphasis>
Lists <filename>.bbappend</filename> files and the
recipe files to which they apply.
</para></listitem>
- <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-cross-depends:</filename></emphasis>
Lists dependency relationships between recipes that
cross layer boundaries.
</para></listitem>
- <listitem><para><filename><emphasis>add-layer:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>add-layer:</filename></emphasis>
Adds a layer to <filename>bblayers.conf</filename>.
</para></listitem>
- <listitem><para><filename><emphasis>remove-layer:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>remove-layer:</filename></emphasis>
Removes a layer from <filename>bblayers.conf</filename>
</para></listitem>
- <listitem><para><filename><emphasis>flatten:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>flatten:</filename></emphasis>
Flattens the layer configuration into a separate output
directory.
Flattening your layer configuration builds a "flattened"
@@ -917,18 +941,21 @@
You might have to perform some manual cleanup of the
flattened layer as follows:
<itemizedlist>
- <listitem><para>Non-recipe files (such as patches)
+ <listitem><para>
+ Non-recipe files (such as patches)
are overwritten.
The flatten command shows a warning for these
files.
</para></listitem>
- <listitem><para>Anything beyond the normal layer
+ <listitem><para>
+ Anything beyond the normal layer
setup has been added to the
<filename>layer.conf</filename> file.
Only the lowest priority layer's
<filename>layer.conf</filename> is used.
</para></listitem>
- <listitem><para>Overridden and appended items from
+ <listitem><para>
+ Overridden and appended items from
<filename>.bbappend</filename> files need to be
cleaned up.
The contents of each
@@ -1000,13 +1027,13 @@
Developer's Guide.
</para></listitem>
<listitem><para>
- The <filename>bitbake-layers</filename> script
- replaces the <filename>yocto-layer</filename>
- script, which is deprecated in the Yocto Project
- 2.4 release.
- The <filename>yocto-layer</filename> script
- continues to function as part of the 2.4 release
- but will be removed post 2.4.
+ In order to use a layer with the OpenEmbedded
+ build system, you need to add the layer to your
+ <filename>bblayers.conf</filename> configuration
+ file.
+ See the
+ "<link linkend='adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section for more information.
</para></listitem>
</itemizedlist>
</note>
@@ -1047,6 +1074,14 @@
<literallayout class='monospaced'>
$ bitbake-layers create-layer <replaceable>your_layer_name</replaceable>
</literallayout>
+ As an example, the following command creates a layer named
+ <filename>meta-scottrif</filename> in your home directory:
+ <literallayout class='monospaced'>
+ $ cd /usr/home
+ $ bitbake-layers create-layer meta-scottrif
+ NOTE: Starting bitbake server...
+ Add your new layer with 'bitbake-layers add-layer meta-scottrif'
+ </literallayout>
</para>
<para>
@@ -1089,26 +1124,36 @@
Filename of the example recipe
</literallayout>
</para>
+ </section>
+
+ <section id='adding-a-layer-using-the-bitbake-layers-script'>
+ <title>Adding a Layer Using the <filename>bitbake-layers</filename> Script</title>
<para>
Once you create your general layer, you must add it to your
<filename>bblayers.conf</filename> file.
- You can add your layer by using the
+ Adding the layer to this configuration file makes the
+ OpenEmbedded build system aware of your layer so that it can
+ search it for metadata.
+ </para>
+
+ <para>
+ Add your layer by using the
<filename>bitbake-layers add-layer</filename> command:
<literallayout class='monospaced'>
$ bitbake-layers add-layer <replaceable>your_layer_name</replaceable>
</literallayout>
- Here is an example where a layer named
- <filename>meta-scottrif</filename> is added and then the
- layers are shown using the
- <filename>bitbake-layers show-layers</filename> command:
+ Here is an example that adds a layer named
+ <filename>meta-scottrif</filename> to the configuration file.
+ Following the command that adds the layer is another
+ <filename>bitbake-layers</filename> command that shows the
+ layers that are in your <filename>bblayers.conf</filename>
+ file:
<literallayout class='monospaced'>
$ bitbake-layers add-layer meta-scottrif
NOTE: Starting bitbake server...
- Loading cache: 100% |############################################| Time: 0:00:00
- Loaded 1275 entries from dependency cache.
- Parsing recipes: 100% |##########################################| Time: 0:00:00
- Parsing of 819 .bb files complete (817 cached, 2 parsed). 1276 targets, 44 skipped, 0 masked, 0 errors.
+ Parsing recipes: 100% |##########################################################| Time: 0:00:49
+ Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors.
$ bitbake-layers show-layers
NOTE: Starting bitbake server...
layer path priority
@@ -1116,12 +1161,16 @@
meta /home/scottrif/poky/meta 5
meta-poky /home/scottrif/poky/meta-poky 5
meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5
- meta-mylayer /home/scottrif/meta-mylayer 6
workspace /home/scottrif/poky/build/workspace 99
meta-scottrif /home/scottrif/poky/build/meta-scottrif 6
</literallayout>
Adding the layer to this file enables the build system to
locate the layer during the build.
+ <note>
+ During a build, the OpenEmbedded build system looks in
+ the layers from the top of the list down to the bottom
+ in that order.
+ </note>
</para>
</section>
</section>
@@ -1222,8 +1271,8 @@
To understand how these features work, the best reference is
<filename>meta/classes/core-image.bbclass</filename>.
This class lists out the available
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
- of which most map to package groups while some, such as
+ <filename>IMAGE_FEATURES</filename> of which most map to
+ package groups while some, such as
<filename>debug-tweaks</filename> and
<filename>read-only-rootfs</filename>, resolve as general
configuration settings.
@@ -1520,8 +1569,8 @@
</itemizedlist>
<note>
For information on recipe syntax, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#recipe-syntax'>Recipe Syntax</ulink>"
- section in the Yocto Project Reference Manual.
+ "<link linkend='recipe-syntax'>Recipe Syntax</link>"
+ section.
</note>
</para>
@@ -1572,47 +1621,43 @@
and have sourced the build environment setup script
(i.e.
<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>).
- Here is the basic <filename>recipetool</filename> syntax:
- <note>
- Running <filename>recipetool -h</filename> or
- <filename>recipetool create -h</filename> produces the
- Python-generated help, which presented differently
- than what follows here.
- </note>
+ To get help on the tool, use the following command:
<literallayout class='monospaced'>
- recipetool -h
- recipetool create [-h]
- recipetool [-d] [-q] [--color auto | always | never ] create -o <replaceable>OUTFILE</replaceable> [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable>
+ $ recipetool -h
+ NOTE: Starting bitbake server...
+ usage: recipetool [-d] [-q] [--color COLOR] [-h] <subcommand> ...
- -d Enables debug output.
- -q Outputs only errors (quiet mode).
- --color Colorizes the output automatically, always, or never.
- -h Displays Python generated syntax for recipetool.
- create Causes recipetool to create a base recipe. The create
- command is further defined with these options:
+ OpenEmbedded recipe tool
- -o <replaceable>OUTFILE</replaceable> Specifies the full path and filename for the generated
- recipe.
- -m Causes the recipe to be machine-specific rather than
- architecture-specific (default).
- -x <replaceable>EXTERNALSRC</replaceable> Fetches and extracts source files from <replaceable>source</replaceable>
- and places them in <replaceable>EXTERNALSRC</replaceable>.
- <replaceable>source</replaceable> must be a URL.
- -h Displays Python-generated syntax for create.
- <replaceable>source</replaceable> Specifies the source code on which to base the
- recipe.
+ options:
+ -d, --debug Enable debug output
+ -q, --quiet Print only errors
+ --color COLOR Colorize output (where COLOR is auto, always, never)
+ -h, --help show this help message and exit
+
+ subcommands:
+ create Create a new recipe
+ newappend Create a bbappend for the specified target in the specified
+ layer
+ setvar Set a variable within a recipe
+ appendfile Create/update a bbappend to replace a target file
+ appendsrcfiles Create/update a bbappend to add or replace source files
+ appendsrcfile Create/update a bbappend to add or replace a source file
+ Use recipetool <subcommand> --help to get help on a specific command
</literallayout>
</para>
<para>
- Running <filename>recipetool create -o</filename> <replaceable>OUTFILE</replaceable>
+ Running
+ <filename>recipetool create -o</filename> <replaceable>OUTFILE</replaceable>
creates the base recipe and locates it properly in the
layer that contains your source files.
Following are some syntax examples:
</para>
<para>
- Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
+ Use this syntax to generate a recipe based on
+ <replaceable>source</replaceable>.
Once generated, the recipe resides in the existing source
code layer:
<literallayout class='monospaced'>
@@ -1625,7 +1670,8 @@
<literallayout class='monospaced'>
recipetool create -o <replaceable>OUTFILE</replaceable> -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable>
</literallayout>
- Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
+ Use this syntax to generate a recipe based on
+ <replaceable>source</replaceable>.
The options direct <filename>recipetool</filename> to
generate debugging information.
Once generated, the recipe resides in the existing source
@@ -1646,7 +1692,7 @@
The Yocto Project and OpenEmbedded communities maintain many
recipes that might be candidates for what you are doing.
You can find a good central index of these recipes in the
- <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
+ <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink>.
</para>
<para>
@@ -1811,8 +1857,8 @@
<para>
You can find more information about the build process in
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-development-environment'>The Yocto Project Development Environment</ulink>"
- chapter of the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>The Yocto Project Development Environment</ulink>"
+ chapter of the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -1828,8 +1874,8 @@
Your recipe must have a <filename>SRC_URI</filename> variable
that points to where the source is located.
For a graphical representation of source locations, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
- section in the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#sources-dev-environment'>Sources</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
<para>
@@ -2141,8 +2187,9 @@
containing the current checksum.
For more explanation and examples of how to set the
<filename>LIC_FILES_CHKSUM</filename> variable, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
- section in the Yocto Project Reference Manual.</para>
+ "<link link='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>"
+ section.</para>
+
<para>To determine the correct checksum string, you
can list the appropriate files in the
<filename>LIC_FILES_CHKSUM</filename> variable with
@@ -2288,8 +2335,9 @@
automatically add a runtime dependency to "mypackage" on
"example").
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
- in the Yocto Project Reference Manual for further details.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for
+ further details.
</para>
</section>
@@ -2977,6 +3025,133 @@
</para>
</section>
+ <section id='metadata-virtual-providers'>
+ <title>Using Virtual Providers</title>
+
+ <para>
+ Prior to a build, if you know that several different recipes
+ provide the same functionality, you can use a virtual provider
+ (i.e. <filename>virtual/*</filename>) as a placeholder for the
+ actual provider.
+ The actual provider is determined at build-time.
+ </para>
+
+ <para>
+ A common scenario where a virtual provider is used would be
+ for the kernel recipe.
+ Suppose you have three kernel recipes whose
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
+ values map to <filename>kernel-big</filename>,
+ <filename>kernel-mid</filename>, and
+ <filename>kernel-small</filename>.
+ Furthermore, each of these recipes in some way uses a
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+ statement that essentially identifies itself as being able
+ to provide <filename>virtual/kernel</filename>.
+ Here is one way through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-kernel'><filename>kernel</filename></ulink>
+ class:
+ <literallayout class='monospaced'>
+ PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }"
+ </literallayout>
+ Any recipe that inherits the <filename>kernel</filename> class
+ is going to utilize a <filename>PROVIDES</filename> statement
+ that identifies that recipe as being able to provide the
+ <filename>virtual/kernel</filename> item.
+ </para>
+
+ <para>
+ Now comes the time to actually build an image and you need a
+ kernel recipe, but which one?
+ You can configure your build to call out the kernel recipe
+ you want by using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+ variable.
+ As an example, consider the
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/x86-base.inc'><filename>x86-base.inc</filename></ulink>
+ include file, which is a machine
+ (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>)
+ configuration file.
+ This include file is the reason all x86-based machines use the
+ <filename>linux-yocto</filename> kernel.
+ Here are the relevant lines from the include file:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto"
+ PREFERRED_VERSION_linux-yocto ??= "4.15%"
+ </literallayout>
+ </para>
+
+ <para>
+ When you use a virtual provider, you do not have to
+ "hard code" a recipe name as a build dependency.
+ You can use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ variable to state the build is dependent on
+ <filename>virtual/kernel</filename> for example:
+ <literallayout class='monospaced'>
+ DEPENDS = "virtual/kernel"
+ </literallayout>
+ During the build, the OpenEmbedded build system picks
+ the correct recipe needed for the
+ <filename>virtual/kernel</filename> dependency based on the
+ <filename>PREFERRED_PROVIDER</filename> variable.
+ If you want to use the small kernel mentioned at the beginning
+ of this section, configure your build as follows:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small"
+ </literallayout>
+ <note>
+ Any recipe that
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+ a <filename>virtual/*</filename> item that is ultimately
+ not selected through
+ <filename>PREFERRED_PROVIDER</filename> does not get built.
+ Preventing these recipes from building is usually the
+ desired behavior since this mechanism's purpose is to
+ select between mutually exclusive alternative providers.
+ </note>
+ </para>
+
+ <para>
+ The following lists specific examples of virtual providers:
+ <itemizedlist>
+ <listitem><para>
+ <filename>virtual/kernel</filename>:
+ Provides the name of the kernel recipe to use when
+ building a kernel image.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/bootloader</filename>:
+ Provides the name of the bootloader to use when
+ building an image.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/mesa</filename>:
+ Provides <filename>gbm.pc</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/egl</filename>:
+ Provides <filename>egl.pc</filename> and possibly
+ <filename>wayland-egl.pc</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/libgl</filename>:
+ Provides <filename>gl.pc</filename> (i.e. libGL).
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/libgles1</filename>:
+ Provides <filename>glesv1_cm.pc</filename>
+ (i.e. libGLESv1_CM).
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/libgles2</filename>:
+ Provides <filename>glesv2.pc</filename>
+ (i.e. libGLESv2).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
<section id='properly-versioning-pre-release-recipes'>
<title>Properly Versioning Pre-Release Recipes</title>
@@ -3224,8 +3399,10 @@
The variable
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
is used to track source license changes as described in the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
- You can quickly create Autotool-based recipes in a manner similar to the previous example.
+ "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>"
+ section in the Yocto Project Overview and Concepts Manual.
+ You can quickly create Autotool-based recipes in a manner
+ similar to the previous example.
</para>
</section>
@@ -3430,9 +3607,9 @@
allows runtime dependencies between packages
to be added automatically.
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
- section in the Yocto Project Reference Manual
- for more information.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and
+ Concepts Manual for more information.
</para></listitem>
</itemizedlist>
</note>
@@ -3517,6 +3694,330 @@
style.
</para>
</section>
+
+ <section id='recipe-syntax'>
+ <title>Recipe Syntax</title>
+
+ <para>
+ Understanding recipe file syntax is important for writing
+ recipes.
+ The following list overviews the basic items that make up a
+ BitBake recipe file.
+ For more complete BitBake syntax descriptions, see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
+ chapter of the BitBake User Manual.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Variable Assignments and Manipulations:</emphasis>
+ Variable assignments allow a value to be assigned to a
+ variable.
+ The assignment can be static text or might include
+ the contents of other variables.
+ In addition to the assignment, appending and prepending
+ operations are also supported.</para>
+
+ <para>The following example shows some of the ways
+ you can use variables in recipes:
+ <literallayout class='monospaced'>
+ S = "${WORKDIR}/postfix-${PV}"
+ CFLAGS += "-DNO_ASM"
+ SRC_URI_append = " file://fixup.patch"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Functions:</emphasis>
+ Functions provide a series of actions to be performed.
+ You usually use functions to override the default
+ implementation of a task function or to complement
+ a default function (i.e. append or prepend to an
+ existing function).
+ Standard functions use <filename>sh</filename> shell
+ syntax, although access to OpenEmbedded variables and
+ internal methods are also available.</para>
+
+ <para>The following is an example function from the
+ <filename>sed</filename> recipe:
+ <literallayout class='monospaced'>
+ do_install () {
+ autotools_do_install
+ install -d ${D}${base_bindir}
+ mv ${D}${bindir}/sed ${D}${base_bindir}/sed
+ rmdir ${D}${bindir}/
+ }
+ </literallayout>
+ It is also possible to implement new functions that
+ are called between existing tasks as long as the
+ new functions are not replacing or complementing the
+ default functions.
+ You can implement functions in Python
+ instead of shell.
+ Both of these options are not seen in the majority of
+ recipes.
+ </para></listitem>
+ <listitem><para><emphasis>Keywords:</emphasis>
+ BitBake recipes use only a few keywords.
+ You use keywords to include common
+ functions (<filename>inherit</filename>), load parts
+ of a recipe from other files
+ (<filename>include</filename> and
+ <filename>require</filename>) and export variables
+ to the environment (<filename>export</filename>).
+ </para>
+
+ <para>The following example shows the use of some of
+ these keywords:
+ <literallayout class='monospaced'>
+ export POSTCONF = "${STAGING_BINDIR}/postconf"
+ inherit autoconf
+ require otherfile.inc
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Comments (#):</emphasis>
+ Any lines that begin with the hash character
+ (<filename>#</filename>) are treated as comment lines
+ and are ignored:
+ <literallayout class='monospaced'>
+ # This is a comment
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ This next list summarizes the most important and most commonly
+ used parts of the recipe syntax.
+ For more information on these parts of the syntax, you can
+ reference the
+ <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
+ chapter in the BitBake User Manual.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Line Continuation (\):</emphasis>
+ Use the backward slash (<filename>\</filename>)
+ character to split a statement over multiple lines.
+ Place the slash character at the end of the line that
+ is to be continued on the next line:
+ <literallayout class='monospaced'>
+ VAR = "A really long \
+ line"
+ </literallayout>
+ <note>
+ You cannot have any characters including spaces
+ or tabs after the slash character.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Using Variables (${<replaceable>VARNAME</replaceable>}):</emphasis>
+ Use the <filename>${<replaceable>VARNAME</replaceable>}</filename>
+ syntax to access the contents of a variable:
+ <literallayout class='monospaced'>
+ SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
+ </literallayout>
+ <note>
+ It is important to understand that the value of a
+ variable expressed in this form does not get
+ substituted automatically.
+ The expansion of these expressions happens
+ on-demand later (e.g. usually when a function that
+ makes reference to the variable executes).
+ This behavior ensures that the values are most
+ appropriate for the context in which they are
+ finally used.
+ On the rare occasion that you do need the variable
+ expression to be expanded immediately, you can use
+ the <filename>:=</filename> operator instead of
+ <filename>=</filename> when you make the
+ assignment, but this is not generally needed.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Quote All Assignments ("<replaceable>value</replaceable>"):</emphasis>
+ Use double quotes around values in all variable
+ assignments (e.g.
+ <filename>"<replaceable>value</replaceable>"</filename>).
+ Following is an example:
+ <literallayout class='monospaced'>
+ VAR1 = "${OTHERVAR}"
+ VAR2 = "The version is ${PV}"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Conditional Assignment (?=):</emphasis>
+ Conditional assignment is used to assign a
+ value to a variable, but only when the variable is
+ currently unset.
+ Use the question mark followed by the equal sign
+ (<filename>?=</filename>) to make a "soft" assignment
+ used for conditional assignment.
+ Typically, "soft" assignments are used in the
+ <filename>local.conf</filename> file for variables
+ that are allowed to come through from the external
+ environment.
+ </para>
+
+ <para>Here is an example where
+ <filename>VAR1</filename> is set to "New value" if
+ it is currently empty.
+ However, if <filename>VAR1</filename> has already been
+ set, it remains unchanged:
+ <literallayout class='monospaced'>
+ VAR1 ?= "New value"
+ </literallayout>
+ In this next example, <filename>VAR1</filename>
+ is left with the value "Original value":
+ <literallayout class='monospaced'>
+ VAR1 = "Original value"
+ VAR1 ?= "New value"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Appending (+=):</emphasis>
+ Use the plus character followed by the equals sign
+ (<filename>+=</filename>) to append values to existing
+ variables.
+ <note>
+ This operator adds a space between the existing
+ content of the variable and the new content.
+ </note></para>
+
+ <para>Here is an example:
+ <literallayout class='monospaced'>
+ SRC_URI += "file://fix-makefile.patch"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Prepending (=+):</emphasis>
+ Use the equals sign followed by the plus character
+ (<filename>=+</filename>) to prepend values to existing
+ variables.
+ <note>
+ This operator adds a space between the new content
+ and the existing content of the variable.
+ </note></para>
+
+ <para>Here is an example:
+ <literallayout class='monospaced'>
+ VAR =+ "Starts"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Appending (_append):</emphasis>
+ Use the <filename>_append</filename> operator to
+ append values to existing variables.
+ This operator does not add any additional space.
+ Also, the operator is applied after all the
+ <filename>+=</filename>, and
+ <filename>=+</filename> operators have been applied and
+ after all <filename>=</filename> assignments have
+ occurred.
+ </para>
+
+ <para>The following example shows the space being
+ explicitly added to the start to ensure the appended
+ value is not merged with the existing value:
+ <literallayout class='monospaced'>
+ SRC_URI_append = " file://fix-makefile.patch"
+ </literallayout>
+ You can also use the <filename>_append</filename>
+ operator with overrides, which results in the actions
+ only being performed for the specified target or
+ machine:
+ <literallayout class='monospaced'>
+ SRC_URI_append_sh4 = " file://fix-makefile.patch"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Prepending (_prepend):</emphasis>
+ Use the <filename>_prepend</filename> operator to
+ prepend values to existing variables.
+ This operator does not add any additional space.
+ Also, the operator is applied after all the
+ <filename>+=</filename>, and
+ <filename>=+</filename> operators have been applied and
+ after all <filename>=</filename> assignments have
+ occurred.
+ </para>
+
+ <para>The following example shows the space being
+ explicitly added to the end to ensure the prepended
+ value is not merged with the existing value:
+ <literallayout class='monospaced'>
+ CFLAGS_prepend = "-I${S}/myincludes "
+ </literallayout>
+ You can also use the <filename>_prepend</filename>
+ operator with overrides, which results in the actions
+ only being performed for the specified target or
+ machine:
+ <literallayout class='monospaced'>
+ CFLAGS_prepend_sh4 = "-I${S}/myincludes "
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Overrides:</emphasis>
+ You can use overrides to set a value conditionally,
+ typically based on how the recipe is being built.
+ For example, to set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
+ variable's value to "standard/base" for any target
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
+ except for qemuarm where it should be set to
+ "standard/arm-versatile-926ejs", you would do the
+ following:
+ <literallayout class='monospaced'>
+ KBRANCH = "standard/base"
+ KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
+ </literallayout>
+ Overrides are also used to separate alternate values
+ of a variable in other situations.
+ For example, when setting variables such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
+ that are specific to individual packages produced by
+ a recipe, you should always use an override that
+ specifies the name of the package.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Indentation:</emphasis>
+ Use spaces for indentation rather than than tabs.
+ For shell functions, both currently work.
+ However, it is a policy decision of the Yocto Project
+ to use tabs in shell functions.
+ Realize that some layers have a policy to use spaces
+ for all indentation.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Using Python for Complex Operations:</emphasis>
+ For more advanced processing, it is possible to use
+ Python code during variable assignments (e.g.
+ search and replacement on a variable).</para>
+
+ <para>You indicate Python code using the
+ <filename>${@<replaceable>python_code</replaceable>}</filename>
+ syntax for the variable assignment:
+ <literallayout class='monospaced'>
+ SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Shell Function Syntax:</emphasis>
+ Write shell functions as if you were writing a shell
+ script when you describe a list of actions to take.
+ You should ensure that your script works with a generic
+ <filename>sh</filename> and that it does not require
+ any <filename>bash</filename> or other shell-specific
+ functionality.
+ The same considerations apply to various system
+ utilities (e.g. <filename>sed</filename>,
+ <filename>grep</filename>, <filename>awk</filename>,
+ and so forth) that you might wish to use.
+ If in doubt, you should check with multiple
+ implementations - including those from BusyBox.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
</section>
<section id="platdev-newmachine">
@@ -3538,8 +4039,9 @@
<para>
For a complete example that shows how to add a new machine,
see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
- section in the Yocto Project Board Support Package (BSP) Developer's Guide.
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section in the Yocto Project Board Support Package (BSP)
+ Developer's Guide.
</para>
<section id="platdev-newmachine-conffile">
@@ -3694,6 +4196,562 @@
</section>
</section>
+ <section id='gs-upgrading-recipes'>
+ <title>Upgrading Recipes</title>
+
+ <para>
+ Over time, upstream developers publish new versions for software
+ built by layer recipes.
+ It is recommended to keep recipes up-to-date with upstream
+ version releases.
+ You can use the Automated Upgrade Helper (AUH) to set up
+ automatic version upgrades.
+ Alternatively, you can use <filename>devtool upgrade</filename>
+ to set up semi-automatic version upgrades.
+ Finally, you can even manually upgrade a recipe by editing the
+ recipe itself.
+ </para>
+
+ <section id='gs-using-the-auto-upgrade-helper'>
+ <title>Using the Auto Upgrade Helper (AUH)</title>
+
+ <para>
+ The AUH utility works in conjunction with the
+ OpenEmbedded build system in order to automatically generate
+ upgrades for recipes based on new versions being
+ published upstream.
+ Use AUH when you want to create a service that performs the
+ upgrades automatically and optionally sends you an email with
+ the results.
+ </para>
+
+ <para>
+ AUH allows you to update several recipes with a single use.
+ You can also optionally perform build and integration tests
+ using images with the results saved to your hard drive and
+ emails of results optionally sent to recipe maintainers.
+ Finally, AUH creates Git commits with appropriate commit
+ messages in the layer's tree for the changes made to recipes.
+ <note>
+ Conditions do exist when you should not use AUH to upgrade
+ recipes and you should instead use either
+ <filename>devtool upgrade</filename> or upgrade your
+ recipes manually:
+ <itemizedlist>
+ <listitem><para>
+ When AUH cannot complete the upgrade sequence.
+ This situation usually results because custom
+ patches carried by the recipe cannot be
+ automatically rebased to the new version.
+ In this case, <filename>devtool upgrade</filename>
+ allows you to manually resolve conflicts.
+ </para></listitem>
+ <listitem><para>
+ When for any reason you want fuller control over
+ the upgrade process.
+ For example, when you want special arrangements
+ for testing.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The following steps describe how to set up the AUH utility:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Be Sure the Development Host is Set Up:</emphasis>
+ You need to be sure that your development host is
+ set up to use the Yocto Project.
+ For information on how to set up your host, see the
+ "<link linkend='setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure Git is Configured:</emphasis>
+ The AUH utility requires Git to be configured because
+ AUH uses Git to save upgrades.
+ Thus, you must have Git user and email configured.
+ The following command shows your configurations:
+ <literallayout class='monospaced'>
+ $ git config --list
+ </literallayout>
+ If you do not have the user and email configured, you
+ can use the following commands to do so:
+ <literallayout class='monospaced'>
+ $ git config --global user.name <replaceable>some_name</replaceable>
+ $ git config --global user.email <replaceable>username</replaceable>@<replaceable>domain</replaceable>.com
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the AUH Repository:</emphasis>
+ To use AUH, you must clone the repository onto your
+ development host.
+ The following command uses Git to create a local
+ copy of the repository on your system:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/auto-upgrade-helper
+ Cloning into 'auto-upgrade-helper'...
+ remote: Counting objects: 768, done.
+ remote: Compressing objects: 100% (300/300), done.
+ remote: Total 768 (delta 499), reused 703 (delta 434)
+ Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done.
+ Resolving deltas: 100% (499/499), done.
+ Checking connectivity... done.
+ </literallayout>
+ AUH is not part of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
+ repositories.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Dedicated Build Directory:</emphasis>
+ Run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
+ script to create a fresh build directory that you
+ use exclusively for running the AUH utility:
+ <literallayout class='monospaced'>
+ $ cd ~/poky
+ $ source oe-init-build-env <replaceable>your_AUH_build_directory</replaceable>
+ </literallayout>
+ Re-using an existing build directory and its
+ configurations is not recommended as existing settings
+ could cause AUH to fail or behave undesirably.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Configurations in Your Local Configuration File:</emphasis>
+ Several settings need to exist in the
+ <filename>local.conf</filename> file in the build
+ directory you just created for AUH.
+ Make these following configurations:
+ <itemizedlist>
+ <listitem><para>
+ Enable "distrodata" as follows:
+ <literallayout class='monospaced'>
+ INHERIT =+ "distrodata"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If you want to enable
+ <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Build History</ulink>,
+ which is optional, you need the following
+ lines in the
+ <filename>conf/local.conf</filename> file:
+ <literallayout class='monospaced'>
+ INHERIT =+ "buildhistory"
+ BUILDHISTORY_COMMIT = "1"
+ </literallayout>
+ With this configuration and a successful
+ upgrade, a build history "diff" file appears in
+ the
+ <filename>upgrade-helper/work/recipe/buildhistory-diff.txt</filename>
+ file found in your build directory.
+ </para></listitem>
+ <listitem><para>
+ If you want to enable testing through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
+ class, which is optional, you need to have the
+ following set in your
+ <filename>conf/local.conf</filename> file:
+ <literallayout class='monospaced'>
+ INHERIT += "testimage"
+ </literallayout>
+ <note>
+ If your distro does not enable by default
+ ptest, which Poky does, you need the
+ following in your
+ <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ DISTRO_FEATURES_append = " ptest"
+ </literallayout>
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Start a vncserver:</emphasis>
+ If you are running in a server without an X11 session,
+ you need to start a vncserver:
+ <literallayout class='monospaced'>
+ $ vncserver :1
+ $ export DISPLAY=:1
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create and Edit an AUH Configuration File:</emphasis>
+ You need to have the
+ <filename>upgrade-helper/upgrade-helper.conf</filename>
+ configuration file in your build directory.
+ You can find a sample configuration file in the
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/'>AUH source repository</ulink>.
+ </para>
+
+ <para>Read through the sample file and make
+ configurations as needed.
+ For example, if you enabled build history in your
+ <filename>local.conf</filename> as described earlier,
+ you must enable it in
+ <filename>upgrade-helper.conf</filename>.</para>
+
+ <para>Also, if you are using the default
+ <filename>maintainers.inc</filename> file supplied
+ with Poky and located in
+ <filename>meta-yocto</filename> and you do not set a
+ "maintainers_whitelist" or "global_maintainer_override"
+ in the <filename>upgrade-helper.conf</filename>
+ configuration, and you specify "-e all" on the
+ AUH command-line, the utility automatically sends out
+ emails to all the default maintainers.
+ Please avoid this.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ This next set of examples describes how to use the AUH:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Upgrading a Specific Recipe:</emphasis>
+ To upgrade a specific recipe, use the following
+ form:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py <replaceable>recipe_name</replaceable>
+ </literallayout>
+ For example, this command upgrades the
+ <filename>xmodmap</filename> recipe:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py xmodmap
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upgrading a Specific Recipe to a Particular Version:</emphasis>
+ To upgrade a specific recipe to a particular version,
+ use the following form:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py <replaceable>recipe_name</replaceable> -t <replaceable>version</replaceable>
+ </literallayout>
+ For example, this command upgrades the
+ <filename>xmodmap</filename> recipe to version
+ 1.2.3:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py xmodmap -t 1.2.3
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upgrading all Recipes to the Latest Versions and Suppressing Email Notifications:</emphasis>
+ To upgrade all recipes to their most recent versions
+ and suppress the email notifications, use the following
+ command:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py all
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upgrading all Recipes to the Latest Versions and Send Email Notifications:</emphasis>
+ To upgrade all recipes to their most recent versions
+ and send email messages to maintainers for each
+ attempted recipe as well as a status email, use the
+ following command:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py -e all
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Once you have run the AUH utility, you can find the results
+ in the AUH build directory:
+ <literallayout class='monospaced'>
+ ${BUILDDIR}/upgrade-helper/<replaceable>timestamp</replaceable>
+ </literallayout>
+ The AUH utility also creates recipe update commits from
+ successful upgrade attempts in the layer tree.
+ </para>
+
+ <para>
+ You can easily set up to run the AUH utility on a regular
+ basis by using a cron job.
+ See the
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh'><filename>weeklyjob.sh</filename></ulink>
+ file distributed with the utility for an example.
+ </para>
+ </section>
+
+ <section id='gs-using-devtool-upgrade'>
+ <title>Using <filename>devtool upgrade</filename></title>
+
+ <para>
+ As mentioned earlier, an alternative method for upgrading
+ recipes to newer versions is to use
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool upgrade</filename></ulink>.
+ You can read about <filename>devtool upgrade</filename> in
+ general in the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) Manual.
+ </para>
+
+ <para>
+ To see all the command-line options available with
+ <filename>devtool upgrade</filename>, use the following help
+ command:
+ <literallayout class='monospaced'>
+ $ devtool upgrade -h
+ </literallayout>
+ </para>
+
+ <para>
+ If you want to find out what version a recipe is currently at
+ upstream without any attempt to upgrade your local version of
+ the recipe, you can use the following command:
+ <literallayout class='monospaced'>
+ $ devtool latest-version <replaceable>recipe_name</replaceable>
+ </literallayout>
+ </para>
+
+ <para>
+ As mentioned in the previous section describing AUH,
+ <filename>devtool upgrade</filename> works in a
+ less-automated manner than AUH.
+ Specifically, <filename>devtool upgrade</filename> only
+ works on a single recipe that you name on the command line,
+ cannot perform build and integration testing using images,
+ and does not automatically generate commits for changes in
+ the source tree.
+ Despite all these "limitations",
+ <filename>devtool upgrade</filename> updates the recipe file
+ to the new upstream version and attempts to rebase custom
+ patches contained by the recipe as needed.
+ <note>
+ AUH uses much of <filename>devtool upgrade</filename>
+ behind the scenes making AUH somewhat of a "wrapper"
+ application for <filename>devtool upgrade</filename>.
+ </note>
+ </para>
+
+ <para>
+ A typical scenario involves having used Git to clone an
+ upstream repository that you use during build operations.
+ Because you are (or have) built the recipe in the past, the
+ layer is likely added to your configuration already.
+ If for some reason, the layer is not added, you could add
+ it easily using the
+ <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></ulink>
+ script.
+ For example, suppose you use the <filename>nano.bb</filename>
+ recipe from the <filename>meta-oe</filename> layer in the
+ <filename>meta-openembedded</filename> repository.
+ For this example, assume that the layer has been cloned into
+ following area:
+ <literallayout class='monospaced'>
+ /home/scottrif/meta-openembedded
+ </literallayout>
+ The following command from your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ adds the layer to your build configuration (i.e.
+ <filename>${BUILDDIR}/conf/bblayers.conf</filename>):
+ <literallayout class='monospaced'>
+ $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe
+ NOTE: Starting bitbake server...
+ Parsing recipes: 100% |##########################################| Time: 0:00:55
+ Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
+ Removing 12 recipes from the x86_64 sysroot: 100% |##############| Time: 0:00:00
+ Removing 1 recipes from the x86_64_i586 sysroot: 100% |##########| Time: 0:00:00
+ Removing 5 recipes from the i586 sysroot: 100% |#################| Time: 0:00:00
+ Removing 5 recipes from the qemux86 sysroot: 100% |##############| Time: 0:00:00
+ </literallayout>
+ For this example, assume that the <filename>nano.bb</filename>
+ recipe that is upstream has a 2.9.3 version number.
+ However, the version in the local repository is 2.7.4.
+ The following command from your build directory automatically
+ upgrades the recipe for you:
+ <note>
+ Using the <filename>-V</filename> option is not necessary.
+ Omitting the version number causes
+ <filename>devtool upgrade</filename> to upgrade the recipe
+ to the most recent version.
+ </note>
+ <literallayout class='monospaced'>
+ $ devtool upgrade nano -V 2.9.3
+ NOTE: Starting bitbake server...
+ NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace
+ Parsing recipes: 100% |##########################################| Time: 0:00:46
+ Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
+ NOTE: Extracting current version source...
+ NOTE: Resolving any missing task queue dependencies
+ .
+ .
+ .
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded.
+ Adding changed files: 100% |#####################################| Time: 0:00:00
+ NOTE: Upgraded source extracted to /home/scottrif/poky/build/workspace/sources/nano
+ NOTE: New recipe is /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb
+ </literallayout>
+ Continuing with this example, you can use
+ <filename>devtool build</filename> to build the newly upgraded
+ recipe:
+ <literallayout class='monospaced'>
+ $ devtool build nano
+ NOTE: Starting bitbake server...
+ Loading cache: 100% |################################################################################################| Time: 0:00:01
+ Loaded 2040 entries from dependency cache.
+ Parsing recipes: 100% |##############################################################################################| Time: 0:00:00
+ Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
+ NOTE: Resolving any missing task queue dependencies
+ .
+ .
+ .
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano
+ NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
+ </literallayout>
+ Within the <filename>devtool upgrade</filename> workflow,
+ opportunity exists to deploy and test your rebuilt software.
+ For this example, however, running
+ <filename>devtool finish</filename> cleans up the workspace
+ once the source in your workspace is clean.
+ This usually means using Git to stage and submit commits
+ for the changes generated by the upgrade process.
+ </para>
+
+ <para>
+ Once the tree is clean, you can clean things up in this
+ example with the following command from the
+ <filename>${BUILDDIR}/workspace/sources/nano</filename>
+ directory:
+ <literallayout class='monospaced'>
+ $ devtool finish nano meta-oe
+ NOTE: Starting bitbake server...
+ Loading cache: 100% |################################################################################################| Time: 0:00:00
+ Loaded 2040 entries from dependency cache.
+ Parsing recipes: 100% |##############################################################################################| Time: 0:00:01
+ Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
+ NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch
+ NOTE: Updating recipe nano_2.9.3.bb
+ NOTE: Removing file /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
+ NOTE: Moving recipe file to /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano
+ NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
+ </literallayout>
+ Using the <filename>devtool finish</filename> command cleans
+ up the workspace and creates a patch file based on your
+ commits.
+ The tool puts all patch files back into the source directory
+ in a sub-directory named <filename>nano</filename> in this
+ case.
+ </para>
+ </section>
+
+ <section id='dev-manually-upgrading-a-recipe'>
+ <title>Manually Upgrading a Recipe</title>
+
+ <para>
+ If for some reason you choose not to upgrade recipes using the
+ <link linkend='gs-using-the-auto-upgrade-helper'>Auto Upgrade Helper (AUH)</link>
+ or by using
+ <link linkend='gs-using-devtool-upgrade'><filename>devtool upgrade</filename></link>,
+ you can manually edit the recipe files to upgrade the versions.
+ <note><title>Caution</title>
+ Manually updating multiple recipes scales poorly and
+ involves many steps.
+ The recommendation to upgrade recipe versions is through
+ AUH or <filename>devtool upgrade</filename>, both of which
+ automate some steps and provide guidance for others needed
+ for the manual process.
+ </note>
+ </para>
+
+ <para>
+ To manually upgrade recipe versions, follow these general steps:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Change the Version:</emphasis>
+ Rename the recipe such that the version (i.e. the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+ part of the recipe name) changes appropriately.
+ If the version is not part of the recipe name, change
+ the value as it is set for <filename>PV</filename>
+ within the recipe itself.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Update <filename>SRCREV</filename> if Needed:</emphasis>
+ If the source code your recipe builds is fetched from
+ Git or some other version control system, update
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ to point to the commit hash that matches the new
+ version.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Software:</emphasis>
+ Try to build the recipe using BitBake.
+ Typical build failures include the following:
+ <itemizedlist>
+ <listitem><para>
+ License statements were updated for the new
+ version.
+ For this case, you need to review any changes
+ to the license and update the values of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ as needed.
+ <note>
+ License changes are often inconsequential.
+ For example, the license text's copyright
+ year might have changed.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Custom patches carried by the older version of
+ the recipe might fail to apply to the new
+ version.
+ For these cases, you need to review the
+ failures.
+ Patches might not be necessary for the new
+ version of the software if the upgraded version
+ has fixed those issues.
+ If a patch is necessary and failing, you need
+ to rebase it into the new version.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Attempt to Build for Several Architectures:</emphasis>
+ Once you successfully build the new software for a
+ given architecture, you could test the build for
+ other architectures by changing the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable and rebuilding the software.
+ This optional step is especially important if the
+ recipe is to be released publicly.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Check the Upstream Change Log or Release Notes:</emphasis>
+ Checking both these reveals if new features exist that
+ could break backwards-compatibility.
+ If so, you need to take steps to mitigate or eliminate
+ that situation.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Create a Bootable Image and Test:</emphasis>
+ If you want, you can test the new software by booting
+ it onto actual hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Commit with the Change in the Layer Repository:</emphasis>
+ After all builds work and any testing is successful,
+ you can create commits for any changes in the layer
+ holding your upgraded recipe.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+
<section id='finding-the-temporary-source-code'>
<title>Finding Temporary Source Code</title>
@@ -3888,8 +4946,8 @@
Modifications will also disappear if you use the
<filename>rm_work</filename> feature as described
in the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section of the Yocto Project Quick Start.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-saving-memory-during-a-build'>Conserving Disk Space During Builds</ulink>"
+ section.
</note>
</para></listitem>
<listitem><para>
@@ -4105,102 +5163,1224 @@
</para>
</section>
- <section id='platdev-building-targets-with-multiple-configurations'>
- <title>Building Targets with Multiple Configurations</title>
+ <section id='dev-building'>
+ <title>Building</title>
<para>
- Bitbake also has functionality that allows you to build
- multiple targets at the same time, where each target uses
- a different configuration.
+ This section describes various build procedures.
+ For example, the steps needed for a simple build, a target that
+ uses multiple configurations, building an image for more than
+ one machine, and so forth.
</para>
- <para>
- In order to accomplish this, you setup each of the configurations
- you need to use in parallel by placing the configuration files in
- your current build directory alongside the usual
- <filename>local.conf</filename> file.
- </para>
+ <section id='dev-building-a-simple-image'>
+ <title>Building a Simple Image</title>
+
+ <para>
+ In the development environment, you need to build an image
+ whenever you change hardware support, add or change system
+ libraries, or add or change services that have dependencies.
+ Several methods exist that allow you to build an image within
+ the Yocto Project.
+ This section presents the basic steps you need to build a
+ simple image using BitBake from a build host running Linux.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ For information on how to build an image using
+ <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
+ see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ <listitem><para>
+ For information on how to use
+ <filename>devtool</filename> to build images, see
+ the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
+ section in the Yocto Project Application
+ Development and the Extensible Software Development
+ Kit (eSDK) manual.
+ </para></listitem>
+ <listitem><para>
+ For a quick example on how to build an image using
+ the OpenEmbedded build system, see the
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+ document.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The build process creates an entire Linux distribution from
+ source and places it in your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ under <filename>tmp/deploy/images</filename>.
+ For detailed information on the build process using BitBake,
+ see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para>
+
+ <para>
+ The following figure and list overviews the build process:
+ <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set up Your Host Development System to Support
+ Development Using the Yocto Project</emphasis>:
+ See the
+ "<link linkend='dev-manual-start'>Setting Up to Use the Yocto Project</link>"
+ section for options on how to get a build host ready to
+ use the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ Initialize the build environment by sourcing the build
+ environment script (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
+ <literallayout class='monospaced'>
+ $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
+ </literallayout></para>
+
+ <para>When you use the initialization script, the
+ OpenEmbedded build system uses
+ <filename>build</filename> as the default Build
+ Directory in your current work directory.
+ You can use a <replaceable>build_dir</replaceable>
+ argument with the script to specify a different build
+ directory.
+ <note><title>Tip</title>
+ A common practice is to use a different Build
+ Directory for different targets.
+ For example, <filename>~/build/x86</filename> for a
+ <filename>qemux86</filename> target, and
+ <filename>~/build/arm</filename> for a
+ <filename>qemuarm</filename> target.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure Your <filename>local.conf</filename>
+ File is Correct:</emphasis>
+ Ensure the <filename>conf/local.conf</filename>
+ configuration file, which is found in the Build
+ Directory, is set up how you want it.
+ This file defines many aspects of the build environment
+ including the target machine architecture through the
+ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
+ the packaging format used during the build
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
+ and a centralized tarball download directory through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Image:</emphasis>
+ Build the image using the <filename>bitbake</filename>
+ command:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>target</replaceable>
+ </literallayout>
+ <note>
+ For information on BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </note>
+ The <replaceable>target</replaceable> is the name of the
+ recipe you want to build.
+ Common targets are the images in
+ <filename>meta/recipes-core/images</filename>,
+ <filename>meta/recipes-sato/images</filename>, and so
+ forth all found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ Or, the target can be the name of a recipe for a
+ specific piece of software such as BusyBox.
+ For more details about the images the OpenEmbedded build
+ system supports, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual.</para>
+
+ <para>As an example, the following command builds the
+ <filename>core-image-minimal</filename> image:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-minimal
+ </literallayout>
+ Once an image has been built, it often needs to be
+ installed.
+ The images and kernels built by the OpenEmbedded
+ build system are placed in the Build Directory in
+ <filename class="directory">tmp/deploy/images</filename>.
+ For information on how to run pre-built images such as
+ <filename>qemux86</filename> and <filename>qemuarm</filename>,
+ see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ For information about how to install these images,
+ see the documentation for your particular board or
+ machine.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='platdev-building-targets-with-multiple-configurations'>
+ <title>Building Targets with Multiple Configurations</title>
+
+ <para>
+ Bitbake also has functionality that allows you to build
+ multiple targets at the same time, where each target uses
+ a different configuration.
+ </para>
+
+ <para>
+ In order to accomplish this, you setup each of the configurations
+ you need to use in parallel by placing the configuration files in
+ your current build directory alongside the usual
+ <filename>local.conf</filename> file.
+ </para>
+
+ <para>
+ Follow these guidelines to create an environment that supports
+ multiple configurations:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create Configuration Files</emphasis>:
+ You need to create a single configuration file for each
+ configuration for which you want to add support.
+ These files would contain lines such as the following:
+ <literallayout class='monospaced'>
+ MACHINE = "A"
+ </literallayout>
+ The files would contain any other variables that can
+ be set and built in the same directory.
+ <note>
+ You can change the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ to not conflict.
+ </note></para>
+
+ <para>
+ Furthermore, the configuration file must be located in the
+ current build directory in a directory named
+ <filename>multiconfig</filename> under the build's
+ <filename>conf</filename> directory where
+ <filename>local.conf</filename> resides.
+ The reason for this restriction is because the
+ <filename>BBPATH</filename> variable is not constructed
+ until the layers are parsed.
+ Consequently, using the configuration file as a
+ pre-configuration file is not possible unless it is
+ located in the current working directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>:
+ Use the
+ <filename>BBMULTICONFIG</filename>
+ variable in your <filename>conf/local.conf</filename>
+ configuration file to specify each separate configuration.
+ For example, the following line tells BitBake it should load
+ <filename>conf/multiconfig/configA.conf</filename>,
+ <filename>conf/multiconfig/configB.conf</filename>, and
+ <filename>conf/multiconfig/configC.conf</filename>.
+ <literallayout class='monospaced'>
+ BBMULTICONFIG = "configA configB configC"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch BitBake</emphasis>:
+ Use the following BitBake command form to launch the
+ build:
+ <literallayout class='monospaced'>
+ $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
+ </literallayout>
+ Following is an example that supports building a minimal
+ image for configuration A alongside a standard
+ <filename>core-image-sato</filename>, which takes its
+ configuration from <filename>local.conf</filename>:
+ <literallayout class='monospaced'>
+ $ bitbake multiconfig:configA:core-image-minimal core-image-sato
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Support for multiple configurations in this current release of
+ the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues:
+ <itemizedlist>
+ <listitem><para>
+ No inter-multi-configuration dependencies exist.
+ </para></listitem>
+ <listitem><para>
+ Shared State (sstate) optimizations do not exist.
+ Consequently, if the build uses the same object twice
+ in, for example, two different
+ <filename>TMPDIR</filename> directories, the build
+ will either load from an existing sstate cache at the
+ start or build the object twice.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='building-an-initramfs-image'>
+ <title>Building an Initial RAM Filesystem (initramfs) Image</title>
+
+ <para>
+ An initial RAM filesystem (initramfs) image provides a temporary
+ root filesystem used for early system initialization (e.g.
+ loading of modules needed to locate and mount the "real" root
+ filesystem).
+ <note>
+ The initramfs image is the successor of initial RAM disk
+ (initrd).
+ It is a "copy in and out" (cpio) archive of the initial
+ filesystem that gets loaded into memory during the Linux
+ startup process.
+ Because Linux uses the contents of the archive during
+ initialization, the initramfs image needs to contain all of the
+ device drivers and tools needed to mount the final root
+ filesystem.
+ </note>
+ </para>
+
+ <para>
+ Follow these steps to create an initramfs image:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create the initramfs Image Recipe:</emphasis>
+ You can reference the
+ <filename>core-image-minimal-initramfs.bb</filename>
+ recipe found in the <filename>meta/recipes-core</filename>
+ directory of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ as an example from which to work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Decide if You Need to Bundle the initramfs Image
+ Into the Kernel Image:</emphasis>
+ If you want the initramfs image that is built to be
+ bundled in with the kernel image, set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable to "1" in your <filename>local.conf</filename>
+ configuration file and set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
+ variable in the recipe that builds the kernel image.
+ <note><title>Tip</title>
+ It is recommended that you do bundle the initramfs
+ image with the kernel image to avoid circular
+ dependencies between the kernel recipe and the
+ initramfs recipe should the initramfs image
+ include kernel modules.
+ </note>
+ Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
+ flag causes the initramfs image to be unpacked
+ into the <filename>${B}/usr/</filename> directory.
+ The unpacked initramfs image is then passed to the kernel's
+ <filename>Makefile</filename> using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
+ variable, allowing the initramfs image to be built into
+ the kernel normally.
+ <note>
+ If you choose to not bundle the initramfs image with
+ the kernel image, you are essentially using an
+ <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
+ Creating an initrd is handled primarily through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
+ <filename>INITRD_LIVE</filename>, and
+ <filename>INITRD_IMAGE_LIVE</filename> variables.
+ For more information, see the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
+ file.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Add Items to the initramfs Image
+ Through the initramfs Image Recipe:</emphasis>
+ If you add items to the initramfs image by way of its
+ recipe, you should use
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
+ rather than
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
+ <filename>PACKAGE_INSTALL</filename> gives more direct
+ control of what is added to the image as compared to
+ the defaults you might not necessarily want that are
+ set by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
+ classes.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Kernel Image and the initramfs
+ Image:</emphasis>
+ Build your kernel image using BitBake.
+ Because the initramfs image recipe is a dependency of the
+ kernel image, the initramfs image is built as well and
+ bundled with the kernel image if you used the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable described earlier.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='building-a-tiny-system'>
+ <title>Building a Tiny System</title>
+
+ <para>
+ Very small distributions have some significant advantages such
+ as requiring less on-die or in-package memory (cheaper), better
+ performance through efficient cache usage, lower power requirements
+ due to less memory, faster boot times, and reduced development
+ overhead.
+ Some real-world examples where a very small distribution gives
+ you distinct advantages are digital cameras, medical devices,
+ and small headless systems.
+ </para>
+
+ <para>
+ This section presents information that shows you how you can
+ trim your distribution to even smaller sizes than the
+ <filename>poky-tiny</filename> distribution, which is around
+ 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
+ </para>
+
+ <section id='tiny-system-overview'>
+ <title>Overview</title>
+
+ <para>
+ The following list presents the overall steps you need to
+ consider and perform to create distributions with smaller
+ root filesystems, achieve faster boot times, maintain your critical
+ functionality, and avoid initial RAM disks:
+ <itemizedlist>
+ <listitem><para>
+ <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='iterate-on-the-process'>Iterate on the process.</link>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='goals-and-guiding-principles'>
+ <title>Goals and Guiding Principles</title>
+
+ <para>
+ Before you can reach your destination, you need to know
+ where you are going.
+ Here is an example list that you can use as a guide when
+ creating very small distributions:
+ <itemizedlist>
+ <listitem><para>Determine how much space you need
+ (e.g. a kernel that is 1 Mbyte or less and
+ a root filesystem that is 3 Mbytes or less).
+ </para></listitem>
+ <listitem><para>Find the areas that are currently
+ taking 90% of the space and concentrate on reducing
+ those areas.
+ </para></listitem>
+ <listitem><para>Do not create any difficult "hacks"
+ to achieve your goals.</para></listitem>
+ <listitem><para>Leverage the device-specific
+ options.</para></listitem>
+ <listitem><para>Work in a separate layer so that you
+ keep changes isolated.
+ For information on how to create layers, see
+ the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='understand-what-gives-your-image-size'>
+ <title>Understand What Contributes to Your Image Size</title>
+
+ <para>
+ It is easiest to have something to start with when creating
+ your own distribution.
+ You can use the Yocto Project out-of-the-box to create the
+ <filename>poky-tiny</filename> distribution.
+ Ultimately, you will want to make changes in your own
+ distribution that are likely modeled after
+ <filename>poky-tiny</filename>.
+ <note>
+ To use <filename>poky-tiny</filename> in your build,
+ set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ variable in your
+ <filename>local.conf</filename> file to "poky-tiny"
+ as described in the
+ "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ Understanding some memory concepts will help you reduce the
+ system size.
+ Memory consists of static, dynamic, and temporary memory.
+ Static memory is the TEXT (code), DATA (initialized data
+ in the code), and BSS (uninitialized data) sections.
+ Dynamic memory represents memory that is allocated at runtime:
+ stacks, hash tables, and so forth.
+ Temporary memory is recovered after the boot process.
+ This memory consists of memory used for decompressing
+ the kernel and for the <filename>__init__</filename>
+ functions.
+ </para>
+
+ <para>
+ To help you see where you currently are with kernel and root
+ filesystem sizes, you can use two tools found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in
+ the <filename>scripts/tiny/</filename> directory:
+ <itemizedlist>
+ <listitem><para><filename>ksize.py</filename>: Reports
+ component sizes for the kernel build objects.
+ </para></listitem>
+ <listitem><para><filename>dirsize.py</filename>: Reports
+ component sizes for the root filesystem.</para></listitem>
+ </itemizedlist>
+ This next tool and command help you organize configuration
+ fragments and view file dependencies in a human-readable form:
+ <itemizedlist>
+ <listitem><para><filename>merge_config.sh</filename>:
+ Helps you manage configuration files and fragments
+ within the kernel.
+ With this tool, you can merge individual configuration
+ fragments together.
+ The tool allows you to make overrides and warns you
+ of any missing configuration options.
+ The tool is ideal for allowing you to iterate on
+ configurations, create minimal configurations, and
+ create configuration files for different machines
+ without having to duplicate your process.</para>
+ <para>The <filename>merge_config.sh</filename> script is
+ part of the Linux Yocto kernel Git repositories
+ (i.e. <filename>linux-yocto-3.14</filename>,
+ <filename>linux-yocto-3.10</filename>,
+ <filename>linux-yocto-3.8</filename>, and so forth)
+ in the
+ <filename>scripts/kconfig</filename> directory.</para>
+ <para>For more information on configuration fragments,
+ see the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
+ section in the Yocto Project Linux Kernel Development
+ Manual.
+ </para></listitem>
+ <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>:
+ Using the BitBake command with these options brings up
+ a Dependency Explorer from which you can view file
+ dependencies.
+ Understanding these dependencies allows you to make
+ informed decisions when cutting out various pieces of the
+ kernel and root filesystem.</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='trim-the-root-filesystem'>
+ <title>Trim the Root Filesystem</title>
+
+ <para>
+ The root filesystem is made up of packages for booting,
+ libraries, and applications.
+ To change things, you can configure how the packaging happens,
+ which changes the way you build them.
+ You can also modify the filesystem itself or select a different
+ filesystem.
+ </para>
+
+ <para>
+ First, find out what is hogging your root filesystem by running the
+ <filename>dirsize.py</filename> script from your root directory:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>root-directory-of-image</replaceable>
+ $ dirsize.py 100000 > dirsize-100k.log
+ $ cat dirsize-100k.log
+ </literallayout>
+ You can apply a filter to the script to ignore files under
+ a certain size.
+ The previous example filters out any files below 100 Kbytes.
+ The sizes reported by the tool are uncompressed, and thus
+ will be smaller by a relatively constant factor in a
+ compressed root filesystem.
+ When you examine your log file, you can focus on areas of the
+ root filesystem that take up large amounts of memory.
+ </para>
+
+ <para>
+ You need to be sure that what you eliminate does not cripple
+ the functionality you need.
+ One way to see how packages relate to each other is by using
+ the Dependency Explorer UI with the BitBake command:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>image-directory</replaceable>
+ $ bitbake -u taskexp -g <replaceable>image</replaceable>
+ </literallayout>
+ Use the interface to select potential packages you wish to
+ eliminate and see their dependency relationships.
+ </para>
+
+ <para>
+ When deciding how to reduce the size, get rid of packages that
+ result in minimal impact on the feature set.
+ For example, you might not need a VGA display.
+ Or, you might be able to get by with <filename>devtmpfs</filename>
+ and <filename>mdev</filename> instead of
+ <filename>udev</filename>.
+ </para>
+
+ <para>
+ Use your <filename>local.conf</filename> file to make changes.
+ For example, to eliminate <filename>udev</filename> and
+ <filename>glib</filename>, set the following in the
+ local configuration file:
+ <literallayout class='monospaced'>
+ VIRTUAL-RUNTIME_dev_manager = ""
+ </literallayout>
+ </para>
+
+ <para>
+ Finally, you should consider exactly the type of root
+ filesystem you need to meet your needs while also reducing
+ its size.
+ For example, consider <filename>cramfs</filename>,
+ <filename>squashfs</filename>, <filename>ubifs</filename>,
+ <filename>ext2</filename>, or an <filename>initramfs</filename>
+ using <filename>initramfs</filename>.
+ Be aware that <filename>ext3</filename> requires a 1 Mbyte
+ journal.
+ If you are okay with running read-only, you do not need this
+ journal.
+ </para>
+
+ <note>
+ After each round of elimination, you need to rebuild your
+ system and then use the tools to see the effects of your
+ reductions.
+ </note>
+ </section>
+
+ <section id='trim-the-kernel'>
+ <title>Trim the Kernel</title>
+
+ <para>
+ The kernel is built by including policies for hardware-independent
+ aspects.
+ What subsystems do you enable?
+ For what architecture are you building?
+ Which drivers do you build by default?
+ <note>You can modify the kernel source if you want to help
+ with boot time.
+ </note>
+ </para>
+
+ <para>
+ Run the <filename>ksize.py</filename> script from the top-level
+ Linux build directory to get an idea of what is making up
+ the kernel:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>top-level-linux-build-directory</replaceable>
+ $ ksize.py > ksize.log
+ $ cat ksize.log
+ </literallayout>
+ When you examine the log, you will see how much space is
+ taken up with the built-in <filename>.o</filename> files for
+ drivers, networking, core kernel files, filesystem, sound,
+ and so forth.
+ The sizes reported by the tool are uncompressed, and thus
+ will be smaller by a relatively constant factor in a compressed
+ kernel image.
+ Look to reduce the areas that are large and taking up around
+ the "90% rule."
+ </para>
+
+ <para>
+ To examine, or drill down, into any particular area, use the
+ <filename>-d</filename> option with the script:
+ <literallayout class='monospaced'>
+ $ ksize.py -d > ksize.log
+ </literallayout>
+ Using this option breaks out the individual file information
+ for each area of the kernel (e.g. drivers, networking, and
+ so forth).
+ </para>
+
+ <para>
+ Use your log file to see what you can eliminate from the kernel
+ based on features you can let go.
+ For example, if you are not going to need sound, you do not
+ need any drivers that support sound.
+ </para>
+
+ <para>
+ After figuring out what to eliminate, you need to reconfigure
+ the kernel to reflect those changes during the next build.
+ You could run <filename>menuconfig</filename> and make all your
+ changes at once.
+ However, that makes it difficult to see the effects of your
+ individual eliminations and also makes it difficult to replicate
+ the changes for perhaps another target device.
+ A better method is to start with no configurations using
+ <filename>allnoconfig</filename>, create configuration
+ fragments for individual changes, and then manage the
+ fragments into a single configuration file using
+ <filename>merge_config.sh</filename>.
+ The tool makes it easy for you to iterate using the
+ configuration change and build cycle.
+ </para>
+
+ <para>
+ Each time you make configuration changes, you need to rebuild
+ the kernel and check to see what impact your changes had on
+ the overall size.
+ </para>
+ </section>
+
+ <section id='remove-package-management-requirements'>
+ <title>Remove Package Management Requirements</title>
+
+ <para>
+ Packaging requirements add size to the image.
+ One way to reduce the size of the image is to remove all the
+ packaging requirements from the image.
+ This reduction includes both removing the package manager
+ and its unique dependencies as well as removing the package
+ management data itself.
+ </para>
+
+ <para>
+ To eliminate all the packaging requirements for an image,
+ be sure that "package-management" is not part of your
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+ statement for the image.
+ When you remove this feature, you are removing the package
+ manager as well as its dependencies from the root filesystem.
+ </para>
+ </section>
+
+ <section id='look-for-other-ways-to-minimize-size'>
+ <title>Look for Other Ways to Minimize Size</title>
+
+ <para>
+ Depending on your particular circumstances, other areas that you
+ can trim likely exist.
+ The key to finding these areas is through tools and methods
+ described here combined with experimentation and iteration.
+ Here are a couple of areas to experiment with:
+ <itemizedlist>
+ <listitem><para><filename>glibc</filename>:
+ In general, follow this process:
+ <orderedlist>
+ <listitem><para>Remove <filename>glibc</filename>
+ features from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+ that you think you do not need.</para></listitem>
+ <listitem><para>Build your distribution.
+ </para></listitem>
+ <listitem><para>If the build fails due to missing
+ symbols in a package, determine if you can
+ reconfigure the package to not need those
+ features.
+ For example, change the configuration to not
+ support wide character support as is done for
+ <filename>ncurses</filename>.
+ Or, if support for those characters is needed,
+ determine what <filename>glibc</filename>
+ features provide the support and restore the
+ configuration.
+ </para></listitem>
+ <listitem><para>Rebuild and repeat the process.
+ </para></listitem>
+ </orderedlist></para></listitem>
+ <listitem><para><filename>busybox</filename>:
+ For BusyBox, use a process similar as described for
+ <filename>glibc</filename>.
+ A difference is you will need to boot the resulting
+ system to see if you are able to do everything you
+ expect from the running system.
+ You need to be sure to integrate configuration fragments
+ into Busybox because BusyBox handles its own core
+ features and then allows you to add configuration
+ fragments on top.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='iterate-on-the-process'>
+ <title>Iterate on the Process</title>
+
+ <para>
+ If you have not reached your goals on system size, you need
+ to iterate on the process.
+ The process is the same.
+ Use the tools and see just what is taking up 90% of the root
+ filesystem and the kernel.
+ Decide what you can eliminate without limiting your device
+ beyond what you need.
+ </para>
+
+ <para>
+ Depending on your system, a good place to look might be
+ Busybox, which provides a stripped down
+ version of Unix tools in a single, executable file.
+ You might be able to drop virtual terminal services or perhaps
+ ipv6.
+ </para>
+ </section>
+ </section>
+
+ <section id='building-images-for-more-than-one-machine'>
+ <title>Building Images for More than One Machine</title>
+
+ <para>
+ A common scenario developers face is creating images for several
+ different machines that use the same software environment.
+ In this situation, it is tempting to set the
+ tunings and optimization flags for each build specifically for
+ the targeted hardware (i.e. "maxing out" the tunings).
+ Doing so can considerably add to build times and package feed
+ maintenance collectively for the machines.
+ For example, selecting tunes that are extremely specific to a
+ CPU core used in a system might enable some micro optimizations
+ in GCC for that particular system but would otherwise not gain
+ you much of a performance difference across the other systems
+ as compared to using a more general tuning across all the builds
+ (e.g. setting
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
+ specifically for each machine's build).
+ Rather than "max out" each build's tunings, you can take steps that
+ cause the OpenEmbedded build system to reuse software across the
+ various machines where it makes sense.
+ </para>
+
+ <para>
+ If build speed and package feed maintenance are considerations,
+ you should consider the points in this section that can help you
+ optimize your tunings to best consider build times and package
+ feed maintenance.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Share the Build Directory:</emphasis>
+ If at all possible, share the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ across builds.
+ The Yocto Project supports switching between different
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ values in the same <filename>TMPDIR</filename>.
+ This practice is well supported and regularly used by
+ developers when building for multiple machines.
+ When you use the same <filename>TMPDIR</filename> for
+ multiple machine builds, the OpenEmbedded build system can
+ reuse the existing native and often cross-recipes for
+ multiple machines.
+ Thus, build time decreases.
+ <note>
+ If
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ settings change or fundamental configuration settings
+ such as the filesystem layout, you need to work with
+ a clean <filename>TMPDIR</filename>.
+ Sharing <filename>TMPDIR</filename> under these
+ circumstances might work but since it is not
+ guaranteed, you should use a clean
+ <filename>TMPDIR</filename>.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Enable the Appropriate Package Architecture:</emphasis>
+ By default, the OpenEmbedded build system enables three
+ levels of package architectures: "all", "tune" or "package",
+ and "machine".
+ Any given recipe usually selects one of these package
+ architectures (types) for its output.
+ Depending for what a given recipe creates packages, making
+ sure you enable the appropriate package architecture can
+ directly impact the build time.</para>
+
+ <para>A recipe that just generates scripts can enable
+ "all" architecture because there are no binaries to build.
+ To specifically enable "all" architecture, be sure your
+ recipe inherits the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
+ class.
+ This class is useful for "all" architectures because it
+ configures many variables so packages can be used across
+ multiple architectures.</para>
+
+ <para>If your recipe needs to generate packages that are
+ machine-specific or when one of the build or runtime
+ dependencies is already machine-architecture dependent,
+ which makes your recipe also machine-architecture dependent,
+ make sure your recipe enables the "machine" package
+ architecture through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
+ variable:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCH = "${MACHINE_ARCH}"
+ </literallayout>
+ When you do not specifically enable a package
+ architecture through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
+ The OpenEmbedded build system defaults to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink>
+ setting:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCH = "${TUNE_PKGARCH}"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Choose a Generic Tuning File if Possible:</emphasis>
+ Some tunes are more generic and can run on multiple targets
+ (e.g. an <filename>armv5</filename> set of packages could
+ run on <filename>armv6</filename> and
+ <filename>armv7</filename> processors in most cases).
+ Similarly, <filename>i486</filename> binaries could work
+ on <filename>i586</filename> and higher processors.
+ You should realize, however, that advances on newer
+ processor versions would not be used.</para>
+
+ <para>If you select the same tune for several different
+ machines, the OpenEmbedded build system reuses software
+ previously built, thus speeding up the overall build time.
+ Realize that even though a new sysroot for each machine is
+ generated, the software is not recompiled and only one
+ package feed exists.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Manage Granular Level Packaging:</emphasis>
+ Sometimes cases exist where injecting another level of
+ package architecture beyond the three higher levels noted
+ earlier can be useful.
+ For example, consider how NXP (formerly Freescale) allows
+ for the easy reuse of binary packages in their layer
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/'><filename>meta-freescale</filename></ulink>.
+ In this example, the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/classes/fsl-dynamic-packagearch.bbclass'><filename>fsl-dynamic-packagearch</filename></ulink>
+ class shares GPU packages for i.MX53 boards because
+ all boards share the AMD GPU.
+ The i.MX6-based boards can do the same because all boards
+ share the Vivante GPU.
+ This class inspects the BitBake datastore to identify if
+ the package provides or depends on one of the
+ sub-architecture values.
+ If so, the class sets the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
+ value based on the <filename>MACHINE_SUBARCH</filename>
+ value.
+ If the package does not provide or depend on one of the
+ sub-architecture values but it matches a value in the
+ machine-specific filter, it sets
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>.
+ This behavior reduces the number of packages built and
+ saves build time by reusing binaries.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use Tools to Debug Issues:</emphasis>
+ Sometimes you can run into situations where software is
+ being rebuilt when you think it should not be.
+ For example, the OpenEmbedded build system might not be
+ using shared state between machines when you think it
+ should be.
+ These types of situations are usually due to references
+ to machine-specific variables such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>,
+ and so forth in code that is supposed to only be
+ tune-specific or when the recipe depends
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>,
+ and so forth) on some other recipe that already has
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
+ defined as "${MACHINE_ARCH}".
+ <note>
+ Patches to fix any issues identified are most welcome
+ as these issues occasionally do occur.
+ </note></para>
+
+ <para>For such cases, you can use some tools to help you
+ sort out the situation:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
+ You can find this tool in the
+ <filename>scripts</filename> directory of the
+ Source Repositories.
+ See the comments in the script for information on
+ how to use the tool.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>BitBake's "-S printdiff" Option:</emphasis>
+ Using this option causes BitBake to try to
+ establish the closest signature match it can
+ (e.g. in the shared state cache) and then run
+ <filename>bitbake-diffsigs</filename> over the
+ matches to determine the stamps and delta where
+ these two stamp trees diverge.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="building-software-from-an-external-source">
+ <title>Building Software from an External Source</title>
+
+ <para>
+ By default, the OpenEmbedded build system uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ when building source code.
+ The build process involves fetching the source files, unpacking
+ them, and then patching them if necessary before the build takes
+ place.
+ </para>
+
+ <para>
+ Situations exist where you might want to build software from source
+ files that are external to and thus outside of the
+ OpenEmbedded build system.
+ For example, suppose you have a project that includes a new BSP with
+ a heavily customized kernel.
+ And, you want to minimize exposing the build system to the
+ development team so that they can focus on their project and
+ maintain everyone's workflow as much as possible.
+ In this case, you want a kernel source directory on the development
+ machine where the development occurs.
+ You want the recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ variable to point to the external directory and use it as is, not
+ copy it.
+ </para>
+
+ <para>
+ To build from software that comes from an external source, all you
+ need to do is inherit the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
+ class and then set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
+ variable to point to your external source code.
+ Here are the statements to put in your
+ <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ INHERIT += "externalsrc"
+ EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
+ </literallayout>
+ </para>
+
+ <para>
+ This next example shows how to accomplish the same thing by setting
+ <filename>EXTERNALSRC</filename> in the recipe itself or in the
+ recipe's append file:
+ <literallayout class='monospaced'>
+ EXTERNALSRC = "<replaceable>path</replaceable>"
+ EXTERNALSRC_BUILD = "<replaceable>path</replaceable>"
+ </literallayout>
+ <note>
+ In order for these settings to take effect, you must globally
+ or locally inherit the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
+ class.
+ </note>
+ </para>
+
+ <para>
+ By default, <filename>externalsrc.bbclass</filename> builds
+ the source code in a directory separate from the external source
+ directory as specified by
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
+ If you need to have the source built in the same directory in
+ which it resides, or some other nominated directory, you can set
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
+ to point to that directory:
+ <literallayout class='monospaced'>
+ EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+
+
+ <section id='speeding-up-a-build'>
+ <title>Speeding Up a Build</title>
<para>
- Follow these guidelines to create an environment that supports
- multiple configurations:
+ Build time can be an issue.
+ By default, the build system uses simple controls to try and maximize
+ build efficiency.
+ In general, the default settings for all the following variables
+ result in the most efficient build times when dealing with single
+ socket systems (i.e. a single CPU).
+ If you have multiple CPUs, you might try increasing the default
+ values to gain more speed.
+ See the descriptions in the glossary for each variable for more
+ information:
<itemizedlist>
<listitem><para>
- <emphasis>Create Configuration Files</emphasis>:
- You need to create a single configuration file for each
- configuration for which you want to add support.
- These files would contain lines such as the following:
- <literallayout class='monospaced'>
- MACHINE = "A"
- </literallayout>
- The files would contain any other variables that can
- be set and built in the same directory.
- <note>
- You can change the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
- to not conflict.
- </note></para>
-
- <para>
- Furthermore, the configuration file must be located in the
- current build directory in a directory named
- <filename>multiconfig</filename> under the build's
- <filename>conf</filename> directory where
- <filename>local.conf</filename> resides.
- The reason for this restriction is because the
- <filename>BBPATH</filename> variable is not constructed
- until the layers are parsed.
- Consequently, using the configuration file as a
- pre-configuration file is not possible unless it is
- located in the current working directory.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</ulink>
+ The maximum number of threads BitBake simultaneously executes.
</para></listitem>
<listitem><para>
- <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>:
- Use the
- <filename>BBMULTICONFIG</filename>
- variable in your <filename>conf/local.conf</filename>
- configuration file to specify each separate configuration.
- For example, the following line tells BitBake it should load
- <filename>conf/multiconfig/configA.conf</filename>,
- <filename>conf/multiconfig/configB.conf</filename>, and
- <filename>conf/multiconfig/configC.conf</filename>.
- <literallayout class='monospaced'>
- BBMULTICONFIG = "configA configB configC"
- </literallayout>
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
+ The number of threads BitBake uses during parsing.
</para></listitem>
<listitem><para>
- <emphasis>Launch BitBake</emphasis>:
- Use the following BitBake command form to launch the
- build:
- <literallayout class='monospaced'>
- $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
- </literallayout>
- Following is an example that supports building a minimal
- image for configuration A alongside a standard
- <filename>core-image-sato</filename>, which takes its
- configuration from <filename>local.conf</filename>:
- <literallayout class='monospaced'>
- $ bitbake multiconfig:configA:core-image-minimal core-image-sato
- </literallayout>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</ulink>
+ Extra options passed to the <filename>make</filename> command
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+ task in order to specify parallel compilation on the
+ local build host.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</ulink>
+ Extra options passed to the <filename>make</filename> command
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task in order to specify parallel installation on the
+ local build host.
</para></listitem>
</itemizedlist>
+ As mentioned, these variables all scale to the number of processor
+ cores available on the build system.
+ For single socket systems, this auto-scaling ensures that the build
+ system fundamentally takes advantage of potential parallel operations
+ during the build based on the build machine's capabilities.
</para>
<para>
- Support for multiple configurations in this current release of
- the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues:
+ Following are additional factors that can affect build speed:
<itemizedlist>
<listitem><para>
- No inter-multi-configuration dependencies exist.
+ File system type:
+ The file system type that the build is being performed on can
+ also influence performance.
+ Using <filename>ext4</filename> is recommended as compared
+ to <filename>ext2</filename> and <filename>ext3</filename>
+ due to <filename>ext4</filename> improved features
+ such as extents.
</para></listitem>
<listitem><para>
- Shared State (sstate) optimizations do not exist.
- Consequently, if the build uses the same object twice
- in, for example, two different
- <filename>TMPDIR</filename> directories, the build
- will either load from an existing sstate cache at the
- start or build the object twice.
+ Disabling the updating of access time using
+ <filename>noatime</filename>:
+ The <filename>noatime</filename> mount option prevents the
+ build system from updating file and directory access times.
</para></listitem>
+ <listitem><para>
+ Setting a longer commit:
+ Using the "commit=" mount option increases the interval
+ in seconds between disk cache writes.
+ Changing this interval from the five second default to
+ something longer increases the risk of data loss but decreases
+ the need to write to the disk, thus increasing the build
+ performance.
+ </para></listitem>
+ <listitem><para>
+ Choosing the packaging backend:
+ Of the available packaging backends, IPK is the fastest.
+ Additionally, selecting a singular packaging backend also
+ helps.
+ </para></listitem>
+ <listitem><para>
+ Using <filename>tmpfs</filename> for
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ as a temporary file system:
+ While this can help speed up the build, the benefits are
+ limited due to the compiler using
+ <filename>-pipe</filename>.
+ The build system goes to some lengths to avoid
+ <filename>sync()</filename> calls into the
+ file system on the principle that if there was a significant
+ failure, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ contents could easily be rebuilt.
+ </para></listitem>
+ <listitem><para>
+ Inheriting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+ class:
+ Inheriting this class has shown to speed up builds due to
+ significantly lower amounts of data stored in the data
+ cache as well as on disk.
+ Inheriting this class also makes cleanup of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ faster, at the expense of being easily able to dive into the
+ source code.
+ File system maintainers have recommended that the fastest way
+ to clean up large numbers of files is to reformat partitions
+ rather than delete files due to the linear nature of
+ partitions.
+ This, of course, assumes you structure the disk partitions and
+ file systems in a way that this is practical.
+ </para></listitem>
+ </itemizedlist>
+ Aside from the previous list, you should keep some trade offs in
+ mind that can help you speed up the build:
+ <itemizedlist>
+ <listitem><para>
+ Remove items from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+ that you might not need.
+ </para></listitem>
+ <listitem><para>
+ Exclude debug symbols and other debug information:
+ If you do not need these symbols and other debug information,
+ disabling the <filename>*-dbg</filename> package generation
+ can speed up the build.
+ You can disable this generation by setting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></ulink>
+ variable to "1".
+ </para></listitem>
+ <listitem><para>
+ Disable static library generation for recipes derived from
+ <filename>autoconf</filename> or <filename>libtool</filename>:
+ Following is an example showing how to disable static
+ libraries and still provide an override to handle exceptions:
+ <literallayout class='monospaced'>
+ STATICLIBCONF = "--disable-static"
+ STATICLIBCONF_sqlite3-native = ""
+ EXTRA_OECONF += "${STATICLIBCONF}"
+ </literallayout>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Some recipes need static libraries in order to work
+ correctly (e.g. <filename>pseudo-native</filename>
+ needs <filename>sqlite3-native</filename>).
+ Overrides, as in the previous example, account for
+ these kinds of exceptions.
+ </para></listitem>
+ <listitem><para>
+ Some packages have packaging code that assumes the
+ presence of the static libraries.
+ If so, you might need to exclude them as well.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
</itemizedlist>
</para>
</section>
@@ -4543,6 +6723,84 @@
</section>
</section>
+ <section id='using-x32-psabi'>
+ <title>Using x32 psABI</title>
+
+ <para>
+ x32 processor-specific Application Binary Interface
+ (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>)
+ is a native 32-bit processor-specific ABI for
+ <trademark class='registered'>Intel</trademark> 64 (x86-64)
+ architectures.
+ An ABI defines the calling conventions between functions in a
+ processing environment.
+ The interface determines what registers are used and what the
+ sizes are for various C data types.
+ </para>
+
+ <para>
+ Some processing environments prefer using 32-bit applications even
+ when running on Intel 64-bit platforms.
+ Consider the i386 psABI, which is a very old 32-bit ABI for Intel
+ 64-bit platforms.
+ The i386 psABI does not provide efficient use and access of the
+ Intel 64-bit processor resources, leaving the system underutilized.
+ Now consider the x86_64 psABI.
+ This ABI is newer and uses 64-bits for data sizes and program
+ pointers.
+ The extra bits increase the footprint size of the programs,
+ libraries, and also increases the memory and file system size
+ requirements.
+ Executing under the x32 psABI enables user programs to utilize CPU
+ and system resources more efficiently while keeping the memory
+ footprint of the applications low.
+ Extra bits are used for registers but not for addressing mechanisms.
+ </para>
+
+ <para>
+ The Yocto Project supports the final specifications of x32 psABI
+ as follows:
+ <itemizedlist>
+ <listitem><para>
+ You can create packages and images in x32 psABI format on
+ x86_64 architecture targets.
+ </para></listitem>
+ <listitem><para>
+ You can successfully build recipes with the x32 toolchain.
+ </para></listitem>
+ <listitem><para>
+ You can create and boot
+ <filename>core-image-minimal</filename> and
+ <filename>core-image-sato</filename> images.
+ </para></listitem>
+ <listitem><para>
+ RPM Package Manager (RPM) support exists for x32 binaries.
+ </para></listitem>
+ <listitem><para>
+ Support for large images exists.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To use the x32 psABI, you need to edit your
+ <filename>conf/local.conf</filename> configuration file as
+ follows:
+ <literallayout class='monospaced'>
+ MACHINE = "qemux86-64"
+ DEFAULTTUNE = "x86-64-x32"
+ baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
+ or 'INVALID'), True) or 'lib'}"
+ </literallayout>
+ Once you have set up your configuration file, use BitBake to
+ build an image that supports the x32 psABI.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-sato
+ </literallayout>
+ </para>
+ </section>
+
<section id='enabling-gobject-introspection-support'>
<title>Enabling GObject Introspection Support</title>
@@ -4795,8 +7053,7 @@
variable.
</para></listitem>
<listitem><para>
- Set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink>
+ Set the <filename>EXTERNAL_TOOLCHAIN</filename>
variable in your <filename>local.conf</filename> file
to the location in which you installed the toolchain.
</para></listitem>
@@ -4846,7 +7103,7 @@
system.
<note>
For a kickstart file reference, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#openembedded-kickstart-wks-reference'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</ulink>"
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</ulink>"
Chapter in the Yocto Project Reference Manual.
</note>
</para>
@@ -4858,16 +7115,17 @@
customized images, and as such, was designed to be
completely extensible through a plug-in interface.
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>"
- section in the Yocto Project Reference Manual for information
- on these plug-ins.
+ "<link linkend='wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</link>"
+ section for information on these plug-ins.
</para>
<para>
This section provides some background information on Wic,
describes what you need to have in
place to run the tool, provides instruction on how to use
- the Wic utility, and provides several examples.
+ the Wic utility, provides information on using the Wic plug-ins
+ interface, and provides several examples that show how to use
+ Wic.
</para>
<section id='wic-background'>
@@ -4899,7 +7157,7 @@
Wic is a completely independent
standalone utility that initially provides
easier-to-use and more flexible replacements for an
- existing functionality in OE Core's
+ existing functionality in OE-Core's
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
class and <filename>mkefidisk.sh</filename> script.
The difference between
@@ -4988,6 +7246,7 @@
<literallayout class='monospaced'>
$ wic -h
$ wic --help
+ $ wic help
</literallayout>
</para>
@@ -4997,51 +7256,66 @@
<filename>help</filename>, <filename>list</filename>,
<filename>ls</filename>, <filename>rm</filename>, and
<filename>write</filename>.
- You can get help for these commands as follows with
- <replaceable>command</replaceable> being one of the
- supported commands:
+ You can get help for all these commands except "help" by
+ using the following form:
<literallayout class='monospaced'>
$ wic help <replaceable>command</replaceable>
</literallayout>
- </para>
-
- <para>
- You can also get detailed help on a number of topics
- from the help system.
- The output of <filename>wic --help</filename>
- displays a list of available help
- topics under a "Help topics" heading.
- You can have the help system display the help text for
- a given topic by prefacing the topic with
- <filename>wic help</filename>:
+ For example, the following command returns help for the
+ <filename>write</filename> command:
<literallayout class='monospaced'>
- $ wic help <replaceable>help_topic</replaceable>
+ $ wic help write
</literallayout>
</para>
<para>
- You can find out more about the images Wic creates using
- the existing kickstart files with the following form of
- the command:
+ Wic supports help for three topics:
+ <filename>overview</filename>,
+ <filename>plugins</filename>, and
+ <filename>kickstart</filename>.
+ You can get help for any topic using the following form:
<literallayout class='monospaced'>
- $ wic list <replaceable>image</replaceable> help
+ $ wic help <replaceable>topic</replaceable>
</literallayout>
- For <replaceable>image</replaceable>, you can provide
- any of the following:
+ For example, the following returns overview help for Wic:
<literallayout class='monospaced'>
- beaglebone
- mpc8315e-rdb
- genericx86
- edgerouter
- qemux86-directdisk
- directdisk-gpt
- mkefidisk
- directdisk
- systemd-bootdisk
- mkhybridiso
- sdimage-bootpart
- directdisk-multi-rootfs
- directdisk-bootloader-config
+ $ wic help overview
+ </literallayout>
+ </para>
+
+ <para>
+ One additional level of help exists for Wic.
+ You can get help on individual images through the
+ <filename>list</filename> command.
+ You can use the <filename>list</filename> command to return the
+ available Wic images as follows:
+ <literallayout class='monospaced'>
+ $ wic list images
+ mpc8315e-rdb Create SD card image for MPC8315E-RDB
+ genericx86 Create an EFI disk image for genericx86*
+ beaglebone-yocto Create SD card image for Beaglebone
+ edgerouter Create SD card image for Edgerouter
+ qemux86-directdisk Create a qemu machine 'pcbios' direct disk image
+ directdisk-gpt Create a 'pcbios' direct disk image
+ mkefidisk Create an EFI disk image
+ directdisk Create a 'pcbios' direct disk image
+ systemd-bootdisk Create an EFI disk image with systemd-boot
+ mkhybridiso Create a hybrid ISO image
+ sdimage-bootpart Create SD card image with a boot partition
+ directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
+ directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
+ </literallayout>
+ Once you know the list of available Wic images, you can use
+ <filename>help</filename> with the command to get help on a
+ particular image.
+ For example, the following command returns help on the
+ "beaglebone-yocto" image:
+ <literallayout class='monospaced'>
+ $ wic list beaglebone-yocto help
+
+
+ Creates a partitioned SD card image for Beaglebone.
+ Boot files are located in the first vfat partition.
</literallayout>
</para>
</section>
@@ -5058,7 +7332,7 @@
<listitem><para>
<emphasis>Raw Mode:</emphasis>
You explicitly specify build artifacts through
- <filename>wic</filename> command-line arguments.
+ Wic command-line arguments.
</para></listitem>
<listitem><para>
<emphasis>Cooked Mode:</emphasis>
@@ -5153,7 +7427,7 @@
<para>
Running Wic in cooked mode leverages off artifacts in
- Build Directory.
+ the Build Directory.
In other words, you do not have to specify kernel or
root filesystem locations as part of the command.
All you need to provide is a kickstart file and the
@@ -5195,7 +7469,7 @@
can use an existing file provided by the Wic installation.
As shipped, kickstart files can be found in the
Yocto Project
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
in the following two locations:
<literallayout class='monospaced'>
poky/meta-yocto-bsp/wic
@@ -5205,9 +7479,9 @@
files:
<literallayout class='monospaced'>
$ wic list images
- beaglebone Create SD card image for Beaglebone
mpc8315e-rdb Create SD card image for MPC8315E-RDB
genericx86 Create an EFI disk image for genericx86*
+ beaglebone-yocto Create SD card image for Beaglebone
edgerouter Create SD card image for Edgerouter
qemux86-directdisk Create a qemu machine 'pcbios' direct disk image
directdisk-gpt Create a 'pcbios' direct disk image
@@ -5245,6 +7519,209 @@
</para>
</section>
+ <section id='wic-using-the-wic-plug-ins-interface'>
+ <title>Using the Wic Plug-Ins Interface</title>
+
+ <para>
+ You can extend and specialize Wic functionality by using
+ Wic plug-ins.
+ This section explains the Wic plug-in interface.
+ <note>
+ Wic plug-ins consist of "source" and "imager" plug-ins.
+ Imager plug-ins are beyond the scope of this section.
+ </note>
+ </para>
+
+ <para>
+ Source plug-ins provide a mechanism to customize partition
+ content during the Wic image generation process.
+ You can use source plug-ins to map values that you specify
+ using <filename>--source</filename> commands in kickstart
+ files (i.e. <filename>*.wks</filename>) to a plug-in
+ implementation used to populate a given partition.
+ <note>
+ If you use plug-ins that have build-time dependencies
+ (e.g. native tools, bootloaders, and so forth)
+ when building a Wic image, you need to specify those
+ dependencies using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink>
+ variable.
+ </note>
+ </para>
+
+ <para>
+ Source plug-ins are subclasses defined in plug-in files.
+ As shipped, the Yocto Project provides several plug-in
+ files.
+ You can see the source plug-in files that ship with the
+ Yocto Project
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
+ Each of these plug-in files contains source plug-ins that
+ are designed to populate a specific Wic image partition.
+ </para>
+
+ <para>
+ Source plug-ins are subclasses of the
+ <filename>SourcePlugin</filename> class, which is
+ defined in the
+ <filename>poky/scripts/lib/wic/pluginbase.py</filename>
+ file.
+ For example, the <filename>BootimgEFIPlugin</filename>
+ source plug-in found in the
+ <filename>bootimg-efi.py</filename> file is a subclass of
+ the <filename>SourcePlugin</filename> class, which is found
+ in the <filename>pluginbase.py</filename> file.
+ </para>
+
+ <para>
+ You can also implement source plug-ins in a layer outside
+ of the Source Repositories (external layer).
+ To do so, be sure that your plug-in files are located in
+ a directory whose path is
+ <filename>scripts/lib/wic/plugins/source/</filename>
+ within your external layer.
+ When the plug-in files are located there, the source
+ plug-ins they contain are made available to Wic.
+ </para>
+
+ <para>
+ When the Wic implementation needs to invoke a
+ partition-specific implementation, it looks for the plug-in
+ with the same name as the <filename>--source</filename>
+ parameter used in the kickstart file given to that
+ partition.
+ For example, if the partition is set up using the following
+ command in a kickstart file:
+ <literallayout class='monospaced'>
+ part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
+ </literallayout>
+ The methods defined as class members of the matching
+ source plug-in (i.e. <filename>bootimg-pcbios</filename>)
+ in the <filename>bootimg-pcbios.py</filename> plug-in file
+ are used.
+ </para>
+
+ <para>
+ To be more concrete, here is the corresponding plug-in
+ definition from the <filename>bootimg-pcbios.py</filename>
+ file for the previous command along with an example
+ method called by the Wic implementation when it needs to
+ prepare a partition using an implementation-specific
+ function:
+ <literallayout class='monospaced'>
+ .
+ .
+ .
+ class BootimgPcbiosPlugin(SourcePlugin):
+ """
+ Create MBR boot partition and install syslinux on it.
+ """
+
+ name = 'bootimg-pcbios'
+ .
+ .
+ .
+ @classmethod
+ def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
+ oe_builddir, bootimg_dir, kernel_dir,
+ rootfs_dir, native_sysroot):
+ """
+ Called to do the actual content population for a partition i.e. it
+ 'prepares' the partition to be incorporated into the image.
+ In this case, prepare content for legacy bios boot partition.
+ """
+ .
+ .
+ .
+ </literallayout>
+ If a subclass (plug-in) itself does not implement a
+ particular function, Wic locates and uses the default
+ version in the superclass.
+ It is for this reason that all source plug-ins are derived
+ from the <filename>SourcePlugin</filename> class.
+ </para>
+
+ <para>
+ The <filename>SourcePlugin</filename> class defined in
+ the <filename>pluginbase.py</filename> file defines
+ a set of methods that source plug-ins can implement or
+ override.
+ Any plug-ins (subclass of
+ <filename>SourcePlugin</filename>) that do not implement
+ a particular method inherit the implementation of the
+ method from the <filename>SourcePlugin</filename> class.
+ For more information, see the
+ <filename>SourcePlugin</filename> class in the
+ <filename>pluginbase.py</filename> file for details:
+ </para>
+
+ <para>
+ The following list describes the methods implemented in the
+ <filename>SourcePlugin</filename> class:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
+ Called to populate a partition with actual content.
+ In other words, the method prepares the final
+ partition image that is incorporated into the
+ disk image.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_configure_partition()</filename>:</emphasis>
+ Called before
+ <filename>do_prepare_partition()</filename> to
+ create custom configuration files for a partition
+ (e.g. syslinux or grub configuration files).
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_install_disk()</filename>:</emphasis>
+ Called after all partitions have been prepared and
+ assembled into a disk image.
+ This method provides a hook to allow finalization
+ of a disk image (e.g. writing an MBR).
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_stage_partition()</filename>:</emphasis>
+ Special content-staging hook called before
+ <filename>do_prepare_partition()</filename>.
+ This method is normally empty.</para>
+
+ <para>Typically, a partition just uses the passed-in
+ parameters (e.g. the unmodified value of
+ <filename>bootimg_dir</filename>).
+ However, in some cases, things might need to be
+ more tailored.
+ As an example, certain files might additionally
+ need to be taken from
+ <filename>bootimg_dir + /boot</filename>.
+ This hook allows those files to be staged in a
+ customized fashion.
+ <note>
+ <filename>get_bitbake_var()</filename>
+ allows you to access non-standard variables
+ that you might want to use for this
+ behavior.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ You can extend the source plug-in mechanism.
+ To add more hooks, create more source plug-in methods
+ within <filename>SourcePlugin</filename> and the
+ corresponding derived subclasses.
+ The code that calls the plug-in methods uses the
+ <filename>plugin.get_source_plugin_methods()</filename>
+ function to find the method or methods needed by the call.
+ Retrieval of those methods is accomplished by filling up
+ a dict with keys that contain the method names of interest.
+ On success, these will be filled in with the actual
+ methods.
+ See the Wic implementation for examples and details.
+ </para>
+ </section>
+
<section id='wic-usage-examples'>
<title>Examples</title>
@@ -5271,16 +7748,16 @@
.
.
INFO: The new image(s) can be found here:
- ./mkefidisk-201710061409-sda.direct
+ ./mkefidisk-201804191017-sda.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.r4hkds0b/rootfs_copy
- BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
- NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks
+ /home/stephano/build/master/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks
</literallayout>
The previous example shows the easiest way to create
an image by running in cooked mode and supplying
@@ -5305,17 +7782,18 @@
<para>
Continuing with the example, you can now write the
- image to a USB stick, or whatever media for which you
- built your image, and boot from the media.
+ image from the Build Directory onto a USB stick, or
+ whatever media for which you built your image, and boot
+ from the media.
You can write the image by using
<filename>bmaptool</filename> or
<filename>dd</filename>:
<literallayout class='monospaced'>
- $ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sd<replaceable>X</replaceable>
+ $ oe-run-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sd<replaceable>X</replaceable>
</literallayout>
or
<literallayout class='monospaced'>
- $ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sd<replaceable>X</replaceable>
+ $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sd<replaceable>X</replaceable>
</literallayout>
<note>
For more information on how to use the
@@ -5375,8 +7853,8 @@
directory and then by changing the lines that specify
the target disk from which to boot.
<literallayout class='monospaced'>
- $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
- /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
+ $ cp /home/stephano/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
+ /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
</literallayout>
Next, the example modifies the
<filename>directdisksdb-gpt.wks</filename> file and
@@ -5412,13 +7890,13 @@
./directdisksdb-gpt-201710090938-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.hk3wl6zn/rootfs_copy
- BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
- NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
+ /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
</literallayout>
Continuing with the example, you can now directly
<filename>dd</filename> the image to a USB stick, or
@@ -5445,25 +7923,25 @@
somewhere other than the default output directory,
which is the current directory:
<literallayout class='monospaced'>
- $ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \
- --rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
- --bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
- --kernel-dir /home/scottrif/poky/build/tmp/deploy/images/qemux86 \
- --native-sysroot /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ $ wic create /home/stephano/my_yocto/test.wks -o /home/stephano/testwic \
+ --rootfs-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
+ --bootimg-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
+ --kernel-dir /home/stephano/build/master/build/tmp/deploy/images/qemux86 \
+ --native-sysroot /home/stephano/build/master/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: Creating image(s)...
INFO: The new image(s) can be found here:
- /home/scottrif/testwic/test-201710091445-sdb.direct
+ /home/stephano/testwic/test-201710091445-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/scottrif/testwic/tmp.wic.x4wipbmb/rootfs_copy
- BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
- NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/scottrif/my_yocto/test.wks
+ /home/stephano/my_yocto/test.wks
</literallayout>
For this example,
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
@@ -5608,222 +8086,91 @@
</section>
</section>
- <section id='building-an-initramfs-image'>
- <title>Building an Initial RAM Filesystem (initramfs) Image</title>
-
- <para>
- An initial RAM filesystem (initramfs) image provides a temporary
- root filesystem used for early system initialization (e.g.
- loading of modules needed to locate and mount the "real" root
- filesystem).
- <note>
- The initramfs image is the successor of initial RAM disk
- (initrd).
- It is a "copy in and out" (cpio) archive of the initial
- filesystem that gets loaded into memory during the Linux
- startup process.
- Because Linux uses the contents of the archive during
- initialization, the initramfs image needs to contain all of the
- device drivers and tools needed to mount the final root
- filesystem.
- </note>
- </para>
-
- <para>
- Follow these steps to create an initramfs image:
- <orderedlist>
- <listitem><para>
- <emphasis>Create the initramfs Image Recipe:</emphasis>
- You can reference the
- <filename>core-image-minimal-initramfs.bb</filename>
- recipe found in the <filename>meta/recipes-core</filename>
- directory of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- as an example from which to work.
- </para></listitem>
- <listitem><para>
- <emphasis>Decide if You Need to Bundle the initramfs Image
- Into the Kernel Image:</emphasis>
- If you want the initramfs image that is built to be
- bundled in with the kernel image, set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
- variable to "1" in your <filename>local.conf</filename>
- configuration file and set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
- variable in the recipe that builds the kernel image.
- <note><title>Tip</title>
- It is recommended that you do bundle the initramfs
- image with the kernel image to avoid circular
- dependencies between the kernel recipe and the
- initramfs recipe should the initramfs image
- include kernel modules.
- </note>
- Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
- flag causes the initramfs image to be unpacked
- into the <filename>${B}/usr/</filename> directory.
- The unpacked initramfs image is then passed to the kernel's
- <filename>Makefile</filename> using the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
- variable, allowing the initramfs image to be built into
- the kernel normally.
- <note>
- If you choose to not bundle the initramfs image with
- the kernel image, you are essentially using an
- <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
- Creating an initrd is handled primarily through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
- <filename>INITRD_LIVE</filename>, and
- <filename>INITRD_IMAGE_LIVE</filename> variables.
- For more information, see the
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
- file.
- </note>
- </para></listitem>
-<!--
-Some notes from Cal:
-
- A non-bundled initramfs is essentially an initrd, which I am discovering
- to be rather confusingly supported in OE at the moment.
-
- Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
- variables. INITRD_IMAGE* is the primary image target, which gets added to
- INITRD*, which is a list of cpio filesystems. You can add more cpio
- filesystems to the INITRD variable to add more to the initrd. For
- instance, meta-intel adds intel-microcode via the following:
-
- INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
-
- If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
-
- INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
-
- Unfortunately you need the full path, and its up to you to sort out
- dependencies as well. For instance, we have the following:
-
- MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
-
- which resolves to:
-
- MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
-
- However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
- another beast entirely, with current wic kickstart files not supporting
- initrds, and only partial support in the source plugins. That being said,
- I know the generic bootfs work Ed is working on will help immensely in this
- aspect. He or Saul can provide more details here.
-
- Anyhow, its rather fractured and confusing and could probably use a
- rework honestly. I don't know how feasible it is to document all the
- details and corner cases of this area.
--->
- <listitem><para>
- <emphasis>Optionally Add Items to the initramfs Image
- Through the initramfs Image Recipe:</emphasis>
- If you add items to the initramfs image by way of its
- recipe, you should use
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
- rather than
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
- <filename>PACKAGE_INSTALL</filename> gives more direct
- control of what is added to the image as compared to
- the defaults you might not necessarily want that are
- set by the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
- classes.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Kernel Image and the initramfs
- Image:</emphasis>
- Build your kernel image using BitBake.
- Because the initramfs image recipe is a dependency of the
- kernel image, the initramfs image is built as well and
- bundled with the kernel image if you used the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
- variable described earlier.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
<section id='flashing-images-using-bmaptool'>
<title>Flashing Images Using <filename>bmaptool</filename></title>
<para>
- An easy way to flash an image to a bootable device is to use
- <filename>bmaptool</filename>, which is integrated into the
- OpenEmbedded build system.
+ A fast and easy way to flash an image to a bootable device
+ is to use Bmaptool, which is integrated into the OpenEmbedded
+ build system.
+ Bmaptool is a generic tool that creates a file's block map (bmap)
+ and then uses that map to copy the file.
+ As compared to traditional tools such as dd or cp, Bmaptool
+ can copy (or flash) large files like raw system image files
+ much faster.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ If you are using Ubuntu or Debian distributions, you
+ can install the <filename>bmap-tools</filename> package
+ using the following command and then use the tool
+ without specifying <filename>PATH</filename> even from
+ the root account:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install bmap-tools
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If you are unable to install the
+ <filename>bmap-tools</filename> package, you will
+ need to build Bmaptool before using it.
+ Use the following command:
+ <literallayout class='monospaced'>
+ $ bitbake bmap-tools-native
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </note>
</para>
<para>
Following, is an example that shows how to flash a Wic image.
- <note>
- You can use <filename>bmaptool</filename> to flash any
- type of image.
- </note>
- Use these steps to flash an image using
- <filename>bmaptool</filename>:
- <note>
- Unless you are able to install the
- <filename>bmap-tools</filename> package as mentioned in the note
- in the second bullet of step 3 further down, you will need to build
- <filename>bmaptool</filename> before using it.
- Build the tool using the following command:
- <literallayout class='monospaced'>
- $ bitbake bmap-tools-native
- </literallayout>
- </note>
+ Realize that while this example uses a Wic image, you can use
+ Bmaptool to flash any type of image.
+ Use these steps to flash an image using Bmaptool:
<orderedlist>
<listitem><para>
- <emphasis>Update the <filename>local.conf</filename> File:</emphasis>
- Add the following to your <filename>local.conf</filename>
- file:
+ <emphasis>Update your <filename>local.conf</filename> File:</emphasis>
+ You need to have the following set in your
+ <filename>local.conf</filename> file before building
+ your image:
<literallayout class='monospaced'>
IMAGE_FSTYPES += "wic wic.bmap"
</literallayout>
</para></listitem>
<listitem><para>
<emphasis>Get Your Image:</emphasis>
- Either have your image ready (pre-built) or take the step
- build the image:
+ Either have your image ready (pre-built with the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
+ setting previously mentioned) or take the step to build
+ the image:
<literallayout class='monospaced'>
$ bitbake <replaceable>image</replaceable>
</literallayout>
</para></listitem>
<listitem><para>
<emphasis>Flash the Device:</emphasis>
- Flash the device with the image by using
- <filename>bmaptool</filename> depending on your particular
- setup:
+ Flash the device with the image by using Bmaptool
+ depending on your particular setup.
+ The following commands assume the image resides in the
+ Build Directory's <filename>deploy/images/</filename>
+ area:
<itemizedlist>
<listitem><para>
- If you have write access to the media,
- use this command form:
+ If you have write access to the media, use this
+ command form:
<literallayout class='monospaced'>
- $ oe-run-native bmap-tools-native bmaptool copy ./tmp/deploy/images/qemux86-64-core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
+ $ oe-run-native bmap-tools-native bmaptool copy <replaceable>build-directory</replaceable>/tmp/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.wic /dev/sd<replaceable>X</replaceable>
</literallayout>
</para></listitem>
<listitem><para>
- If you do not have write access to
- the media, use the following
- commands:
+ If you do not have write access to the media, set
+ your permissions first and then use the same
+ command form:
<literallayout class='monospaced'>
$ sudo chmod 666 /dev/sd<replaceable>X</replaceable>
- $ oe-run-native bmap-tools-native bmaptool copy ./tmp/deploy/images/qemux86-64-core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
+ $ oe-run-native bmap-tools-native bmaptool copy <replaceable>build-directory</replaceable>/tmp/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.wic /dev/sd<replaceable>X</replaceable>
</literallayout>
- <note>
- If you are using Ubuntu or Debian distributions,
- you can install the
- <filename>bmap-tools</filename> package using
- the following command and then use the tool
- without specifying
- <filename>PATH</filename> even from the
- root account:
- <literallayout class='monospaced'>
- $ sudo apt-get install bmap-tools
- </literallayout>
- </note>
</para></listitem>
</itemizedlist>
</para></listitem>
@@ -5852,7 +8199,7 @@
by Bruce Schneier
</para></listitem>
<listitem><para><emphasis>
- "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis>
+ "<ulink url='http://census2012.sourceforge.net/paper.html'>Internet Census 2012</ulink>"</emphasis>
by Carna Botnet</para></listitem>
<listitem><para><emphasis>
"<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis>
@@ -6060,7 +8407,7 @@
more secure.
You can find these tools in the
<filename>meta-security</filename> layer of the
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
+ <ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>.
</para>
</section>
</section>
@@ -6308,616 +8655,22 @@
</para>
</section>
- <section id='building-a-tiny-system'>
- <title>Building a Tiny System</title>
+ <section id='dev-saving-memory-during-a-build'>
+ <title>Conserving Disk Space During Builds</title>
<para>
- Very small distributions have some significant advantages such
- as requiring less on-die or in-package memory (cheaper), better
- performance through efficient cache usage, lower power requirements
- due to less memory, faster boot times, and reduced development
- overhead.
- Some real-world examples where a very small distribution gives
- you distinct advantages are digital cameras, medical devices,
- and small headless systems.
- </para>
-
- <para>
- This section presents information that shows you how you can
- trim your distribution to even smaller sizes than the
- <filename>poky-tiny</filename> distribution, which is around
- 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
- </para>
-
- <section id='tiny-system-overview'>
- <title>Overview</title>
-
- <para>
- The following list presents the overall steps you need to
- consider and perform to create distributions with smaller
- root filesystems, achieve faster boot times, maintain your critical
- functionality, and avoid initial RAM disks:
- <itemizedlist>
- <listitem><para>
- <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='iterate-on-the-process'>Iterate on the process.</link>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='goals-and-guiding-principles'>
- <title>Goals and Guiding Principles</title>
-
- <para>
- Before you can reach your destination, you need to know
- where you are going.
- Here is an example list that you can use as a guide when
- creating very small distributions:
- <itemizedlist>
- <listitem><para>Determine how much space you need
- (e.g. a kernel that is 1 Mbyte or less and
- a root filesystem that is 3 Mbytes or less).
- </para></listitem>
- <listitem><para>Find the areas that are currently
- taking 90% of the space and concentrate on reducing
- those areas.
- </para></listitem>
- <listitem><para>Do not create any difficult "hacks"
- to achieve your goals.</para></listitem>
- <listitem><para>Leverage the device-specific
- options.</para></listitem>
- <listitem><para>Work in a separate layer so that you
- keep changes isolated.
- For information on how to create layers, see
- the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='understand-what-gives-your-image-size'>
- <title>Understand What Contributes to Your Image Size</title>
-
- <para>
- It is easiest to have something to start with when creating
- your own distribution.
- You can use the Yocto Project out-of-the-box to create the
- <filename>poky-tiny</filename> distribution.
- Ultimately, you will want to make changes in your own
- distribution that are likely modeled after
- <filename>poky-tiny</filename>.
- <note>
- To use <filename>poky-tiny</filename> in your build,
- set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
- variable in your
- <filename>local.conf</filename> file to "poky-tiny"
- as described in the
- "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
- section.
- </note>
- </para>
-
- <para>
- Understanding some memory concepts will help you reduce the
- system size.
- Memory consists of static, dynamic, and temporary memory.
- Static memory is the TEXT (code), DATA (initialized data
- in the code), and BSS (uninitialized data) sections.
- Dynamic memory represents memory that is allocated at runtime:
- stacks, hash tables, and so forth.
- Temporary memory is recovered after the boot process.
- This memory consists of memory used for decompressing
- the kernel and for the <filename>__init__</filename>
- functions.
- </para>
-
- <para>
- To help you see where you currently are with kernel and root
- filesystem sizes, you can use two tools found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in
- the <filename>scripts/tiny/</filename> directory:
- <itemizedlist>
- <listitem><para><filename>ksize.py</filename>: Reports
- component sizes for the kernel build objects.
- </para></listitem>
- <listitem><para><filename>dirsize.py</filename>: Reports
- component sizes for the root filesystem.</para></listitem>
- </itemizedlist>
- This next tool and command help you organize configuration
- fragments and view file dependencies in a human-readable form:
- <itemizedlist>
- <listitem><para><filename>merge_config.sh</filename>:
- Helps you manage configuration files and fragments
- within the kernel.
- With this tool, you can merge individual configuration
- fragments together.
- The tool allows you to make overrides and warns you
- of any missing configuration options.
- The tool is ideal for allowing you to iterate on
- configurations, create minimal configurations, and
- create configuration files for different machines
- without having to duplicate your process.</para>
- <para>The <filename>merge_config.sh</filename> script is
- part of the Linux Yocto kernel Git repositories
- (i.e. <filename>linux-yocto-3.14</filename>,
- <filename>linux-yocto-3.10</filename>,
- <filename>linux-yocto-3.8</filename>, and so forth)
- in the
- <filename>scripts/kconfig</filename> directory.</para>
- <para>For more information on configuration fragments,
- see the
- "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
- section in the Yocto Project Linux Kernel Development
- Manual.
- </para></listitem>
- <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>:
- Using the BitBake command with these options brings up
- a Dependency Explorer from which you can view file
- dependencies.
- Understanding these dependencies allows you to make
- informed decisions when cutting out various pieces of the
- kernel and root filesystem.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='trim-the-root-filesystem'>
- <title>Trim the Root Filesystem</title>
-
- <para>
- The root filesystem is made up of packages for booting,
- libraries, and applications.
- To change things, you can configure how the packaging happens,
- which changes the way you build them.
- You can also modify the filesystem itself or select a different
- filesystem.
- </para>
-
- <para>
- First, find out what is hogging your root filesystem by running the
- <filename>dirsize.py</filename> script from your root directory:
- <literallayout class='monospaced'>
- $ cd <replaceable>root-directory-of-image</replaceable>
- $ dirsize.py 100000 > dirsize-100k.log
- $ cat dirsize-100k.log
- </literallayout>
- You can apply a filter to the script to ignore files under
- a certain size.
- The previous example filters out any files below 100 Kbytes.
- The sizes reported by the tool are uncompressed, and thus
- will be smaller by a relatively constant factor in a
- compressed root filesystem.
- When you examine your log file, you can focus on areas of the
- root filesystem that take up large amounts of memory.
- </para>
-
- <para>
- You need to be sure that what you eliminate does not cripple
- the functionality you need.
- One way to see how packages relate to each other is by using
- the Dependency Explorer UI with the BitBake command:
- <literallayout class='monospaced'>
- $ cd <replaceable>image-directory</replaceable>
- $ bitbake -u taskexp -g <replaceable>image</replaceable>
- </literallayout>
- Use the interface to select potential packages you wish to
- eliminate and see their dependency relationships.
- </para>
-
- <para>
- When deciding how to reduce the size, get rid of packages that
- result in minimal impact on the feature set.
- For example, you might not need a VGA display.
- Or, you might be able to get by with <filename>devtmpfs</filename>
- and <filename>mdev</filename> instead of
- <filename>udev</filename>.
- </para>
-
- <para>
- Use your <filename>local.conf</filename> file to make changes.
- For example, to eliminate <filename>udev</filename> and
- <filename>glib</filename>, set the following in the
- local configuration file:
- <literallayout class='monospaced'>
- VIRTUAL-RUNTIME_dev_manager = ""
- </literallayout>
- </para>
-
- <para>
- Finally, you should consider exactly the type of root
- filesystem you need to meet your needs while also reducing
- its size.
- For example, consider <filename>cramfs</filename>,
- <filename>squashfs</filename>, <filename>ubifs</filename>,
- <filename>ext2</filename>, or an <filename>initramfs</filename>
- using <filename>initramfs</filename>.
- Be aware that <filename>ext3</filename> requires a 1 Mbyte
- journal.
- If you are okay with running read-only, you do not need this
- journal.
- </para>
-
- <note>
- After each round of elimination, you need to rebuild your
- system and then use the tools to see the effects of your
- reductions.
- </note>
-
-
- </section>
-
- <section id='trim-the-kernel'>
- <title>Trim the Kernel</title>
-
- <para>
- The kernel is built by including policies for hardware-independent
- aspects.
- What subsystems do you enable?
- For what architecture are you building?
- Which drivers do you build by default?
- <note>You can modify the kernel source if you want to help
- with boot time.
- </note>
- </para>
-
- <para>
- Run the <filename>ksize.py</filename> script from the top-level
- Linux build directory to get an idea of what is making up
- the kernel:
- <literallayout class='monospaced'>
- $ cd <replaceable>top-level-linux-build-directory</replaceable>
- $ ksize.py > ksize.log
- $ cat ksize.log
- </literallayout>
- When you examine the log, you will see how much space is
- taken up with the built-in <filename>.o</filename> files for
- drivers, networking, core kernel files, filesystem, sound,
- and so forth.
- The sizes reported by the tool are uncompressed, and thus
- will be smaller by a relatively constant factor in a compressed
- kernel image.
- Look to reduce the areas that are large and taking up around
- the "90% rule."
- </para>
-
- <para>
- To examine, or drill down, into any particular area, use the
- <filename>-d</filename> option with the script:
- <literallayout class='monospaced'>
- $ ksize.py -d > ksize.log
- </literallayout>
- Using this option breaks out the individual file information
- for each area of the kernel (e.g. drivers, networking, and
- so forth).
- </para>
-
- <para>
- Use your log file to see what you can eliminate from the kernel
- based on features you can let go.
- For example, if you are not going to need sound, you do not
- need any drivers that support sound.
- </para>
-
- <para>
- After figuring out what to eliminate, you need to reconfigure
- the kernel to reflect those changes during the next build.
- You could run <filename>menuconfig</filename> and make all your
- changes at once.
- However, that makes it difficult to see the effects of your
- individual eliminations and also makes it difficult to replicate
- the changes for perhaps another target device.
- A better method is to start with no configurations using
- <filename>allnoconfig</filename>, create configuration
- fragments for individual changes, and then manage the
- fragments into a single configuration file using
- <filename>merge_config.sh</filename>.
- The tool makes it easy for you to iterate using the
- configuration change and build cycle.
- </para>
-
- <para>
- Each time you make configuration changes, you need to rebuild
- the kernel and check to see what impact your changes had on
- the overall size.
- </para>
- </section>
-
- <section id='remove-package-management-requirements'>
- <title>Remove Package Management Requirements</title>
-
- <para>
- Packaging requirements add size to the image.
- One way to reduce the size of the image is to remove all the
- packaging requirements from the image.
- This reduction includes both removing the package manager
- and its unique dependencies as well as removing the package
- management data itself.
- </para>
-
- <para>
- To eliminate all the packaging requirements for an image,
- be sure that "package-management" is not part of your
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
- statement for the image.
- When you remove this feature, you are removing the package
- manager as well as its dependencies from the root filesystem.
- </para>
- </section>
-
- <section id='look-for-other-ways-to-minimize-size'>
- <title>Look for Other Ways to Minimize Size</title>
-
- <para>
- Depending on your particular circumstances, other areas that you
- can trim likely exist.
- The key to finding these areas is through tools and methods
- described here combined with experimentation and iteration.
- Here are a couple of areas to experiment with:
- <itemizedlist>
- <listitem><para><filename>glibc</filename>:
- In general, follow this process:
- <orderedlist>
- <listitem><para>Remove <filename>glibc</filename>
- features from
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
- that you think you do not need.</para></listitem>
- <listitem><para>Build your distribution.
- </para></listitem>
- <listitem><para>If the build fails due to missing
- symbols in a package, determine if you can
- reconfigure the package to not need those
- features.
- For example, change the configuration to not
- support wide character support as is done for
- <filename>ncurses</filename>.
- Or, if support for those characters is needed,
- determine what <filename>glibc</filename>
- features provide the support and restore the
- configuration.
- </para></listitem>
- <listitem><para>Rebuild and repeat the process.
- </para></listitem>
- </orderedlist></para></listitem>
- <listitem><para><filename>busybox</filename>:
- For BusyBox, use a process similar as described for
- <filename>glibc</filename>.
- A difference is you will need to boot the resulting
- system to see if you are able to do everything you
- expect from the running system.
- You need to be sure to integrate configuration fragments
- into Busybox because BusyBox handles its own core
- features and then allows you to add configuration
- fragments on top.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='iterate-on-the-process'>
- <title>Iterate on the Process</title>
-
- <para>
- If you have not reached your goals on system size, you need
- to iterate on the process.
- The process is the same.
- Use the tools and see just what is taking up 90% of the root
- filesystem and the kernel.
- Decide what you can eliminate without limiting your device
- beyond what you need.
- </para>
-
- <para>
- Depending on your system, a good place to look might be
- Busybox, which provides a stripped down
- version of Unix tools in a single, executable file.
- You might be able to drop virtual terminal services or perhaps
- ipv6.
- </para>
- </section>
- </section>
-
- <section id='building-images-for-more-than-one-machine'>
- <title>Building Images for More than One Machine</title>
-
- <para>
- A common scenario developers face is creating images for several
- different machines that use the same software environment.
- In this situation, it is tempting to set the
- tunings and optimization flags for each build specifically for
- the targeted hardware (i.e. "maxing out" the tunings).
- Doing so can considerably add to build times and package feed
- maintenance collectively for the machines.
- For example, selecting tunes that are extremely specific to a
- CPU core used in a system might enable some micro optimizations
- in GCC for that particular system but would otherwise not gain
- you much of a performance difference across the other systems
- as compared to using a more general tuning across all the builds
- (e.g. setting
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
- specifically for each machine's build).
- Rather than "max out" each build's tunings, you can take steps that
- cause the OpenEmbedded build system to reuse software across the
- various machines where it makes sense.
- </para>
- <para>
- If build speed and package feed maintenance are considerations,
- you should consider the points in this section that can help you
- optimize your tunings to best consider build times and package
- feed maintenance.
- <itemizedlist>
- <listitem><para><emphasis>Share the Build Directory:</emphasis>
- If at all possible, share the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
- across builds.
- The Yocto Project supports switching between different
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- values in the same <filename>TMPDIR</filename>.
- This practice is well supported and regularly used by
- developers when building for multiple machines.
- When you use the same <filename>TMPDIR</filename> for
- multiple machine builds, the OpenEmbedded build system can
- reuse the existing native and often cross-recipes for
- multiple machines.
- Thus, build time decreases.
- <note>
- If
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
- settings change or fundamental configuration settings
- such as the filesystem layout, you need to work with
- a clean <filename>TMPDIR</filename>.
- Sharing <filename>TMPDIR</filename> under these
- circumstances might work but since it is not
- guaranteed, you should use a clean
- <filename>TMPDIR</filename>.
- </note>
- </para></listitem>
- <listitem><para><emphasis>Enable the Appropriate Package Architecture:</emphasis>
- By default, the OpenEmbedded build system enables three
- levels of package architectures: "all", "tune" or "package",
- and "machine".
- Any given recipe usually selects one of these package
- architectures (types) for its output.
- Depending for what a given recipe creates packages, making
- sure you enable the appropriate package architecture can
- directly impact the build time.</para>
- <para>A recipe that just generates scripts can enable
- "all" architecture because there are no binaries to build.
- To specifically enable "all" architecture, be sure your
- recipe inherits the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
- class.
- This class is useful for "all" architectures because it
- configures many variables so packages can be used across
- multiple architectures.</para>
- <para>If your recipe needs to generate packages that are
- machine-specific or when one of the build or runtime
- dependencies is already machine-architecture dependent,
- which makes your recipe also machine-architecture dependent,
- make sure your recipe enables the "machine" package
- architecture through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
- variable:
- <literallayout class='monospaced'>
- PACKAGE_ARCH = "${MACHINE_ARCH}"
- </literallayout>
- When you do not specifically enable a package
- architecture through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
- The OpenEmbedded build system defaults to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink>
- setting:
- <literallayout class='monospaced'>
- PACKAGE_ARCH = "${TUNE_PKGARCH}"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Choose a Generic Tuning File if Possible:</emphasis>
- Some tunes are more generic and can run on multiple targets
- (e.g. an <filename>armv5</filename> set of packages could
- run on <filename>armv6</filename> and
- <filename>armv7</filename> processors in most cases).
- Similarly, <filename>i486</filename> binaries could work
- on <filename>i586</filename> and higher processors.
- You should realize, however, that advances on newer
- processor versions would not be used.</para>
- <para>If you select the same tune for several different
- machines, the OpenEmbedded build system reuses software
- previously built, thus speeding up the overall build time.
- Realize that even though a new sysroot for each machine is
- generated, the software is not recompiled and only one
- package feed exists.
- </para></listitem>
- <listitem><para><emphasis>Manage Granular Level Packaging:</emphasis>
- Sometimes cases exist where injecting another level
- of package architecture beyond the three higher levels
- noted earlier can be useful.
- For example, consider the <filename>emgd</filename>
- graphics stack in the
- <filename>meta-intel</filename> layer.
- In this layer, a subset of software exists that is
- compiled against something different from the rest of the
- generic packages.
- You can examine the key code in the
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>
- "daisy" branch in
- <filename>classes/emgd-gl.bbclass</filename>.
- For a specific set of packages, the code redefines
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>.
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXTRA_ARCHS'><filename>PACKAGE_EXTRA_ARCHS</filename></ulink>
- is then appended with this extra tune name in
- <filename>meta-intel-emgd.inc</filename>.
- The result is that when searching for packages, the
- build system uses a four-level search and the packages
- in this new level are preferred as compared to the standard
- tune.
- The overall result is that the build system reuses most
- software from the common tune except for specific cases
- as needed.
- </para></listitem>
- <listitem><para><emphasis>Use Tools to Debug Issues:</emphasis>
- Sometimes you can run into situations where software is
- being rebuilt when you think it should not be.
- For example, the OpenEmbedded build system might not be
- using shared state between machines when you think it
- should be.
- These types of situations are usually due to references
- to machine-specific variables such as
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>,
- and so forth in code that is supposed to only be
- tune-specific or when the recipe depends
- (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>,
- and so forth) on some other recipe that already has
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
- defined as "${MACHINE_ARCH}".
- <note>
- Patches to fix any issues identified are most welcome
- as these issues occasionally do occur.
- </note></para>
- <para>For such cases, you can use some tools to help you
- sort out the situation:
- <itemizedlist>
- <listitem><para><emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
- You can find this tool in the
- <filename>scripts</filename> directory of the
- Source Repositories.
- See the comments in the script for information on
- how to use the tool.
- </para></listitem>
- <listitem><para><emphasis>BitBake's "-S printdiff" Option:</emphasis>
- Using this option causes BitBake to try to
- establish the closest signature match it can
- (e.g. in the shared state cache) and then run
- <filename>bitbake-diffsigs</filename> over the
- matches to determine the stamps and delta where
- these two stamp trees diverge.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- </itemizedlist>
+ To help conserve disk space during builds, you can add the
+ following statement to your project's
+ <filename>local.conf</filename> configuration file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
+ INHERIT += "rm_work"
+ </literallayout>
+ Adding this statement deletes the work directory used for building
+ a recipe once the recipe is built.
+ For more information on "rm_work", see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+ class in the Yocto Project Reference Manual.
</para>
</section>
@@ -7121,7 +8874,7 @@
<para>
Because the OpenEmbedded build system uses
- "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
+ "<ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>signatures</ulink>",
which are unique to a given build, the build system
knows when to rebuild packages.
All the inputs into a given task are represented by a
@@ -7206,8 +8959,8 @@
BUILDHISTORY_COMMIT = "1"
</literallayout>
For information on build history, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
- section in the Yocto Project Reference Manual.
+ "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
+ section.
</para>
<note>
@@ -7225,8 +8978,9 @@
<para>
For more information on shared state, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
- section in the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual.
</para>
</note>
</section>
@@ -7470,7 +9224,7 @@
<filename>connman.inc</filename> file in the
<filename>meta/recipes-connectivity/connman/</filename>
directory of the <filename>poky</filename>
- <ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>source repository</ulink>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>source repository</ulink>.
You can also find examples in
<filename>meta/classes/kernel.bbclass</filename>.
</para>
@@ -7599,11 +9353,13 @@
During a build, BitBake always transforms a recipe into one or
more packages.
For example, BitBake takes the <filename>bash</filename> recipe
- and currently produces the <filename>bash-dbg</filename>,
- <filename>bash-staticdev</filename>,
- <filename>bash-dev</filename>, <filename>bash-doc</filename>,
- <filename>bash-locale</filename>, and
- <filename>bash</filename> packages.
+ and produces a number of packages (e.g.
+ <filename>bash</filename>, <filename>bash-bashbug</filename>,
+ <filename>bash-completion</filename>,
+ <filename>bash-completion-dbg</filename>,
+ <filename>bash-completion-dev</filename>,
+ <filename>bash-completion-extra</filename>,
+ <filename>bash-dbg</filename>, and so forth).
Not all generated packages are included in an image.
</para>
@@ -7647,7 +9403,7 @@
<para>
In order to use runtime package management, you
- need a host/server machine that serves up the pre-compiled
+ need a host or server machine that serves up the pre-compiled
packages plus the required metadata.
You also need package manipulation tools on the target.
The build machine is a likely candidate to act as the server.
@@ -7655,6 +9411,10 @@
package server.
The build machine could push its artifacts to another machine
that acts as the server (e.g. Internet-facing).
+ In fact, doing so is advantageous for a production
+ environment as getting the packages away from the
+ development system's build directory prevents accidental
+ overwrites.
</para>
<para>
@@ -7664,11 +9424,11 @@
out into a couple of different package groupings based on
criteria such as the target's CPU architecture, the target
board, or the C library used on the target.
- For example, a build targeting the <filename>qemuarm</filename>
+ For example, a build targeting the <filename>qemux86</filename>
device produces the following three package databases:
- <filename>all</filename>, <filename>armv5te</filename>, and
- <filename>qemuarm</filename>.
- If you wanted your <filename>qemuarm</filename> device to be
+ <filename>noarch</filename>, <filename>i586</filename>, and
+ <filename>qemux86</filename>.
+ If you wanted your <filename>qemux86</filename> device to be
aware of all the packages that were available to it,
you would need to point it to each of these databases
individually.
@@ -7714,10 +9474,10 @@
PACKAGE_CLASSES ?= “package_<replaceable>packageformat</replaceable>”
</literallayout>
where <replaceable>packageformat</replaceable>
- can be "ipk", "rpm", and "deb", which are the
+ can be "ipk", "rpm", "deb", or "tar" which are the
supported package formats.
<note>
- Because the Yocto Project supports three
+ Because the Yocto Project supports four
different package formats, you can set the
variable with more than one argument.
However, the OpenEmbedded build system only
@@ -7736,12 +9496,12 @@
"package-management" in the
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
variable.
- Including "package-management" in this
- configuration variable ensures that when the image
- is assembled for your target, the image includes
- the currently-known package databases as well as
- the target-specific tools required for runtime
- package management to be performed on the target.
+ Including "package-management" in this configuration
+ variable ensures that when the image is assembled for your
+ target, the image includes the currently-known package
+ databases as well as the target-specific tools required
+ for runtime package management to be performed on the
+ target.
However, this is not strictly necessary.
You could start your image off without any databases
but only include the required on-target package
@@ -7755,21 +9515,26 @@
<para>
Whenever you perform any sort of build step that can
- potentially generate a package or modify an existing
+ potentially generate a package or modify existing
package, it is always a good idea to re-generate the
- package index with:
+ package index after the build by using the following
+ command:
<literallayout class='monospaced'>
$ bitbake package-index
</literallayout>
- Realize that it is not sufficient to simply do the
- following:
+ It might be tempting to build the package and the
+ package index at the same time with a command such as
+ the following:
<literallayout class='monospaced'>
$ bitbake <replaceable>some-package</replaceable> package-index
</literallayout>
- The reason for this restriction is because BitBake does not
- properly schedule the <filename>package-index</filename>
- target fully after any other target has completed.
- Thus, be sure to run the package update step separately.
+ Do not do this as BitBake does not schedule the package
+ index for after the completion of the package you are
+ building.
+ Consequently, you cannot be sure of the package index
+ including information for the package you just built.
+ Thus, be sure to run the package update step separately
+ after building any packages.
</para>
<para>
@@ -7794,8 +9559,8 @@
For example, if
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink><filename>}</filename>
is <filename>tmp</filename> and your selected package type
- is IPK, then your IPK packages are available in
- <filename>tmp/deploy/ipk</filename>.
+ is RPM, then your RPM packages are available in
+ <filename>tmp/deploy/rpm</filename>.
</para>
</section>
@@ -7850,17 +9615,39 @@
<title>Using RPM</title>
<para>
- The <filename>dnf</filename> application performs
- runtime package management of RPM packages.
- You must perform an initial setup for
- <filename>dnf</filename> on the target machine
- if the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>,
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink>
- variables have not been set or the target image was
- built before the variables were set.
+ The
+ <ulink url='https://en.wikipedia.org/wiki/DNF_(software)'>Dandified Packaging Tool</ulink>
+ (DNF) performs runtime package management of RPM
+ packages.
+ In order to use DNF for runtime package management,
+ you must perform an initial setup on the target
+ machine for cases where the
+ <filename>PACKAGE_FEED_*</filename> variables were not
+ set as part of the image that is running on the
+ target.
+ This means if you built your image and did not not use
+ these variables as part of the build and your image is
+ now running on the target, you need to perform the
+ steps in this section if you want to use runtime
+ package management.
+ <note>
+ For information on the
+ <filename>PACKAGE_FEED_*</filename> variables, see
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink>
+ in the Yocto Project Reference Manual variables
+ glossary.
+ </note>
+ </para>
+
+ <para>
+ On the target, you must inform DNF that package
+ databases are available.
+ You do this by creating a file named
+ <filename>/etc/yum.repos.d/oe-packages.repo</filename>
+ and defining the <filename>oe-packages</filename>.
</para>
<para>
@@ -7869,21 +9656,65 @@
<filename>all</filename>, <filename>i586</filename>,
and <filename>qemux86</filename> from a server named
<filename>my.server</filename>.
- You must inform <filename>dnf</filename> of the
- availability of these databases by creating a
- <filename>/etc/yum.repos.d/oe-packages.repo</filename>
- file with the following content:
- <literallayout class='monospaced'>
+ The specifics for setting up the web server are up to
+ you.
+ The critical requirement is that the URIs in the
+ target repository configuration point to the
+ correct remote location for the feeds.
+ <note><title>Tip</title>
+ For development purposes, you can point the web
+ server to the build system's
+ <filename>deploy</filename> directory.
+ However, for production use, it is better to copy
+ the package directories to a location outside of
+ the build area and use that location.
+ Doing so avoids situations where the build system
+ overwrites or changes the
+ <filename>deploy</filename> directory.
+ </note>
+ </para>
+
+ <para>
+ When telling DNF where to look for the package
+ databases, you must declare individual locations
+ per architecture or a single location used for all
+ architectures.
+ You cannot do both:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create an Explicit List of Architectures:</emphasis>
+ Define individual base URLs to identify where
+ each package database is located:
+ <literallayout class='monospaced'>
[oe-packages]
baseurl=http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all
- </literallayout>
- From the target machine, fetch the repository:
+ </literallayout>
+ This example informs DNF about individual
+ package databases for all three architectures.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Single (Full) Package Index:</emphasis>
+ Define a single base URL that identifies where
+ a full package database is located:
+ <literallayout class='monospaced'>
+ [oe-packages]
+ baseurl=http://my.server/rpm
+ </literallayout>
+ This example informs DNF about a single package
+ database that contains all the package index
+ information for all supported architectures.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Once you have informed DNF where to find the package
+ databases, you need to fetch them:
<literallayout class='monospaced'>
# dnf makecache
</literallayout>
- After everything is set up, <filename>dnf</filename>
- is able to find, install, and upgrade packages from
- the specified repository.
+ DNF is now able to find, install, and upgrade packages
+ from the specified repository or repositories.
<note>
See the
<ulink url='http://dnf.readthedocs.io/en/latest/'>DNF documentation</ulink>
@@ -8294,8 +10125,8 @@
</section>
</section>
- <section id='working-with-source-files'>
- <title>Working with Source Files</title>
+ <section id='efficiently-fetching-source-files-during-a-build'>
+ <title>Efficiently Fetching Source Files During a Build</title>
<para>
The OpenEmbedded build system works with source files located
@@ -8309,16 +10140,16 @@
</para>
<para>
- This section presents information for working with source
- files that can lead to more efficient use of resources and
- time.
+ This section shows you how you can use mirrors to speed up
+ fetching source files and how you can pre-fetch files all of which
+ leads to more efficient use of resources and time.
</para>
<section id='setting-up-effective-mirrors'>
<title>Setting up Effective Mirrors</title>
<para>
- As mentioned, a good deal that goes into a Yocto Project
+ A good deal that goes into a Yocto Project
build is simply downloading all of the source tarballs.
Maybe you have been working with another build system
(OpenEmbedded or Angstrom) for which you have built up a
@@ -8381,7 +10212,7 @@
Use the following BitBake command form to fetch all the
necessary sources without starting the build:
<literallayout class='monospaced'>
- $ bitbake -c fetchall <replaceable>target</replaceable>
+ $ bitbake -c <replaceable>target</replaceable> runall="fetch"
</literallayout>
This variation of the BitBake command guarantees that you
have all the sources for that BitBake target should you
@@ -8391,81 +10222,6 @@
</section>
</section>
- <section id="building-software-from-an-external-source">
- <title>Building Software from an External Source</title>
-
- <para>
- By default, the OpenEmbedded build system uses the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- when building source code.
- The build process involves fetching the source files, unpacking
- them, and then patching them if necessary before the build takes
- place.
- </para>
-
- <para>
- Situations exist where you might want to build software from source
- files that are external to and thus outside of the
- OpenEmbedded build system.
- For example, suppose you have a project that includes a new BSP with
- a heavily customized kernel.
- And, you want to minimize exposing the build system to the
- development team so that they can focus on their project and
- maintain everyone's workflow as much as possible.
- In this case, you want a kernel source directory on the development
- machine where the development occurs.
- You want the recipe's
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- variable to point to the external directory and use it as is, not
- copy it.
- </para>
-
- <para>
- To build from software that comes from an external source, all you
- need to do is inherit the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
- class and then set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
- variable to point to your external source code.
- Here are the statements to put in your
- <filename>local.conf</filename> file:
- <literallayout class='monospaced'>
- INHERIT += "externalsrc"
- EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
- </literallayout>
- </para>
-
- <para>
- This next example shows how to accomplish the same thing by setting
- <filename>EXTERNALSRC</filename> in the recipe itself or in the
- recipe's append file:
- <literallayout class='monospaced'>
- EXTERNALSRC = "<replaceable>path</replaceable>"
- EXTERNALSRC_BUILD = "<replaceable>path</replaceable>"
- </literallayout>
- <note>
- In order for these settings to take effect, you must globally
- or locally inherit the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
- class.
- </note>
- </para>
-
- <para>
- By default, <filename>externalsrc.bbclass</filename> builds
- the source code in a directory separate from the external source
- directory as specified by
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
- If you need to have the source built in the same directory in
- which it resides, or some other nominated directory, you can set
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
- to point to that directory:
- <literallayout class='monospaced'>
- EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
- </literallayout>
- </para>
- </section>
-
<section id="selecting-an-initialization-manager">
<title>Selecting an Initialization Manager</title>
@@ -8863,6 +10619,566 @@
</section>
</section>
+
+
+
+ <section id='maintaining-build-output-quality'>
+ <title>Maintaining Build Output Quality</title>
+
+ <para>
+ Many factors can influence the quality of a build.
+ For example, if you upgrade a recipe to use a new version of an
+ upstream software package or you experiment with some new
+ configuration options, subtle changes can occur that you might
+ not detect until later.
+ Consider the case where your recipe is using a newer version of
+ an upstream package.
+ In this case, a new version of a piece of software might
+ introduce an optional dependency on another library, which is
+ auto-detected.
+ If that library has already been built when the software is
+ building, the software will link to the built library and that
+ library will be pulled into your image along with the new
+ software even if you did not want the library.
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
+ class exists to help you maintain the quality of your build
+ output.
+ You can use the class to highlight unexpected and possibly
+ unwanted changes in the build output.
+ When you enable build history, it records information about the
+ contents of each package and image and then commits that
+ information to a local Git repository where you can examine
+ the information.
+ </para>
+
+ <para>
+ The remainder of this section describes the following:
+ <itemizedlist>
+ <listitem><para>
+ How you can enable and disable build history
+ </para></listitem>
+ <listitem><para>
+ How to understand what the build history contains
+ </para></listitem>
+ <listitem><para>
+ How to limit the information used for build history
+ </para></listitem>
+ <listitem><para>
+ How to examine the build history from both a
+ command-line and web interface
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <section id='enabling-and-disabling-build-history'>
+ <title>Enabling and Disabling Build History</title>
+
+ <para>
+ Build history is disabled by default.
+ To enable it, add the following <filename>INHERIT</filename>
+ statement and set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></ulink>
+ variable to "1" at the end of your
+ <filename>conf/local.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
+ INHERIT += "buildhistory"
+ BUILDHISTORY_COMMIT = "1"
+ </literallayout>
+ Enabling build history as previously described causes the
+ OpenEmbedded build system to collect build output information
+ and commit it as a single commit to a local
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
+ repository.
+ <note>
+ Enabling build history increases your build times slightly,
+ particularly for images, and increases the amount of disk
+ space used during the build.
+ </note>
+ </para>
+
+ <para>
+ You can disable build history by removing the previous
+ statements from your <filename>conf/local.conf</filename>
+ file.
+ </para>
+ </section>
+
+ <section id='understanding-what-the-build-history-contains'>
+ <title>Understanding What the Build History Contains</title>
+
+ <para>
+ Build history information is kept in
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink><filename>}/buildhistory</filename>
+ in the Build Directory as defined by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></ulink>
+ variable.
+ The following is an example abbreviated listing:
+ <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
+ </para>
+
+ <para>
+ At the top level, a <filename>metadata-revs</filename>
+ file exists that lists the revisions of the repositories for
+ the enabled layers when the build was produced.
+ The rest of the data splits into separate
+ <filename>packages</filename>, <filename>images</filename>
+ and <filename>sdk</filename> directories, the contents of
+ which are described as follows.
+ </para>
+
+ <section id='build-history-package-information'>
+ <title>Build History Package Information</title>
+
+ <para>
+ The history for each package contains a text file that has
+ name-value pairs with information about the package.
+ For example,
+ <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename>
+ contains the following:
+ <literallayout class='monospaced'>
+ PV = 1.22.1
+ PR = r32
+ RPROVIDES =
+ RDEPENDS = glibc (>= 2.20) update-alternatives-opkg
+ RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d
+ PKGSIZE = 540168
+ FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \
+ /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \
+ /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \
+ /usr/share/pixmaps /usr/share/applications /usr/share/idl \
+ /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
+ FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \
+ /etc/busybox.links.nosuid /etc/busybox.links.suid
+ </literallayout>
+ Most of these name-value pairs correspond to variables
+ used to produce the package.
+ The exceptions are <filename>FILELIST</filename>, which
+ is the actual list of files in the package, and
+ <filename>PKGSIZE</filename>, which is the total size of
+ files in the package in bytes.
+ </para>
+
+ <para>
+ A file also exists that corresponds to the recipe from
+ which the package came (e.g.
+ <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>):
+ <literallayout class='monospaced'>
+ PV = 1.22.1
+ PR = r32
+ DEPENDS = initscripts kern-tools-native update-rc.d-native \
+ virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \
+ virtual/libc virtual/update-alternatives
+ PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \
+ busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \
+ busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
+ </literallayout>
+ </para>
+
+ <para>
+ Finally, for those recipes fetched from a version control
+ system (e.g., Git), a file exists that lists source
+ revisions that are specified in the recipe and lists
+ the actual revisions used during the build.
+ Listed and actual revisions might differ when
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ is set to
+ ${<ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>}.
+ Here is an example assuming
+ <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>):
+ <literallayout class='monospaced'>
+ # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
+ SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
+ # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
+ SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
+ </literallayout>
+ You can use the
+ <filename>buildhistory-collect-srcrevs</filename>
+ command with the <filename>-a</filename> option to
+ collect the stored <filename>SRCREV</filename> values
+ from build history and report them in a format suitable for
+ use in global configuration (e.g.,
+ <filename>local.conf</filename> or a distro include file)
+ to override floating <filename>AUTOREV</filename> values
+ to a fixed set of revisions.
+ Here is some example output from this command:
+ <literallayout class='monospaced'>
+ $ buildhistory-collect-srcrevs -a
+ # i586-poky-linux
+ SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"
+ SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"
+ SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"
+ SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
+ # x86_64-linux
+ SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa"
+ SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"
+ SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11"
+ SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"
+ SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"
+ SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"
+ SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a"
+ SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff"
+ SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
+ # qemux86-poky-linux
+ SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
+ SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"
+ # all-poky-linux
+ SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"
+ </literallayout>
+ <note>
+ Here are some notes on using the
+ <filename>buildhistory-collect-srcrevs</filename>
+ command:
+ <itemizedlist>
+ <listitem><para>
+ By default, only values where the
+ <filename>SRCREV</filename> was not hardcoded
+ (usually when <filename>AUTOREV</filename>
+ is used) are reported.
+ Use the <filename>-a</filename> option to
+ see all <filename>SRCREV</filename> values.
+ </para></listitem>
+ <listitem><para>
+ The output statements might not have any effect
+ if overrides are applied elsewhere in the
+ build system configuration.
+ Use the <filename>-f</filename> option to add
+ the <filename>forcevariable</filename> override
+ to each output line if you need to work around
+ this restriction.
+ </para></listitem>
+ <listitem><para>
+ The script does apply special handling when
+ building for multiple machines.
+ However, the script does place a comment before
+ each set of values that specifies which
+ triplet to which they belong as previously
+ shown (e.g.,
+ <filename>i586-poky-linux</filename>).
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+ </section>
+
+ <section id='build-history-image-information'>
+ <title>Build History Image Information</title>
+
+ <para>
+ The files produced for each image are as follows:
+ <itemizedlist>
+ <listitem><para>
+ <filename>image-files:</filename>
+ A directory containing selected files from the root
+ filesystem.
+ The files are defined by
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></ulink>.
+ </para></listitem>
+ <listitem><para>
+ <filename>build-id.txt:</filename>
+ Human-readable information about the build
+ configuration and metadata source revisions.
+ This file contains the full build header as printed
+ by BitBake.
+ </para></listitem>
+ <listitem><para>
+ <filename>*.dot:</filename>
+ Dependency graphs for the image that are
+ compatible with <filename>graphviz</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>files-in-image.txt:</filename>
+ A list of files in the image with permissions,
+ owner, group, size, and symlink information.
+ </para></listitem>
+ <listitem><para>
+ <filename>image-info.txt:</filename>
+ A text file containing name-value pairs with
+ information about the image.
+ See the following listing example for more
+ information.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-names.txt:</filename>
+ A list of installed packages by name only.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-sizes.txt:</filename>
+ A list of installed packages ordered by size.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-packages.txt:</filename>
+ A list of installed packages with full package
+ filenames.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ Installed package information is able to be gathered
+ and produced even if package management is disabled
+ for the final image.
+ </note>
+ </para>
+
+ <para>
+ Here is an example of <filename>image-info.txt</filename>:
+ <literallayout class='monospaced'>
+ DISTRO = poky
+ DISTRO_VERSION = 1.7
+ USER_CLASSES = buildstats image-mklibs image-prelink
+ IMAGE_CLASSES = image_types
+ IMAGE_FEATURES = debug-tweaks
+ IMAGE_LINGUAS =
+ IMAGE_INSTALL = packagegroup-core-boot run-postinsts
+ BAD_RECOMMENDATIONS =
+ NO_RECOMMENDATIONS =
+ PACKAGE_EXCLUDE =
+ ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \
+ write_image_manifest ; buildhistory_list_installed_image ; \
+ buildhistory_get_image_installed ; ssh_allow_empty_password; \
+ postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;
+ IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
+ IMAGESIZE = 6900
+ </literallayout>
+ Other than <filename>IMAGESIZE</filename>, which is the
+ total size of the files in the image in Kbytes, the
+ name-value pairs are variables that may have influenced the
+ content of the image.
+ This information is often useful when you are trying to
+ determine why a change in the package or file
+ listings has occurred.
+ </para>
+ </section>
+
+ <section id='using-build-history-to-gather-image-information-only'>
+ <title>Using Build History to Gather Image Information Only</title>
+
+ <para>
+ As you can see, build history produces image information,
+ including dependency graphs, so you can see why something
+ was pulled into the image.
+ If you are just interested in this information and not
+ interested in collecting specific package or SDK
+ information, you can enable writing only image information
+ without any history by adding the following to your
+ <filename>conf/local.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
+ INHERIT += "buildhistory"
+ BUILDHISTORY_COMMIT = "0"
+ BUILDHISTORY_FEATURES = "image"
+ </literallayout>
+ Here, you set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></ulink>
+ variable to use the image feature only.
+ </para>
+ </section>
+
+ <section id='build-history-sdk-information'>
+ <title>Build History SDK Information</title>
+
+ <para>
+ Build history collects similar information on the contents
+ of SDKs
+ (e.g. <filename>bitbake -c populate_sdk imagename</filename>)
+ as compared to information it collects for images.
+ Furthermore, this information differs depending on whether
+ an extensible or standard SDK is being produced.
+ </para>
+
+ <para>
+ The following list shows the files produced for SDKs:
+ <itemizedlist>
+ <listitem><para>
+ <filename>files-in-sdk.txt:</filename>
+ A list of files in the SDK with permissions,
+ owner, group, size, and symlink information.
+ This list includes both the host and target parts
+ of the SDK.
+ </para></listitem>
+ <listitem><para>
+ <filename>sdk-info.txt:</filename>
+ A text file containing name-value pairs with
+ information about the SDK.
+ See the following listing example for more
+ information.
+ </para></listitem>
+ <listitem><para>
+ <filename>sstate-task-sizes.txt:</filename>
+ A text file containing name-value pairs with
+ information about task group sizes
+ (e.g. <filename>do_populate_sysroot</filename>
+ tasks have a total size).
+ The <filename>sstate-task-sizes.txt</filename> file
+ exists only when an extensible SDK is created.
+ </para></listitem>
+ <listitem><para>
+ <filename>sstate-package-sizes.txt:</filename>
+ A text file containing name-value pairs with
+ information for the shared-state packages and
+ sizes in the SDK.
+ The <filename>sstate-package-sizes.txt</filename>
+ file exists only when an extensible SDK is created.
+ </para></listitem>
+ <listitem><para>
+ <filename>sdk-files:</filename>
+ A folder that contains copies of the files
+ mentioned in
+ <filename>BUILDHISTORY_SDK_FILES</filename> if the
+ files are present in the output.
+ Additionally, the default value of
+ <filename>BUILDHISTORY_SDK_FILES</filename> is
+ specific to the extensible SDK although you can
+ set it differently if you would like to pull in
+ specific files from the standard SDK.</para>
+
+ <para>The default files are
+ <filename>conf/local.conf</filename>,
+ <filename>conf/bblayers.conf</filename>,
+ <filename>conf/auto.conf</filename>,
+ <filename>conf/locked-sigs.inc</filename>, and
+ <filename>conf/devtool.conf</filename>.
+ Thus, for an extensible SDK, these files get
+ copied into the <filename>sdk-files</filename>
+ directory.
+ </para></listitem>
+ <listitem><para>
+ The following information appears under
+ each of the <filename>host</filename>
+ and <filename>target</filename> directories
+ for the portions of the SDK that run on the host
+ and on the target, respectively:
+ <note>
+ The following files for the most part are empty
+ when producing an extensible SDK because this
+ type of SDK is not constructed from packages
+ as is the standard SDK.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <filename>depends.dot:</filename>
+ Dependency graph for the SDK that is
+ compatible with
+ <filename>graphviz</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-names.txt:</filename>
+ A list of installed packages by name only.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-sizes.txt:</filename>
+ A list of installed packages ordered by size.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-packages.txt:</filename>
+ A list of installed packages with full
+ package filenames.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Here is an example of <filename>sdk-info.txt</filename>:
+ <literallayout class='monospaced'>
+ DISTRO = poky
+ DISTRO_VERSION = 1.3+snapshot-20130327
+ SDK_NAME = poky-glibc-i686-arm
+ SDK_VERSION = 1.3+snapshot
+ SDKMACHINE =
+ SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
+ BAD_RECOMMENDATIONS =
+ SDKSIZE = 352712
+ </literallayout>
+ Other than <filename>SDKSIZE</filename>, which is the
+ total size of the files in the SDK in Kbytes, the
+ name-value pairs are variables that might have influenced
+ the content of the SDK.
+ This information is often useful when you are trying to
+ determine why a change in the package or file listings
+ has occurred.
+ </para>
+ </section>
+
+ <section id='examining-build-history-information'>
+ <title>Examining Build History Information</title>
+
+ <para>
+ You can examine build history output from the command
+ line or from a web interface.
+ </para>
+
+ <para>
+ To see any changes that have occurred (assuming you have
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></ulink><filename> = "1"</filename>),
+ you can simply use any Git command that allows you to
+ view the history of a repository.
+ Here is one method:
+ <literallayout class='monospaced'>
+ $ git log -p
+ </literallayout>
+ You need to realize, however, that this method does show
+ changes that are not significant (e.g. a package's size
+ changing by a few bytes).
+ </para>
+
+ <para>
+ A command-line tool called
+ <filename>buildhistory-diff</filename> does exist, though,
+ that queries the Git repository and prints just the
+ differences that might be significant in human-readable
+ form.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
+ Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt):
+ /etc/anotherpkg.conf was added
+ /sbin/anotherpkg was added
+ * (installed-package-names.txt):
+ * anotherpkg was added
+ Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt):
+ anotherpkg was added
+ packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
+ * PR changed from "r0" to "r1"
+ * PV changed from "0.1.10" to "0.1.12"
+ packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
+ * PR changed from "r0" to "r1"
+ * PV changed from "0.1.10" to "0.1.12"
+ </literallayout>
+ <note>
+ The <filename>buildhistory-diff</filename> tool
+ requires the <filename>GitPython</filename> package.
+ Be sure to install it using Pip3 as follows:
+ <literallayout class='monospaced'>
+ $ pip3 install GitPython --user
+ </literallayout>
+ Alternatively, you can install
+ <filename>python3-git</filename> using the appropriate
+ distribution package manager (e.g.
+ <filename>apt-get</filename>, <filename>dnf</filename>,
+ or <filename>zipper</filename>).
+ </note>
+ </para>
+
+ <para>
+ To see changes to the build history using a web interface,
+ follow the instruction in the <filename>README</filename>
+ file here.
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
+ </para>
+
+ <para>
+ Here is a sample screenshot of the interface:
+ <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
+ </para>
+ </section>
+ </section>
+ </section>
+
<section id="performing-automated-runtime-testing">
<title>Performing Automated Runtime Testing</title>
@@ -8926,6 +11242,25 @@
which should generate a list of tap devices.
This is the option typically chosen for
Autobuilder-type environments.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Be sure to use an absolute path
+ when calling this script
+ with sudo.
+ </para></listitem>
+ <listitem><para>
+ The package recipe
+ <filename>qemu-helper-native</filename>
+ is required to run this script.
+ Build the package using the
+ following command:
+ <literallayout class='monospaced'>
+ $ bitbake qemu-helper-native
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </note>
</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis>Set the
@@ -9768,368 +12103,1009 @@
</section>
</section>
- <section id="platdev-gdb-remotedebug">
- <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+ <section id='usingpoky-debugging-tools-and-techniques'>
+ <title>Debugging Tools and Techniques</title>
<para>
- GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
- It also allows you to perform post-mortem style analysis of program crashes.
- GDB is available as a package within the Yocto Project and is
- installed in SDK images by default.
- See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
- in the Yocto Project Reference Manual for a description of these images.
- You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
- </para>
-
- <tip>
- For best results, install debug (<filename>-dbg</filename>) packages
- for the applications you are going to debug.
- Doing so makes extra debug symbols available that give you more
- meaningful output.
- </tip>
-
- <para>
- Sometimes, due to memory or disk space constraints, it is not possible
- to use GDB directly on the remote target to debug applications.
- These constraints arise because GDB needs to load the debugging information and the
- binaries of the process being debugged.
- Additionally, GDB needs to perform many computations to locate information such as function
- names, variable names and values, stack traces and so forth - even before starting the
- debugging process.
- These extra computations place more load on the target system and can alter the
- characteristics of the program being debugged.
+ The exact method for debugging build failures depends on the nature
+ of the problem and on the system's area from which the bug
+ originates.
+ Standard debugging practices such as comparison against the last
+ known working version with examination of the changes and the
+ re-application of steps to identify the one causing the problem are
+ valid for the Yocto Project just as they are for any other system.
+ Even though it is impossible to detail every possible potential
+ failure, this section provides some general tips to aid in
+ debugging given a variety of situations.
+ <note><title>Tip</title>
+ A useful feature for debugging is the error reporting tool.
+ Configuring the Yocto Project to use this tool causes the
+ OpenEmbedded build system to produce error reporting commands as
+ part of the console output.
+ You can enter the commands after the build completes to log
+ error information into a common database, that can help you
+ figure out what might be going wrong.
+ For information on how to enable and use this feature, see the
+ "<link linkend='using-the-error-reporting-tool'>Using the Error Reporting Tool</link>"
+ section.
+ </note>
</para>
<para>
- To help get past the previously mentioned constraints, you can use
- gdbserver, which runs on the remote target and does not load any
- debugging information from the debugged process.
- Instead, a GDB instance processes the debugging information that is run on a
- remote computer - the host GDB.
- The host GDB then sends control commands to gdbserver to make it stop or start the debugged
- program, as well as read or write memory regions of that debugged program.
- All the debugging information loaded and processed as well
- as all the heavy debugging is done by the host GDB.
- Offloading these processes gives the gdbserver running on the target a chance to remain
- small and fast.
- </para>
-
- <para>
- Because the host GDB is responsible for loading the debugging information and
- for doing the necessary processing to make actual debugging happen,
- you have to make sure the host can access the unstripped binaries complete
- with their debugging information and also be sure the target is compiled with no optimizations.
- The host GDB must also have local access to all the libraries used by the
- debugged program.
- Because gdbserver does not need any local debugging information, the binaries on
- the remote target can remain stripped.
- However, the binaries must also be compiled without optimization
- so they match the host's binaries.
- </para>
-
- <para>
- To remain consistent with GDB documentation and terminology, the binary being debugged
- on the remote target machine is referred to as the "inferior" binary.
- For documentation on GDB see the
- <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
- </para>
-
- <para>
- The following steps show you how to debug using the GNU project
- debugger.
- <orderedlist>
- <listitem><para>
- <emphasis>Configure your build system to construct the
- companion debug filesystem:</emphasis></para>
-
- <para>In your <filename>local.conf</filename> file, set
- the following:
- <literallayout class='monospaced'>
- IMAGE_GEN_DEBUGFS = "1"
- IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
- </literallayout>
- These options cause the OpenEmbedded build system
- to generate a special companion filesystem fragment,
- which contains the matching source and debug symbols to
- your deployable filesystem.
- The build system does this by looking at what is in the
- deployed filesystem, and pulling the corresponding
- <filename>-dbg</filename> packages.</para>
-
- <para>The companion debug filesystem is not a complete
- filesystem, but only contains the debug fragments.
- This filesystem must be combined with the full filesystem
- for debugging.
- Subsequent steps in this procedure show how to combine
- the partial filesystem with the full filesystem.
- </para></listitem>
- <listitem><para>
- <emphasis>Configure the system to include gdbserver in
- the target filesystem:</emphasis></para>
-
- <para>Make the following addition in either your
- <filename>local.conf</filename> file or in an image
- recipe:
- <literallayout class='monospaced'>
- IMAGE_INSTALL_append = “ gdbserver"
- </literallayout>
- The change makes sure the <filename>gdbserver</filename>
- package is included.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the environment:</emphasis></para>
-
- <para>Use the following command to construct the image and
- the companion Debug Filesystem:
- <literallayout class='monospaced'>
- $ bitbake <replaceable>image</replaceable>
- </literallayout>
- Build the cross GDB component and make it available
- for debugging.
- Build the SDK that matches the image.
- Building the SDK is best for a production build
- that can be used later for debugging, especially
- during long term maintenance:
- <literallayout class='monospaced'>
- $ bitbake -c populate_sdk <replaceable>image</replaceable>
- </literallayout></para>
-
- <para>Alternatively, you can build the minimal
- toolchain components that match the target.
- Doing so creates a smaller than typical SDK and only
- contains a minimal set of components with which to
- build simple test applications, as well as run the
- debugger:
- <literallayout class='monospaced'>
- $ bitbake meta-toolchain
- </literallayout></para>
-
- <para>A final method is to build Gdb itself within
- the build system:
- <literallayout class='monospaced'>
- $ bitbake gdb-cross-<replaceable>architecture</replaceable>
- </literallayout>
- Doing so produces a temporary copy of
- <filename>cross-gdb</filename> you can use for
- debugging during development.
- While this is the quickest approach, the two previous
- methods in this step are better when considering
- long-term maintenance strategies.
- <note>
- If you run
- <filename>bitbake gdb-cross</filename>, the
- OpenEmbedded build system suggests the actual
- image (e.g. <filename>gdb-cross-i586</filename>).
- The suggestion is usually the actual name you want
- to use.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up the</emphasis> <filename>debugfs</filename></para>
-
- <para>Run the following commands to set up the
- <filename>debugfs</filename>:
- <literallayout class='monospaced'>
- $ mkdir debugfs
- $ cd debugfs
- $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
- $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up GDB</emphasis></para>
-
- <para>Install the SDK (if you built one) and then
- source the correct environment file.
- Sourcing the environment file puts the SDK in your
- <filename>PATH</filename> environment variable.</para>
-
- <para>If you are using the build system, Gdb is
- located in
- <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
- </para></listitem>
- <listitem><para>
- <emphasis>Boot the target:</emphasis></para>
-
- <para>For information on how to run QEMU, see the
- <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
- <note>
- Be sure to verify that your host can access the
- target via TCP.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Debug a program:</emphasis></para>
-
- <para>Debugging a program involves running gdbserver
- on the target and then running Gdb on the host.
- The example in this step debugs
- <filename>gzip</filename>:
- <literallayout class='monospaced'>
- root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
- </literallayout>
- For additional gdbserver options, see the
- <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
- </para>
-
- <para>After running gdbserver on the target, you need
- to run Gdb on the host and configure it and connect to
- the target.
- Use these commands:
- <literallayout class='monospaced'>
- $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
- $ <replaceable>arch</replaceable>-gdb
-
- (gdb) set sysroot debugfs
- (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
- (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
- </literallayout>
- At this point, everything should automatically load
- (i.e. matching binaries, symbols and headers).
- <note>
- The Gdb <filename>set</filename> commands in the
- previous example can be placed into the users
- <filename>~/.gdbinit</filename> file.
- Upon starting, Gdb automatically runs whatever
- commands are in that file.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Deploying without a full image
- rebuild:</emphasis></para>
-
- <para>In many cases, during development you want a
- quick method to deploy a new binary to the target and
- debug it, without waiting for a full image build.
- </para>
-
- <para>One approach to solving this situation is to
- just build the component you want to debug.
- Once you have built the component, copy the
- executable directly to both the target and the
- host <filename>debugfs</filename>.</para>
-
- <para>If the binary is processed through the debug
- splitting in OpenEmbedded, you should also
- copy the debug items (i.e. <filename>.debug</filename>
- contents and corresponding
- <filename>/usr/src/debug</filename> files)
- from the work directory.
- Here is an example:
- <literallayout class='monospaced'>
- $ bitbake bash
- $ bitbake -c devshell bash
- $ cd ..
- $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
- $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
- <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
-
- <para>
- The previous section addressed using GDB remotely for debugging
- purposes, which is the most usual case due to the inherent
- hardware limitations on many embedded devices.
- However, debugging in the target hardware itself is also possible
- with more powerful devices.
- This section describes what you need to do in order to support
- using GDB to debug on the target hardware.
- </para>
-
- <para>
- To support this kind of debugging, you need do the following:
+ The following list shows the debugging topics in the remainder of
+ this section:
<itemizedlist>
<listitem><para>
- Ensure that GDB is on the target.
- You can do this by adding "gdb" to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
- <literallayout class='monospaced'>
- IMAGE_INSTALL_append = " gdb"
- </literallayout>
- Alternatively, you can add "tools-debug" to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
- <literallayout class='monospaced'>
- IMAGE_FEATURES_append = " tools-debug"
- </literallayout>
+ "<link linkend='dev-debugging-viewing-logs-from-failed-tasks'>Viewing Logs from Failed Tasks</link>"
+ describes how to find and view logs from tasks that
+ failed during the build process.
</para></listitem>
<listitem><para>
- Ensure that debug symbols are present.
- You can make sure these symbols are present by installing
- <filename>-dbg</filename>:
- <literallayout class='monospaced'>
- IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
- </literallayout>
- Alternatively, you can do the following to include all the
- debug symbols:
- <literallayout class='monospaced'>
- IMAGE_FEATURES_append = " dbg-pkgs"
- </literallayout>
+ "<link linkend='dev-debugging-viewing-variable-values'>Viewing Variable Values</link>"
+ describes how to use the BitBake <filename>-e</filename>
+ option to examine variable values after a recipe has been
+ parsed.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
+ describes how to use the
+ <filename>oe-pkgdata-util</filename> utility to query
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+ and display package-related information for built
+ packages.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-viewing-dependencies-between-recipes-and-tasks'>Viewing Dependencies Between Recipes and Tasks</link>"
+ describes how to use the BitBake <filename>-g</filename>
+ option to display recipe dependency information used
+ during the build.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
+ describes how to use the
+ <filename>bitbake-dumpsig</filename> command in
+ conjunction with key subdirectories in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ to determine variable dependencies.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-debugging-taskrunning'>Running Specific Tasks</link>"
+ describes how to use several BitBake options (e.g.
+ <filename>-c</filename>, <filename>-C</filename>, and
+ <filename>-f</filename>) to run specific tasks in the
+ build chain.
+ It can be useful to run tasks "out-of-order" when trying
+ isolate build issues.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-debugging-bitbake'>General BitBake Problems</link>"
+ describes how to use BitBake's <filename>-D</filename>
+ debug output option to reveal more about what BitBake is
+ doing during the build.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-debugging-buildfile'>Building with No Dependencies</link>"
+ describes how to use the BitBake <filename>-b</filename>
+ option to build a recipe while ignoring dependencies.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='recipe-logging-mechanisms'>Recipe Logging Mechanisms</link>"
+ describes how to use the many recipe logging functions
+ to produce debugging output and report errors and warnings.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
+ describes how to debug situations where the build consists
+ of several parts that are run simultaneously and when the
+ output or result of one part is not ready for use with a
+ different part of the build that depends on that output.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</link>"
+ describes how to use GDB to allow you to examine running
+ programs, which can help you fix problems.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>Debugging with the GNU Project Debugger (GDB) on the Target</link>"
+ describes how to use GDB directly on target hardware for
+ debugging.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-other-debugging-others'>Other Debugging Tips</link>"
+ describes miscellaneous debugging tips that can be useful.
</para></listitem>
</itemizedlist>
- <note>
- To improve the debug information accuracy, you can reduce the
- level of optimization used by the compiler.
- For example, when adding the following line to your
- <filename>local.conf</filename> file, you will reduce
- optimization from
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
- of "-O2" to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
- of "-O -fno-omit-frame-pointer":
- <literallayout class='monospaced'>
- DEBUG_BUILD = "1"
- </literallayout>
- Consider that this will reduce the application's performance
- and is recommended only for debugging purposes.
- </note>
</para>
- </section>
-
- <section id='debugging-parallel-make-races'>
- <title>Debugging Parallel Make Races</title>
<para>
- A parallel <filename>make</filename> race occurs when the build
- consists of several parts that are run simultaneously and
- a situation occurs when the output or result of one
- part is not ready for use with a different part of the build that
- depends on that output.
- Parallel make races are annoying and can sometimes be difficult
- to reproduce and fix.
- However, some simple tips and tricks exist that can help
- you debug and fix them.
- This section presents a real-world example of an error encountered
- on the Yocto Project autobuilder and the process used to fix it.
- <note>
- If you cannot properly fix a <filename>make</filename> race
- condition, you can work around it by clearing either the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
- variables.
- </note>
+ For debugging information within the popular
+ <trademark class='trade'>Eclipse</trademark> IDE, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
</para>
- <section id='the-failure'>
- <title>The Failure</title>
+ <section id='dev-debugging-viewing-logs-from-failed-tasks'>
+ <title>Viewing Logs from Failed Tasks</title>
<para>
- For this example, assume that you are building an image that
- depends on the "neard" package.
- And, during the build, BitBake runs into problems and
- creates the following output.
- <note>
- This example log file has longer lines artificially
- broken to make the listing easier to read.
- </note>
- If you examine the output or the log file, you see the
- failure during <filename>make</filename>:
+ You can find the log for a task in the file
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
+ For example, the log for the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+ task of the QEMU minimal image for the x86 machine
+ (<filename>qemux86</filename>) might be in
+ <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
+ To see the commands
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ ran to generate a log, look at the corresponding
+ <filename>run.do_</filename><replaceable>taskname</replaceable>
+ file in the same directory.
+ </para>
+
+ <para>
+ <filename>log.do_</filename><replaceable>taskname</replaceable>
+ and
+ <filename>run.do_</filename><replaceable>taskname</replaceable>
+ are actually symbolic links to
+ <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
+ and
+ <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
+ where <replaceable>pid</replaceable> is the PID the task had
+ when it ran.
+ The symlinks always point to the files corresponding to the most
+ recent run.
+ </para>
+ </section>
+
+ <section id='dev-debugging-viewing-variable-values'>
+ <title>Viewing Variable Values</title>
+
+ <para>
+ BitBake's <filename>-e</filename> option is used to display
+ variable values after parsing.
+ The following command displays the variable values after the
+ configuration files (i.e. <filename>local.conf</filename>,
+ <filename>bblayers.conf</filename>,
+ <filename>bitbake.conf</filename> and so forth) have been
+ parsed:
<literallayout class='monospaced'>
+ $ bitbake -e
+ </literallayout>
+ The following command displays variable values after a specific
+ recipe has been parsed.
+ The variables include those from the configuration as well:
+ <literallayout class='monospaced'>
+ $ bitbake -e recipename
+ </literallayout>
+ <note><para>
+ Each recipe has its own private set of variables
+ (datastore).
+ Internally, after parsing the configuration, a copy of the
+ resulting datastore is made prior to parsing each recipe.
+ This copying implies that variables set in one recipe will
+ not be visible to other recipes.</para>
+
+ <para>Likewise, each task within a recipe gets a private
+ datastore based on the recipe datastore, which means that
+ variables set within one task will not be visible to
+ other tasks.</para>
+ </note>
+ </para>
+
+ <para>
+ In the output of <filename>bitbake -e</filename>, each
+ variable is preceded by a description of how the variable
+ got its value, including temporary values that were later
+ overriden.
+ This description also includes variable flags (varflags) set on
+ the variable.
+ The output can be very helpful during debugging.
+ </para>
+
+ <para>
+ Variables that are exported to the environment are preceded by
+ <filename>export</filename> in the output of
+ <filename>bitbake -e</filename>.
+ See the following example:
+ <literallayout class='monospaced'>
+ export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
+ </literallayout>
+ </para>
+
+ <para>
+ In addition to variable values, the output of the
+ <filename>bitbake -e</filename> and
+ <filename>bitbake -e</filename> <replaceable>recipe</replaceable>
+ commands includes the following information:
+ <itemizedlist>
+ <listitem><para>
+ The output starts with a tree listing all configuration
+ files and classes included globally, recursively listing
+ the files they include or inherit in turn.
+ Much of the behavior of the OpenEmbedded build system
+ (including the behavior of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>)
+ is implemented in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
+ class and the classes it inherits, rather than being
+ built into BitBake itself.
+ </para></listitem>
+ <listitem><para>
+ After the variable values, all functions appear in the
+ output.
+ For shell functions, variables referenced within the
+ function body are expanded.
+ If a function has been modified using overrides or
+ using override-style operators like
+ <filename>_append</filename> and
+ <filename>_prepend</filename>, then the final assembled
+ function body appears in the output.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='viewing-package-information-with-oe-pkgdata-util'>
+ <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
+
+ <para>
+ You can use the <filename>oe-pkgdata-util</filename>
+ command-line utility to query
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+ and display various package-related information.
+ When you use the utility, you must use it to view information
+ on packages that have already been built.
+ </para>
+
+ <para>
+ Following are a few of the available
+ <filename>oe-pkgdata-util</filename> subcommands.
+ <note>
+ You can use the standard * and ? globbing wildcards as part
+ of package names and paths.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
+ Lists all packages that have been built, optionally
+ limiting the match to packages that match
+ <replaceable>pattern</replaceable>.
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>:
+ Lists the files and directories contained in the given
+ packages.
+ <note>
+ <para>
+ A different way to view the contents of a package is
+ to look at the
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
+ directory of the recipe that generates the
+ package.
+ This directory is created by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task and has one subdirectory for each package the
+ recipe generates, which contains the files stored in
+ that package.</para>
+ <para>
+ If you want to inspect the
+ <filename>${WORKDIR}/packages-split</filename>
+ directory, make sure that
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+ is not enabled when you build the recipe.
+ </para>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>:
+ Lists the names of the packages that contain the given
+ paths.
+ For example, the following tells us that
+ <filename>/usr/share/man/man1/make.1</filename>
+ is contained in the <filename>make-doc</filename>
+ package:
+ <literallayout class='monospaced'>
+ $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
+ make-doc: /usr/share/man/man1/make.1
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>:
+ Lists the name of the recipes that
+ produce the given packages.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For more information on the <filename>oe-pkgdata-util</filename>
+ command, use the help facility:
+ <literallayout class='monospaced'>
+ $ oe-pkgdata-util ‐‐help
+ $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='dev-viewing-dependencies-between-recipes-and-tasks'>
+ <title>Viewing Dependencies Between Recipes and Tasks</title>
+
+ <para>
+ Sometimes it can be hard to see why BitBake wants to build other
+ recipes before the one you have specified.
+ Dependency information can help you understand why a recipe is
+ built.
+ </para>
+
+ <para>
+ To generate dependency information for a recipe, run the
+ following command:
+ <literallayout class='monospaced'>
+ $ bitbake -g <replaceable>recipename</replaceable>
+ </literallayout>
+ This command writes the following files in the current
+ directory:
+ <itemizedlist>
+ <listitem><para>
+ <filename>pn-buildlist</filename>: A list of
+ recipes/targets involved in building
+ <replaceable>recipename</replaceable>.
+ "Involved" here means that at least one task from the
+ recipe needs to run when building
+ <replaceable>recipename</replaceable> from scratch.
+ Targets that are in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></ulink>
+ are not listed.
+ </para></listitem>
+ <listitem><para>
+ <filename>task-depends.dot</filename>: A graph showing
+ dependencies between tasks.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The graphs are in
+ <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
+ format and can be converted to images (e.g. using the
+ <filename>dot</filename> tool from
+ <ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ DOT files use a plain text format.
+ The graphs generated using the
+ <filename>bitbake -g</filename> command are often so
+ large as to be difficult to read without special
+ pruning (e.g. with Bitbake's
+ <filename>-I</filename> option) and processing.
+ Despite the form and size of the graphs, the
+ corresponding <filename>.dot</filename> files can
+ still be possible to read and provide useful
+ information.
+ </para>
+
+ <para>As an example, the
+ <filename>task-depends.dot</filename> file contains
+ lines such as the following:
+ <literallayout class='monospaced'>
+ "libxslt.do_configure" -> "libxml2.do_populate_sysroot"
+ </literallayout>
+ The above example line reveals that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
+ task in <filename>libxslt</filename> depends on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
+ task in <filename>libxml2</filename>, which is a
+ normal
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ dependency between the two recipes.
+ </para></listitem>
+ <listitem><para>
+ For an example of how <filename>.dot</filename>
+ files can be processed, see the
+ <filename>scripts/contrib/graph-tool</filename>
+ Python script, which finds and displays paths
+ between graph nodes.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ You can use a different method to view dependency information
+ by using the following command:
+ <literallayout class='monospaced'>
+ $ bitbake -g -u taskexp <replaceable>recipename</replaceable>
+ </literallayout>
+ This command displays a GUI window from which you can view
+ build-time and runtime dependencies for the recipes involved in
+ building <replaceable>recipename</replaceable>.
+ </para>
+ </section>
+
+ <section id='dev-viewing-task-variable-dependencies'>
+ <title>Viewing Task Variable Dependencies</title>
+
+ <para>
+ As mentioned in the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"
+ section of the BitBake User Manual, BitBake tries to
+ automatically determine what variables a task depends on so
+ that it can rerun the task if any values of the variables
+ change.
+ This determination is usually reliable.
+ However, if you do things like construct variable names at
+ runtime, then you might have to manually declare dependencies
+ on those variables using <filename>vardeps</filename> as
+ described in the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
+ section of the BitBake User Manual.
+ </para>
+
+ <para>
+ If you are unsure whether a variable dependency is being
+ picked up automatically for a given task, you can list the
+ variable dependencies BitBake has determined by doing the
+ following:
+ <orderedlist>
+ <listitem><para>
+ Build the recipe containing the task:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>recipename</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Inside the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
+ directory, find the signature data
+ (<filename>sigdata</filename>) file that corresponds
+ to the task.
+ The <filename>sigdata</filename> files contain a pickled
+ Python database of all the metadata that went into
+ creating the input checksum for the task.
+ As an example, for the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
+ task of the <filename>db</filename> recipe, the
+ <filename>sigdata</filename> file might be found in the
+ following location:
+ <literallayout class='monospaced'>
+ ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
+ </literallayout>
+ For tasks that are accelerated through the shared state
+ (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
+ cache, an additional <filename>siginfo</filename> file
+ is written into
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ along with the cached task output.
+ The <filename>siginfo</filename> files contain exactly
+ the same information as <filename>sigdata</filename>
+ files.
+ </para></listitem>
+ <listitem><para>
+ Run <filename>bitbake-dumpsig</filename> on the
+ <filename>sigdata</filename> or
+ <filename>siginfo</filename> file.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
+ </literallayout>
+ In the output of the above command, you will find a
+ line like the following, which lists all the (inferred)
+ variable dependencies for the task.
+ This list also includes indirect dependencies from
+ variables depending on other variables, recursively.
+ <literallayout class='monospaced'>
+ Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
+ </literallayout>
+ <note>
+ Functions (e.g. <filename>base_do_fetch</filename>)
+ also count as variable dependencies.
+ These functions in turn depend on the variables they
+ reference.
+ </note>
+ The output of <filename>bitbake-dumpsig</filename> also
+ includes the value each variable had, a list of
+ dependencies for each variable, and
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>
+ information.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ There is also a <filename>bitbake-diffsigs</filename> command
+ for comparing two <filename>siginfo</filename> or
+ <filename>sigdata</filename> files.
+ This command can be helpful when trying to figure out what
+ changed between two versions of a task.
+ If you call <filename>bitbake-diffsigs</filename> with just one
+ file, the command behaves like
+ <filename>bitbake-dumpsig</filename>.
+ </para>
+
+ <para>
+ You can also use BitBake to dump out the signature construction
+ information without executing tasks by using either of the
+ following BitBake command-line options:
+ <literallayout class='monospaced'>
+ ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
+ -S <replaceable>SIGNATURE_HANDLER</replaceable>
+ </literallayout>
+ <note>
+ Two common values for
+ <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and
+ "printdiff", which dump only the signature or compare the
+ dumped signature with the cached one, respectively.
+ </note>
+ Using BitBake with either of these options causes BitBake to
+ dump out <filename>sigdata</filename> files in the
+ <filename>stamps</filename> directory for every task it would
+ have executed instead of building the specified target package.
+ </para>
+ </section>
+
+ <section id='dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>
+ <title>Viewing Metadata Used to Create the Input Signature of a Shared State Task</title>
+
+ <para>
+ Seeing what metadata went into creating the input signature
+ of a shared state (sstate) task can be a useful debugging
+ aid.
+ This information is available in signature information
+ (<filename>siginfo</filename>) files in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
+ For information on how to view and interpret information in
+ <filename>siginfo</filename> files, see the
+ "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
+ section.
+ </para>
+
+ <para>
+ For conceptual information on shared state, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>Shared State</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para>
+ </section>
+
+ <section id='dev-invalidating-shared-state-to-force-a-task-to-run'>
+ <title>Invalidating Shared State to Force a Task to Run</title>
+
+ <para>
+ The OpenEmbedded build system uses
+ <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>checksums</ulink>
+ and
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>shared state</ulink>
+ cache to avoid unnecessarily rebuilding tasks.
+ Collectively, this scheme is known as "shared state code."
+ </para>
+
+ <para>
+ As with all schemes, this one has some drawbacks.
+ It is possible that you could make implicit changes to your
+ code that the checksum calculations do not take into
+ account.
+ These implicit changes affect a task's output but do not
+ trigger the shared state code into rebuilding a recipe.
+ Consider an example during which a tool changes its output.
+ Assume that the output of <filename>rpmdeps</filename>
+ changes.
+ The result of the change should be that all the
+ <filename>package</filename> and
+ <filename>package_write_rpm</filename> shared state cache
+ items become invalid.
+ However, because the change to the output is
+ external to the code and therefore implicit,
+ the associated shared state cache items do not become
+ invalidated.
+ In this case, the build process uses the cached items
+ rather than running the task again.
+ Obviously, these types of implicit changes can cause
+ problems.
+ </para>
+
+ <para>
+ To avoid these problems during the build, you need to
+ understand the effects of any changes you make.
+ Realize that changes you make directly to a function
+ are automatically factored into the checksum calculation.
+ Thus, these explicit changes invalidate the associated
+ area of shared state cache.
+ However, you need to be aware of any implicit changes that
+ are not obvious changes to the code and could affect
+ the output of a given task.
+ </para>
+
+ <para>
+ When you identify an implicit change, you can easily
+ take steps to invalidate the cache and force the tasks
+ to run.
+ The steps you can take are as simple as changing a
+ function's comments in the source code.
+ For example, to invalidate package shared state files,
+ change the comment statements of
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ or the comments of one of the functions it calls.
+ Even though the change is purely cosmetic, it causes the
+ checksum to be recalculated and forces the build system to
+ run the task again.
+ <note>
+ For an example of a commit that makes a cosmetic
+ change to invalidate shared state, see this
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
+ </note>
+ </para>
+ </section>
+
+ <section id='dev-debugging-taskrunning'>
+ <title>Running Specific Tasks</title>
+
+ <para>
+ Any given recipe consists of a set of tasks.
+ The standard BitBake behavior in most cases is:
+ <filename>do_fetch</filename>,
+ <filename>do_unpack</filename>,
+ <filename>do_patch</filename>,
+ <filename>do_configure</filename>,
+ <filename>do_compile</filename>,
+ <filename>do_install</filename>,
+ <filename>do_package</filename>,
+ <filename>do_package_write_*</filename>, and
+ <filename>do_build</filename>.
+ The default task is <filename>do_build</filename> and any tasks
+ on which it depends build first.
+ Some tasks, such as <filename>do_devshell</filename>, are not
+ part of the default build chain.
+ If you wish to run a task that is not part of the default build
+ chain, you can use the <filename>-c</filename> option in
+ BitBake.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -c devshell
+ </literallayout>
+ </para>
+
+ <para>
+ The <filename>-c</filename> option respects task dependencies,
+ which means that all other tasks (including tasks from other
+ recipes) that the specified task depends on will be run before
+ the task.
+ Even when you manually specify a task to run with
+ <filename>-c</filename>, BitBake will only run the task if it
+ considers it "out of date".
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for
+ how BitBake determines whether a task is "out of date".
+ </para>
+
+ <para>
+ If you want to force an up-to-date task to be rerun (e.g.
+ because you made manual modifications to the recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+ that you want to try out), then you can use the
+ <filename>-f</filename> option.
+ <note>
+ The reason <filename>-f</filename> is never required when
+ running the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-devshell'><filename>do_devshell</filename></ulink>
+ task is because the
+ <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
+ variable flag is already set for the task.
+ </note>
+ The following example shows one way you can use the
+ <filename>-f</filename> option:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop
+ .
+ .
+ make some changes to the source code in the work directory
+ .
+ .
+ $ bitbake matchbox-desktop -c compile -f
+ $ bitbake matchbox-desktop
+ </literallayout>
+ </para>
+
+ <para>
+ This sequence first builds and then recompiles
+ <filename>matchbox-desktop</filename>.
+ The last command reruns all tasks (basically the packaging
+ tasks) after the compile.
+ BitBake recognizes that the <filename>do_compile</filename>
+ task was rerun and therefore understands that the other tasks
+ also need to be run again.
+ </para>
+
+ <para>
+ Another, shorter way to rerun a task and all
+ <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>
+ that depend on it is to use the <filename>-C</filename>
+ option.
+ <note>
+ This option is upper-cased and is separate from the
+ <filename>-c</filename> option, which is lower-cased.
+ </note>
+ Using this option invalidates the given task and then runs the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-build'><filename>do_build</filename></ulink>
+ task, which is the default task if no task is given, and the
+ tasks on which it depends.
+ You could replace the final two commands in the previous example
+ with the following single command:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -C compile
+ </literallayout>
+ Internally, the <filename>-f</filename> and
+ <filename>-C</filename> options work by tainting (modifying) the
+ input checksum of the specified task.
+ This tainting indirectly causes the task and its
+ dependent tasks to be rerun through the normal task dependency
+ mechanisms.
+ <note>
+ BitBake explicitly keeps track of which tasks have been
+ tainted in this fashion, and will print warnings such as the
+ following for builds involving such tasks:
+ <literallayout class='monospaced'>
+ WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
+ </literallayout>
+ The purpose of the warning is to let you know that the work
+ directory and build output might not be in the clean state
+ they would be in for a "normal" build, depending on what
+ actions you took.
+ To get rid of such warnings, you can remove the work
+ directory and rebuild the recipe, as follows:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -c clean
+ $ bitbake matchbox-desktop
+ </literallayout>
+ </note>
+ </para>
+
+ <para>
+ You can view a list of tasks in a given package by running the
+ <filename>do_listtasks</filename> task as follows:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -c listtasks
+ </literallayout>
+ The results appear as output to the console and are also in the
+ file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
+ </para>
+ </section>
+
+ <section id='dev-debugging-bitbake'>
+ <title>General BitBake Problems</title>
+
+ <para>
+ You can see debug output from BitBake by using the
+ <filename>-D</filename> option.
+ The debug output gives more information about what BitBake
+ is doing and the reason behind it.
+ Each <filename>-D</filename> option you use increases the
+ logging level.
+ The most common usage is <filename>-DDD</filename>.
+ </para>
+
+ <para>
+ The output from
+ <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable>
+ can reveal why BitBake chose a certain version of a package or
+ why BitBake picked a certain provider.
+ This command could also help you in a situation where you think
+ BitBake did something unexpected.
+ </para>
+ </section>
+
+ <section id='dev-debugging-buildfile'>
+ <title>Building with No Dependencies</title>
+
+ <para>
+ To build a specific recipe (<filename>.bb</filename> file),
+ you can use the following command form:
+ <literallayout class='monospaced'>
+ $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
+ </literallayout>
+ This command form does not check for dependencies.
+ Consequently, you should use it only when you know existing
+ dependencies have been met.
+ <note>
+ You can also specify fragments of the filename.
+ In this case, BitBake checks for a unique match.
+ </note>
+ </para>
+ </section>
+
+ <section id='recipe-logging-mechanisms'>
+ <title>Recipe Logging Mechanisms</title>
+
+ <para>
+ The Yocto Project provides several logging functions for
+ producing debugging output and reporting errors and warnings.
+ For Python functions, the following logging functions exist.
+ All of these functions log to
+ <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
+ and can also log to standard output (stdout) with the right
+ settings:
+ <itemizedlist>
+ <listitem><para>
+ <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes <replaceable>msg</replaceable> as is to the
+ log while also logging to stdout.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "NOTE: <replaceable>msg</replaceable>" to the
+ log.
+ Also logs to stdout if BitBake is called with "-v".
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "DEBUG: <replaceable>msg</replaceable>" to the
+ log.
+ Also logs to stdout if the log level is greater than or
+ equal to <replaceable>level</replaceable>.
+ See the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
+ option in the BitBake User Manual for more information.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "WARNING: <replaceable>msg</replaceable>" to the
+ log while also logging to stdout.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "ERROR: <replaceable>msg</replaceable>" to the
+ log while also logging to standard out (stdout).
+ <note>
+ Calling this function does not cause the task to fail.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ This logging function is similar to
+ <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
+ but also causes the calling task to fail.
+ <note>
+ <filename>bb.fatal()</filename> raises an exception,
+ which means you do not need to put a "return"
+ statement after the function.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The same logging functions are also available in shell
+ functions, under the names
+ <filename>bbplain</filename>, <filename>bbnote</filename>,
+ <filename>bbdebug</filename>, <filename>bbwarn</filename>,
+ <filename>bberror</filename>, and <filename>bbfatal</filename>.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-logging'><filename>logging</filename></ulink>
+ class implements these functions.
+ See that class in the
+ <filename>meta/classes</filename> folder of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ for information.
+ </para>
+
+ <section id='logging-with-python'>
+ <title>Logging With Python</title>
+
+ <para>
+ When creating recipes using Python and inserting code that
+ handles build logs, keep in mind the goal is to have
+ informative logs while keeping the console as "silent" as
+ possible.
+ Also, if you want status messages in the log, use the
+ "debug" loglevel.
+ </para>
+
+ <para>
+ Following is an example written in Python.
+ The code handles logging for a function that determines the
+ number of tasks needed to be run.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-listtasks'><filename>do_listtasks</filename></ulink>"
+ section for additional information:
+ <literallayout class='monospaced'>
+ python do_listtasks() {
+ bb.debug(2, "Starting to figure out the task list")
+ if noteworthy_condition:
+ bb.note("There are 47 tasks to run")
+ bb.debug(2, "Got to point xyz")
+ if warning_trigger:
+ bb.warn("Detected warning_trigger, this might be a problem later.")
+ if recoverable_error:
+ bb.error("Hit recoverable_error, you really need to fix this!")
+ if fatal_error:
+ bb.fatal("fatal_error detected, unable to print the task list")
+ bb.plain("The tasks present are abc")
+ bb.debug(2, "Finished figuring out the tasklist")
+ }
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='logging-with-bash'>
+ <title>Logging With Bash</title>
+
+ <para>
+ When creating recipes using Bash and inserting code that
+ handles build logs, you have the same goals - informative
+ with minimal console output.
+ The syntax you use for recipes written in Bash is similar
+ to that of recipes written in Python described in the
+ previous section.
+ </para>
+
+ <para>
+ Following is an example written in Bash.
+ The code logs the progress of the <filename>do_my_function</filename> function.
+ <literallayout class='monospaced'>
+ do_my_function() {
+ bbdebug 2 "Running do_my_function"
+ if [ exceptional_condition ]; then
+ bbnote "Hit exceptional_condition"
+ fi
+ bbdebug 2 "Got to point xyz"
+ if [ warning_trigger ]; then
+ bbwarn "Detected warning_trigger, this might cause a problem later."
+ fi
+ if [ recoverable_error ]; then
+ bberror "Hit recoverable_error, correcting"
+ fi
+ if [ fatal_error ]; then
+ bbfatal "fatal_error detected"
+ fi
+ bbdebug 2 "Completed do_my_function"
+ }
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+ <section id='debugging-parallel-make-races'>
+ <title>Debugging Parallel Make Races</title>
+
+ <para>
+ A parallel <filename>make</filename> race occurs when the build
+ consists of several parts that are run simultaneously and
+ a situation occurs when the output or result of one
+ part is not ready for use with a different part of the build
+ that depends on that output.
+ Parallel make races are annoying and can sometimes be difficult
+ to reproduce and fix.
+ However, some simple tips and tricks exist that can help
+ you debug and fix them.
+ This section presents a real-world example of an error
+ encountered on the Yocto Project autobuilder and the process
+ used to fix it.
+ <note>
+ If you cannot properly fix a <filename>make</filename> race
+ condition, you can work around it by clearing either the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
+ variables.
+ </note>
+ </para>
+
+ <section id='the-failure'>
+ <title>The Failure</title>
+
+ <para>
+ For this example, assume that you are building an image that
+ depends on the "neard" package.
+ And, during the build, BitBake runs into problems and
+ creates the following output.
+ <note>
+ This example log file has longer lines artificially
+ broken to make the listing easier to read.
+ </note>
+ If you examine the output or the log file, you see the
+ failure during <filename>make</filename>:
+ <literallayout class='monospaced'>
| DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
| DEBUG: Executing shell function do_compile
| NOTE: make -j 16
@@ -10194,61 +13170,62 @@
| make[1]: *** Waiting for unfinished jobs....
| make: *** [all] Error 2
| ERROR: oe_runmake failed
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='reproducing-the-error'>
- <title>Reproducing the Error</title>
+ <section id='reproducing-the-error'>
+ <title>Reproducing the Error</title>
- <para>
- Because race conditions are intermittent, they do not
- manifest themselves every time you do the build.
- In fact, most times the build will complete without problems
- even though the potential race condition exists.
- Thus, once the error surfaces, you need a way to reproduce it.
- </para>
+ <para>
+ Because race conditions are intermittent, they do not
+ manifest themselves every time you do the build.
+ In fact, most times the build will complete without problems
+ even though the potential race condition exists.
+ Thus, once the error surfaces, you need a way to reproduce
+ it.
+ </para>
- <para>
- In this example, compiling the "neard" package is causing the
- problem.
- So the first thing to do is build "neard" locally.
- Before you start the build, set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
- variable in your <filename>local.conf</filename> file to
- a high number (e.g. "-j 20").
- Using a high value for <filename>PARALLEL_MAKE</filename>
- increases the chances of the race condition showing up:
- <literallayout class='monospaced'>
+ <para>
+ In this example, compiling the "neard" package is causing
+ the problem.
+ So the first thing to do is build "neard" locally.
+ Before you start the build, set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
+ variable in your <filename>local.conf</filename> file to
+ a high number (e.g. "-j 20").
+ Using a high value for <filename>PARALLEL_MAKE</filename>
+ increases the chances of the race condition showing up:
+ <literallayout class='monospaced'>
$ bitbake neard
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- Once the local build for "neard" completes, start a
- <filename>devshell</filename> build:
- <literallayout class='monospaced'>
+ <para>
+ Once the local build for "neard" completes, start a
+ <filename>devshell</filename> build:
+ <literallayout class='monospaced'>
$ bitbake neard -c devshell
- </literallayout>
- For information on how to use a
- <filename>devshell</filename>, see the
- "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
- section.
- </para>
+ </literallayout>
+ For information on how to use a
+ <filename>devshell</filename>, see the
+ "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
+ section.
+ </para>
- <para>
- In the <filename>devshell</filename>, do the following:
- <literallayout class='monospaced'>
+ <para>
+ In the <filename>devshell</filename>, do the following:
+ <literallayout class='monospaced'>
$ make clean
$ make tools/snep-send.o
- </literallayout>
- The <filename>devshell</filename> commands cause the failure
- to clearly be visible.
- In this case, a missing dependency exists for the "neard"
- Makefile target.
- Here is some abbreviated, sample output with the
- missing dependency clearly visible at the end:
- <literallayout class='monospaced'>
+ </literallayout>
+ The <filename>devshell</filename> commands cause the failure
+ to clearly be visible.
+ In this case, a missing dependency exists for the "neard"
+ Makefile target.
+ Here is some abbreviated, sample output with the
+ missing dependency clearly visible at the end:
+ <literallayout class='monospaced'>
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
.
.
@@ -10261,238 +13238,1687 @@
compilation terminated.
make: *** [tools/snep-send.o] Error 1
$
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='creating-a-patch-for-the-fix'>
- <title>Creating a Patch for the Fix</title>
+ <section id='creating-a-patch-for-the-fix'>
+ <title>Creating a Patch for the Fix</title>
- <para>
- Because there is a missing dependency for the Makefile
- target, you need to patch the
- <filename>Makefile.am</filename> file, which is generated
- from <filename>Makefile.in</filename>.
- You can use Quilt to create the patch:
- <literallayout class='monospaced'>
+ <para>
+ Because there is a missing dependency for the Makefile
+ target, you need to patch the
+ <filename>Makefile.am</filename> file, which is generated
+ from <filename>Makefile.in</filename>.
+ You can use Quilt to create the patch:
+ <literallayout class='monospaced'>
$ quilt new parallelmake.patch
Patch patches/parallelmake.patch is now on top
$ quilt add Makefile.am
File Makefile.am added to patch patches/parallelmake.patch
- </literallayout>
- For more information on using Quilt, see the
- "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
- section.
- </para>
+ </literallayout>
+ For more information on using Quilt, see the
+ "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
+ section.
+ </para>
- <para>
- At this point you need to make the edits to
- <filename>Makefile.am</filename> to add the missing
- dependency.
- For our example, you have to add the following line
- to the file:
- <literallayout class='monospaced'>
+ <para>
+ At this point you need to make the edits to
+ <filename>Makefile.am</filename> to add the missing
+ dependency.
+ For our example, you have to add the following line
+ to the file:
+ <literallayout class='monospaced'>
tools/snep-send.$(OBJEXT): include/near/dbus.h
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- Once you have edited the file, use the
- <filename>refresh</filename> command to create the patch:
- <literallayout class='monospaced'>
+ <para>
+ Once you have edited the file, use the
+ <filename>refresh</filename> command to create the patch:
+ <literallayout class='monospaced'>
$ quilt refresh
Refreshed patch patches/parallelmake.patch
- </literallayout>
- Once the patch file exists, you need to add it back to the
- originating recipe folder.
- Here is an example assuming a top-level
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- named <filename>poky</filename>:
- <literallayout class='monospaced'>
+ </literallayout>
+ Once the patch file exists, you need to add it back to the
+ originating recipe folder.
+ Here is an example assuming a top-level
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ named <filename>poky</filename>:
+ <literallayout class='monospaced'>
$ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
- </literallayout>
- The final thing you need to do to implement the fix in the
- build is to update the "neard" recipe (i.e.
- <filename>neard-0.14.bb</filename>) so that the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statement includes the patch file.
- The recipe file is in the folder above the patch.
- Here is what the edited <filename>SRC_URI</filename>
- statement would look like:
- <literallayout class='monospaced'>
+ </literallayout>
+ The final thing you need to do to implement the fix in the
+ build is to update the "neard" recipe (i.e.
+ <filename>neard-0.14.bb</filename>) so that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statement includes the patch file.
+ The recipe file is in the folder above the patch.
+ Here is what the edited <filename>SRC_URI</filename>
+ statement would look like:
+ <literallayout class='monospaced'>
SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
file://neard.in \
file://neard.service.in \
file://parallelmake.patch \
"
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- With the patch complete and moved to the correct folder and
- the <filename>SRC_URI</filename> statement updated, you can
- exit the <filename>devshell</filename>:
- <literallayout class='monospaced'>
+ <para>
+ With the patch complete and moved to the correct folder and
+ the <filename>SRC_URI</filename> statement updated, you can
+ exit the <filename>devshell</filename>:
+ <literallayout class='monospaced'>
$ exit
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='testing-the-build'>
- <title>Testing the Build</title>
+ <section id='testing-the-build'>
+ <title>Testing the Build</title>
- <para>
- With everything in place, you can get back to trying the
- build again locally:
- <literallayout class='monospaced'>
+ <para>
+ With everything in place, you can get back to trying the
+ build again locally:
+ <literallayout class='monospaced'>
$ bitbake neard
- </literallayout>
- This build should succeed.
- </para>
+ </literallayout>
+ This build should succeed.
+ </para>
- <para>
- Now you can open up a <filename>devshell</filename> again
- and repeat the clean and make operations as follows:
- <literallayout class='monospaced'>
+ <para>
+ Now you can open up a <filename>devshell</filename> again
+ and repeat the clean and make operations as follows:
+ <literallayout class='monospaced'>
$ bitbake neard -c devshell
$ make clean
$ make tools/snep-send.o
- </literallayout>
- The build should work without issue.
+ </literallayout>
+ The build should work without issue.
+ </para>
+
+ <para>
+ As with all solved problems, if they originated upstream,
+ you need to submit the fix for the recipe in OE-Core and
+ upstream so that the problem is taken care of at its
+ source.
+ See the
+ "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+ section for more information.
+ </para>
+ </section>
+ </section>
+
+ <section id="platdev-gdb-remotedebug">
+ <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+
+ <para>
+ GDB allows you to examine running programs, which in turn helps
+ you to understand and fix problems.
+ It also allows you to perform post-mortem style analysis of
+ program crashes.
+ GDB is available as a package within the Yocto Project and is
+ installed in SDK images by default.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual for a description of
+ these images.
+ You can find information on GDB at
+ <ulink url="http://sourceware.org/gdb/"/>.
+ <note><title>Tip</title>
+ For best results, install debug (<filename>-dbg</filename>)
+ packages for the applications you are going to debug.
+ Doing so makes extra debug symbols available that give you
+ more meaningful output.
+ </note>
</para>
<para>
- As with all solved problems, if they originated upstream, you
- need to submit the fix for the recipe in OE-Core and upstream
- so that the problem is taken care of at its source.
- See the
- "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
- section for more information.
+ Sometimes, due to memory or disk space constraints, it is not
+ possible to use GDB directly on the remote target to debug
+ applications.
+ These constraints arise because GDB needs to load the debugging
+ information and the binaries of the process being debugged.
+ Additionally, GDB needs to perform many computations to locate
+ information such as function names, variable names and values,
+ stack traces and so forth - even before starting the debugging
+ process.
+ These extra computations place more load on the target system
+ and can alter the characteristics of the program being debugged.
+ </para>
+
+ <para>
+ To help get past the previously mentioned constraints, you can
+ use gdbserver, which runs on the remote target and does not
+ load any debugging information from the debugged process.
+ Instead, a GDB instance processes the debugging information that
+ is run on a remote computer - the host GDB.
+ The host GDB then sends control commands to gdbserver to make
+ it stop or start the debugged program, as well as read or write
+ memory regions of that debugged program.
+ All the debugging information loaded and processed as well
+ as all the heavy debugging is done by the host GDB.
+ Offloading these processes gives the gdbserver running on the
+ target a chance to remain small and fast.
+ </para>
+
+ <para>
+ Because the host GDB is responsible for loading the debugging
+ information and for doing the necessary processing to make
+ actual debugging happen, you have to make sure the host can
+ access the unstripped binaries complete with their debugging
+ information and also be sure the target is compiled with no
+ optimizations.
+ The host GDB must also have local access to all the libraries
+ used by the debugged program.
+ Because gdbserver does not need any local debugging information,
+ the binaries on the remote target can remain stripped.
+ However, the binaries must also be compiled without optimization
+ so they match the host's binaries.
+ </para>
+
+ <para>
+ To remain consistent with GDB documentation and terminology,
+ the binary being debugged on the remote target machine is
+ referred to as the "inferior" binary.
+ For documentation on GDB see the
+ <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
+ </para>
+
+ <para>
+ The following steps show you how to debug using the GNU project
+ debugger.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Configure your build system to construct the
+ companion debug filesystem:</emphasis></para>
+
+ <para>In your <filename>local.conf</filename> file, set
+ the following:
+ <literallayout class='monospaced'>
+ IMAGE_GEN_DEBUGFS = "1"
+ IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
+ </literallayout>
+ These options cause the OpenEmbedded build system
+ to generate a special companion filesystem fragment,
+ which contains the matching source and debug symbols to
+ your deployable filesystem.
+ The build system does this by looking at what is in the
+ deployed filesystem, and pulling the corresponding
+ <filename>-dbg</filename> packages.</para>
+
+ <para>The companion debug filesystem is not a complete
+ filesystem, but only contains the debug fragments.
+ This filesystem must be combined with the full filesystem
+ for debugging.
+ Subsequent steps in this procedure show how to combine
+ the partial filesystem with the full filesystem.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Configure the system to include gdbserver in
+ the target filesystem:</emphasis></para>
+
+ <para>Make the following addition in either your
+ <filename>local.conf</filename> file or in an image
+ recipe:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = “ gdbserver"
+ </literallayout>
+ The change makes sure the <filename>gdbserver</filename>
+ package is included.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the environment:</emphasis></para>
+
+ <para>Use the following command to construct the image
+ and the companion Debug Filesystem:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>image</replaceable>
+ </literallayout>
+ Build the cross GDB component and make it available
+ for debugging.
+ Build the SDK that matches the image.
+ Building the SDK is best for a production build
+ that can be used later for debugging, especially
+ during long term maintenance:
+ <literallayout class='monospaced'>
+ $ bitbake -c populate_sdk <replaceable>image</replaceable>
+ </literallayout></para>
+
+ <para>Alternatively, you can build the minimal
+ toolchain components that match the target.
+ Doing so creates a smaller than typical SDK and only
+ contains a minimal set of components with which to
+ build simple test applications, as well as run the
+ debugger:
+ <literallayout class='monospaced'>
+ $ bitbake meta-toolchain
+ </literallayout></para>
+
+ <para>A final method is to build Gdb itself within
+ the build system:
+ <literallayout class='monospaced'>
+ $ bitbake gdb-cross-<replaceable>architecture</replaceable>
+ </literallayout>
+ Doing so produces a temporary copy of
+ <filename>cross-gdb</filename> you can use for
+ debugging during development.
+ While this is the quickest approach, the two previous
+ methods in this step are better when considering
+ long-term maintenance strategies.
+ <note>
+ If you run
+ <filename>bitbake gdb-cross</filename>, the
+ OpenEmbedded build system suggests the actual
+ image (e.g. <filename>gdb-cross-i586</filename>).
+ The suggestion is usually the actual name you want
+ to use.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up the</emphasis> <filename>debugfs</filename></para>
+
+ <para>Run the following commands to set up the
+ <filename>debugfs</filename>:
+ <literallayout class='monospaced'>
+ $ mkdir debugfs
+ $ cd debugfs
+ $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
+ $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up GDB</emphasis></para>
+
+ <para>Install the SDK (if you built one) and then
+ source the correct environment file.
+ Sourcing the environment file puts the SDK in your
+ <filename>PATH</filename> environment variable.</para>
+
+ <para>If you are using the build system, Gdb is
+ located in
+ <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Boot the target:</emphasis></para>
+
+ <para>For information on how to run QEMU, see the
+ <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
+ <note>
+ Be sure to verify that your host can access the
+ target via TCP.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Debug a program:</emphasis></para>
+
+ <para>Debugging a program involves running gdbserver
+ on the target and then running Gdb on the host.
+ The example in this step debugs
+ <filename>gzip</filename>:
+ <literallayout class='monospaced'>
+ root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
+ </literallayout>
+ For additional gdbserver options, see the
+ <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
+ </para>
+
+ <para>After running gdbserver on the target, you need
+ to run Gdb on the host and configure it and connect to
+ the target.
+ Use these commands:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
+ $ <replaceable>arch</replaceable>-gdb
+
+ (gdb) set sysroot debugfs
+ (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
+ (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
+ </literallayout>
+ At this point, everything should automatically load
+ (i.e. matching binaries, symbols and headers).
+ <note>
+ The Gdb <filename>set</filename> commands in the
+ previous example can be placed into the users
+ <filename>~/.gdbinit</filename> file.
+ Upon starting, Gdb automatically runs whatever
+ commands are in that file.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Deploying without a full image
+ rebuild:</emphasis></para>
+
+ <para>In many cases, during development you want a
+ quick method to deploy a new binary to the target and
+ debug it, without waiting for a full image build.
+ </para>
+
+ <para>One approach to solving this situation is to
+ just build the component you want to debug.
+ Once you have built the component, copy the
+ executable directly to both the target and the
+ host <filename>debugfs</filename>.</para>
+
+ <para>If the binary is processed through the debug
+ splitting in OpenEmbedded, you should also
+ copy the debug items (i.e. <filename>.debug</filename>
+ contents and corresponding
+ <filename>/usr/src/debug</filename> files)
+ from the work directory.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake bash
+ $ bitbake -c devshell bash
+ $ cd ..
+ $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
+ $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
+ <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
+
+ <para>
+ The previous section addressed using GDB remotely for debugging
+ purposes, which is the most usual case due to the inherent
+ hardware limitations on many embedded devices.
+ However, debugging in the target hardware itself is also
+ possible with more powerful devices.
+ This section describes what you need to do in order to support
+ using GDB to debug on the target hardware.
+ </para>
+
+ <para>
+ To support this kind of debugging, you need do the following:
+ <itemizedlist>
+ <listitem><para>
+ Ensure that GDB is on the target.
+ You can do this by adding "gdb" to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = " gdb"
+ </literallayout>
+ Alternatively, you can add "tools-debug" to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
+ <literallayout class='monospaced'>
+ IMAGE_FEATURES_append = " tools-debug"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Ensure that debug symbols are present.
+ You can make sure these symbols are present by
+ installing <filename>-dbg</filename>:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
+ </literallayout>
+ Alternatively, you can do the following to include all
+ the debug symbols:
+ <literallayout class='monospaced'>
+ IMAGE_FEATURES_append = " dbg-pkgs"
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ To improve the debug information accuracy, you can reduce
+ the level of optimization used by the compiler.
+ For example, when adding the following line to your
+ <filename>local.conf</filename> file, you will reduce
+ optimization from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
+ of "-O2" to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
+ of "-O -fno-omit-frame-pointer":
+ <literallayout class='monospaced'>
+ DEBUG_BUILD = "1"
+ </literallayout>
+ Consider that this will reduce the application's performance
+ and is recommended only for debugging purposes.
+ </note>
+ </para>
+ </section>
+
+ <section id='dev-other-debugging-others'>
+ <title>Other Debugging Tips</title>
+
+ <para>
+ Here are some other tips that you might find useful:
+ <itemizedlist>
+ <listitem><para>
+ When adding new packages, it is worth watching for
+ undesirable items making their way into compiler command
+ lines.
+ For example, you do not want references to local system
+ files like
+ <filename>/usr/lib/</filename> or
+ <filename>/usr/include/</filename>.
+ </para></listitem>
+ <listitem><para>
+ If you want to remove the <filename>psplash</filename>
+ boot splashscreen,
+ add <filename>psplash=false</filename> to the kernel
+ command line.
+ Doing so prevents <filename>psplash</filename> from
+ loading and thus allows you to see the console.
+ It is also possible to switch out of the splashscreen by
+ switching the virtual console (e.g. Fn+Left or Fn+Right
+ on a Zaurus).
+ </para></listitem>
+ <listitem><para>
+ Removing
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ (usually <filename>tmp/</filename>, within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>)
+ can often fix temporary build issues.
+ Removing <filename>TMPDIR</filename> is usually a
+ relatively cheap operation, because task output will be
+ cached in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ (usually <filename>sstate-cache/</filename>, which is
+ also in the Build Directory).
+ <note>
+ Removing <filename>TMPDIR</filename> might be a
+ workaround rather than a fix.
+ Consequently, trying to determine the underlying
+ cause of an issue before removing the directory is
+ a good idea.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Understanding how a feature is used in practice within
+ existing recipes can be very helpful.
+ It is recommended that you configure some method that
+ allows you to quickly search through files.</para>
+
+ <para>Using GNU Grep, you can use the following shell
+ function to recursively search through common
+ recipe-related files, skipping binary files,
+ <filename>.git</filename> directories, and the
+ Build Directory (assuming its name starts with
+ "build"):
+ <literallayout class='monospaced'>
+ g() {
+ grep -Ir \
+ --exclude-dir=.git \
+ --exclude-dir='build*' \
+ --include='*.bb*' \
+ --include='*.inc*' \
+ --include='*.conf*' \
+ --include='*.py*' \
+ "$@"
+ }
+ </literallayout>
+ Following are some usage examples:
+ <literallayout class='monospaced'>
+ $ g FOO # Search recursively for "FOO"
+ $ g -i foo # Search recursively for "foo", ignoring case
+ $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"
+ </literallayout>
+ If figuring out how some feature works requires a lot of
+ searching, it might indicate that the documentation
+ should be extended or improved.
+ In such cases, consider filing a documentation bug using
+ the Yocto Project implementation of
+ <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
+ For information on how to submit a bug against
+ the Yocto Project, see the Yocto Project Bugzilla
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>
+ and the
+ "<link linkend='submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</link>"
+ section.
+ <note>
+ The manuals might not be the right place to document
+ variables that are purely internal and have a
+ limited scope (e.g. internal variables used to
+ implement a single <filename>.bbclass</filename>
+ file).
+ </note>
+ </para></listitem>
+ </itemizedlist>
</para>
</section>
</section>
- <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
- <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
+ <section id='making-changes-to-the-yocto-project'>
+ <title>Making Changes to the Yocto Project</title>
<para>
- One of the concerns for a development organization using open source
- software is how to maintain compliance with various open source
- licensing during the lifecycle of the product.
- While this section does not provide legal advice or
- comprehensively cover all scenarios, it does
- present methods that you can use to
- assist you in meeting the compliance requirements during a software
- release.
+ Because the Yocto Project is an open-source, community-based
+ project, you can effect changes to the project.
+ This section presents procedures that show you how to submit
+ a defect against the project and how to submit a change.
</para>
- <para>
- With hundreds of different open source licenses that the Yocto
- Project tracks, it is difficult to know the requirements of each
- and every license.
- However, the requirements of the major FLOSS licenses can begin
- to be covered by
- assuming that three main areas of concern exist:
- <itemizedlist>
- <listitem><para>Source code must be provided.</para></listitem>
- <listitem><para>License text for the software must be
- provided.</para></listitem>
- <listitem><para>Compilation scripts and modifications to the
- source code must be provided.
- </para></listitem>
- </itemizedlist>
- There are other requirements beyond the scope of these
- three and the methods described in this section
- (e.g. the mechanism through which source code is distributed).
- </para>
-
- <para>
- As different organizations have different methods of complying with
- open source licensing, this section is not meant to imply that
- there is only one single way to meet your compliance obligations,
- but rather to describe one method of achieving compliance.
- The remainder of this section describes methods supported to meet the
- previously mentioned three requirements.
- Once you take steps to meet these requirements,
- and prior to releasing images, sources, and the build system,
- you should audit all artifacts to ensure completeness.
- <note>
- The Yocto Project generates a license manifest during
- image creation that is located
- in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
- to assist with any audits.
- </note>
- </para>
-
- <section id='providing-the-source-code'>
- <title>Providing the Source Code</title>
+ <section id='submitting-a-defect-against-the-yocto-project'>
+ <title>Submitting a Defect Against the Yocto Project</title>
<para>
- Compliance activities should begin before you generate the
- final image.
- The first thing you should look at is the requirement that
- tops the list for most compliance groups - providing
- the source.
- The Yocto Project has a few ways of meeting this
- requirement.
+ Use the Yocto Project implementation of
+ <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
+ to submit a defect (bug) against the Yocto Project.
+ For additional information on this implementation of Bugzilla see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
+ section in the Yocto Project Reference Manual.
+ For more detail on any of the following steps, see the Yocto Project
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
</para>
<para>
- One of the easiest ways to meet this requirement is
- to provide the entire
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
- used by the build.
- This method, however, has a few issues.
- The most obvious is the size of the directory since it includes
- all sources used in the build and not just the source used in
- the released image.
- It will include toolchain source, and other artifacts, which
- you would not generally release.
- However, the more serious issue for most companies is accidental
- release of proprietary software.
- The Yocto Project provides an
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
- class to help avoid some of these concerns.
+ Use the following general steps to submit a bug"
+
+ <orderedlist>
+ <listitem><para>
+ Open the Yocto Project implementation of
+ <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
+ </para></listitem>
+ <listitem><para>
+ Click "File a Bug" to enter a new bug.
+ </para></listitem>
+ <listitem><para>
+ Choose the appropriate "Classification", "Product", and
+ "Component" for which the bug was found.
+ Bugs for the Yocto Project fall into one of several
+ classifications, which in turn break down into several
+ products and components.
+ For example, for a bug against the
+ <filename>meta-intel</filename> layer, you would choose
+ "Build System, Metadata & Runtime", "BSPs", and
+ "bsps-meta-intel", respectively.
+ </para></listitem>
+ <listitem><para>
+ Choose the "Version" of the Yocto Project for which you found
+ the bug (e.g. &DISTRO;).
+ </para></listitem>
+ <listitem><para>
+ Determine and select the "Severity" of the bug.
+ The severity indicates how the bug impacted your work.
+ </para></listitem>
+ <listitem><para>
+ Choose the "Hardware" that the bug impacts.
+ </para></listitem>
+ <listitem><para>
+ Choose the "Architecture" that the bug impacts.
+ </para></listitem>
+ <listitem><para>
+ Choose a "Documentation change" item for the bug.
+ Fixing a bug might or might not affect the Yocto Project
+ documentation.
+ If you are unsure of the impact to the documentation, select
+ "Don't Know".
+ </para></listitem>
+ <listitem><para>
+ Provide a brief "Summary" of the bug.
+ Try to limit your summary to just a line or two and be sure
+ to capture the essence of the bug.
+ </para></listitem>
+ <listitem><para>
+ Provide a detailed "Description" of the bug.
+ You should provide as much detail as you can about the context,
+ behavior, output, and so forth that surrounds the bug.
+ You can even attach supporting files for output from logs by
+ using the "Add an attachment" button.
+ </para></listitem>
+ <listitem><para>
+ Click the "Submit Bug" button submit the bug.
+ A new Bugzilla number is assigned to the bug and the defect
+ is logged in the bug tracking system.
+ </para></listitem>
+ </orderedlist>
+ Once you file a bug, the bug is processed by the Yocto Project Bug
+ Triage Team and further details concerning the bug are assigned
+ (e.g. priority and owner).
+ You are the "Submitter" of the bug and any further categorization,
+ progress, or comments on the bug result in Bugzilla sending you an
+ automated email concerning the particular change or progress to the
+ bug.
+ </para>
+ </section>
+
+ <section id='how-to-submit-a-change'>
+ <title>Submitting a Change to the Yocto Project</title>
+
+ <para>
+ Contributions to the Yocto Project and OpenEmbedded are very welcome.
+ Because the system is extremely configurable and flexible, we recognize
+ that developers will want to extend, configure or optimize it for
+ their specific uses.
</para>
<para>
- Before you employ <filename>DL_DIR</filename> or the
- <filename>archiver</filename> class, you need to decide how
- you choose to provide source.
- The source <filename>archiver</filename> class can generate
- tarballs and SRPMs and can create them with various levels of
- compliance in mind.
+ The Yocto Project uses a mailing list and a patch-based workflow
+ that is similar to the Linux kernel but contains important
+ differences.
+ In general, a mailing list exists through which you can submit
+ patches.
+ You should send patches to the appropriate mailing list so that they
+ can be reviewed and merged by the appropriate maintainer.
+ The specific mailing list you need to use depends on the
+ location of the code you are changing.
+ Each component (e.g. layer) should have a
+ <filename>README</filename> file that indicates where to send
+ the changes and which process to follow.
</para>
<para>
- One way of doing this (but certainly not the only way) is to
- release just the source as a tarball.
- You can do this by adding the following to the
- <filename>local.conf</filename> file found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ You can send the patch to the mailing list using whichever approach
+ you feel comfortable with to generate the patch.
+ Once sent, the patch is usually reviewed by the community at large.
+ If somebody has concerns with the patch, they will usually voice
+ their concern over the mailing list.
+ If a patch does not receive any negative reviews, the maintainer of
+ the affected layer typically takes the patch, tests it, and then
+ based on successful testing, merges the patch.
+ </para>
+
+ <para id='figuring-out-the-mailing-list-to-use'>
+ The "poky" repository, which is the Yocto Project's reference build
+ environment, is a hybrid repository that contains several
+ individual pieces (e.g. BitBake, Metadata, documentation,
+ and so forth) built using the combo-layer tool.
+ The upstream location used for submitting changes varies by
+ component:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Core Metadata:</emphasis>
+ Send your patch to the
+ <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
+ mailing list. For example, a change to anything under
+ the <filename>meta</filename> or
+ <filename>scripts</filename> directories should be sent
+ to this mailing list.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>BitBake:</emphasis>
+ For changes to BitBake (i.e. anything under the
+ <filename>bitbake</filename> directory), send your patch
+ to the
+ <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
+ mailing list.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>"meta-*" trees:</emphasis>
+ These trees contain Metadata.
+ Use the
+ <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
+ mailing list.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For changes to other layers hosted in the Yocto Project source
+ repositories (i.e. <filename>yoctoproject.org</filename>), tools,
+ and the Yocto Project documentation, use the
+ <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
+ general mailing list.
+ <note>
+ Sometimes a layer's documentation specifies to use a
+ particular mailing list.
+ If so, use that list.
+ </note>
+ For additional recipes that do not fit into the core Metadata, you
+ should determine which layer the recipe should go into and submit
+ the change in the manner recommended by the documentation (e.g.
+ the <filename>README</filename> file) supplied with the layer.
+ If in doubt, please ask on the Yocto general mailing list or on
+ the openembedded-devel mailing list.
+ </para>
+
+ <para>
+ You can also push a change upstream and request a maintainer to
+ pull the change into the component's upstream repository.
+ You do this by pushing to a contribution repository that is upstream.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for additional
+ concepts on working in the Yocto Project development environment.
+ </para>
+
+ <para>
+ Two commonly used testing repositories exist for
+ OpenEmbedded-Core:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>"ross/mut" branch:</emphasis>
+ The "mut" (master-under-test) tree
+ exists in the <filename>poky-contrib</filename> repository
+ in the
+ <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>"master-next" branch:</emphasis>
+ This branch is part of the main
+ "poky" repository in the Yocto Project source repositories.
+ </para></listitem>
+ </itemizedlist>
+ Maintainers use these branches to test submissions prior to merging
+ patches.
+ Thus, you can get an idea of the status of a patch based on
+ whether the patch has been merged into one of these branches.
+ <note>
+ This system is imperfect and changes can sometimes get lost in the
+ flow.
+ Asking about the status of a patch or change is reasonable if the
+ change has been idle for a while with no feedback.
+ The Yocto Project does have plans to use
+ <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
+ to track the status of patches and also to automatically preview
+ patches.
+ </note>
+ </para>
+
+ <para>
+ The following sections provide procedures for submitting a change.
+ </para>
+
+ <section id='pushing-a-change-upstream'>
+ <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
+
+ <para>
+ Follow this procedure to push a change to an upstream "contrib"
+ Git repository:
+ <note>
+ You can find general Git information on how to push a change
+ upstream in the
+ <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Make Your Changes Locally:</emphasis>
+ Make your changes in your local Git repository.
+ You should make small, controlled, isolated changes.
+ Keeping changes small and isolated aids review,
+ makes merging/rebasing easier and keeps the change
+ history clean should anyone need to refer to it in
+ future.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Stage Your Changes:</emphasis>
+ Stage your changes by using the <filename>git add</filename>
+ command on each file you changed.
+ </para></listitem>
+ <listitem><para id='making-sure-you-have-correct-commit-information'>
+ <emphasis>Commit Your Changes:</emphasis>
+ Commit the change by using the
+ <filename>git commit</filename> command.
+ Make sure your commit information follows standards by
+ following these accepted conventions:
+ <itemizedlist>
+ <listitem><para>
+ Be sure to include a "Signed-off-by:" line in the
+ same style as required by the Linux kernel.
+ Adding this line signifies that you, the submitter,
+ have agreed to the Developer's Certificate of
+ Origin 1.1 as follows:
+ <literallayout class='monospaced'>
+ Developer's Certificate of Origin 1.1
+
+ By making a contribution to this project, I certify that:
+
+ (a) The contribution was created in whole or in part by me and I
+ have the right to submit it under the open source license
+ indicated in the file; or
+
+ (b) The contribution is based upon previous work that, to the best
+ of my knowledge, is covered under an appropriate open source
+ license and I have the right under that license to submit that
+ work with modifications, whether created in whole or in part
+ by me, under the same open source license (unless I am
+ permitted to submit under a different license), as indicated
+ in the file; or
+
+ (c) The contribution was provided directly to me by some other
+ person who certified (a), (b) or (c) and I have not modified
+ it.
+
+ (d) I understand and agree that this project and the contribution
+ are public and that a record of the contribution (including all
+ personal information I submit with it, including my sign-off) is
+ maintained indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Provide a single-line summary of the change.
+ and,
+ if more explanation is needed, provide more
+ detail in the body of the commit.
+ This summary is typically viewable in the
+ "shortlist" of changes.
+ Thus, providing something short and descriptive
+ that gives the reader a summary of the change is
+ useful when viewing a list of many commits.
+ You should prefix this short description with the
+ recipe name (if changing a recipe), or else with
+ the short form path to the file being changed.
+ </para></listitem>
+ <listitem><para>
+ For the body of the commit message, provide
+ detailed information that describes what you
+ changed, why you made the change, and the approach
+ you used.
+ It might also be helpful if you mention how you
+ tested the change.
+ Provide as much detail as you can in the body of
+ the commit message.
+ <note>
+ You do not need to provide a more detailed
+ explanation of a change if the change is
+ minor to the point of the single line
+ summary providing all the information.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ If the change addresses a specific bug or issue
+ that is associated with a bug-tracking ID,
+ include a reference to that ID in your detailed
+ description.
+ For example, the Yocto Project uses a specific
+ convention for bug references - any commit that
+ addresses a specific bug should use the following
+ form for the detailed description.
+ Be sure to use the actual bug-tracking ID from
+ Bugzilla for
+ <replaceable>bug-id</replaceable>:
+ <literallayout class='monospaced'>
+ Fixes [YOCTO #<replaceable>bug-id</replaceable>]
+
+ <replaceable>detailed description of change</replaceable>
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
+ If you have arranged for permissions to push to an
+ upstream contrib repository, push the change to that
+ repository:
+ <literallayout class='monospaced'>
+ $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
+ </literallayout>
+ For example, suppose you have permissions to push into the
+ upstream <filename>meta-intel-contrib</filename>
+ repository and you are working in a local branch named
+ <replaceable>your_name</replaceable><filename>/README</filename>.
+ The following command pushes your local commits to the
+ <filename>meta-intel-contrib</filename> upstream
+ repository and puts the commit in a branch named
+ <replaceable>your_name</replaceable><filename>/README</filename>:
+ <literallayout class='monospaced'>
+ $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
+ </literallayout>
+ </para></listitem>
+ <listitem><para id='push-determine-who-to-notify'>
+ <emphasis>Determine Who to Notify:</emphasis>
+ Determine the maintainer or the mailing list
+ that you need to notify for the change.</para>
+
+ <para>Before submitting any change, you need to be sure
+ who the maintainer is or what mailing list that you need
+ to notify.
+ Use either these methods to find out:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Maintenance File:</emphasis>
+ Examine the <filename>maintainers.inc</filename>
+ file, which is located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ at
+ <filename>meta/conf/distro/include</filename>,
+ to see who is responsible for code.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Search by File:</emphasis>
+ Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>,
+ you can enter the following command to bring up a
+ short list of all commits against a specific file:
+ <literallayout class='monospaced'>
+ git shortlog -- <replaceable>filename</replaceable>
+ </literallayout>
+ Just provide the name of the file for which you
+ are interested.
+ The information returned is not ordered by history
+ but does include a list of everyone who has
+ committed grouped by name.
+ From the list, you can see who is responsible for
+ the bulk of the changes against the file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Examine the List of Mailing Lists:</emphasis>
+ For a list of the Yocto Project and related mailing
+ lists, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make a Pull Request:</emphasis>
+ Notify the maintainer or the mailing list that you have
+ pushed a change by making a pull request.</para>
+
+ <para>The Yocto Project provides two scripts that
+ conveniently let you generate and send pull requests to the
+ Yocto Project.
+ These scripts are <filename>create-pull-request</filename>
+ and <filename>send-pull-request</filename>.
+ You can find these scripts in the
+ <filename>scripts</filename> directory within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (e.g. <filename>~/poky/scripts</filename>).
+ </para>
+
+ <para>Using these scripts correctly formats the requests
+ without introducing any whitespace or HTML formatting.
+ The maintainer that receives your patches either directly
+ or through the mailing list needs to be able to save and
+ apply them directly from your emails.
+ Using these scripts is the preferred method for sending
+ patches.</para>
+
+ <para>First, create the pull request.
+ For example, the following command runs the script,
+ specifies the upstream repository in the contrib directory
+ into which you pushed the change, and provides a subject
+ line in the created patch files:
+ <literallayout class='monospaced'>
+ $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
+ </literallayout>
+ Running this script forms
+ <filename>*.patch</filename> files in a folder named
+ <filename>pull-</filename><replaceable>PID</replaceable>
+ in the current directory.
+ One of the patch files is a cover letter.</para>
+
+ <para>Before running the
+ <filename>send-pull-request</filename> script, you must
+ edit the cover letter patch to insert information about
+ your change.
+ After editing the cover letter, send the pull request.
+ For example, the following command runs the script and
+ specifies the patch directory and email address.
+ In this example, the email address is a mailing list:
+ <literallayout class='monospaced'>
+ $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
+ </literallayout>
+ You need to follow the prompts as the script is
+ interactive.
+ <note>
+ For help on using these scripts, simply provide the
+ <filename>-h</filename> argument as follows:
+ <literallayout class='monospaced'>
+ $ poky/scripts/create-pull-request -h
+ $ poky/scripts/send-pull-request -h
+ </literallayout>
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='submitting-a-patch'>
+ <title>Using Email to Submit a Patch</title>
+
+ <para>
+ You can submit patches without using the
+ <filename>create-pull-request</filename> and
+ <filename>send-pull-request</filename> scripts described in the
+ previous section.
+ However, keep in mind, the preferred method is to use the scripts.
+ </para>
+
+ <para>
+ Depending on the components changed, you need to submit the email
+ to a specific mailing list.
+ For some guidance on which mailing list to use, see the
+ <link linkend='figuring-out-the-mailing-list-to-use'>list</link>
+ at the beginning of this section.
+ For a description of all the available mailing lists, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para>
+
+ <para>
+ Here is the general procedure on how to submit a patch through
+ email without using the scripts:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Make Your Changes Locally:</emphasis>
+ Make your changes in your local Git repository.
+ You should make small, controlled, isolated changes.
+ Keeping changes small and isolated aids review,
+ makes merging/rebasing easier and keeps the change
+ history clean should anyone need to refer to it in
+ future.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Stage Your Changes:</emphasis>
+ Stage your changes by using the <filename>git add</filename>
+ command on each file you changed.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Commit Your Changes:</emphasis>
+ Commit the change by using the
+ <filename>git commit --signoff</filename> command.
+ Using the <filename>--signoff</filename> option identifies
+ you as the person making the change and also satisfies
+ the Developer's Certificate of Origin (DCO) shown earlier.
+ </para>
+
+ <para>When you form a commit, you must follow certain
+ standards established by the Yocto Project development
+ team.
+ See
+ <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
+ in the previous section for information on how to
+ provide commit information that meets Yocto Project
+ commit message standards.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Format the Commit:</emphasis>
+ Format the commit into an email message.
+ To format commits, use the
+ <filename>git format-patch</filename> command.
+ When you provide the command, you must include a revision
+ list or a number of patches as part of the command.
+ For example, either of these two commands takes your most
+ recent single commit and formats it as an email message in
+ the current directory:
+ <literallayout class='monospaced'>
+ $ git format-patch -1
+ </literallayout>
+ or
+ <literallayout class='monospaced'>
+ $ git format-patch HEAD~
+ </literallayout></para>
+
+ <para>After the command is run, the current directory
+ contains a numbered <filename>.patch</filename> file for
+ the commit.</para>
+
+ <para>If you provide several commits as part of the
+ command, the <filename>git format-patch</filename> command
+ produces a series of numbered files in the current
+ directory – one for each commit.
+ If you have more than one patch, you should also use the
+ <filename>--cover</filename> option with the command,
+ which generates a cover letter as the first "patch" in
+ the series.
+ You can then edit the cover letter to provide a
+ description for the series of patches.
+ For information on the
+ <filename>git format-patch</filename> command,
+ see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
+ using the <filename>man git-format-patch</filename>
+ command.
+ <note>
+ If you are or will be a frequent contributor to the
+ Yocto Project or to OpenEmbedded, you might consider
+ requesting a contrib area and the necessary associated
+ rights.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Import the Files Into Your Mail Client:</emphasis>
+ Import the files into your mail client by using the
+ <filename>git send-email</filename> command.
+ <note>
+ In order to use <filename>git send-email</filename>,
+ you must have the proper Git packages installed on
+ your host.
+ For Ubuntu, Debian, and Fedora the package is
+ <filename>git-email</filename>.
+ </note></para>
+
+ <para>The <filename>git send-email</filename> command
+ sends email by using a local or remote Mail Transport Agent
+ (MTA) such as <filename>msmtp</filename>,
+ <filename>sendmail</filename>, or through a direct
+ <filename>smtp</filename> configuration in your Git
+ <filename>~/.gitconfig</filename> file.
+ If you are submitting patches through email only, it is
+ very important that you submit them without any whitespace
+ or HTML formatting that either you or your mailer
+ introduces.
+ The maintainer that receives your patches needs to be able
+ to save and apply them directly from your emails.
+ A good way to verify that what you are sending will be
+ applicable by the maintainer is to do a dry run and send
+ them to yourself and then save and apply them as the
+ maintainer would.</para>
+
+ <para>The <filename>git send-email</filename> command is
+ the preferred method for sending your patches using
+ email since there is no risk of compromising whitespace
+ in the body of the message, which can occur when you use
+ your own mail client.
+ The command also has several options that let you
+ specify recipients and perform further editing of the
+ email message.
+ For information on how to use the
+ <filename>git send-email</filename> command,
+ see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
+ the <filename>man git-send-email</filename> command.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section id='working-with-licenses'>
+ <title>Working With Licenses</title>
+
+ <para>
+ As mentioned in the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
+ section in the Yocto Project Overview and Concepts Manual,
+ open source projects are open to the public and they
+ consequently have different licensing structures in place.
+ This section describes the mechanism by which the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ tracks changes to licensing text and covers how to maintain open
+ source license compliance during your project's lifecycle.
+ The section also describes how to enable commercially licensed
+ recipes, which by default are disabled.
+ </para>
+
+ <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
+ <title>Tracking License Changes</title>
+
+ <para>
+ The license of an upstream project might change in the future.
+ In order to prevent these changes going unnoticed, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ variable tracks changes to the license text. The checksums are
+ validated at the end of the configure step, and if the
+ checksums do not match, the build will fail.
+ </para>
+
+ <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
+ <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
+
+ <para>
+ The <filename>LIC_FILES_CHKSUM</filename>
+ variable contains checksums of the license text in the
+ source code for the recipe.
+ Following is an example of how to specify
+ <filename>LIC_FILES_CHKSUM</filename>:
+ <literallayout class='monospaced'>
+ LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
+ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
+ file://licfile2.txt;endline=50;md5=zzzz \
+ ..."
+ </literallayout>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ When using "beginline" and "endline", realize
+ that line numbering begins with one and not
+ zero.
+ Also, the included lines are inclusive (i.e.
+ lines five through and including 29 in the
+ previous example for
+ <filename>licfile1.txt</filename>).
+ </para></listitem>
+ <listitem><para>
+ When a license check fails, the selected license
+ text is included as part of the QA message.
+ Using this output, you can determine the exact
+ start and finish for the needed license text.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The build system uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+ variable as the default directory when searching files
+ listed in <filename>LIC_FILES_CHKSUM</filename>.
+ The previous example employs the default directory.
+ </para>
+
+ <para>
+ Consider this next example:
+ <literallayout class='monospaced'>
+ LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
+ md5=bb14ed3c4cda583abc85401304b5cd4e"
+ LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
+ </literallayout>
+ </para>
+
+ <para>
+ The first line locates a file in
+ <filename>${S}/src/ls.c</filename> and isolates lines five
+ through 16 as license text.
+ The second line refers to a file in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
+ </para>
+
+ <para>
+ Note that <filename>LIC_FILES_CHKSUM</filename> variable is
+ mandatory for all recipes, unless the
+ <filename>LICENSE</filename> variable is set to "CLOSED".
+ </para>
+ </section>
+
+ <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
+ <title>Explanation of Syntax</title>
+
+ <para>
+ As mentioned in the previous section, the
+ <filename>LIC_FILES_CHKSUM</filename> variable lists all
+ the important files that contain the license text for the
+ source code.
+ It is possible to specify a checksum for an entire file,
+ or a specific section of a file (specified by beginning and
+ ending line numbers with the "beginline" and "endline"
+ parameters, respectively).
+ The latter is useful for source files with a license
+ notice header, README documents, and so forth.
+ If you do not use the "beginline" parameter, then it is
+ assumed that the text begins on the first line of the file.
+ Similarly, if you do not use the "endline" parameter,
+ it is assumed that the license text ends with the last
+ line of the file.
+ </para>
+
+ <para>
+ The "md5" parameter stores the md5 checksum of the license
+ text.
+ If the license text changes in any way as compared to
+ this parameter then a mismatch occurs.
+ This mismatch triggers a build failure and notifies
+ the developer.
+ Notification allows the developer to review and address
+ the license text changes.
+ Also note that if a mismatch occurs during the build,
+ the correct md5 checksum is placed in the build log and
+ can be easily copied to the recipe.
+ </para>
+
+ <para>
+ There is no limit to how many files you can specify using
+ the <filename>LIC_FILES_CHKSUM</filename> variable.
+ Generally, however, every project requires a few
+ specifications for license tracking.
+ Many projects have a "COPYING" file that stores the
+ license information for all the source code files.
+ This practice allows you to just track the "COPYING"
+ file as long as it is kept up to date.
+ <note><title>Tips</title>
+ <itemizedlist>
+ <listitem><para>
+ If you specify an empty or invalid "md5"
+ parameter,
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ returns an md5 mis-match
+ error and displays the correct "md5" parameter
+ value during the build.
+ The correct parameter is also captured in
+ the build log.
+ </para></listitem>
+ <listitem><para>
+ If the whole file contains only license text,
+ you do not need to use the "beginline" and
+ "endline" parameters.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id="enabling-commercially-licensed-recipes">
+ <title>Enabling Commercially Licensed Recipes</title>
+
+ <para>
+ By default, the OpenEmbedded build system disables
+ components that have commercial or other special licensing
+ requirements.
+ Such requirements are defined on a
+ recipe-by-recipe basis through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ variable definition in the affected recipe.
+ For instance, the
+ <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ recipe contains the following statement:
<literallayout class='monospaced'>
+ LICENSE_FLAGS = "commercial"
+ </literallayout>
+ Here is a slightly more complicated example that contains both
+ an explicit recipe name and version (after variable expansion):
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS = "license_${PN}_${PV}"
+ </literallayout>
+ In order for a component restricted by a
+ <filename>LICENSE_FLAGS</filename> definition to be enabled and
+ included in an image, it needs to have a matching entry in the
+ global
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
+ variable, which is a variable typically defined in your
+ <filename>local.conf</filename> file.
+ For example, to enable the
+ <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ package, you could add either the string
+ "commercial_gst-plugins-ugly" or the more general string
+ "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
+ See the
+ "<link linkend='license-flag-matching'>License Flag Matching</link>"
+ section for a full
+ explanation of how <filename>LICENSE_FLAGS</filename> matching
+ works.
+ Here is the example:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
+ </literallayout>
+ Likewise, to additionally enable the package built from the
+ recipe containing
+ <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
+ and assuming that the actual recipe name was
+ <filename>emgd_1.10.bb</filename>, the following string would
+ enable that package as well as the original
+ <filename>gst-plugins-ugly</filename> package:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
+ </literallayout>
+ As a convenience, you do not need to specify the complete
+ license string in the whitelist for every package.
+ You can use an abbreviated form, which consists
+ of just the first portion or portions of the license
+ string before the initial underscore character or characters.
+ A partial string will match any license that contains the
+ given string as the first portion of its license.
+ For example, the following whitelist string will also match
+ both of the packages previously mentioned as well as any other
+ packages that have licenses starting with "commercial" or
+ "license".
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial license"
+ </literallayout>
+ </para>
+
+ <section id="license-flag-matching">
+ <title>License Flag Matching</title>
+
+ <para>
+ License flag matching allows you to control what recipes
+ the OpenEmbedded build system includes in the build.
+ Fundamentally, the build system attempts to match
+ <filename>LICENSE_FLAGS</filename> strings found in recipes
+ against <filename>LICENSE_FLAGS_WHITELIST</filename>
+ strings found in the whitelist.
+ A match causes the build system to include a recipe in the
+ build, while failure to find a match causes the build
+ system to exclude a recipe.
+ </para>
+
+ <para>
+ In general, license flag matching is simple.
+ However, understanding some concepts will help you
+ correctly and effectively use matching.
+ </para>
+
+ <para>
+ Before a flag
+ defined by a particular recipe is tested against the
+ contents of the whitelist, the expanded string
+ <filename>_${PN}</filename> is appended to the flag.
+ This expansion makes each
+ <filename>LICENSE_FLAGS</filename> value recipe-specific.
+ After expansion, the string is then matched against the
+ whitelist.
+ Thus, specifying
+ <filename>LICENSE_FLAGS = "commercial"</filename>
+ in recipe "foo", for example, results in the string
+ <filename>"commercial_foo"</filename>.
+ And, to create a match, that string must appear in the
+ whitelist.
+ </para>
+
+ <para>
+ Judicious use of the <filename>LICENSE_FLAGS</filename>
+ strings and the contents of the
+ <filename>LICENSE_FLAGS_WHITELIST</filename> variable
+ allows you a lot of flexibility for including or excluding
+ recipes based on licensing.
+ For example, you can broaden the matching capabilities by
+ using license flags string subsets in the whitelist.
+ <note>
+ When using a string subset, be sure to use the part of
+ the expanded string that precedes the appended
+ underscore character (e.g.
+ <filename>usethispart_1.3</filename>,
+ <filename>usethispart_1.4</filename>, and so forth).
+ </note>
+ For example, simply specifying the string "commercial" in
+ the whitelist matches any expanded
+ <filename>LICENSE_FLAGS</filename> definition that starts
+ with the string "commercial" such as "commercial_foo" and
+ "commercial_bar", which are the strings the build system
+ automatically generates for hypothetical recipes named
+ "foo" and "bar" assuming those recipes simply specify the
+ following:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS = "commercial"
+ </literallayout>
+ Thus, you can choose to exhaustively
+ enumerate each license flag in the whitelist and
+ allow only specific recipes into the image, or
+ you can use a string subset that causes a broader range of
+ matches to allow a range of recipes into the image.
+ </para>
+
+ <para>
+ This scheme works even if the
+ <filename>LICENSE_FLAGS</filename> string already
+ has <filename>_${PN}</filename> appended.
+ For example, the build system turns the license flag
+ "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
+ would match both the general "commercial" and the specific
+ "commercial_1.2_foo" strings found in the whitelist, as
+ expected.
+ </para>
+
+ <para>
+ Here are some other scenarios:
+ <itemizedlist>
+ <listitem><para>
+ You can specify a versioned string in the recipe
+ such as "commercial_foo_1.2" in a "foo" recipe.
+ The build system expands this string to
+ "commercial_foo_1.2_foo".
+ Combine this license flag with a whitelist that has
+ the string "commercial" and you match the flag
+ along with any other flag that starts with the
+ string "commercial".
+ </para></listitem>
+ <listitem><para>
+ Under the same circumstances, you can use
+ "commercial_foo" in the whitelist and the build
+ system not only matches "commercial_foo_1.2" but
+ also matches any license flag with the string
+ "commercial_foo", regardless of the version.
+ </para></listitem>
+ <listitem><para>
+ You can be very specific and use both the
+ package and version parts in the whitelist (e.g.
+ "commercial_foo_1.2") to specifically match a
+ versioned recipe.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="other-variables-related-to-commercial-licenses">
+ <title>Other Variables Related to Commercial Licenses</title>
+
+ <para>
+ Other helpful variables related to commercial
+ license handling exist and are defined in the
+ <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
+ <literallayout class='monospaced'>
+ COMMERCIAL_AUDIO_PLUGINS ?= ""
+ COMMERCIAL_VIDEO_PLUGINS ?= ""
+ </literallayout>
+ If you want to enable these components, you can do so by
+ making sure you have statements similar to the following
+ in your <filename>local.conf</filename> configuration file:
+ <literallayout class='monospaced'>
+ COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
+ gst-plugins-ugly-mpegaudioparse"
+ COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
+ gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
+ </literallayout>
+ Of course, you could also create a matching whitelist
+ for those components using the more general "commercial"
+ in the whitelist, but that would also enable all the
+ other packages with <filename>LICENSE_FLAGS</filename>
+ containing "commercial", which you may or may not want:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial"
+ </literallayout>
+ </para>
+
+ <para>
+ Specifying audio and video plug-ins as part of the
+ <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
+ <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
+ (along with the enabling
+ <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
+ plug-ins or components into built images, thus adding
+ support for media formats or components.
+ </para>
+ </section>
+ </section>
+
+ <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
+ <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
+
+ <para>
+ One of the concerns for a development organization using open source
+ software is how to maintain compliance with various open source
+ licensing during the lifecycle of the product.
+ While this section does not provide legal advice or
+ comprehensively cover all scenarios, it does
+ present methods that you can use to
+ assist you in meeting the compliance requirements during a software
+ release.
+ </para>
+
+ <para>
+ With hundreds of different open source licenses that the Yocto
+ Project tracks, it is difficult to know the requirements of each
+ and every license.
+ However, the requirements of the major FLOSS licenses can begin
+ to be covered by
+ assuming that three main areas of concern exist:
+ <itemizedlist>
+ <listitem><para>Source code must be provided.</para></listitem>
+ <listitem><para>License text for the software must be
+ provided.</para></listitem>
+ <listitem><para>Compilation scripts and modifications to the
+ source code must be provided.
+ </para></listitem>
+ </itemizedlist>
+ There are other requirements beyond the scope of these
+ three and the methods described in this section
+ (e.g. the mechanism through which source code is distributed).
+ </para>
+
+ <para>
+ As different organizations have different methods of complying with
+ open source licensing, this section is not meant to imply that
+ there is only one single way to meet your compliance obligations,
+ but rather to describe one method of achieving compliance.
+ The remainder of this section describes methods supported to meet the
+ previously mentioned three requirements.
+ Once you take steps to meet these requirements,
+ and prior to releasing images, sources, and the build system,
+ you should audit all artifacts to ensure completeness.
+ <note>
+ The Yocto Project generates a license manifest during
+ image creation that is located
+ in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
+ to assist with any audits.
+ </note>
+ </para>
+
+ <section id='providing-the-source-code'>
+ <title>Providing the Source Code</title>
+
+ <para>
+ Compliance activities should begin before you generate the
+ final image.
+ The first thing you should look at is the requirement that
+ tops the list for most compliance groups - providing
+ the source.
+ The Yocto Project has a few ways of meeting this
+ requirement.
+ </para>
+
+ <para>
+ One of the easiest ways to meet this requirement is
+ to provide the entire
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+ used by the build.
+ This method, however, has a few issues.
+ The most obvious is the size of the directory since it includes
+ all sources used in the build and not just the source used in
+ the released image.
+ It will include toolchain source, and other artifacts, which
+ you would not generally release.
+ However, the more serious issue for most companies is accidental
+ release of proprietary software.
+ The Yocto Project provides an
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
+ class to help avoid some of these concerns.
+ </para>
+
+ <para>
+ Before you employ <filename>DL_DIR</filename> or the
+ <filename>archiver</filename> class, you need to decide how
+ you choose to provide source.
+ The source <filename>archiver</filename> class can generate
+ tarballs and SRPMs and can create them with various levels of
+ compliance in mind.
+ </para>
+
+ <para>
+ One way of doing this (but certainly not the only way) is to
+ release just the source as a tarball.
+ You can do this by adding the following to the
+ <filename>local.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
- </literallayout>
- During the creation of your image, the source from all
- recipes that deploy packages to the image is placed within
- subdirectories of
- <filename>DEPLOY_DIR/sources</filename> based on the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
- for each recipe.
- Releasing the entire directory enables you to comply with
- requirements concerning providing the unmodified source.
- It is important to note that the size of the directory can
- get large.
- </para>
+ </literallayout>
+ During the creation of your image, the source from all
+ recipes that deploy packages to the image is placed within
+ subdirectories of
+ <filename>DEPLOY_DIR/sources</filename> based on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+ for each recipe.
+ Releasing the entire directory enables you to comply with
+ requirements concerning providing the unmodified source.
+ It is important to note that the size of the directory can
+ get large.
+ </para>
- <para>
- A way to help mitigate the size issue is to only release
- tarballs for licenses that require the release of
- source.
- Let us assume you are only concerned with GPL code as
- identified by running the following script:
- <literallayout class='monospaced'>
+ <para>
+ A way to help mitigate the size issue is to only release
+ tarballs for licenses that require the release of
+ source.
+ Let us assume you are only concerned with GPL code as
+ identified by running the following script:
+ <literallayout class='monospaced'>
# Script to archive a subset of packages matching specific license(s)
# Source and license files are copied into sub folders of package folder
# Must be run from build folder
@@ -10515,96 +14941,97 @@
cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null
fi
done
- done </literallayout>
- At this point, you could create a tarball from the
- <filename>gpl_source_release</filename> directory and
- provide that to the end user.
- This method would be a step toward achieving compliance
- with section 3a of GPLv2 and with section 6 of GPLv3.
- </para>
- </section>
+ done
+ </literallayout>
+ At this point, you could create a tarball from the
+ <filename>gpl_source_release</filename> directory and
+ provide that to the end user.
+ This method would be a step toward achieving compliance
+ with section 3a of GPLv2 and with section 6 of GPLv3.
+ </para>
+ </section>
- <section id='providing-license-text'>
- <title>Providing License Text</title>
+ <section id='providing-license-text'>
+ <title>Providing License Text</title>
- <para>
- One requirement that is often overlooked is inclusion
- of license text.
- This requirement also needs to be dealt with prior to
- generating the final image.
- Some licenses require the license text to accompany
- the binary.
- You can achieve this by adding the following to your
- <filename>local.conf</filename> file:
- <literallayout class='monospaced'>
+ <para>
+ One requirement that is often overlooked is inclusion
+ of license text.
+ This requirement also needs to be dealt with prior to
+ generating the final image.
+ Some licenses require the license text to accompany
+ the binary.
+ You can achieve this by adding the following to your
+ <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
COPY_LIC_MANIFEST = "1"
COPY_LIC_DIRS = "1"
LICENSE_CREATE_PACKAGE = "1"
- </literallayout>
- Adding these statements to the configuration file ensures
- that the licenses collected during package generation
- are included on your image.
- <note>
- <para>Setting all three variables to "1" results in the
- image having two copies of the same license file.
- One copy resides in
- <filename>/usr/share/common-licenses</filename> and
- the other resides in
- <filename>/usr/share/license</filename>.</para>
+ </literallayout>
+ Adding these statements to the configuration file ensures
+ that the licenses collected during package generation
+ are included on your image.
+ <note>
+ <para>Setting all three variables to "1" results in the
+ image having two copies of the same license file.
+ One copy resides in
+ <filename>/usr/share/common-licenses</filename> and
+ the other resides in
+ <filename>/usr/share/license</filename>.</para>
- <para>The reason for this behavior is because
- <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink>
- add a copy of the license when the image is built but do
- not offer a path for adding licenses for newly installed
- packages to an image.
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>
- adds a separate package and an upgrade path for adding
- licenses to an image.</para>
- </note>
- </para>
+ <para>The reason for this behavior is because
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink>
+ add a copy of the license when the image is built but do
+ not offer a path for adding licenses for newly installed
+ packages to an image.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>
+ adds a separate package and an upgrade path for adding
+ licenses to an image.</para>
+ </note>
+ </para>
- <para>
- As the source <filename>archiver</filename> class has already
- archived the original
- unmodified source that contains the license files,
- you would have already met the requirements for inclusion
- of the license information with source as defined by the GPL
- and other open source licenses.
- </para>
- </section>
+ <para>
+ As the source <filename>archiver</filename> class has already
+ archived the original
+ unmodified source that contains the license files,
+ you would have already met the requirements for inclusion
+ of the license information with source as defined by the GPL
+ and other open source licenses.
+ </para>
+ </section>
- <section id='providing-compilation-scripts-and-source-code-modifications'>
- <title>Providing Compilation Scripts and Source Code Modifications</title>
+ <section id='providing-compilation-scripts-and-source-code-modifications'>
+ <title>Providing Compilation Scripts and Source Code Modifications</title>
- <para>
- At this point, we have addressed all we need to
- prior to generating the image.
- The next two requirements are addressed during the final
- packaging of the release.
- </para>
+ <para>
+ At this point, we have addressed all we need to
+ prior to generating the image.
+ The next two requirements are addressed during the final
+ packaging of the release.
+ </para>
- <para>
- By releasing the version of the OpenEmbedded build system
- and the layers used during the build, you will be providing both
- compilation scripts and the source code modifications in one
- step.
- </para>
+ <para>
+ By releasing the version of the OpenEmbedded build system
+ and the layers used during the build, you will be providing both
+ compilation scripts and the source code modifications in one
+ step.
+ </para>
- <para>
- If the deployment team has a
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
- and a distro layer, and those those layers are used to patch,
- compile, package, or modify (in any way) any open source
- software included in your released images, you
- might be required to release those layers under section 3 of
- GPLv2 or section 1 of GPLv3.
- One way of doing that is with a clean
- checkout of the version of the Yocto Project and layers used
- during your build.
- Here is an example:
- <literallayout class='monospaced'>
+ <para>
+ If the deployment team has a
+ <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
+ and a distro layer, and those those layers are used to patch,
+ compile, package, or modify (in any way) any open source
+ software included in your released images, you
+ might be required to release those layers under section 3 of
+ GPLv2 or section 1 of GPLv3.
+ One way of doing that is with a clean
+ checkout of the version of the Yocto Project and layers used
+ during your build.
+ Here is an example:
+ <literallayout class='monospaced'>
# We built using the &DISTRO_NAME_NO_CAP; branch of the poky repo
$ git clone -b &DISTRO_NAME_NO_CAP; git://git.yoctoproject.org/poky
$ cd poky
@@ -10613,18 +15040,18 @@
$ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
# clean up the .git repos
$ find . -name ".git" -type d -exec rm -rf {} \;
- </literallayout>
- One thing a development organization might want to consider
- for end-user convenience is to modify
- <filename>meta-poky/conf/bblayers.conf.sample</filename> to
- ensure that when the end user utilizes the released build
- system to build an image, the development organization's
- layers are included in the <filename>bblayers.conf</filename>
- file automatically:
- <literallayout class='monospaced'>
- # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
+ </literallayout>
+ One thing a development organization might want to consider
+ for end-user convenience is to modify
+ <filename>meta-poky/conf/bblayers.conf.sample</filename> to
+ ensure that when the end user utilizes the released build
+ system to build an image, the development organization's
+ layers are included in the <filename>bblayers.conf</filename>
+ file automatically:
+ <literallayout class='monospaced'>
+ # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
- LCONF_VERSION = "6"
+ POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
@@ -10635,14 +15062,15 @@
##OEROOT##/meta-yocto-bsp \
##OEROOT##/meta-mylayer \
"
- </literallayout>
- Creating and providing an archive of the
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
- layers (recipes, configuration files, and so forth)
- enables you to meet your
- requirements to include the scripts to control compilation
- as well as any modifications to the original source.
- </para>
+ </literallayout>
+ Creating and providing an archive of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ layers (recipes, configuration files, and so forth)
+ enables you to meet your
+ requirements to include the scripts to control compilation
+ as well as any modifications to the original source.
+ </para>
+ </section>
</section>
</section>
@@ -10761,6 +15189,136 @@
</para>
</section>
</section>
+
+ <section id="dev-using-wayland-and-weston">
+ <title>Using Wayland and Weston</title>
+
+ <para>
+ <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink>
+ is a computer display server protocol that
+ provides a method for compositing window managers to communicate
+ directly with applications and video hardware and expects them to
+ communicate with input hardware using other libraries.
+ Using Wayland with supporting targets can result in better control
+ over graphics frame rendering than an application might otherwise
+ achieve.
+ </para>
+
+ <para>
+ The Yocto Project provides the Wayland protocol libraries and the
+ reference
+ <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink>
+ compositor as part of its release.
+ You can find the integrated packages in the
+ <filename>meta</filename> layer of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ Specifically, you can find the recipes that build both Wayland
+ and Weston at <filename>meta/recipes-graphics/wayland</filename>.
+ </para>
+
+ <para>
+ You can build both the Wayland and Weston packages for use only
+ with targets that accept the
+ <ulink url='https://en.wikipedia.org/wiki/Mesa_(computer_graphics)'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
+ which is also known as Mesa DRI.
+ This implies that you cannot build and use the packages if your
+ target uses, for example, the
+ <trademark class='registered'>Intel</trademark> Embedded Media
+ and Graphics Driver
+ (<trademark class='registered'>Intel</trademark> EMGD) that
+ overrides Mesa DRI.
+ <note>
+ Due to lack of EGL support, Weston 1.0.3 will not run
+ directly on the emulated QEMU hardware.
+ However, this version of Weston will run under X emulation
+ without issues.
+ </note>
+ </para>
+
+ <para>
+ This section describes what you need to do to implement Wayland and
+ use the Weston compositor when building an image for a supporting
+ target.
+ </para>
+
+ <section id="enabling-wayland-in-an-image">
+ <title>Enabling Wayland in an Image</title>
+
+ <para>
+ To enable Wayland, you need to enable it to be built and enable
+ it to be included (installed) in the image.
+ </para>
+
+ <section id="enable-building">
+ <title>Building</title>
+
+ <para>
+ To cause Mesa to build the <filename>wayland-egl</filename>
+ platform and Weston to build Wayland with Kernel Mode
+ Setting
+ (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
+ support, include the "wayland" flag in the
+ <ulink url="&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></ulink>
+ statement in your <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ DISTRO_FEATURES_append = " wayland"
+ </literallayout>
+ <note>
+ If X11 has been enabled elsewhere, Weston will build
+ Wayland with X11 support
+ </note>
+ </para>
+ </section>
+
+ <section id="enable-installation-in-an-image">
+ <title>Installing</title>
+
+ <para>
+ To install the Wayland feature into an image, you must
+ include the following
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></ulink>
+ statement in your <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+ <section id="running-weston">
+ <title>Running Weston</title>
+
+ <para>
+ To run Weston inside X11, enabling it as described earlier and
+ building a Sato image is sufficient.
+ If you are running your image under Sato, a Weston Launcher
+ appears in the "Utility" category.
+ </para>
+
+ <para>
+ Alternatively, you can run Weston through the command-line
+ interpretor (CLI), which is better suited for development work.
+ To run Weston under the CLI, you need to do the following after
+ your image is built:
+ <orderedlist>
+ <listitem><para>
+ Run these commands to export
+ <filename>XDG_RUNTIME_DIR</filename>:
+ <literallayout class='monospaced'>
+ mkdir -p /tmp/$USER-weston
+ chmod 0700 /tmp/$USER-weston
+ export XDG_RUNTIME_DIR=/tmp/$USER-weston
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Launch Weston in the shell:
+ <literallayout class='monospaced'>
+ weston
+ </literallayout></para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
</chapter>
<!--
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml
index 47c8006..f457c80 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml
@@ -16,33 +16,29 @@
The manual groups related procedures into higher-level sections.
Procedures can consist of high-level steps or low-level steps
depending on the topic.
- You can find conceptual information related to a procedure by
- following appropriate links to the Yocto Project Reference
- Manual.
</para>
<para>
The following list describes what you can get from this manual:
<itemizedlist>
<listitem><para>
- <emphasis>Setup Procedures:</emphasis>
- Procedures that show you how to set
- up a Yocto Project Development environment and how
- to accomplish the change workflow through logging
- defects and submitting changes.
+ Procedures that help you get going with the Yocto Project.
+ For example, procedures that show you how to set up
+ a build host and work with the Yocto Project
+ source repositories.
</para></listitem>
<listitem><para>
- <emphasis>Emulation Procedures:</emphasis>
- Procedures that show you how to use the
- Yocto Project integrated QuickEMUlator (QEMU), which lets
- you simulate running on hardware an image you have built
- using the OpenEmbedded build system.
+ Procedures that show you how to submit changes to the
+ Yocto Project.
+ Changes can be improvements, new features, or bug
+ fixes.
</para></listitem>
<listitem><para>
- <emphasis>Common Procedures:</emphasis>
Procedures related to "everyday" tasks you perform while
developing images and applications using the Yocto
Project.
+ For example, procedures to create a layer, customize an
+ image, write a new recipe, and so forth.
</para></listitem>
</itemizedlist>
</para>
@@ -51,7 +47,7 @@
This manual will not give you the following:
<itemizedlist>
<listitem><para>
- <emphasis>Redundant Step-by-step Instructions:</emphasis>
+ Redundant Step-by-step Instructions:
For example, the
<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
manual contains detailed instructions on how to install an
@@ -59,14 +55,15 @@
hardware.
</para></listitem>
<listitem><para>
- <emphasis>Reference or Conceptual Material:</emphasis>
- This type of material resides in an appropriate reference manual.
+ Reference or Conceptual Material:
+ This type of material resides in an appropriate reference
+ manual.
For example, system variables are documented in the
<ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.
</para></listitem>
<listitem><para>
- <emphasis>Detailed Public Information Not Specific to the
- Yocto Project:</emphasis>
+ Detailed Public Information Not Specific to the
+ Yocto Project:
For example, exhaustive information on how to use the
Source Control Manager Git is better covered with Internet
searches and official Git Documentation than through the
@@ -85,9 +82,10 @@
comprehension.
For introductory information on the Yocto Project, see the
<ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
- You can find an introductory to using the Yocto Project by working
- through the
- <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+ If you want to build an image with no knowledge of Yocto Project
+ as a way of quickly testing it out, see the
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+ document.
</para>
<para>
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml
deleted file mode 100644
index a0fbb4b..0000000
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml
+++ /dev/null
@@ -1,989 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='dev-manual-newbie'>
-
-<title>The Yocto Project Open Source Development Environment</title>
-
-<section id="usingpoky-changes-collaborate">
- <title>Setting Up a Team Yocto Project Development Environment</title>
-
- <para>
- It might not be immediately clear how you can use the Yocto
- Project in a team development environment, or scale it for a large
- team of developers.
- One of the strengths of the Yocto Project is that it is extremely
- flexible.
- Thus, you can adapt it to many different use cases and scenarios.
- However, these characteristics can cause a struggle if you are trying
- to create a working setup that scales across a large team.
- </para>
-
- <para>
- To help you understand how to set up this type of environment,
- this section presents a procedure that gives you the information
- to learn how to get the results you want.
- The procedure is high-level and presents some of the project's most
- successful experiences, practices, solutions, and available
- technologies that work well.
- Keep in mind, the procedure here is a starting point.
- You can build off it and customize it to fit any
- particular working environment and set of practices.
- <orderedlist>
- <listitem><para>
- <emphasis>Determine Who is Going to be Developing:</emphasis>
- You need to understand who is going to be doing anything
- related to the Yocto Project and what their roles would be.
- Making this determination is essential to completing the
- steps two and three, which are to get your equipment together
- and set up your development environment's hardware topology.
- </para>
-
- <para>The following roles exist:
- <itemizedlist>
- <listitem><para>
- <emphasis>Application Development:</emphasis>
- These types of developers do application level work
- on top of an existing software stack.
- </para></listitem>
- <listitem><para>
- <emphasis>Core System Development:</emphasis>
- These types of developers work on the contents of the
- operating system image itself.
- </para></listitem>
- <listitem><para>
- <emphasis>Build Engineer:</emphasis>
- This type of developer manages Autobuilders and
- releases.
- Not all environments need a Build Engineer.
- </para></listitem>
- <listitem><para>
- <emphasis>Test Engineer:</emphasis>
- This type of developer creates and manages automated
- tests needed to ensure all application and core
- system development meets desired quality standards.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Gather the Hardware:</emphasis>
- Based on the size and make-up of the team, get the hardware
- together.
- Any development, build, or test engineer should be using
- a system that is running a supported Linux distribution.
- Systems, in general, should be high performance (e.g. dual,
- six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
- You can help ensure efficiency by having any machines used
- for testing or that run Autobuilders be as high performance
- as possible.
- </para></listitem>
- <listitem><para>
- <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
- Now that you know how many developers and support engineers
- are required, you can understand the topology of the
- hardware environment.
- The following figure shows a moderately sized Yocto Project
- development environment.
-
- <para role="writernotes">
- Need figure.</para>
-
- </para></listitem>
- <listitem><para>
- <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
- Keeping your
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
- and any software you are developing under the
- control of an SCM system that is compatible
- with the OpenEmbedded build system is advisable.
- Of the SCMs BitBake supports, the
- Yocto Project team strongly recommends using
- <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>.
- Git is a distributed system that is easy to backup,
- allows you to work remotely, and then connects back to the
- infrastructure.
- <note>
- For information about BitBake, see the
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
- </note></para>
-
- <para>It is relatively easy to set up Git services and create
- infrastructure like
- <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
- which is based on server software called
- <filename>gitolite</filename> with <filename>cgit</filename>
- being used to generate the web interface that lets you view the
- repositories.
- The <filename>gitolite</filename> software identifies users
- using SSH keys and allows branch-based
- access controls to repositories that you can control as little
- or as much as necessary.
-
- <note>
- The setup of these services is beyond the scope of this
- manual.
- However, sites such as these exist that describe how to
- perform setup:
- <itemizedlist>
- <listitem><para>
- <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
- Describes how to install <filename>gitolite</filename>
- on the server.
- </para></listitem>
- <listitem><para>
- <ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
- All topics for <filename>gitolite</filename>.
- </para></listitem>
- <listitem><para>
- <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
- Documentation on how to create interfaces and frontends
- for Git.
- </para></listitem>
- </itemizedlist>
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up the Application Development Machines:</emphasis>
- As mentioned earlier, application developers are creating
- applications on top of existing software stacks.
- Following are some best practices for setting up machines
- that do application development:
- <itemizedlist>
- <listitem><para>
- Use a pre-built toolchain that
- contains the software stack itself.
- Then, develop the application code on top of the
- stack.
- This method works well for small numbers of relatively
- isolated applications.
- </para></listitem>
- <listitem><para>
- When possible, use the Yocto Project
- plug-in for the
- <trademark class='trade'>Eclipse</trademark> IDE
- and SDK development practices.
- For more information, see the
- "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
- manual.
- </para></listitem>
- <listitem><para>
- Keep your cross-development toolchains updated.
- You can do this through provisioning either as new
- toolchain downloads or as updates through a package
- update mechanism using <filename>opkg</filename>
- to provide updates to an existing toolchain.
- The exact mechanics of how and when to do this are a
- question for local policy.
- </para></listitem>
- <listitem><para>
- Use multiple toolchains installed locally
- into different locations to allow development across
- versions.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up the Core Development Machines:</emphasis>
- As mentioned earlier, these types of developers work on the
- contents of the operating system itself.
- Following are some best practices for setting up machines
- used for developing images:
- <itemizedlist>
- <listitem><para>
- Have the Yocto Project build system itself available on
- the developer workstations so developers can run their own
- builds and directly rebuild the software stack.
- </para></listitem>
- <listitem><para>
- Keep the core system unchanged as much as
- possible and do your work in layers on top of the
- core system.
- Doing so gives you a greater level of portability when
- upgrading to new versions of the core system or Board
- Support Packages (BSPs).
- </para></listitem>
- <listitem><para>
- Share layers amongst the developers of a
- particular project and contain the policy configuration
- that defines the project.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up an Autobuilder:</emphasis>
- Autobuilders are often the core of the development
- environment.
- It is here that changes from individual developers are brought
- together and centrally tested and subsequent decisions about
- releases can be made.
- Autobuilders also allow for "continuous integration" style
- testing of software components and regression identification
- and tracking.</para>
-
- <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
- for more information and links to buildbot.
- The Yocto Project team has found this implementation
- works well in this role.
- A public example of this is the Yocto Project
- Autobuilders, which we use to test the overall health of the
- project.</para>
-
- <para>The features of this system are:
- <itemizedlist>
- <listitem><para>
- Highlights when commits break the build.
- </para></listitem>
- <listitem><para>
- Populates an sstate cache from which
- developers can pull rather than requiring local
- builds.
- </para></listitem>
- <listitem><para>
- Allows commit hook triggers,
- which trigger builds when commits are made.
- </para></listitem>
- <listitem><para>
- Allows triggering of automated image booting
- and testing under the QuickEMUlator (QEMU).
- </para></listitem>
- <listitem><para>
- Supports incremental build testing and
- from-scratch builds.
- </para></listitem>
- <listitem><para>
- Shares output that allows developer
- testing and historical regression investigation.
- </para></listitem>
- <listitem><para>
- Creates output that can be used for releases.
- </para></listitem>
- <listitem><para>
- Allows scheduling of builds so that resources
- can be used efficiently.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up Test Machines:</emphasis>
- Use a small number of shared, high performance systems
- for testing purposes.
- Developers can use these systems for wider, more
- extensive testing while they continue to develop
- locally using their primary development system.
- </para></listitem>
- <listitem><para>
- <emphasis>Document Policies and Change Flow:</emphasis>
- The Yocto Project itself uses a hierarchical structure and a
- pull model.
- Scripts exist to create and send pull requests
- (i.e. <filename>create-pull-request</filename> and
- <filename>send-pull-request</filename>).
- This model is in line with other open source projects where
- maintainers are responsible for specific areas of the project
- and a single maintainer handles the final "top-of-tree" merges.
- <note>
- You can also use a more collective push model.
- The <filename>gitolite</filename> software supports both the
- push and pull models quite easily.
- </note></para>
-
- <para>As with any development environment, it is important
- to document the policy used as well as any main project
- guidelines so they are understood by everyone.
- It is also a good idea to have well structured
- commit messages, which are usually a part of a project's
- guidelines.
- Good commit messages are essential when looking back in time and
- trying to understand why changes were made.</para>
-
- <para>If you discover that changes are needed to the core
- layer of the project, it is worth sharing those with the
- community as soon as possible.
- Chances are if you have discovered the need for changes,
- someone else in the community needs them also.
- </para></listitem>
- <listitem><para>
- <emphasis>Development Environment Summary:</emphasis>
- Aside from the previous steps, some best practices exist
- within the Yocto Project development environment.
- Consider the following:
- <itemizedlist>
- <listitem><para>
- Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>
- as the source control system.
- </para></listitem>
- <listitem><para>
- Maintain your Metadata in layers that make sense
- for your situation.
- See the "<link linkend='understanding-and-creating-layers'>Understanding
- and Creating Layers</link>" section for more information on
- layers.
- </para></listitem>
- <listitem><para>
- Separate the project's Metadata and code by using
- separate Git repositories.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
- section for information on these repositories.
- See the
- "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
- section for information on how to set up local Git
- repositories for related upstream Yocto Project
- Git repositories.
- </para></listitem>
- <listitem><para>
- Set up the directory for the shared state cache
- (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
- where it makes sense.
- For example, set up the sstate cache on a system used
- by developers in the same organization and share the
- same source directories on their machines.
- </para></listitem>
- <listitem><para>
- Set up an Autobuilder and have it populate the
- sstate cache and source directories.
- </para></listitem>
- <listitem><para>
- The Yocto Project community encourages you
- to send patches to the project to fix bugs or add features.
- If you do submit patches, follow the project commit
- guidelines for writing good commit messages.
- See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
- section.
- </para></listitem>
- <listitem><para>
- Send changes to the core sooner than later
- as others are likely to run into the same issues.
- For some guidance on mailing lists to use, see the list in the
- "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
- section.
- For a description of the available mailing lists, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
- section in the Yocto Project Reference Manual.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- </orderedlist>
- </para>
-</section>
-
-<section id='submitting-a-defect-against-the-yocto-project'>
- <title>Submitting a Defect Against the Yocto Project</title>
-
- <para>
- Use the Yocto Project implementation of
- <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
- to submit a defect (bug) against the Yocto Project.
- For additional information on this implementation of Bugzilla see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
- section in the Yocto Project Reference Manual.
- For more detail on any of the following steps, see the Yocto Project
- <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
- </para>
-
- <para>
- Use the following general steps to submit a bug"
-
- <orderedlist>
- <listitem><para>
- Open the Yocto Project implementation of
- <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
- </para></listitem>
- <listitem><para>
- Click "File a Bug" to enter a new bug.
- </para></listitem>
- <listitem><para>
- Choose the appropriate "Classification", "Product", and
- "Component" for which the bug was found.
- Bugs for the Yocto Project fall into one of several
- classifications, which in turn break down into several
- products and components.
- For example, for a bug against the
- <filename>meta-intel</filename> layer, you would choose
- "Build System, Metadata & Runtime", "BSPs", and
- "bsps-meta-intel", respectively.
- </para></listitem>
- <listitem><para>
- Choose the "Version" of the Yocto Project for which you found
- the bug (e.g. &DISTRO;).
- </para></listitem>
- <listitem><para>
- Determine and select the "Severity" of the bug.
- The severity indicates how the bug impacted your work.
- </para></listitem>
- <listitem><para>
- Choose the "Hardware" that the bug impacts.
- </para></listitem>
- <listitem><para>
- Choose the "Architecture" that the bug impacts.
- </para></listitem>
- <listitem><para>
- Choose a "Documentation change" item for the bug.
- Fixing a bug might or might not affect the Yocto Project
- documentation.
- If you are unsure of the impact to the documentation, select
- "Don't Know".
- </para></listitem>
- <listitem><para>
- Provide a brief "Summary" of the bug.
- Try to limit your summary to just a line or two and be sure
- to capture the essence of the bug.
- </para></listitem>
- <listitem><para>
- Provide a detailed "Description" of the bug.
- You should provide as much detail as you can about the context,
- behavior, output, and so forth that surrounds the bug.
- You can even attach supporting files for output from logs by
- using the "Add an attachment" button.
- </para></listitem>
- <listitem><para>
- Click the "Submit Bug" button submit the bug.
- A new Bugzilla number is assigned to the bug and the defect
- is logged in the bug tracking system.
- </para></listitem>
- </orderedlist>
- Once you file a bug, the bug is processed by the Yocto Project Bug
- Triage Team and further details concerning the bug are assigned
- (e.g. priority and owner).
- You are the "Submitter" of the bug and any further categorization,
- progress, or comments on the bug result in Bugzilla sending you an
- automated email concerning the particular change or progress to the
- bug.
- </para>
-</section>
-
-<section id='how-to-submit-a-change'>
- <title>Submitting a Change to the Yocto Project</title>
-
- <para>
- Contributions to the Yocto Project and OpenEmbedded are very welcome.
- Because the system is extremely configurable and flexible, we recognize
- that developers will want to extend, configure or optimize it for
- their specific uses.
- </para>
-
- <para>
- The Yocto Project uses a mailing list and a patch-based workflow
- that is similar to the Linux kernel but contains important
- differences.
- In general, a mailing list exists through which you can submit
- patches.
- You should send patches to the appropriate mailing list so that they
- can be reviewed and merged by the appropriate maintainer.
- The specific mailing list you need to use depends on the
- location of the code you are changing.
- Each component (e.g. layer) should have a
- <filename>README</filename> file that indicates where to send
- the changes and which process to follow.
- </para>
-
- <para>
- You can send the patch to the mailing list using whichever approach
- you feel comfortable with to generate the patch.
- Once sent, the patch is usually reviewed by the community at large.
- If somebody has concerns with the patch, they will usually voice
- their concern over the mailing list.
- If a patch does not receive any negative reviews, the maintainer of
- the affected layer typically takes the patch, tests it, and then
- based on successful testing, merges the patch.
- </para>
-
- <para id='figuring-out-the-mailing-list-to-use'>
- The "poky" repository, which is the Yocto Project's reference build
- environment, is a hybrid repository that contains several
- individual pieces (e.g. BitBake, Metadata, documentation,
- and so forth) built using the combo-layer tool.
- The upstream location used for submitting changes varies by
- component:
- <itemizedlist>
- <listitem><para>
- <emphasis>Core Metadata:</emphasis>
- Send your patch to the
- <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
- mailing list. For example, a change to anything under
- the <filename>meta</filename> or
- <filename>scripts</filename> directories should be sent
- to this mailing list.
- </para></listitem>
- <listitem><para>
- <emphasis>BitBake:</emphasis>
- For changes to BitBake (i.e. anything under the
- <filename>bitbake</filename> directory), send your patch
- to the
- <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
- mailing list.
- </para></listitem>
- <listitem><para>
- <emphasis>"meta-*" trees:</emphasis>
- These trees contain Metadata.
- Use the
- <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
- mailing list.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- For changes to other layers hosted in the Yocto Project source
- repositories (i.e. <filename>yoctoproject.org</filename>), tools,
- and the Yocto Project documentation, use the
- <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
- general mailing list.
- <note>
- Sometimes a layer's documentation specifies to use a
- particular mailing list.
- If so, use that list.
- </note>
- For additional recipes that do not fit into the core Metadata, you
- should determine which layer the recipe should go into and submit
- the change in the manner recommended by the documentation (e.g.
- the <filename>README</filename> file) supplied with the layer.
- If in doubt, please ask on the Yocto general mailing list or on
- the openembedded-devel mailing list.
- </para>
-
- <para>
- You can also push a change upstream and request a maintainer to
- pull the change into the component's upstream repository.
- You do this by pushing to a contribution repository that is upstream.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#workflows'>Workflows</ulink>"
- section in the Yocto Project Reference Manual for additional
- concepts on working in the Yocto Project development environment.
- </para>
-
- <para>
- Two commonly used testing repositories exist for
- OpenEmbedded-Core:
- <itemizedlist>
- <listitem><para>
- <emphasis>"ross/mut" branch:</emphasis>
- The "mut" (master-under-test) tree
- exists in the <filename>poky-contrib</filename> repository
- in the
- <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
- </para></listitem>
- <listitem><para>
- <emphasis>"master-next" branch:</emphasis>
- This branch is part of the main
- "poky" repository in the Yocto Project source repositories.
- </para></listitem>
- </itemizedlist>
- Maintainers use these branches to test submissions prior to merging
- patches.
- Thus, you can get an idea of the status of a patch based on
- whether the patch has been merged into one of these branches.
- <note>
- This system is imperfect and changes can sometimes get lost in the
- flow.
- Asking about the status of a patch or change is reasonable if the
- change has been idle for a while with no feedback.
- The Yocto Project does have plans to use
- <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
- to track the status of patches and also to automatically preview
- patches.
- </note>
- </para>
-
- <para>
- The following sections provide procedures for submitting a change.
- </para>
-
- <section id='pushing-a-change-upstream'>
- <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
-
- <para>
- Follow this procedure to push a change to an upstream "contrib"
- Git repository:
- <note>
- You can find general Git information on how to push a change
- upstream in the
- <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
- </note>
- <orderedlist>
- <listitem><para>
- <emphasis>Make Your Changes Locally:</emphasis>
- Make your changes in your local Git repository.
- You should make small, controlled, isolated changes.
- Keeping changes small and isolated aids review,
- makes merging/rebasing easier and keeps the change
- history clean should anyone need to refer to it in
- future.
- </para></listitem>
- <listitem><para>
- <emphasis>Stage Your Changes:</emphasis>
- Stage your changes by using the <filename>git add</filename>
- command on each file you changed.
- </para></listitem>
- <listitem><para id='making-sure-you-have-correct-commit-information'>
- <emphasis>Commit Your Changes:</emphasis>
- Commit the change by using the
- <filename>git commit</filename> command.
- Make sure your commit information follows standards by
- following these accepted conventions:
- <itemizedlist>
- <listitem><para>
- Be sure to include a "Signed-off-by:" line in the
- same style as required by the Linux kernel.
- Adding this line signifies that you, the submitter,
- have agreed to the Developer's Certificate of
- Origin 1.1 as follows:
- <literallayout class='monospaced'>
- Developer's Certificate of Origin 1.1
-
- By making a contribution to this project, I certify that:
-
- (a) The contribution was created in whole or in part by me and I
- have the right to submit it under the open source license
- indicated in the file; or
-
- (b) The contribution is based upon previous work that, to the best
- of my knowledge, is covered under an appropriate open source
- license and I have the right under that license to submit that
- work with modifications, whether created in whole or in part
- by me, under the same open source license (unless I am
- permitted to submit under a different license), as indicated
- in the file; or
-
- (c) The contribution was provided directly to me by some other
- person who certified (a), (b) or (c) and I have not modified
- it.
-
- (d) I understand and agree that this project and the contribution
- are public and that a record of the contribution (including all
- personal information I submit with it, including my sign-off) is
- maintained indefinitely and may be redistributed consistent with
- this project or the open source license(s) involved.
- </literallayout>
- </para></listitem>
- <listitem><para>
- Provide a single-line summary of the change.
- and,
- if more explanation is needed, provide more
- detail in the body of the commit.
- This summary is typically viewable in the
- "shortlist" of changes.
- Thus, providing something short and descriptive
- that gives the reader a summary of the change is
- useful when viewing a list of many commits.
- You should prefix this short description with the
- recipe name (if changing a recipe), or else with
- the short form path to the file being changed.
- </para></listitem>
- <listitem><para>
- For the body of the commit message, provide
- detailed information that describes what you
- changed, why you made the change, and the approach
- you used.
- It might also be helpful if you mention how you
- tested the change.
- Provide as much detail as you can in the body of
- the commit message.
- <note>
- You do not need to provide a more detailed
- explanation of a change if the change is
- minor to the point of the single line
- summary providing all the information.
- </note>
- </para></listitem>
- <listitem><para>
- If the change addresses a specific bug or issue
- that is associated with a bug-tracking ID,
- include a reference to that ID in your detailed
- description.
- For example, the Yocto Project uses a specific
- convention for bug references - any commit that
- addresses a specific bug should use the following
- form for the detailed description.
- Be sure to use the actual bug-tracking ID from
- Bugzilla for
- <replaceable>bug-id</replaceable>:
- <literallayout class='monospaced'>
- Fixes [YOCTO #<replaceable>bug-id</replaceable>]
-
- <replaceable>detailed description of change</replaceable>
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
- If you have arranged for permissions to push to an
- upstream contrib repository, push the change to that
- repository:
- <literallayout class='monospaced'>
- $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
- </literallayout>
- For example, suppose you have permissions to push into the
- upstream <filename>meta-intel-contrib</filename>
- repository and you are working in a local branch named
- <replaceable>your_name</replaceable><filename>/README</filename>.
- The following command pushes your local commits to the
- <filename>meta-intel-contrib</filename> upstream
- repository and puts the commit in a branch named
- <replaceable>your_name</replaceable><filename>/README</filename>:
- <literallayout class='monospaced'>
- $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
- </literallayout>
- </para></listitem>
- <listitem><para id='push-determine-who-to-notify'>
- <emphasis>Determine Who to Notify:</emphasis>
- Determine the maintainer or the mailing list
- that you need to notify for the change.</para>
-
- <para>Before submitting any change, you need to be sure
- who the maintainer is or what mailing list that you need
- to notify.
- Use either these methods to find out:
- <itemizedlist>
- <listitem><para>
- <emphasis>Maintenance File:</emphasis>
- Examine the <filename>maintainers.inc</filename>
- file, which is located in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- at
- <filename>meta/conf/distro/include</filename>,
- to see who is responsible for code.
- </para></listitem>
- <listitem><para>
- <emphasis>Search by File:</emphasis>
- Using <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>,
- you can enter the following command to bring up a
- short list of all commits against a specific file:
- <literallayout class='monospaced'>
- git shortlog -- <replaceable>filename</replaceable>
- </literallayout>
- Just provide the name of the file for which you
- are interested.
- The information returned is not ordered by history
- but does include a list of everyone who has
- committed grouped by name.
- From the list, you can see who is responsible for
- the bulk of the changes against the file.
- </para></listitem>
- <listitem><para>
- <emphasis>Examine the List of Mailing Lists:</emphasis>
- For a list of the Yocto Project and related mailing
- lists, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
- section in the Yocto Project Reference Manual.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Make a Pull Request:</emphasis>
- Notify the maintainer or the mailing list that you have
- pushed a change by making a pull request.</para>
-
- <para>The Yocto Project provides two scripts that
- conveniently let you generate and send pull requests to the
- Yocto Project.
- These scripts are <filename>create-pull-request</filename>
- and <filename>send-pull-request</filename>.
- You can find these scripts in the
- <filename>scripts</filename> directory within the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (e.g. <filename>~/poky/scripts</filename>).
- </para>
-
- <para>Using these scripts correctly formats the requests
- without introducing any whitespace or HTML formatting.
- The maintainer that receives your patches either directly
- or through the mailing list needs to be able to save and
- apply them directly from your emails.
- Using these scripts is the preferred method for sending
- patches.</para>
-
- <para>First, create the pull request.
- For example, the following command runs the script,
- specifies the upstream repository in the contrib directory
- into which you pushed the change, and provides a subject
- line in the created patch files:
- <literallayout class='monospaced'>
- $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
- </literallayout>
- Running this script forms
- <filename>*.patch</filename> files in a folder named
- <filename>pull-</filename><replaceable>PID</replaceable>
- in the current directory.
- One of the patch files is a cover letter.</para>
-
- <para>Before running the
- <filename>send-pull-request</filename> script, you must
- edit the cover letter patch to insert information about
- your change.
- After editing the cover letter, send the pull request.
- For example, the following command runs the script and
- specifies the patch directory and email address.
- In this example, the email address is a mailing list:
- <literallayout class='monospaced'>
- $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
- </literallayout>
- You need to follow the prompts as the script is
- interactive.
- <note>
- For help on using these scripts, simply provide the
- <filename>-h</filename> argument as follows:
- <literallayout class='monospaced'>
- $ poky/scripts/create-pull-request -h
- $ poky/scripts/send-pull-request -h
- </literallayout>
- </note>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='submitting-a-patch'>
- <title>Using Email to Submit a Patch</title>
-
- <para>
- You can submit patches without using the
- <filename>create-pull-request</filename> and
- <filename>send-pull-request</filename> scripts described in the
- previous section.
- However, keep in mind, the preferred method is to use the scripts.
- </para>
-
- <para>
- Depending on the components changed, you need to submit the email
- to a specific mailing list.
- For some guidance on which mailing list to use, see the
- <link linkend='figuring-out-the-mailing-list-to-use'>beginning</link>
- of this section.
- For a description of all the available mailing lists, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
- section in the Yocto Project Reference Manual.
- </para>
-
- <para>
- Here is the general procedure on how to submit a patch through
- email without using the scripts:
- <orderedlist>
- <listitem><para>
- <emphasis>Make Your Changes Locally:</emphasis>
- Make your changes in your local Git repository.
- You should make small, controlled, isolated changes.
- Keeping changes small and isolated aids review,
- makes merging/rebasing easier and keeps the change
- history clean should anyone need to refer to it in
- future.
- </para></listitem>
- <listitem><para>
- <emphasis>Stage Your Changes:</emphasis>
- Stage your changes by using the <filename>git add</filename>
- command on each file you changed.
- </para></listitem>
- <listitem><para>
- <emphasis>Commit Your Changes:</emphasis>
- Commit the change by using the
- <filename>git commit --signoff</filename> command.
- Using the <filename>--signoff</filename> option identifies
- you as the person making the change and also satisfies
- the Developer's Certificate of Origin (DCO) shown earlier.
- </para>
-
- <para>When you form a commit, you must follow certain
- standards established by the Yocto Project development
- team.
- See
- <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
- in the previous section for information on how to
- provide commit information that meets Yocto Project
- commit message standards.
- </para></listitem>
- <listitem><para>
- <emphasis>Format the Commit:</emphasis>
- Format the commit into an email message.
- To format commits, use the
- <filename>git format-patch</filename> command.
- When you provide the command, you must include a revision
- list or a number of patches as part of the command.
- For example, either of these two commands takes your most
- recent single commit and formats it as an email message in
- the current directory:
- <literallayout class='monospaced'>
- $ git format-patch -1
- </literallayout>
- or
- <literallayout class='monospaced'>
- $ git format-patch HEAD~
- </literallayout></para>
-
- <para>After the command is run, the current directory
- contains a numbered <filename>.patch</filename> file for
- the commit.</para>
-
- <para>If you provide several commits as part of the
- command, the <filename>git format-patch</filename> command
- produces a series of numbered files in the current
- directory – one for each commit.
- If you have more than one patch, you should also use the
- <filename>--cover</filename> option with the command,
- which generates a cover letter as the first "patch" in
- the series.
- You can then edit the cover letter to provide a
- description for the series of patches.
- For information on the
- <filename>git format-patch</filename> command,
- see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
- using the <filename>man git-format-patch</filename>
- command.
- <note>
- If you are or will be a frequent contributor to the
- Yocto Project or to OpenEmbedded, you might consider
- requesting a contrib area and the necessary associated
- rights.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Import the Files Into Your Mail Client:</emphasis>
- Import the files into your mail client by using the
- <filename>git send-email</filename> command.
- <note>
- In order to use <filename>git send-email</filename>,
- you must have the proper Git packages installed on
- your host.
- For Ubuntu, Debian, and Fedora the package is
- <filename>git-email</filename>.
- </note></para>
-
- <para>The <filename>git send-email</filename> command
- sends email by using a local or remote Mail Transport Agent
- (MTA) such as <filename>msmtp</filename>,
- <filename>sendmail</filename>, or through a direct
- <filename>smtp</filename> configuration in your Git
- <filename>~/.gitconfig</filename> file.
- If you are submitting patches through email only, it is
- very important that you submit them without any whitespace
- or HTML formatting that either you or your mailer
- introduces.
- The maintainer that receives your patches needs to be able
- to save and apply them directly from your emails.
- A good way to verify that what you are sending will be
- applicable by the maintainer is to do a dry run and send
- them to yourself and then save and apply them as the
- maintainer would.</para>
-
- <para>The <filename>git send-email</filename> command is
- the preferred method for sending your patches using
- email since there is no risk of compromising whitespace
- in the body of the message, which can occur when you use
- your own mail client.
- The command also has several options that let you
- specify recipients and perform further editing of the
- email message.
- For information on how to use the
- <filename>git send-email</filename> command,
- see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
- the <filename>man git-send-email</filename> command.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-</section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml
index 85e7315..4e7b5de 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml
@@ -7,15 +7,51 @@
<title>Using the Quick EMUlator (QEMU)</title>
<para>
- This chapter provides procedures that show you how to use the
- Quick EMUlator (QEMU), which is an Open Source project the Yocto
- Project uses as part of its development "tool set".
- For reference information on the Yocto Project implementation of QEMU,
- see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-quick-emulator-qemu'>Quick EMUlator (QEMU)</ulink>"
- section in the Yocto Project Reference Manual.
+ The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
+ Open Source project as part of the Yocto Project development "tool
+ set".
+ This chapter provides both procedures that show you how to use the
+ Quick EMUlator (QEMU) and other QEMU information helpful for
+ development purposes.
</para>
+ <section id='qemu-dev-overview'>
+ <title>Overview</title>
+
+ <para>
+ Within the context of the Yocto Project, QEMU is an
+ emulator and virtualization machine that allows you to run a
+ complete image you have built using the Yocto Project as just
+ another task on your build system.
+ QEMU is useful for running and testing images and applications on
+ supported Yocto Project architectures without having actual
+ hardware.
+ Among other things, the Yocto Project uses QEMU to run automated
+ Quality Assurance (QA) tests on final images shipped with each
+ release.
+ <note>
+ This implementation is not the same as QEMU in general.
+ </note>
+ This section provides a brief reference for the Yocto Project
+ implementation of QEMU.
+ </para>
+
+ <para>
+ For official information and documentation on QEMU in general, see
+ the following references:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
+ The official website for the QEMU Open Source project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
+ The QEMU user manual.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
<section id='qemu-running-qemu'>
<title>Running QEMU</title>
@@ -27,6 +63,9 @@
<orderedlist>
<listitem><para>
<emphasis>Install QEMU:</emphasis>
+ QEMU is made available with the Yocto Project a number of
+ ways.
+ One method is to install a Software Development Kit (SDK).
See
"<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
section in the Yocto Project Application Development and
@@ -303,6 +342,345 @@
</note>
</para>
</section>
+
+ <section id='qemu-kvm-cpu-compatibility'>
+ <title>QEMU CPU Compatibility Under KVM</title>
+
+ <para>
+ By default, the QEMU build compiles for and targets 64-bit and x86
+ <trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2
+ Duo processors and 32-bit x86
+ <trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>
+ II processors.
+ QEMU builds for and targets these CPU types because they display
+ a broad range of CPU feature compatibility with many commonly
+ used CPUs.
+ </para>
+
+ <para>
+ Despite this broad range of compatibility, the CPUs could support
+ a feature that your host CPU does not support.
+ Although this situation is not a problem when QEMU uses software
+ emulation of the feature, it can be a problem when QEMU is
+ running with KVM enabled.
+ Specifically, software compiled with a certain CPU feature crashes
+ when run on a CPU under KVM that does not support that feature.
+ To work around this problem, you can override QEMU's runtime CPU
+ setting by changing the <filename>QB_CPU_KVM</filename>
+ variable in <filename>qemuboot.conf</filename> in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
+ <filename>deploy/image</filename> directory.
+ This setting specifies a <filename>-cpu</filename> option
+ passed into QEMU in the <filename>runqemu</filename> script.
+ Running <filename>qemu -cpu help</filename> returns a list of
+ available supported CPU types.
+ </para>
+ </section>
+
+ <section id='qemu-dev-performance'>
+ <title>QEMU Performance</title>
+
+ <para>
+ Using QEMU to emulate your hardware can result in speed issues
+ depending on the target and host architecture mix.
+ For example, using the <filename>qemux86</filename> image in the
+ emulator on an Intel-based 32-bit (x86) host machine is fast
+ because the target and host architectures match.
+ On the other hand, using the <filename>qemuarm</filename> image
+ on the same Intel-based host can be slower.
+ But, you still achieve faithful emulation of ARM-specific issues.
+ </para>
+
+ <para>
+ To speed things up, the QEMU images support using
+ <filename>distcc</filename> to call a cross-compiler outside the
+ emulated system.
+ If you used <filename>runqemu</filename> to start QEMU, and the
+ <filename>distccd</filename> application is present on the host
+ system, any BitBake cross-compiling toolchain available from the
+ build system is automatically used from within QEMU simply by
+ calling <filename>distcc</filename>.
+ You can accomplish this by defining the cross-compiler variable
+ (e.g. <filename>export CC="distcc"</filename>).
+ Alternatively, if you are using a suitable SDK image or the
+ appropriate stand-alone toolchain is present, the toolchain is
+ also automatically used.
+ <note>
+ Several mechanisms exist that let you connect to the system
+ running on the QEMU emulator:
+ <itemizedlist>
+ <listitem><para>
+ QEMU provides a framebuffer interface that makes
+ standard consoles available.
+ </para></listitem>
+ <listitem><para>
+ Generally, headless embedded devices have a serial port.
+ If so, you can configure the operating system of the
+ running image to use that port to run a console.
+ The connection uses standard IP networking.
+ </para></listitem>
+ <listitem><para>
+ SSH servers exist in some QEMU images.
+ The <filename>core-image-sato</filename> QEMU image
+ has a Dropbear secure shell (SSH) server that runs
+ with the root password disabled.
+ The <filename>core-image-full-cmdline</filename> and
+ <filename>core-image-lsb</filename> QEMU images
+ have OpenSSH instead of Dropbear.
+ Including these SSH servers allow you to use standard
+ <filename>ssh</filename> and <filename>scp</filename>
+ commands.
+ The <filename>core-image-minimal</filename> QEMU image,
+ however, contains no SSH server.
+ </para></listitem>
+ <listitem><para>
+ You can use a provided, user-space NFS server to boot
+ the QEMU session using a local copy of the root
+ filesystem on the host.
+ In order to make this connection, you must extract a
+ root filesystem tarball by using the
+ <filename>runqemu-extract-sdk</filename> command.
+ After running the command, you must then point the
+ <filename>runqemu</filename>
+ script to the extracted directory instead of a root
+ filesystem image file.
+ See the
+ "<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"
+ section for more information.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+ </section>
+
+ <section id='qemu-dev-command-line-syntax'>
+ <title>QEMU Command-Line Syntax</title>
+
+ <para>
+ The basic <filename>runqemu</filename> command syntax is as
+ follows:
+ <literallayout class='monospaced'>
+ $ runqemu [<replaceable>option</replaceable> ] [...]
+ </literallayout>
+ Based on what you provide on the command line,
+ <filename>runqemu</filename> does a good job of figuring out what
+ you are trying to do.
+ For example, by default, QEMU looks for the most recently built
+ image according to the timestamp when it needs to look for an
+ image.
+ Minimally, through the use of options, you must provide either
+ a machine name, a virtual machine image
+ (<filename>*wic.vmdk</filename>), or a kernel image
+ (<filename>*.bin</filename>).
+ </para>
+
+ <para>
+ Following is the command-line help output for the
+ <filename>runqemu</filename> command:
+ <literallayout class='monospaced'>
+ $ runqemu --help
+
+ Usage: you can run this script with any valid combination
+ of the following environment variables (in any order):
+ KERNEL - the kernel image file to use
+ ROOTFS - the rootfs image file or nfsroot directory to use
+ MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
+ Simplified QEMU command-line options can be passed with:
+ nographic - disable video console
+ serial - enable a serial console on /dev/ttyS0
+ slirp - enable user networking, no root privileges is required
+ kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
+ kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
+ publicvnc - enable a VNC server open to all hosts
+ audio - enable audio
+ [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
+ tcpserial=<port> - specify tcp serial port number
+ biosdir=<dir> - specify custom bios dir
+ biosfilename=<filename> - specify bios filename
+ qemuparams=<xyz> - specify custom parameters to QEMU
+ bootparams=<xyz> - specify custom kernel parameters during boot
+ help, -h, --help: print this text
+
+ Examples:
+ runqemu
+ runqemu qemuarm
+ runqemu tmp/deploy/images/qemuarm
+ runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
+ runqemu qemux86-64 core-image-sato ext4
+ runqemu qemux86-64 wic-image-minimal wic
+ runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
+ runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
+ runqemu qemux86 qemuparams="-m 256"
+ runqemu qemux86 bootparams="psplash=false"
+ runqemu path/to/<image>-<machine>.wic
+ runqemu path/to/<image>-<machine>.wic.vmdk
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='qemu-dev-runqemu-command-line-options'>
+ <title><filename>runqemu</filename> Command-Line Options</title>
+
+ <para>
+ Following is a description of <filename>runqemu</filename>
+ options you can provide on the command line:
+ <note><title>Tip</title>
+ If you do provide some "illegal" option combination or perhaps
+ you do not provide enough in the way of options,
+ <filename>runqemu</filename> provides appropriate error
+ messaging to help you correct the problem.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <replaceable>QEMUARCH</replaceable>:
+ The QEMU machine architecture, which must be "qemuarm",
+ "qemuarm64", "qemumips", "qemumips64", "qemuppc",
+ "qemux86", or "qemux86-64".
+ </para></listitem>
+ <listitem><para>
+ <filename><replaceable>VM</replaceable></filename>:
+ The virtual machine image, which must be a
+ <filename>.wic.vmdk</filename> file.
+ Use this option when you want to boot a
+ <filename>.wic.vmdk</filename> image.
+ The image filename you provide must contain one of the
+ following strings: "qemux86-64", "qemux86", "qemuarm",
+ "qemumips64", "qemumips", "qemuppc", or "qemush4".
+ </para></listitem>
+ <listitem><para>
+ <replaceable>ROOTFS</replaceable>:
+ A root filesystem that has one of the following
+ filetype extensions: "ext2", "ext3", "ext4", "jffs2",
+ "nfs", or "btrfs".
+ If the filename you provide for this option uses “nfs”, it
+ must provide an explicit root filesystem path.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>KERNEL</replaceable>:
+ A kernel image, which is a <filename>.bin</filename> file.
+ When you provide a <filename>.bin</filename> file,
+ <filename>runqemu</filename> detects it and assumes the
+ file is a kernel image.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>MACHINE</replaceable>:
+ The architecture of the QEMU machine, which must be one
+ of the following: "qemux86", "qemux86-64", "qemuarm",
+ "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
+ The <replaceable>MACHINE</replaceable> and
+ <replaceable>QEMUARCH</replaceable> options are basically
+ identical.
+ If you do not provide a <replaceable>MACHINE</replaceable>
+ option, <filename>runqemu</filename> tries to determine
+ it based on other options.
+ </para></listitem>
+ <listitem><para>
+ <filename>ramfs</filename>:
+ Indicates you are booting an initial RAM disk (initramfs)
+ image, which means the <filename>FSTYPE</filename> is
+ <filename>cpio.gz</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>iso</filename>:
+ Indicates you are booting an ISO image, which means the
+ <filename>FSTYPE</filename> is
+ <filename>.iso</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>nographic</filename>:
+ Disables the video console, which sets the console to
+ "ttys0".
+ </para></listitem>
+ <listitem><para>
+ <filename>serial</filename>:
+ Enables a serial console on
+ <filename>/dev/ttyS0</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>biosdir</filename>:
+ Establishes a custom directory for BIOS, VGA BIOS and
+ keymaps.
+ </para></listitem>
+ <listitem><para>
+ <filename>biosfilename</filename>:
+ Establishes a custom BIOS name.
+ </para></listitem>
+ <listitem><para>
+ <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
+ Specifies custom QEMU parameters.
+ Use this option to pass options other than the simple
+ "kvm" and "serial" options.
+ </para></listitem>
+ <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
+ Specifies custom boot parameters for the kernel.
+ </para></listitem>
+ <listitem><para>
+ <filename>audio</filename>:
+ Enables audio in QEMU.
+ The <replaceable>MACHINE</replaceable> option must be
+ either "qemux86" or "qemux86-64" in order for audio to be
+ enabled.
+ Additionally, the <filename>snd_intel8x0</filename>
+ or <filename>snd_ens1370</filename> driver must be
+ installed in linux guest.
+ </para></listitem>
+ <listitem><para>
+ <filename>slirp</filename>:
+ Enables "slirp" networking, which is a different way
+ of networking that does not need root access
+ but also is not as easy to use or comprehensive
+ as the default.
+ </para></listitem>
+ <listitem><para id='kvm-cond'>
+ <filename>kvm</filename>:
+ Enables KVM when running "qemux86" or "qemux86-64"
+ QEMU architectures.
+ For KVM to work, all the following conditions must be met:
+ <itemizedlist>
+ <listitem><para>
+ Your <replaceable>MACHINE</replaceable> must be either
+qemux86" or "qemux86-64".
+ </para></listitem>
+ <listitem><para>
+ Your build host has to have the KVM modules
+ installed, which are
+ <filename>/dev/kvm</filename>.
+ </para></listitem>
+ <listitem><para>
+ The build host <filename>/dev/kvm</filename>
+ directory has to be both writable and readable.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <filename>kvm-vhost</filename>:
+ Enables KVM with VHOST support when running "qemux86"
+ or "qemux86-64" QEMU architectures.
+ For KVM with VHOST to work, the following conditions must
+ be met:
+ <itemizedlist>
+ <listitem><para>
+ <link linkend='kvm-cond'>kvm</link> option
+ conditions must be met.
+ </para></listitem>
+ <listitem><para>
+ Your build host has to have virtio net device, which
+ are <filename>/dev/vhost-net</filename>.
+ </para></listitem>
+ <listitem><para>
+ The build host <filename>/dev/vhost-net</filename>
+ directory has to be either readable or writable
+ and “slirp-enabled”.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <filename>publicvnc</filename>:
+ Enables a VNC server open to all hosts.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
index 195b22d..d8726b4 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
@@ -4,18 +4,386 @@
<chapter id='dev-manual-start'>
-<title>Getting Started with the Yocto Project</title>
+<title>Setting Up to Use the Yocto Project</title>
<para>
This chapter provides procedures related to getting set up to use the
Yocto Project.
- For a more front-to-end process that takes you from minimally preparing
- a build host through building an image, see the
- <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+ You can learn about creating a team environment that develops using the
+ Yocto Project, how to set up a build host, how to locate Yocto Project
+ source repositories, and how to create local Git repositories.
</para>
+<section id="usingpoky-changes-collaborate">
+ <title>Creating a Team Development Environment</title>
+
+ <para>
+ It might not be immediately clear how you can use the Yocto
+ Project in a team development environment, or scale it for a large
+ team of developers.
+ One of the strengths of the Yocto Project is that it is extremely
+ flexible.
+ Thus, you can adapt it to many different use cases and scenarios.
+ However, these characteristics can cause a struggle if you are trying
+ to create a working setup that scales across a large team.
+ </para>
+
+ <para>
+ To help you understand how to set up this type of environment,
+ this section presents a procedure that gives you the information
+ to learn how to get the results you want.
+ The procedure is high-level and presents some of the project's most
+ successful experiences, practices, solutions, and available
+ technologies that work well.
+ Keep in mind, the procedure here is a starting point.
+ You can build off it and customize it to fit any
+ particular working environment and set of practices.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Determine Who is Going to be Developing:</emphasis>
+ You need to understand who is going to be doing anything
+ related to the Yocto Project and what their roles would be.
+ Making this determination is essential to completing the
+ steps two and three, which are to get your equipment together
+ and set up your development environment's hardware topology.
+ </para>
+
+ <para>The following roles exist:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Application Development:</emphasis>
+ These types of developers do application level work
+ on top of an existing software stack.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Core System Development:</emphasis>
+ These types of developers work on the contents of the
+ operating system image itself.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build Engineer:</emphasis>
+ This type of developer manages Autobuilders and
+ releases.
+ Not all environments need a Build Engineer.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Test Engineer:</emphasis>
+ This type of developer creates and manages automated
+ tests needed to ensure all application and core
+ system development meets desired quality standards.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Gather the Hardware:</emphasis>
+ Based on the size and make-up of the team, get the hardware
+ together.
+ Any development, build, or test engineer should be using
+ a system that is running a supported Linux distribution.
+ Systems, in general, should be high performance (e.g. dual,
+ six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
+ You can help ensure efficiency by having any machines used
+ for testing or that run Autobuilders be as high performance
+ as possible.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
+ Once you understand the hardware involved and the make-up
+ of the team, you can understand the hardware topology of the
+ development environment.
+ You can get a visual idea of the machines and their roles
+ across the development environment.
+
+<!--
+ The following figure shows a moderately sized Yocto Project
+ development environment.
+
+ <para role="writernotes">
+ Need figure.</para>
+-->
+
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
+ Keeping your
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ and any software you are developing under the
+ control of an SCM system that is compatible
+ with the OpenEmbedded build system is advisable.
+ Of the SCMs BitBake supports, the
+ Yocto Project team strongly recommends using
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
+ Git is a distributed system that is easy to backup,
+ allows you to work remotely, and then connects back to the
+ infrastructure.
+ <note>
+ For information about BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </note></para>
+
+ <para>It is relatively easy to set up Git services and create
+ infrastructure like
+ <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
+ which is based on server software called
+ <filename>gitolite</filename> with <filename>cgit</filename>
+ being used to generate the web interface that lets you view the
+ repositories.
+ The <filename>gitolite</filename> software identifies users
+ using SSH keys and allows branch-based
+ access controls to repositories that you can control as little
+ or as much as necessary.
+
+ <note>
+ The setup of these services is beyond the scope of this
+ manual.
+ However, sites such as these exist that describe how to
+ perform setup:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
+ Describes how to install <filename>gitolite</filename>
+ on the server.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='http://gitolite.com'>Gitolite</ulink>:
+ Information for <filename>gitolite</filename>.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
+ Documentation on how to create interfaces and frontends
+ for Git.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up the Application Development Machines:</emphasis>
+ As mentioned earlier, application developers are creating
+ applications on top of existing software stacks.
+ Following are some best practices for setting up machines
+ that do application development:
+ <itemizedlist>
+ <listitem><para>
+ Use a pre-built toolchain that
+ contains the software stack itself.
+ Then, develop the application code on top of the
+ stack.
+ This method works well for small numbers of relatively
+ isolated applications.
+ </para></listitem>
+ <listitem><para>
+ When possible, use the Yocto Project
+ plug-in for the
+ <trademark class='trade'>Eclipse</trademark> IDE
+ and SDK development practices.
+ For more information, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
+ manual.
+ </para></listitem>
+ <listitem><para>
+ Keep your cross-development toolchains updated.
+ You can do this through provisioning either as new
+ toolchain downloads or as updates through a package
+ update mechanism using <filename>opkg</filename>
+ to provide updates to an existing toolchain.
+ The exact mechanics of how and when to do this are a
+ question for local policy.
+ </para></listitem>
+ <listitem><para>
+ Use multiple toolchains installed locally
+ into different locations to allow development across
+ versions.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up the Core Development Machines:</emphasis>
+ As mentioned earlier, these types of developers work on the
+ contents of the operating system itself.
+ Following are some best practices for setting up machines
+ used for developing images:
+ <itemizedlist>
+ <listitem><para>
+ Have the Yocto Project build system itself available on
+ the developer workstations so developers can run their own
+ builds and directly rebuild the software stack.
+ </para></listitem>
+ <listitem><para>
+ Keep the core system unchanged as much as
+ possible and do your work in layers on top of the
+ core system.
+ Doing so gives you a greater level of portability when
+ upgrading to new versions of the core system or Board
+ Support Packages (BSPs).
+ </para></listitem>
+ <listitem><para>
+ Share layers amongst the developers of a
+ particular project and contain the policy configuration
+ that defines the project.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up an Autobuilder:</emphasis>
+ Autobuilders are often the core of the development
+ environment.
+ It is here that changes from individual developers are brought
+ together and centrally tested and subsequent decisions about
+ releases can be made.
+ Autobuilders also allow for "continuous integration" style
+ testing of software components and regression identification
+ and tracking.</para>
+
+ <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
+ for more information and links to buildbot.
+ The Yocto Project team has found this implementation
+ works well in this role.
+ A public example of this is the Yocto Project
+ Autobuilders, which we use to test the overall health of the
+ project.</para>
+
+ <para>The features of this system are:
+ <itemizedlist>
+ <listitem><para>
+ Highlights when commits break the build.
+ </para></listitem>
+ <listitem><para>
+ Populates an sstate cache from which
+ developers can pull rather than requiring local
+ builds.
+ </para></listitem>
+ <listitem><para>
+ Allows commit hook triggers,
+ which trigger builds when commits are made.
+ </para></listitem>
+ <listitem><para>
+ Allows triggering of automated image booting
+ and testing under the QuickEMUlator (QEMU).
+ </para></listitem>
+ <listitem><para>
+ Supports incremental build testing and
+ from-scratch builds.
+ </para></listitem>
+ <listitem><para>
+ Shares output that allows developer
+ testing and historical regression investigation.
+ </para></listitem>
+ <listitem><para>
+ Creates output that can be used for releases.
+ </para></listitem>
+ <listitem><para>
+ Allows scheduling of builds so that resources
+ can be used efficiently.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up Test Machines:</emphasis>
+ Use a small number of shared, high performance systems
+ for testing purposes.
+ Developers can use these systems for wider, more
+ extensive testing while they continue to develop
+ locally using their primary development system.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Document Policies and Change Flow:</emphasis>
+ The Yocto Project itself uses a hierarchical structure and a
+ pull model.
+ Scripts exist to create and send pull requests
+ (i.e. <filename>create-pull-request</filename> and
+ <filename>send-pull-request</filename>).
+ This model is in line with other open source projects where
+ maintainers are responsible for specific areas of the project
+ and a single maintainer handles the final "top-of-tree" merges.
+ <note>
+ You can also use a more collective push model.
+ The <filename>gitolite</filename> software supports both the
+ push and pull models quite easily.
+ </note></para>
+
+ <para>As with any development environment, it is important
+ to document the policy used as well as any main project
+ guidelines so they are understood by everyone.
+ It is also a good idea to have well structured
+ commit messages, which are usually a part of a project's
+ guidelines.
+ Good commit messages are essential when looking back in time and
+ trying to understand why changes were made.</para>
+
+ <para>If you discover that changes are needed to the core
+ layer of the project, it is worth sharing those with the
+ community as soon as possible.
+ Chances are if you have discovered the need for changes,
+ someone else in the community needs them also.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Development Environment Summary:</emphasis>
+ Aside from the previous steps, some best practices exist
+ within the Yocto Project development environment.
+ Consider the following:
+ <itemizedlist>
+ <listitem><para>
+ Use
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
+ as the source control system.
+ </para></listitem>
+ <listitem><para>
+ Maintain your Metadata in layers that make sense
+ for your situation.
+ See the "<link linkend='understanding-and-creating-layers'>Understanding
+ and Creating Layers</link>" section for more information on
+ layers.
+ </para></listitem>
+ <listitem><para>
+ Separate the project's Metadata and code by using
+ separate Git repositories.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+ section for information on these repositories.
+ See the
+ "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
+ section for information on how to set up local Git
+ repositories for related upstream Yocto Project
+ Git repositories.
+ </para></listitem>
+ <listitem><para>
+ Set up the directory for the shared state cache
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
+ where it makes sense.
+ For example, set up the sstate cache on a system used
+ by developers in the same organization and share the
+ same source directories on their machines.
+ </para></listitem>
+ <listitem><para>
+ Set up an Autobuilder and have it populate the
+ sstate cache and source directories.
+ </para></listitem>
+ <listitem><para>
+ The Yocto Project community encourages you
+ to send patches to the project to fix bugs or add features.
+ If you do submit patches, follow the project commit
+ guidelines for writing good commit messages.
+ See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ Send changes to the core sooner than later
+ as others are likely to run into the same issues.
+ For some guidance on mailing lists to use, see the list in the
+ "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+ section.
+ For a description of the available mailing lists, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
<section id='setting-up-the-development-host-to-use-the-yocto-project'>
- <title>Setting Up the Development Host to Use the Yocto Project</title>
+ <title>Preparing the Build Host</title>
<para>
This section provides procedures to set up your development host to
@@ -177,7 +545,7 @@
site.
</para></listitem>
<listitem><para>
- <emphasis>Go the Install Site for Your Platform:</emphasis>
+ <emphasis>Go to the Install Site for Your Platform:</emphasis>
Click the link for the Docker edition associated with
your development host machine's native software.
For example, if your machine is running Microsoft
@@ -213,8 +581,8 @@
the type of the software you need to install.
</para></listitem>
<listitem><para>
- <emphasis>Optionally Orient Yourself With Dockers:</emphasis>
- If you are unfamiliar with Dockers and the container
+ <emphasis>Optionally Orient Yourself With Docker:</emphasis>
+ If you are unfamiliar with Docker and the container
concept, you can learn more here -
<ulink url='https://docs.docker.com/get-started/'></ulink>.
You should be able to launch Docker or the Docker Toolbox
@@ -250,25 +618,25 @@
</section>
</section>
-<section id='working-with-yocto-project-source-files'>
- <title>Working With Yocto Project Source Files</title>
+<section id='locating-yocto-project-source-files'>
+ <title>Locating Yocto Project Source Files</title>
<para>
- This section contains procedures related to locating and securing
- Yocto Project files.
+ This section contains procedures related to locating Yocto Project
+ files.
You establish and use these local files to work on projects.
<note><title>Notes</title>
<itemizedlist>
<listitem><para>
For concepts and introductory information about Git as it
is used in the Yocto Project, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
- section in the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para></listitem>
<listitem><para>
For concepts on Yocto Project source repositories, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
- section in the Yocto Project Reference Manual."
+ "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+ section in the Yocto Project Overview and Concepts Manual."
</para></listitem>
</itemizedlist>
</note>
@@ -278,9 +646,20 @@
<title>Accessing Source Repositories</title>
<para>
- Yocto Project maintains upstream Git
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
- that you can examine and access using a browser-based UI:
+ Working from a copy of the upstream Yocto Project
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
+ is the preferred method for obtaining and using a Yocto Project
+ release.
+ You can view the Yocto Project Source Repositories at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ In particular, you can find the
+ <filename>poky</filename> repository at
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
+ </para>
+
+ <para>
+ Use the following procedure to locate the latest upstream copy of
+ the <filename>poky</filename> Git repository:
<orderedlist>
<listitem><para>
<emphasis>Access Repositories:</emphasis>
@@ -290,24 +669,21 @@
repositories.
</para></listitem>
<listitem><para>
- <emphasis>Select a Repository:</emphasis>
- Click on any repository in which you are interested (e.g.
+ <emphasis>Select the Repository:</emphasis>
+ Click on the repository in which you are interested (i.e.
<filename>poky</filename>).
</para></listitem>
<listitem><para>
<emphasis>Find the URL Used to Clone the Repository:</emphasis>
At the bottom of the page, note the URL used to
- <ulink url='&YOCTO_DOCS_REF_URL;#git-commands-clone'>clone</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#git-commands-clone'>clone</ulink>
that repository (e.g.
<filename>&YOCTO_GIT_URL;/poky</filename>).
- </para></listitem>
- <listitem><para>
- <emphasis>Examine Change History of the Repository:</emphasis>
- At the top of the page, click on any branch in which you
- might be interested (e.g.
- <filename>&DISTRO_NAME_NO_CAP;</filename>).
- You can then view the commit log or tree view for that
- development branch.
+ <note>
+ For information on cloning a repository, see the
+ "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+ section.
+ </note>
</para></listitem>
</orderedlist>
</para>
@@ -319,12 +695,12 @@
<para>
Yocto Project maintains an Index of Releases area that contains
related files that contribute to the Yocto Project.
- Rather than Git repositories, these files represent snapshot
- tarballs.
+ Rather than Git repositories, these files are tarballs that
+ represent snapshots in time of a given component.
<note><title>Tip</title>
The recommended method for accessing Yocto Project
- components is to use Git to clone a repository and work from
- within that local repository.
+ components is to use Git to clone the upstream repository and
+ work from within that locally cloned repository.
The procedure in this section exists should you desire a
tarball snapshot of any given component.
</note>
@@ -342,8 +718,8 @@
full array of released Poky tarballs.
The <filename>poky</filename> directory in the
Index of Releases was historically used for very
- early releases and exists for retroactive
- completeness only.
+ early releases and exists now only for retroactive
+ completeness.
</note>
</para></listitem>
<listitem><para>
@@ -361,7 +737,7 @@
</para></listitem>
<listitem><para>
<emphasis>Download the Tarball:</emphasis>
- Click a tarball to download and save a snapshot of a
+ Click the tarball to download and save a snapshot of the
given component.
</para></listitem>
</orderedlist>
@@ -374,7 +750,7 @@
<para>
The
<ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
- uses a "Downloads" area from which you can locate and download
+ uses a "DOWNLOADS" page from which you can locate and download
tarballs of any Yocto Project release.
Rather than Git repositories, these files represent snapshot
tarballs.
@@ -394,52 +770,100 @@
</para></listitem>
<listitem><para>
<emphasis>Get to the Downloads Area:</emphasis>
- Click the "Downloads" tab.
+ Select the "DOWNLOADS" item from the pull-down
+ "SOFTWARE" tab menu.
</para></listitem>
<listitem><para>
- <emphasis>Select the Type of Files:</emphasis>
- Click the type of files you want (i.e "Build System",
- "Tools", or "Board Support Packages (BSPs)".
+ <emphasis>Select a Yocto Project Release:</emphasis>
+ Use the menu next to "RELEASE" to display and choose
+ a Yocto Project release (e.g. sumo, rocko, pyro, and
+ so forth.
+ For a "map" of Yocto Project releases to version numbers,
+ see the
+ <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink>
+ wiki page.
</para></listitem>
<listitem><para>
- <emphasis>Locate and Download the Tarball:</emphasis>
- From the list of releases, locate the appropriate
- download link and download the files.
+ <emphasis>Download Tools or Board Support Packages (BSPs):</emphasis>
+ From the "DOWNLOADS" page, you can download tools or
+ BSPs as well.
+ Just scroll down the page and look for what you need.
</para></listitem>
</orderedlist>
</para>
</section>
+ <section id='accessing-nightly-builds'>
+ <title>Accessing Nightly Builds</title>
+
+ <para>
+ Yocto Project maintains an area for nightly builds that contains
+ tarball releases at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>.
+ These builds include Yocto Project releases, SDK installation
+ scripts, and experimental builds.
+ </para>
+
+ <para>
+ Should you ever want to access a nightly build of a particular
+ Yocto Project component, use the following procedure:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Access the Nightly Builds:</emphasis>
+ Open a browser and go to
+ <ulink url='&YOCTO_AB_NIGHTLY_URL;'/> to access the
+ Nightly Builds.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select a Build:</emphasis>
+ Click on any build by date in which you are interested.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Find the Tarball:</emphasis>
+ Drill down to find the associated tarball.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download the Tarball:</emphasis>
+ Click the tarball to download and save a snapshot of the
+ given component.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+</section>
+
+<section id='cloning-and-checking-out-branchs'>
+ <title>Cloning and Checking Out Branches</title>
+
+ <para>
+ To use the Yocto Project, you need a release of the Yocto Project
+ locally installed on your development system.
+ The locally installed set of files is referred to as the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ in the Yocto Project documentation.
+ </para>
+
+ <para>
+ You create your Source Directory by using
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local
+ copy of the upstream <filename>poky</filename> repository.
+ <note><title>Tip</title>
+ The preferred method of getting the Yocto Project Source
+ Directory set up is to clone the repository.
+ </note>
+ Working from a copy of the upstream repository allows you
+ to contribute back into the Yocto Project or simply work with
+ the latest software on a development branch.
+ Because Git maintains and creates an upstream repository with
+ a complete history of changes and you are working with a local
+ clone of that repository, you have access to all the Yocto
+ Project development branches and tag names used in the upstream
+ repository.
+ </para>
+
<section id='cloning-the-poky-repository'>
<title>Cloning the <filename>poky</filename> Repository</title>
<para>
- To use the Yocto Project, you need a release of the Yocto Project
- locally installed on your development system.
- The locally installed set of files is referred to as the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- in the Yocto Project documentation.
- </para>
-
- <para>
- You create your Source Directory by using
- <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to clone a local
- copy of the upstream <filename>poky</filename> repository.
- <note><title>Tip</title>
- The preferred method of getting the Yocto Project Source
- Directory set up is to clone the repository.
- </note>
- Working from a copy of the upstream repository allows you
- to contribute back into the Yocto Project or simply work with
- the latest software on a development branch.
- Because Git maintains and creates an upstream repository with
- a complete history of changes and you are working with a local
- clone of that repository, you have access to all the Yocto
- Project development branches and tag names used in the upstream
- repository.
- </para>
-
- <para>
Follow these steps to create a local version of the
upstream
<ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink>
@@ -473,8 +897,8 @@
branch based on a tag name, see the
"<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
and
- <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>",
- respectively.</para>
+ <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>"
+ sections, respectively.</para>
<para>Once the repository is created, you can change to
that directory and check its status.
@@ -635,7 +1059,7 @@
<listitem><para>
<emphasis>Checkout the Branch:</emphasis>
<literallayout class='monospaced'>
- $ git checkout tags/&DISTRO; -b my_yocto_&DISTRO;
+ $ git checkout tags/&DISTRO_REL_TAG; -b my_yocto_&DISTRO;
Switched to a new branch 'my_yocto_&DISTRO;'
$ git branch
master
@@ -656,95 +1080,6 @@
</section>
</section>
-<section id='performing-a-simple-build'>
- <title>Performing a Simple Build</title>
-
- <para>
- Several methods exist that allow you to build an image within the
- Yocto Project.
- This procedure shows how to build an image using BitBake from a
- Linux host.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- For information on how to build an image using
- <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
- see the
- <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
- </para></listitem>
- <listitem><para>
- For information on how to use
- <filename>devtool</filename> to build images, see the
- "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
- section in the Yocto Project Application Development and
- the Extensible Software Development Kit (eSDK) manual.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- The build process creates an entire Linux distribution from source
- and places it in your
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- under <filename>tmp/deploy/images</filename>.
- For detailed information on the build process using BitBake, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#images-dev-environment'>Images</ulink>"
- section in the Yocto Project Reference Manual.
- You can also reference the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section in the Yocto Project Quick Start.
- </para>
-
- <para>
- The following figure and list overviews the build process:
- <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
- <orderedlist>
- <listitem><para>
- <emphasis>Set up Your Host Development System to Support
- Development Using the Yocto Project</emphasis>:
- See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
- section in the Yocto Project Quick Start for options on how
- to get a build host ready to use the Yocto Project.
- </para></listitem>
- <listitem><para>
- <emphasis>Initialize the Build Environment:</emphasis>
- Initialize the build environment by sourcing the build
- environment script (i.e.
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
- </para></listitem>
- <listitem><para>
- <emphasis>Make Sure Your <filename>local.conf</filename>
- File is Correct:</emphasis>
- Ensure the <filename>conf/local.conf</filename> configuration
- file, which is found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
- is set up how you want it.
- This file defines many aspects of the build environment
- including the target machine architecture through the
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
- the packaging format used during the build
- (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
- and a centralized tarball download directory through the
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Image:</emphasis>
- Build the image using the <filename>bitbake</filename> command.
- For example, the following command builds the
- <filename>core-image-minimal</filename> image:
- <literallayout class='monospaced'>
- $ bitbake core-image-minimal
- </literallayout>
- For information on BitBake, see the
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
- </para></listitem>
- </orderedlist>
- </para>
-</section>
-
--->
</chapter>
<!--
vim: expandtab tw=80 ts=4
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml
index ed8011d..93a615c 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml
@@ -102,14 +102,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -133,24 +128,36 @@
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
</legalnotice>
@@ -161,8 +168,6 @@
<xi:include href="dev-manual-start.xml"/>
- <xi:include href="dev-manual-newbie.xml"/>
-
<xi:include href="dev-manual-common-tasks.xml"/>
<xi:include href="dev-manual-qemu.xml"/>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/buildhistory-web.png b/import-layers/yocto-poky/documentation/dev-manual/figures/buildhistory-web.png
similarity index 100%
rename from import-layers/yocto-poky/documentation/ref-manual/figures/buildhistory-web.png
rename to import-layers/yocto-poky/documentation/dev-manual/figures/buildhistory-web.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/buildhistory.png b/import-layers/yocto-poky/documentation/dev-manual/figures/buildhistory.png
similarity index 100%
rename from import-layers/yocto-poky/documentation/ref-manual/figures/buildhistory.png
rename to import-layers/yocto-poky/documentation/dev-manual/figures/buildhistory.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml
index c3013b8..5c76ed2 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -21,7 +21,7 @@
<para>
Kernel Metadata exists in many places.
One area in the Yocto Project
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
is the <filename>yocto-kernel-cache</filename> Git repository.
You can find this repository grouped under the "Yocto Linux Kernel"
heading in the
@@ -64,8 +64,7 @@
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
variable.
This variable is typically set to the same value as the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable, which is used by
+ <filename>MACHINE</filename> variable, which is used by
<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
However, in some cases, the variable might instead refer to the
underlying platform of the <filename>MACHINE</filename>.
@@ -77,8 +76,7 @@
Multiple Corei7-based BSPs could share the same "intel-corei7-64"
value for <filename>KMACHINE</filename>.
It is important to realize that <filename>KMACHINE</filename> is
- just for kernel mapping, while
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ just for kernel mapping, while <filename>MACHINE</filename>
is the machine type within a BSP Layer.
Even with this distinction, however, these two variables can hold
the same value.
@@ -116,8 +114,7 @@
used in assembling the configuration.
If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
it defaults to "standard".
- Together with
- <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
+ Together with <filename>KMACHINE</filename>,
<filename>LINUX_KERNEL_TYPE</filename> defines the search
arguments used by the kernel tools to find the
appropriate description within the kernel Metadata with which to
@@ -631,8 +628,10 @@
<note>
For BSPs supported by the Yocto Project, the BSP description
files are located in the <filename>bsp</filename> directory
- of the <filename>yocto-kernel-cache</filename> repository
- organized under the "Yocto Linux Kernel" heading in the
+ of the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
+ repository organized under the "Yocto Linux Kernel" heading
+ in the
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
</note>
</para>
@@ -641,27 +640,30 @@
This section overviews the BSP description structure, the
aggregation concepts, and presents a detailed example using
a BSP supported by the Yocto Project (i.e. BeagleBone Board).
+ For complete information on BSP layer file hierarchy, see the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
</para>
<section id='bsp-description-file-overview'>
<title>Overview</title>
<para>
- For simplicity, consider the following top-level BSP
+ For simplicity, consider the following root BSP layer
description files for the BeagleBone board.
- Top-level BSP descriptions files employ both a structure
- and naming convention for consistency.
+ These files employ both a structure and naming convention
+ for consistency.
The naming convention for the file is as follows:
<literallayout class='monospaced'>
- <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
+ <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
</literallayout>
- Here are some example top-level BSP filenames for the
+ Here are some example root layer BSP filenames for the
BeagleBone Board BSP, which is supported by the Yocto Project:
<literallayout class='monospaced'>
beaglebone-standard.scc
beaglebone-preempt-rt.scc
</literallayout>
- Each file uses the BSP name followed by the kernel type.
+ Each file uses the root name (i.e "beaglebone") BSP name
+ followed by the kernel type.
</para>
<para>
@@ -850,7 +852,7 @@
<para>
Now consider the "minnow" description for the "tiny" kernel
- type (i.e. <filename>minnow-tiny.scc</filename>:
+ type (i.e. <filename>minnow-tiny.scc</filename>):
<literallayout class='monospaced'>
define KMACHINE minnow
define KTYPE tiny
@@ -1012,8 +1014,7 @@
<para>
If you modify the Metadata, you must not forget to update the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
- statements in the kernel's recipe.
+ <filename>SRCREV</filename> statements in the kernel's recipe.
In particular, you need to update the
<filename>SRCREV_meta</filename> variable to match the commit in
the <filename>KMETA</filename> branch you wish to use.
@@ -1221,9 +1222,13 @@
</para></listitem>
<listitem><para>
<filename>define</filename>:
- Defines variables, such as <filename>KMACHINE</filename>,
- <filename>KTYPE</filename>, <filename>KARCH</filename>,
- and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
+ Defines variables, such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>.
+ </para></listitem>
<listitem><para>
<filename>include SCC_FILE</filename>:
Includes an SCC file in the current file.
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml
index b8fd870..299bac4 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml
@@ -25,7 +25,7 @@
Before you can do any kernel development, you need to be
sure your build host is set up to use the Yocto Project.
For information on how to get set up, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up to Use the Yocto Project</ulink>"
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
section in the Yocto Project Development Tasks Manual.
Part of preparing the system is creating a local Git
repository of the
@@ -79,7 +79,7 @@
</literallayout>
<note>
The previous commands assume the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
(i.e. <filename>poky</filename>) have been cloned
using Git and the local repository is named
"poky".
@@ -136,7 +136,7 @@
Developer's Guide, respectively.
For information on how to use the
<filename>bitbake-layers create-layer</filename>
- command, see the
+ command to quickly set up a layer, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
section in the Yocto Project Development Tasks
Manual.
@@ -303,7 +303,7 @@
</literallayout>
<note>
The previous commands assume the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
(i.e. <filename>poky</filename>) have been cloned
using Git and the local repository is named
"poky".
@@ -360,7 +360,7 @@
Developer's Guide, respectively.
For information on how to use the
<filename>bitbake-layers create-layer</filename>
- command, see the
+ command to quickly set up a layer, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
section in the Yocto Project Development Tasks
Manual.
@@ -387,7 +387,7 @@
You can find Git repositories of supported Yocto Project
kernels organized under "Yocto Linux Kernel" in the
Yocto Project Source Repositories at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
</para>
<para>
@@ -489,7 +489,8 @@
See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
section in the Yocto Project Development Tasks Manual for
- information on how to use this script.
+ information on how to use this script to quick set up a
+ new layer.
</note>
</para>
@@ -1224,18 +1225,6 @@
the
"<link linkend='getting-ready-for-traditional-kernel-development'>Getting Ready for Traditional Kernel Development</link>"
Section.
- </para>
-
- <para>
- Although this example uses Git and shell commands to generate the
- patch, you could use the <filename>yocto-kernel</filename> script
- found in the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- under <filename>scripts</filename> to add and manage kernel
- patches and configuration.
- See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
- section in the Yocto Project Board Support Packages (BSP)
- Developer's Guide for more information on the
- <filename>yocto-kernel</filename> script.
<orderedlist>
<listitem><para>
<emphasis>Edit the Source Files</emphasis>
@@ -1413,9 +1402,9 @@
SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
</literallayout>
The
- <ulink url='&YOCTO_DOCS_REF_URL;var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
and
- <ulink url='&YOCTO_DOCS_REF_URL;var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
statements enable the OpenEmbedded build system to find
the patch file.</para>
@@ -1667,7 +1656,7 @@
after applying the existing defconfig file configurations.
</note>
For more information on configuring the kernel, see the
- "<link link='changing-the-configuration'>Changing the Configuration</link>"
+ "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
section.
</para>
</section>
@@ -2429,7 +2418,7 @@
modules.
If your module <filename>Makefile</filename> uses a different
variable, you might want to override the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
step, or create a patch to
the <filename>Makefile</filename> to work with the more typical
<filename>KERNEL_SRC</filename> or
@@ -2505,7 +2494,7 @@
the Git commands.
You can see the branch names through the web interface
to the Yocto Project source repositories at
- <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
</note>
To see a full range of the changes, use the
<filename>git whatchanged</filename> command and specify a
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index fbecc13..6d675a6 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -49,7 +49,7 @@
<para>
You can find a web interface to the Yocto Linux kernels in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
at
<ulink url='&YOCTO_GIT_URL;'></ulink>.
If you look at the interface, you will see to the left a
@@ -239,8 +239,9 @@
<ulink url='http://git-scm.com/documentation'></ulink>.
You can also get an introduction to Git as it
applies to the Yocto Project in the
- "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
- section in the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual.
The latter reference provides an overview of
Git and presents a minimal set of Git commands
that allows you to be functional using Git.
@@ -381,7 +382,7 @@
generic kernel just for conceptual purposes.
Also keep in mind that this structure represents the Yocto
Project
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
that are either pulled from during the build or established
on the host development system prior to the build by either
cloning a particular kernel's Git repository or by
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml
index dba4549..4e4fd28 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-intro.xml
@@ -108,7 +108,11 @@
review and understand the following documentation:
<itemizedlist>
<listitem><para>
- <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+ document.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
</para></listitem>
<listitem><para>
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
@@ -127,18 +131,6 @@
</para></listitem>
</itemizedlist>
</para>
-
- <para>
- Finally, while this document focuses on the manual creation of
- recipes, patches, and configuration files, the Yocto Project
- Board Support Package (BSP) tools are available to automate
- this process with existing content and work well to create the
- initial framework and boilerplate code.
- For details on these tools, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
- section in the Yocto Project Board Support Package (BSP) Developer's
- Guide.
- </para>
</section>
<section id='kernel-modification-workflow'>
@@ -165,12 +157,15 @@
<para>
<orderedlist>
<listitem><para>
- <emphasis>Set Up Your Host Development System to Support
- Development Using the Yocto Project:</emphasis>
+
+
+ <emphasis>Set up Your Host Development System to Support
+ Development Using the Yocto Project</emphasis>:
See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
- section in the Yocto Project Quick Start for options on how
- to get a build host ready to use the Yocto Project.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
+ section in the Yocto Project Development Tasks Manual for
+ options on how to get a build host ready to use the Yocto
+ Project.
</para></listitem>
<listitem><para>
<emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>
@@ -243,11 +238,7 @@
<para>Additionally, if you are working in a BSP layer
and need to modify the BSP's kernel's configuration,
- you can use the
- <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink>
- script as well as <filename>menuconfig</filename>.
- The <filename>yocto-kernel</filename> script lets
- you interactively set up kernel configurations.
+ you can use <filename>menuconfig</filename>.
</para></listitem>
<listitem><para>
<emphasis>Rebuild the Kernel Image With Your Changes:</emphasis>
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml
index f5fd183..b825ae7 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -14,7 +14,7 @@
create Yocto Linux kernel repositories.
These kernel repositories are found under the heading "Yocto Linux
Kernel" at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
+ <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink>
and are shipped as part of a Yocto Project release.
The team creates these repositories by compiling and executing the
set of feature descriptions for every BSP and feature in the
@@ -118,13 +118,13 @@
The following steps describe what happens when the Yocto Project
Team constructs the Yocto Project kernel source Git repository
(or tree) found at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
+ <ulink url='&YOCTO_GIT_URL;'></ulink> given the
introduction of a new top-level kernel feature or BSP.
- These are the actions that effectively provide the Metadata
- and create the tree that includes the new feature, patch or BSP:
+ The following actions effectively provide the Metadata
+ and create the tree that includes the new feature, patch, or BSP:
<orderedlist>
<listitem><para>
- <emphasis>Pass Feature to Build Subsystem:</emphasis>
+ <emphasis>Pass Feature to the OpenEmbedded Build System:</emphasis>
A top-level kernel feature is passed to the kernel build
subsystem.
Normally, this feature is a BSP for a particular kernel
@@ -138,8 +138,10 @@
<listitem><para>
The in-tree kernel-cache directories, which are
located in the
- <filename>yocto-kernel-cache</filename>
- repository
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp'><filename>yocto-kernel-cache</filename></ulink>
+ repository organized under the "Yocto Linux Kernel"
+ heading in the
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
</para></listitem>
<listitem><para>
Areas pointed to by <filename>SRC_URI</filename>
@@ -148,9 +150,11 @@
</itemizedlist>
For a typical build, the target of the search is a
feature description in an <filename>.scc</filename> file
- whose name follows this format:
+ whose name follows this format (e.g.
+ <filename>beaglebone-standard.scc</filename> and
+ <filename>beaglebone-preempt-rt.scc</filename>):
<literallayout class='monospaced'>
- <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
+ <replaceable>bsp_root_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
</literallayout>
</para></listitem>
<listitem><para>
@@ -213,7 +217,7 @@
end of an existing branch.
The full repository generation that is found in the
official Yocto Project kernel repositories at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
+ <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>
is the combination of all supported boards and
configurations.
</para></listitem>
@@ -227,7 +231,7 @@
</para></listitem>
<listitem><para>
The full kernel tree that you see on
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> is
+ <ulink url='&YOCTO_GIT_URL;'></ulink> is
generated through repeating the above steps for all
valid BSPs.
The end result is a branched, clean history tree that
diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml
index ec36d24..986c440 100644
--- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml
+++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml
@@ -87,14 +87,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -116,24 +111,36 @@
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
</legalnotice>
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/analysis-for-package-splitting.png b/import-layers/yocto-poky/documentation/mega-manual/figures/analysis-for-package-splitting.png
index 04f2794..0cb0386 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/analysis-for-package-splitting.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/analysis-for-package-splitting.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/bsp-dev-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/bsp-dev-flow.png
index 0f82a1f..2ca1fec 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/bsp-dev-flow.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/bsp-dev-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/bypqs-title.png b/import-layers/yocto-poky/documentation/mega-manual/figures/bypqs-title.png
new file mode 100644
index 0000000..9e0a5ce
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/bypqs-title.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/concepts-manual-title.png b/import-layers/yocto-poky/documentation/mega-manual/figures/concepts-manual-title.png
new file mode 100644
index 0000000..bac7a69
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/concepts-manual-title.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/configuration-compile-autoreconf.png b/import-layers/yocto-poky/documentation/mega-manual/figures/configuration-compile-autoreconf.png
index a07464f..043d195 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/configuration-compile-autoreconf.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/configuration-compile-autoreconf.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/cross-development-toolchains.png b/import-layers/yocto-poky/documentation/mega-manual/figures/cross-development-toolchains.png
index d36670a..cbe8371 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/cross-development-toolchains.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/cross-development-toolchains.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/image-generation.png b/import-layers/yocto-poky/documentation/mega-manual/figures/image-generation.png
index 71a48dc..aff9fc2 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/image-generation.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/image-generation.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/images.png b/import-layers/yocto-poky/documentation/mega-manual/figures/images.png
index d99eac1..20c0130 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/images.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/images.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/key-dev-elements.png b/import-layers/yocto-poky/documentation/mega-manual/figures/key-dev-elements.png
new file mode 100644
index 0000000..76c4405
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/key-dev-elements.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/layer-input.png b/import-layers/yocto-poky/documentation/mega-manual/figures/layer-input.png
index 0a4f2e7..29b56f9 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/layer-input.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/layer-input.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/overview-manual-title.png b/import-layers/yocto-poky/documentation/mega-manual/figures/overview-manual-title.png
new file mode 100644
index 0000000..41e9012
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/overview-manual-title.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/package-feeds.png b/import-layers/yocto-poky/documentation/mega-manual/figures/package-feeds.png
index 37c9c32..7592839 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/package-feeds.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/package-feeds.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/patching.png b/import-layers/yocto-poky/documentation/mega-manual/figures/patching.png
index 8ecd018..80fba7e 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/patching.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/patching.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/poky-reference-distribution.png b/import-layers/yocto-poky/documentation/mega-manual/figures/poky-reference-distribution.png
new file mode 100644
index 0000000..1be89ae
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/poky-reference-distribution.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-autotools-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-autotools-flow.png
new file mode 100644
index 0000000..ec6685f
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-autotools-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png
index c09e60e..e7d6173 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png
index cd06c01..18ba8b7 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png
index 65474da..7d4f395 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-generation.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-generation.png
old mode 100755
new mode 100644
index adbe1f4..939f839
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-generation.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-generation.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-makefile-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-makefile-flow.png
new file mode 100644
index 0000000..0ccb418
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-makefile-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk.png
index 5c36b75..a376872 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/source-fetching.png b/import-layers/yocto-poky/documentation/mega-manual/figures/source-fetching.png
index 26aefb5..bf5e187 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/source-fetching.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/source-fetching.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/source-input.png b/import-layers/yocto-poky/documentation/mega-manual/figures/source-input.png
index f751505..6b6ba4b 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/source-input.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/source-input.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/user-configuration.png b/import-layers/yocto-poky/documentation/mega-manual/figures/user-configuration.png
old mode 100755
new mode 100644
index c298401..1424547
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/user-configuration.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/user-configuration.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment-ref.png b/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment-ref.png
deleted file mode 100644
index 650c6c8..0000000
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment-ref.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/yp-download.png b/import-layers/yocto-poky/documentation/mega-manual/figures/yp-download.png
index 5770be6..bfd12b6 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/figures/yp-download.png
+++ b/import-layers/yocto-poky/documentation/mega-manual/figures/yp-download.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml b/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml
index a941d79..2c0943e 100644
--- a/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml
+++ b/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml
@@ -71,14 +71,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -100,24 +95,36 @@
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
@@ -125,10 +132,32 @@
</bookinfo>
-<!-- Includes yocto-project-qs -->
+<!-- Includes brief-yoctoprojectqs -->
+
+ <para>
+ <imagedata fileref="figures/bypqs-title.png" width="100%" align="left" scalefit="1" />
+ </para>
<xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../yocto-project-qs/yocto-project-qs.xml"/>
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../brief-yoctoprojectqs/brief-yoctoprojectqs.xml"/>
+
+<!-- Includes overview-manual title image and then overview-manual chapters -->
+
+ <para>
+ <imagedata fileref="figures/overview-manual-title.png" width="100%" align="left" scalefit="1" />
+ </para>
+
+ <xi:include
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-intro.xml"/>
+
+ <xi:include
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-yp-intro.xml"/>
+
+ <xi:include
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-development-environment.xml"/>
+
+ <xi:include
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-concepts.xml"/>
<!-- Includes dev-manual title image and then dev-manual chapters -->
@@ -141,8 +170,6 @@
<xi:include
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/>
<xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/>
- <xi:include
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
<xi:include
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/>
@@ -170,7 +197,7 @@
<xi:include
xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-customizing-standard.xml"/>
<xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-mars.xml"/>
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-neon.xml"/>
<!-- Includes bsp-guide title image and then bsp-guide chapters -->
@@ -220,16 +247,10 @@
</para>
<xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/introduction.xml"/>
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-system-requirements.xml"/>
<xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/usingpoky.xml"/>
-
- <xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-development-environment.xml"/>
-
- <xi:include
- xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/technical-details.xml"/>
+ xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-terms.xml"/>
<xi:include
xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-release-process.xml"/>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/YP-flow-diagram.png b/import-layers/yocto-poky/documentation/overview-manual/figures/YP-flow-diagram.png
similarity index 100%
rename from import-layers/yocto-poky/documentation/ref-manual/figures/YP-flow-diagram.png
rename to import-layers/yocto-poky/documentation/overview-manual/figures/YP-flow-diagram.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/analysis-for-package-splitting.png b/import-layers/yocto-poky/documentation/overview-manual/figures/analysis-for-package-splitting.png
new file mode 100644
index 0000000..0cb0386
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/analysis-for-package-splitting.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/configuration-compile-autoreconf.png b/import-layers/yocto-poky/documentation/overview-manual/figures/configuration-compile-autoreconf.png
new file mode 100644
index 0000000..043d195
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/configuration-compile-autoreconf.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/cross-development-toolchains.png b/import-layers/yocto-poky/documentation/overview-manual/figures/cross-development-toolchains.png
new file mode 100644
index 0000000..cbe8371
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/cross-development-toolchains.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/git-workflow.png b/import-layers/yocto-poky/documentation/overview-manual/figures/git-workflow.png
similarity index 100%
rename from import-layers/yocto-poky/documentation/ref-manual/figures/git-workflow.png
rename to import-layers/yocto-poky/documentation/overview-manual/figures/git-workflow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/image-generation.png b/import-layers/yocto-poky/documentation/overview-manual/figures/image-generation.png
new file mode 100644
index 0000000..aff9fc2
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/image-generation.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/images.png b/import-layers/yocto-poky/documentation/overview-manual/figures/images.png
new file mode 100644
index 0000000..20c0130
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/images.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/index-downloads.png b/import-layers/yocto-poky/documentation/overview-manual/figures/index-downloads.png
similarity index 100%
rename from import-layers/yocto-poky/documentation/ref-manual/figures/index-downloads.png
rename to import-layers/yocto-poky/documentation/overview-manual/figures/index-downloads.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/key-dev-elements.png b/import-layers/yocto-poky/documentation/overview-manual/figures/key-dev-elements.png
new file mode 100644
index 0000000..76c4405
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/key-dev-elements.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/layer-input.png b/import-layers/yocto-poky/documentation/overview-manual/figures/layer-input.png
new file mode 100644
index 0000000..29b56f9
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/layer-input.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/overview-manual-title.png b/import-layers/yocto-poky/documentation/overview-manual/figures/overview-manual-title.png
new file mode 100644
index 0000000..41e9012
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/overview-manual-title.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/package-feeds.png b/import-layers/yocto-poky/documentation/overview-manual/figures/package-feeds.png
new file mode 100644
index 0000000..7592839
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/package-feeds.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/patching.png b/import-layers/yocto-poky/documentation/overview-manual/figures/patching.png
new file mode 100644
index 0000000..80fba7e
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/patching.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/poky-reference-distribution.png b/import-layers/yocto-poky/documentation/overview-manual/figures/poky-reference-distribution.png
new file mode 100644
index 0000000..1be89ae
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/poky-reference-distribution.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/sdk-generation.png b/import-layers/yocto-poky/documentation/overview-manual/figures/sdk-generation.png
new file mode 100644
index 0000000..939f839
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/sdk-generation.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/sdk.png b/import-layers/yocto-poky/documentation/overview-manual/figures/sdk.png
new file mode 100644
index 0000000..a376872
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/sdk.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/source-fetching.png b/import-layers/yocto-poky/documentation/overview-manual/figures/source-fetching.png
new file mode 100644
index 0000000..bf5e187
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/source-fetching.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/source-input.png b/import-layers/yocto-poky/documentation/overview-manual/figures/source-input.png
new file mode 100644
index 0000000..6b6ba4b
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/source-input.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/source-repos.png b/import-layers/yocto-poky/documentation/overview-manual/figures/source-repos.png
new file mode 100644
index 0000000..603300b
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/source-repos.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/user-configuration.png b/import-layers/yocto-poky/documentation/overview-manual/figures/user-configuration.png
new file mode 100644
index 0000000..1424547
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/user-configuration.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/figures/yp-download.png b/import-layers/yocto-poky/documentation/overview-manual/figures/yp-download.png
new file mode 100644
index 0000000..bfd12b6
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/figures/yp-download.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/overview-manual/overview-manual-concepts.xml b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-concepts.xml
new file mode 100644
index 0000000..338a190
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-concepts.xml
@@ -0,0 +1,3232 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id=' overview-manual-concepts'>
+<title>Yocto Project Concepts</title>
+
+ <para>
+ This chapter provides explanations for Yocto Project concepts that
+ go beyond the surface of "how-to" information and reference (or
+ look-up) material.
+ Concepts such as components, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ workflow, cross-development toolchains, shared state cache, and so
+ forth are explained.
+ </para>
+
+ <section id='yocto-project-components'>
+ <title>Yocto Project Components</title>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ task executor together with various types of configuration files
+ form the
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>.
+ This section overviews these components by describing their use and
+ how they interact.
+ </para>
+
+ <para>
+ BitBake handles the parsing and execution of the data files.
+ The data itself is of various types:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Recipes:</emphasis>
+ Provides details about particular pieces of software.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Class Data:</emphasis>
+ Abstracts common build information (e.g. how to build a
+ Linux kernel).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Configuration Data:</emphasis>
+ Defines machine-specific settings, policy decisions, and
+ so forth.
+ Configuration data acts as the glue to bind everything
+ together.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ BitBake knows how to combine multiple data sources together and
+ refers to each data source as a layer.
+ For information on layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ Following are some brief details on these core components.
+ For additional information on how these components interact during
+ a build, see the
+ "<link linkend='openembedded-build-system-build-concepts'>OpenEmbedded Build System Concepts</link>"
+ section.
+ </para>
+
+ <section id='usingpoky-components-bitbake'>
+ <title>BitBake</title>
+
+ <para>
+ BitBake is the tool at the heart of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ and is responsible for parsing the
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
+ generating a list of tasks from it, and then executing those
+ tasks.
+ </para>
+
+ <para>
+ This section briefly introduces BitBake.
+ If you want more information on BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
+ </para>
+
+ <para>
+ To see a list of the options BitBake supports, use either of
+ the following commands:
+ <literallayout class='monospaced'>
+ $ bitbake -h
+ $ bitbake --help
+ </literallayout>
+ </para>
+
+ <para>
+ The most common usage for BitBake is
+ <filename>bitbake <replaceable>packagename</replaceable></filename>,
+ where <filename>packagename</filename> is the name of the
+ package you want to build (referred to as the "target").
+ The target often equates to the first part of a recipe's
+ filename (e.g. "foo" for a recipe named
+ <filename>foo_1.3.0-r0.bb</filename>).
+ So, to process the
+ <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
+ might type the following:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop
+ </literallayout>
+ Several different versions of
+ <filename>matchbox-desktop</filename> might exist.
+ BitBake chooses the one selected by the distribution
+ configuration.
+ You can get more details about how BitBake chooses between
+ different target versions and providers in the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-preferences'>Preferences</ulink>"
+ section of the BitBake User Manual.
+ </para>
+
+ <para>
+ BitBake also tries to execute any dependent tasks first.
+ So for example, before building
+ <filename>matchbox-desktop</filename>, BitBake would build a
+ cross compiler and <filename>glibc</filename> if they had not
+ already been built.
+ </para>
+
+ <para>
+ A useful BitBake option to consider is the
+ <filename>-k</filename> or <filename>--continue</filename>
+ option.
+ This option instructs BitBake to try and continue processing
+ the job as long as possible even after encountering an error.
+ When an error occurs, the target that failed and those that
+ depend on it cannot be remade.
+ However, when you use this option other dependencies can
+ still be processed.
+ </para>
+ </section>
+
+ <section id='overview-components-recipes'>
+ <title>Recipes</title>
+
+ <para>
+ Files that have the <filename>.bb</filename> suffix are
+ "recipes" files.
+ In general, a recipe contains information about a single piece
+ of software.
+ This information includes the location from which to download
+ the unaltered source, any source patches to be applied to that
+ source (if needed), which special configuration options to
+ apply, how to compile the source files, and how to package the
+ compiled output.
+ </para>
+
+ <para>
+ The term "package" is sometimes used to refer to recipes.
+ However, since the word "package" is used for the packaged
+ output from the OpenEmbedded build system (i.e.
+ <filename>.ipk</filename> or <filename>.deb</filename> files),
+ this document avoids using the term "package" when referring
+ to recipes.
+ </para>
+ </section>
+
+ <section id='overview-components-classes'>
+ <title>Classes</title>
+
+ <para>
+ Class files (<filename>.bbclass</filename>) contain information
+ that is useful to share between recipes files.
+ An example is the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
+ class, which contains common settings for any application that
+ Autotools uses.
+ The
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
+ chapter in the Yocto Project Reference Manual provides
+ details about classes and how to use them.
+ </para>
+ </section>
+
+ <section id='overview-components-configurations'>
+ <title>Configurations</title>
+
+ <para>
+ The configuration files (<filename>.conf</filename>) define
+ various configuration variables that govern the OpenEmbedded
+ build process.
+ These files fall into several areas that define machine
+ configuration options, distribution configuration options,
+ compiler tuning options, general common configuration options,
+ and user configuration options in
+ <filename>conf/local.conf</filename>, which is found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ </para>
+ </section>
+ </section>
+
+ <section id='overview-layers'>
+ <title>Layers</title>
+
+ <para>
+ Layers are repositories that contain related metadata (i.e.
+ sets of instructions) that tell the OpenEmbedded build system how
+ to build a target.
+ Yocto Project's
+ <link linkend='the-yocto-project-layer-model'>layer model</link>
+ facilitates collaboration, sharing, customization, and reuse
+ within the Yocto Project development environment.
+ Layers logically separate information for your project.
+ For example, you can use a layer to hold all the configurations
+ for a particular piece of hardware.
+ Isolating hardware-specific configurations allows you to share
+ other metadata by using a different layer where that metadata
+ might be common across several pieces of hardware.
+ </para>
+
+ <para>
+ Many layers exist that work in the Yocto Project development
+ environment.
+ The
+ <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project Curated Layer Index</ulink>
+ and
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded Layer Index</ulink>
+ both contain layers from which you can use or leverage.
+ </para>
+
+ <para>
+ By convention, layers in the Yocto Project follow a specific form.
+ Conforming to a known structure allows BitBake to make assumptions
+ during builds on where to find types of metadata.
+ You can find procedures and learn about tools (i.e.
+ <filename>bitbake-layers</filename>) for creating layers suitable
+ for the Yocto Project in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
+
+ <section id="openembedded-build-system-build-concepts">
+ <title>OpenEmbedded Build System Concepts</title>
+
+ <para>
+ This section takes a more detailed look inside the build
+ process used by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>,
+ which is the build system specific to the Yocto Project.
+ At the heart of the build system is BitBake, the task executor.
+ </para>
+
+ <para>
+ The following diagram represents the high-level workflow of a
+ build.
+ The remainder of this section expands on the fundamental input,
+ output, process, and metadata logical blocks that make up the
+ workflow.
+ </para>
+
+ <para id='general-workflow-figure'>
+ <imagedata fileref="figures/YP-flow-diagram.png" format="PNG" align='center' width="8in"/>
+ </para>
+
+ <para>
+ In general, the build's workflow consists of several functional
+ areas:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>User Configuration:</emphasis>
+ metadata you can use to control the build process.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Metadata Layers:</emphasis>
+ Various layers that provide software, machine, and
+ distro metadata.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Source Files:</emphasis>
+ Upstream releases, local projects, and SCMs.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build System:</emphasis>
+ Processes under the control of
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
+ This block expands on how BitBake fetches source, applies
+ patches, completes compilation, analyzes output for package
+ generation, creates and tests packages, generates images,
+ and generates cross-development tools.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Package Feeds:</emphasis>
+ Directories containing output packages (RPM, DEB or IPK),
+ which are subsequently used in the construction of an
+ image or Software Development Kit (SDK), produced by the
+ build system.
+ These feeds can also be copied and shared using a web
+ server or other means to facilitate extending or updating
+ existing images on devices at runtime if runtime package
+ management is enabled.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Images:</emphasis>
+ Images produced by the workflow.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Application Development SDK:</emphasis>
+ Cross-development tools that are produced along with
+ an image or separately with BitBake.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <section id="user-configuration">
+ <title>User Configuration</title>
+
+ <para>
+ User configuration helps define the build.
+ Through user configuration, you can tell BitBake the
+ target architecture for which you are building the image,
+ where to store downloaded source, and other build properties.
+ </para>
+
+ <para>
+ The following figure shows an expanded representation of the
+ "User Configuration" box of the
+ <link linkend='general-workflow-figure'>general workflow figure</link>:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/user-configuration.png" align="center" width="8in" depth="4.5in" />
+ </para>
+
+ <para>
+ BitBake needs some basic configuration files in order to
+ complete a build.
+ These files are <filename>*.conf</filename> files.
+ The minimally necessary ones reside as example files in the
+ <filename>build/conf</filename> directory of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ For simplicity, this section refers to the Source Directory as
+ the "Poky Directory."
+ </para>
+
+ <para>
+ When you clone the
+ <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
+ Git repository or you download and unpack a Yocto Project
+ release, you can set up the Source Directory to be named
+ anything you want.
+ For this discussion, the cloned repository uses the default
+ name <filename>poky</filename>.
+ <note>
+ The Poky repository is primarily an aggregation of existing
+ repositories.
+ It is not a canonical upstream source.
+ </note>
+ </para>
+
+ <para>
+ The <filename>meta-poky</filename> layer inside Poky contains
+ a <filename>conf</filename> directory that has example
+ configuration files.
+ These example files are used as a basis for creating actual
+ configuration files when you source
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>,
+ which is the build environment script.
+ </para>
+
+ <para>
+ Sourcing the build environment script creates a
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ if one does not already exist.
+ BitBake uses the Build Directory for all its work during
+ builds.
+ The Build Directory has a <filename>conf</filename> directory
+ that contains default versions of your
+ <filename>local.conf</filename> and
+ <filename>bblayers.conf</filename> configuration files.
+ These default configuration files are created only if versions
+ do not already exist in the Build Directory at the time you
+ source the build environment setup script.
+ </para>
+
+ <para>
+ Because the Poky repository is fundamentally an aggregation of
+ existing repositories, some users might be familiar with
+ running the <filename>&OE_INIT_FILE;</filename> script
+ in the context of separate
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>
+ and BitBake repositories rather than a single Poky repository.
+ This discussion assumes the script is executed from
+ within a cloned or unpacked version of Poky.
+ </para>
+
+ <para>
+ Depending on where the script is sourced, different
+ sub-scripts are called to set up the Build Directory
+ (Yocto or OpenEmbedded).
+ Specifically, the script
+ <filename>scripts/oe-setup-builddir</filename> inside the
+ poky directory sets up the Build Directory and seeds the
+ directory (if necessary) with configuration files appropriate
+ for the Yocto Project development environment.
+ <note>
+ The <filename>scripts/oe-setup-builddir</filename> script
+ uses the <filename>$TEMPLATECONF</filename> variable to
+ determine which sample configuration files to locate.
+ </note>
+ </para>
+
+ <para>
+ The <filename>local.conf</filename> file provides many
+ basic variables that define a build environment.
+ Here is a list of a few.
+ To see the default configurations in a
+ <filename>local.conf</filename> file created by the build
+ environment script, see the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample'><filename>local.conf.sample</filename></ulink>
+ in the <filename>meta-poky</filename> layer:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Target Machine Selection:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download Directory:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Shared State Directory:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build Output:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Distribution Policy:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Packaging Format:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>SDK Target Architecture:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extra Image Packages:</emphasis>
+ Controlled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
+ variable.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ Configurations set in the
+ <filename>conf/local.conf</filename> file can also be set
+ in the <filename>conf/site.conf</filename> and
+ <filename>conf/auto.conf</filename> configuration files.
+ </note>
+ </para>
+
+ <para>
+ The <filename>bblayers.conf</filename> file tells BitBake what
+ layers you want considered during the build.
+ By default, the layers listed in this file include layers
+ minimally needed by the build system.
+ However, you must manually add any custom layers you have
+ created.
+ You can find more information on working with the
+ <filename>bblayers.conf</filename> file in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ The files <filename>site.conf</filename> and
+ <filename>auto.conf</filename> are not created by the
+ environment initialization script.
+ If you want the <filename>site.conf</filename> file, you
+ need to create that yourself.
+ The <filename>auto.conf</filename> file is typically created by
+ an autobuilder:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>site.conf</filename>:</emphasis>
+ You can use the <filename>conf/site.conf</filename>
+ configuration file to configure multiple
+ build directories.
+ For example, suppose you had several build environments
+ and they shared some common features.
+ You can set these default build properties here.
+ A good example is perhaps the packaging format to use
+ through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
+ variable.</para>
+
+ <para>One useful scenario for using the
+ <filename>conf/site.conf</filename> file is to extend
+ your
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
+ variable to include the path to a
+ <filename>conf/site.conf</filename>.
+ Then, when BitBake looks for Metadata using
+ <filename>BBPATH</filename>, it finds the
+ <filename>conf/site.conf</filename> file and applies
+ your common configurations found in the file.
+ To override configurations in a particular build
+ directory, alter the similar configurations within
+ that build directory's
+ <filename>conf/local.conf</filename> file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>auto.conf</filename>:</emphasis>
+ The file is usually created and written to by
+ an autobuilder.
+ The settings put into the file are typically the
+ same as you would find in the
+ <filename>conf/local.conf</filename> or the
+ <filename>conf/site.conf</filename> files.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ You can edit all configuration files to further define
+ any particular build environment.
+ This process is represented by the "User Configuration Edits"
+ box in the figure.
+ </para>
+
+ <para>
+ When you launch your build with the
+ <filename>bitbake <replaceable>target</replaceable></filename>
+ command, BitBake sorts out the configurations to ultimately
+ define your build environment.
+ It is important to understand that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ reads the configuration files in a specific order:
+ <filename>site.conf</filename>, <filename>auto.conf</filename>,
+ and <filename>local.conf</filename>.
+ And, the build system applies the normal assignment statement
+ rules as described in the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
+ chapter of the BitBake User Manual.
+ Because the files are parsed in a specific order, variable
+ assignments for the same variable could be affected.
+ For example, if the <filename>auto.conf</filename> file and
+ the <filename>local.conf</filename> set
+ <replaceable>variable1</replaceable> to different values,
+ because the build system parses <filename>local.conf</filename>
+ after <filename>auto.conf</filename>,
+ <replaceable>variable1</replaceable> is assigned the value from
+ the <filename>local.conf</filename> file.
+ </para>
+ </section>
+
+ <section id="metadata-machine-configuration-and-policy-configuration">
+ <title>Metadata, Machine Configuration, and Policy Configuration</title>
+
+ <para>
+ The previous section described the user configurations that
+ define BitBake's global behavior.
+ This section takes a closer look at the layers the build system
+ uses to further control the build.
+ These layers provide Metadata for the software, machine, and
+ policies.
+ </para>
+
+ <para>
+ In general, three types of layer input exists.
+ You can see them below the "User Configuration" box in the
+ <link linkend='general-workflow-figure'>general workflow figure</link>:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Metadata (<filename>.bb</filename> + Patches):</emphasis>
+ Software layers containing user-supplied recipe files,
+ patches, and append files.
+ A good example of a software layer might be the
+ <ulink url='https://github.com/meta-qt5/meta-qt5'><filename>meta-qt5</filename></ulink>
+ layer from the
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded Layer Index</ulink>.
+ This layer is for version 5.0 of the popular
+ <ulink url='https://wiki.qt.io/About_Qt'>Qt</ulink>
+ cross-platform application development framework for
+ desktop, embedded and mobile.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Machine BSP Configuration:</emphasis>
+ Board Support Package (BSP) layers (i.e. "BSP Layer"
+ in the following figure) providing machine-specific
+ configurations.
+ This type of information is specific to a particular
+ target architecture.
+ A good example of a BSP layer from the
+ <link linkend='gs-reference-distribution-poky'>Poky Reference Distribution</link>
+ is the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>
+ layer.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Policy Configuration:</emphasis>
+ Distribution Layers (i.e. "Distro Layer" in the
+ following figure) providing top-level or general
+ policies for the images or SDKs being built for a
+ particular distribution.
+ For example, in the Poky Reference Distribution the
+ distro layer is the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky'><filename>meta-poky</filename></ulink>
+ layer.
+ Within the distro layer is a
+ <filename>conf/distro</filename> directory that
+ contains distro configuration files (e.g.
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/distro/poky.conf'><filename>poky.conf</filename></ulink>
+ that contain many policy configurations for the
+ Poky distribution.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The following figure shows an expanded representation of
+ these three layers from the
+ <link linkend='general-workflow-figure'>general workflow figure</link>:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="8in" />
+ </para>
+
+ <para>
+ In general, all layers have a similar structure.
+ They all contain a licensing file
+ (e.g. <filename>COPYING.MIT</filename>) if the layer is to be
+ distributed, a <filename>README</filename> file as good
+ practice and especially if the layer is to be distributed, a
+ configuration directory, and recipe directories.
+ You can learn about the general structure for layers used with
+ the Yocto Project in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ For a general discussion on layers and the many layers from
+ which you can draw, see the
+ "<link linkend='overview-layers'>Layers</link>" and
+ "<link linkend='the-yocto-project-layer-model'>The Yocto Project Layer Model</link>"
+ sections both earlier in this manual.
+ </para>
+
+ <para>
+ If you explored the previous links, you discovered some
+ areas where many layers that work with the Yocto Project
+ exist.
+ The
+ <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
+ also shows layers categorized under "Yocto Metadata Layers."
+ <note>
+ Layers exist in the Yocto Project Source Repositories that
+ cannot be found in the OpenEmbedded Layer Index.
+ These layers are either deprecated or experimental
+ in nature.
+ </note>
+ </para>
+
+ <para>
+ BitBake uses the <filename>conf/bblayers.conf</filename> file,
+ which is part of the user configuration, to find what layers it
+ should be using as part of the build.
+ </para>
+
+ <section id="distro-layer">
+ <title>Distro Layer</title>
+
+ <para>
+ The distribution layer provides policy configurations for
+ your distribution.
+ Best practices dictate that you isolate these types of
+ configurations into their own layer.
+ Settings you provide in
+ <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override
+ similar settings that BitBake finds in your
+ <filename>conf/local.conf</filename> file in the Build
+ Directory.
+ </para>
+
+ <para>
+ The following list provides some explanation and references
+ for what you typically find in the distribution layer:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>classes:</emphasis>
+ Class files (<filename>.bbclass</filename>) hold
+ common functionality that can be shared among
+ recipes in the distribution.
+ When your recipes inherit a class, they take on the
+ settings and functions for that class.
+ You can read more about class files in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>"
+ chapter of the Yocto Reference Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>conf:</emphasis>
+ This area holds configuration files for the
+ layer (<filename>conf/layer.conf</filename>),
+ the distribution
+ (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>),
+ and any distribution-wide include files.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>recipes-*:</emphasis>
+ Recipes and append files that affect common
+ functionality across the distribution.
+ This area could include recipes and append files
+ to add distribution-specific configuration,
+ initialization scripts, custom image recipes,
+ and so forth.
+ Examples of <filename>recipes-*</filename>
+ directories are <filename>recipes-core</filename>
+ and <filename>recipes-extra</filename>.
+ Hierarchy and contents within a
+ <filename>recipes-*</filename> directory can vary.
+ Generally, these directories contain recipe files
+ (<filename>*.bb</filename>), recipe append files
+ (<filename>*.bbappend</filename>), directories
+ that are distro-specific for configuration files,
+ and so forth.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="bsp-layer">
+ <title>BSP Layer</title>
+
+ <para>
+ The BSP Layer provides machine configurations that
+ target specific hardware.
+ Everything in this layer is specific to the machine for
+ which you are building the image or the SDK.
+ A common structure or form is defined for BSP layers.
+ You can learn more about this structure in the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+ <note>
+ In order for a BSP layer to be considered compliant
+ with the Yocto Project, it must meet some structural
+ requirements.
+ </note>
+ </para>
+
+ <para>
+ The BSP Layer's configuration directory contains
+ configuration files for the machine
+ (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>)
+ and, of course, the layer
+ (<filename>conf/layer.conf</filename>).
+ </para>
+
+ <para>
+ The remainder of the layer is dedicated to specific recipes
+ by function: <filename>recipes-bsp</filename>,
+ <filename>recipes-core</filename>,
+ <filename>recipes-graphics</filename>,
+ <filename>recipes-kernel</filename>, and so forth.
+ Metadata can exist for multiple formfactors, graphics
+ support systems, and so forth.
+ <note>
+ While the figure shows several
+ <filename>recipes-*</filename> directories, not all
+ these directories appear in all BSP layers.
+ </note>
+ </para>
+ </section>
+
+ <section id="software-layer">
+ <title>Software Layer</title>
+
+ <para>
+ The software layer provides the Metadata for additional
+ software packages used during the build.
+ This layer does not include Metadata that is specific to
+ the distribution or the machine, which are found in their
+ respective layers.
+ </para>
+
+ <para>
+ This layer contains any recipes, append files, and
+ patches, that your project needs.
+ </para>
+ </section>
+ </section>
+
+ <section id="sources-dev-environment">
+ <title>Sources</title>
+
+ <para>
+ In order for the OpenEmbedded build system to create an
+ image or any target, it must be able to access source files.
+ The
+ <link linkend='general-workflow-figure'>general workflow figure</link>
+ represents source files using the "Upstream Project Releases",
+ "Local Projects", and "SCMs (optional)" boxes.
+ The figure represents mirrors, which also play a role in
+ locating source files, with the "Source Materials" box.
+ </para>
+
+ <para>
+ The method by which source files are ultimately organized is
+ a function of the project.
+ For example, for released software, projects tend to use
+ tarballs or other archived files that can capture the
+ state of a release guaranteeing that it is statically
+ represented.
+ On the other hand, for a project that is more dynamic or
+ experimental in nature, a project might keep source files in a
+ repository controlled by a Source Control Manager (SCM) such as
+ Git.
+ Pulling source from a repository allows you to control
+ the point in the repository (the revision) from which you
+ want to build software.
+ Finally, a combination of the two might exist, which would
+ give the consumer a choice when deciding where to get
+ source files.
+ </para>
+
+ <para>
+ BitBake uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ variable to point to source files regardless of their location.
+ Each recipe must have a <filename>SRC_URI</filename> variable
+ that points to the source.
+ </para>
+
+ <para>
+ Another area that plays a significant role in where source
+ files come from is pointed to by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+ variable.
+ This area is a cache that can hold previously downloaded
+ source.
+ You can also instruct the OpenEmbedded build system to create
+ tarballs from Git repositories, which is not the default
+ behavior, and store them in the <filename>DL_DIR</filename>
+ by using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
+ variable.
+ </para>
+
+ <para>
+ Judicious use of a <filename>DL_DIR</filename> directory can
+ save the build system a trip across the Internet when looking
+ for files.
+ A good method for using a download directory is to have
+ <filename>DL_DIR</filename> point to an area outside of your
+ Build Directory.
+ Doing so allows you to safely delete the Build Directory
+ if needed without fear of removing any downloaded source file.
+ </para>
+
+ <para>
+ The remainder of this section provides a deeper look into the
+ source files and the mirrors.
+ Here is a more detailed look at the source file area of the
+ <link linkend='general-workflow-figure'>general workflow figure</link>:
+ </para>
+
+ <para>
+ <imagedata fileref="figures/source-input.png" width="6in" depth="6in" align="center" />
+ </para>
+
+ <section id='upstream-project-releases'>
+ <title>Upstream Project Releases</title>
+
+ <para>
+ Upstream project releases exist anywhere in the form of an
+ archived file (e.g. tarball or zip file).
+ These files correspond to individual recipes.
+ For example, the figure uses specific releases each for
+ BusyBox, Qt, and Dbus.
+ An archive file can be for any released product that can be
+ built using a recipe.
+ </para>
+ </section>
+
+ <section id='local-projects'>
+ <title>Local Projects</title>
+
+ <para>
+ Local projects are custom bits of software the user
+ provides.
+ These bits reside somewhere local to a project - perhaps
+ a directory into which the user checks in items (e.g.
+ a local directory containing a development source tree
+ used by the group).
+ </para>
+
+ <para>
+ The canonical method through which to include a local
+ project is to use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
+ class to include that local project.
+ You use either the <filename>local.conf</filename> or a
+ recipe's append file to override or set the
+ recipe to point to the local directory on your disk to pull
+ in the whole source tree.
+ </para>
+ </section>
+
+ <section id='scms'>
+ <title>Source Control Managers (Optional)</title>
+
+ <para>
+ Another place the build system can get source files from is
+ through an SCM such as Git or Subversion.
+ In this case, a repository is cloned or checked out.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
+ task inside BitBake uses
+ the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ variable and the argument's prefix to determine the correct
+ fetcher module.
+ <note>
+ For information on how to have the OpenEmbedded build
+ system generate tarballs for Git repositories and place
+ them in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+ directory, see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
+ variable.
+ </note>
+ </para>
+
+ <para>
+ When fetching a repository, BitBake uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ variable to determine the specific revision from which to
+ build.
+ </para>
+ </section>
+
+ <section id='source-mirrors'>
+ <title>Source Mirror(s)</title>
+
+ <para>
+ Two kinds of mirrors exist: pre-mirrors and regular
+ mirrors.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MIRRORS'><filename>MIRRORS</filename></ulink>
+ variables point to these, respectively.
+ BitBake checks pre-mirrors before looking upstream for any
+ source files.
+ Pre-mirrors are appropriate when you have a shared
+ directory that is not a directory defined by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+ variable.
+ A Pre-mirror typically points to a shared directory that is
+ local to your organization.
+ </para>
+
+ <para>
+ Regular mirrors can be any site across the Internet
+ that is used as an alternative location for source
+ code should the primary site not be functioning for
+ some reason or another.
+ </para>
+ </section>
+ </section>
+
+ <section id="package-feeds-dev-environment">
+ <title>Package Feeds</title>
+
+ <para>
+ When the OpenEmbedded build system generates an image or an
+ SDK, it gets the packages from a package feed area located
+ in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ The
+ <link linkend='general-workflow-figure'>general workflow figure</link>
+ shows this package feeds area in the upper-right corner.
+ </para>
+
+ <para>
+ This section looks a little closer into the package feeds
+ area used by the build system.
+ Here is a more detailed look at the area:
+ <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
+ </para>
+
+ <para>
+ Package feeds are an intermediary step in the build process.
+ The OpenEmbedded build system provides classes to generate
+ different package types, and you specify which classes to
+ enable through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
+ variable.
+ Before placing the packages into package feeds,
+ the build process validates them with generated output quality
+ assurance checks through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink>
+ class.
+ </para>
+
+ <para>
+ The package feed area resides in the Build Directory.
+ The directory the build system uses to temporarily store
+ packages is determined by a combination of variables and the
+ particular package manager in use.
+ See the "Package Feeds" box in the illustration and note the
+ information to the right of that area.
+ In particular, the following defines where package files are
+ kept:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
+ Defined as <filename>tmp/deploy</filename> in the Build
+ Directory.
+ </para></listitem>
+ <listitem><para>
+ <filename>DEPLOY_DIR_*</filename>:
+ Depending on the package manager used, the package type
+ sub-folder.
+ Given RPM, IPK, or DEB packaging and tarball creation,
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></ulink>,
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></ulink>,
+ variables are used, respectively.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
+ Defines architecture-specific sub-folders.
+ For example, packages could exist for the i586 or
+ qemux86 architectures.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ BitBake uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_*</filename></ulink>
+ tasks to generate packages and place them into the package
+ holding area (e.g. <filename>do_package_write_ipk</filename>
+ for IPK packages).
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></ulink>",
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>",
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></ulink>",
+ and
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></ulink>"
+ sections in the Yocto Project Reference Manual
+ for additional information.
+ As an example, consider a scenario where an IPK packaging
+ manager is being used and package architecture support for
+ both i586 and qemux86 exist.
+ Packages for the i586 architecture are placed in
+ <filename>build/tmp/deploy/ipk/i586</filename>, while packages
+ for the qemux86 architecture are placed in
+ <filename>build/tmp/deploy/ipk/qemux86</filename>.
+ </para>
+ </section>
+
+ <section id='bitbake-dev-environment'>
+ <title>BitBake</title>
+
+ <para>
+ The OpenEmbedded build system uses
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ to produce images and Software Development Kits (SDKs).
+ You can see from the
+ <link linkend='general-workflow-figure'>general workflow figure</link>,
+ the BitBake area consists of several functional areas.
+ This section takes a closer look at each of those areas.
+ <note>
+ Separate documentation exists for the BitBake tool.
+ See the
+ <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
+ for reference material on BitBake.
+ </note>
+ </para>
+
+ <section id='source-fetching-dev-environment'>
+ <title>Source Fetching</title>
+
+ <para>
+ The first stages of building a recipe are to fetch and
+ unpack the source code:
+ <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
+ tasks fetch the source files and unpack them into the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ <note>
+ For every local file (e.g. <filename>file://</filename>)
+ that is part of a recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statement, the OpenEmbedded build system takes a
+ checksum of the file for the recipe and inserts the
+ checksum into the signature for the
+ <filename>do_fetch</filename> task.
+ If any local file has been modified, the
+ <filename>do_fetch</filename> task and all tasks that
+ depend on it are re-executed.
+ </note>
+ By default, everything is accomplished in the Build
+ Directory, which has a defined structure.
+ For additional general information on the Build Directory,
+ see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-build'><filename>build/</filename></ulink>"
+ section in the Yocto Project Reference Manual.
+ </para>
+
+ <para>
+ Each recipe has an area in the Build Directory where the
+ unpacked source code resides.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+ variable points to this area for a recipe's unpacked source
+ code.
+ The name of that directory for any given recipe is defined
+ from several different variables.
+ The preceding figure and the following list describe
+ the Build Directory's hierarchy:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
+ The base directory where the OpenEmbedded build
+ system performs all its work during the build.
+ The default base directory is the
+ <filename>tmp</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>:
+ The architecture of the built package or packages.
+ Depending on the eventual destination of the
+ package or packages (i.e. machine architecture,
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>,
+ SDK, or specific machine),
+ <filename>PACKAGE_ARCH</filename> varies.
+ See the variable's description for details.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>:
+ The operating system of the target device.
+ A typical value would be "linux" (e.g.
+ "qemux86-poky-linux").
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
+ The name of the recipe used to build the package.
+ This variable can have multiple meanings.
+ However, when used in the context of input files,
+ <filename>PN</filename> represents the the name
+ of the recipe.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>:
+ The location where the OpenEmbedded build system
+ builds a recipe (i.e. does the work to create the
+ package).
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
+ The version of the recipe used to build the
+ package.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
+ The revision of the recipe used to build the
+ package.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>:
+ Contains the unpacked source files for a given
+ recipe.
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>:
+ The name of the recipe used to build the
+ package.
+ The <filename>BPN</filename> variable is
+ a version of the <filename>PN</filename>
+ variable but with common prefixes and
+ suffixes removed.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
+ The version of the recipe used to build the
+ package.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ In the previous figure, notice that two sample
+ hierarchies exist: one based on package architecture (i.e.
+ <filename>PACKAGE_ARCH</filename>) and one based on a
+ machine (i.e. <filename>MACHINE</filename>).
+ The underlying structures are identical.
+ The differentiator being what the OpenEmbedded build
+ system is using as a build target (e.g. general
+ architecture, a build host, an SDK, or a specific
+ machine).
+ </note>
+ </para>
+ </section>
+
+ <section id='patching-dev-environment'>
+ <title>Patching</title>
+
+ <para>
+ Once source code is fetched and unpacked, BitBake locates
+ patch files and applies them to the source files:
+ <imagedata fileref="figures/patching.png" align="center" width="7in" depth="6in" />
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
+ task uses a recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statements and the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+ variable to locate applicable patch files.
+ </para>
+
+ <para>
+ Default processing for patch files assumes the files have
+ either <filename>*.patch</filename> or
+ <filename>*.diff</filename> file types.
+ You can use <filename>SRC_URI</filename> parameters to
+ change the way the build system recognizes patch files.
+ See the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
+ task for more information.
+ </para>
+
+ <para>
+ BitBake finds and applies multiple patches for a single
+ recipe in the order in which it locates the patches.
+ The <filename>FILESPATH</filename> variable defines the
+ default set of directories that the build system uses to
+ search for patch files.
+ Once found, patches are applied to the recipe's source
+ files, which are located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+ directory.
+ </para>
+
+ <para>
+ For more information on how the source directories are
+ created, see the
+ "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
+ section.
+ For more information on how to create patches and how the
+ build system processes patches, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ You can also see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</ulink>"
+ section in the Yocto Project Application Development and
+ the Extensible Software Development Kit (SDK) manual and
+ the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</ulink>"
+ section in the Yocto Project Linux Kernel Development
+ Manual.
+ </para>
+ </section>
+
+ <section id='configuration-compilation-and-staging-dev-environment'>
+ <title>Configuration, Compilation, and Staging</title>
+
+ <para>
+ After source code is patched, BitBake executes tasks that
+ configure and compile the source code.
+ Once compilation occurs, the files are copied to a holding
+ area (staged) in preparation for packaging:
+ <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
+ </para>
+
+ <para>
+ This step in the build process consists of the following
+ tasks:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></ulink></emphasis>:
+ This task sets up the two sysroots in
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>
+ (i.e. <filename>recipe-sysroot</filename> and
+ <filename>recipe-sysroot-native</filename>) so that
+ during the packaging phase the sysroots can contain
+ the contents of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
+ tasks of the recipes on which the recipe
+ containing the tasks depends.
+ A sysroot exists for both the target and for the
+ native binaries, which run on the host system.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_configure</filename></emphasis>:
+ This task configures the source by enabling and
+ disabling any build-time and configuration options
+ for the software being built.
+ Configurations can come from the recipe itself as
+ well as from an inherited class.
+ Additionally, the software itself might configure
+ itself depending on the target for which it is
+ being built.</para>
+
+ <para>The configurations handled by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
+ task are specific to configurations for the source
+ code being built by the recipe.</para>
+
+ <para>If you are using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
+ class, you can add additional configuration options
+ by using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink>
+ variables.
+ For information on how this variable works within
+ that class, see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
+ class
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass'>here</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_compile</filename></emphasis>:
+ Once a configuration task has been satisfied,
+ BitBake compiles the source using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+ task.
+ Compilation occurs in the directory pointed to by
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
+ variable.
+ Realize that the <filename>B</filename> directory
+ is, by default, the same as the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+ directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_install</filename></emphasis>:
+ After compilation completes, BitBake executes the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task.
+ This task copies files from the
+ <filename>B</filename> directory and places them
+ in a holding area pointed to by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
+ variable.
+ Packaging occurs later using files from this
+ holding directory.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='package-splitting-dev-environment'>
+ <title>Package Splitting</title>
+
+ <para>
+ After source code is configured, compiled, and staged, the
+ build system analyzes the results and splits the output
+ into packages:
+ <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
+ tasks combine to analyze the files found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
+ directory and split them into subsets based on available
+ packages and files.
+ Analysis involves the following as well as other items:
+ splitting out debugging symbols, looking at shared library
+ dependencies between packages, and looking at package
+ relationships.
+ </para>
+
+ <para>
+ The <filename>do_packagedata</filename> task creates
+ package metadata based on the analysis such that the
+ build system can generate the final packages.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
+ task stages (copies) a subset of the files installed by
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task into the appropriate sysroot.
+ Working, staged, and intermediate results of the analysis
+ and package splitting process use several areas:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGD'><filename>PKGD</filename></ulink>:
+ The destination directory
+ (i.e. <filename>package</filename>) for packages
+ before they are split into individual packages.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDESTWORK'><filename>PKGDESTWORK</filename></ulink>:
+ A temporary work area (i.e.
+ <filename>pkgdata</filename>) used by the
+ <filename>do_package</filename> task to save
+ package metadata.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDEST'><filename>PKGDEST</filename></ulink>:
+ The parent directory (i.e.
+ <filename>packages-split</filename>) for packages
+ after they have been split.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>:
+ A shared, global-state directory that holds
+ packaging metadata generated during the packaging
+ process.
+ The packaging process copies metadata from
+ <filename>PKGDESTWORK</filename> to the
+ <filename>PKGDATA_DIR</filename> area where it
+ becomes globally available.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></ulink>:
+ The path for the sysroot for the system on which
+ a component is built to run (i.e.
+ <filename>recipe-sysroot</filename>).
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></ulink>:
+ The path for the sysroot used when building
+ components for the build host (i.e.
+ <filename>recipe-sysroot-native</filename>).
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></ulink>:
+ The path for the sysroot used when a component that
+ is built to execute on a system and it generates
+ code for yet another machine (e.g. cross-canadian
+ recipes).
+ </para></listitem>
+ </itemizedlist>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
+ variable defines the files that go into each package in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>.
+ If you want details on how this is accomplished, you can
+ look at
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/package.bbclass'><filename>package.bbclass</filename></ulink>.
+ </para>
+
+ <para>
+ Depending on the type of packages being created (RPM, DEB,
+ or IPK), the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_*</filename></ulink>
+ task creates the actual packages and places them in the
+ Package Feed area, which is
+ <filename>${TMPDIR}/deploy</filename>.
+ You can see the
+ "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+ section for more detail on that part of the build process.
+ <note>
+ Support for creating feeds directly from the
+ <filename>deploy/*</filename> directories does not
+ exist.
+ Creating such feeds usually requires some kind of feed
+ maintenance mechanism that would upload the new
+ packages into an official package feed (e.g. the
+ Ångström distribution).
+ This functionality is highly distribution-specific
+ and thus is not provided out of the box.
+ </note>
+ </para>
+ </section>
+
+ <section id='image-generation-dev-environment'>
+ <title>Image Generation</title>
+
+ <para>
+ Once packages are split and stored in the Package Feeds
+ area, the build system uses BitBake to generate the root
+ filesystem image:
+ <imagedata fileref="figures/image-generation.png" align="center" width="7.5in" depth="7.5in" />
+ </para>
+
+ <para>
+ The image generation process consists of several stages and
+ depends on several tasks and variables.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>
+ task creates the root filesystem (file and directory
+ structure) for an image.
+ This task uses several key variables to help create the
+ list of packages to actually install:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+ Lists out the base set of packages from which to
+ install from the Package Feeds area.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
+ Specifies packages that should not be installed
+ into the image.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
+ Specifies features to include in the image.
+ Most of these features map to additional packages
+ for installation.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>:
+ Specifies the package backend (e.g. RPM, DEB, or
+ IPK) to use and consequently helps determine where
+ to locate packages within the Package Feeds area.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></ulink>:
+ Determines the language(s) for which additional
+ language support packages are installed.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>:
+ The final list of packages passed to the package
+ manager for installation into the image.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ With
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></ulink>
+ pointing to the location of the filesystem under
+ construction and the <filename>PACKAGE_INSTALL</filename>
+ variable providing the final list of packages to install,
+ the root file system is created.
+ </para>
+
+ <para>
+ Package installation is under control of the package
+ manager (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of
+ whether or not package management is enabled for the
+ target.
+ At the end of the process, if package management is not
+ enabled for the target, the package manager's data files
+ are deleted from the root filesystem.
+ As part of the final stage of package installation,
+ post installation scripts that are part of the packages
+ are run.
+ Any scripts that fail to run on the build host are run on
+ the target when the target system is first booted.
+ If you are using a
+ <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
+ all the post installation scripts must succeed on the
+ build host during the package installation phase since the
+ root filesystem on the target is read-only.
+ </para>
+
+ <para>
+ The final stages of the <filename>do_rootfs</filename> task
+ handle post processing.
+ Post processing includes creation of a manifest file and
+ optimizations.
+ </para>
+
+ <para>
+ The manifest file (<filename>.manifest</filename>) resides
+ in the same directory as the root filesystem image.
+ This file lists out, line-by-line, the installed packages.
+ The manifest file is useful for the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
+ class, for example, to determine whether or not to run
+ specific tests.
+ See the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></ulink>
+ variable for additional information.
+ </para>
+
+ <para>
+ Optimizing processes that are run across the image include
+ <filename>mklibs</filename>, <filename>prelink</filename>,
+ and any other post-processing commands as defined by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></ulink>
+ variable.
+ The <filename>mklibs</filename> process optimizes the size
+ of the libraries, while the <filename>prelink</filename>
+ process optimizes the dynamic linking of shared libraries
+ to reduce start up time of executables.
+ </para>
+
+ <para>
+ After the root filesystem is built, processing begins on
+ the image through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image</filename></ulink>
+ task.
+ The build system runs any pre-processing commands as
+ defined by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></ulink>
+ variable.
+ This variable specifies a list of functions to call before
+ the build system creates the final image output files.
+ </para>
+
+ <para>
+ The build system dynamically creates
+ <filename>do_image_*</filename> tasks as needed, based
+ on the image types specified in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
+ variable.
+ The process turns everything into an image file or a set of
+ image files and can compress the root filesystem image to
+ reduce the overall size of the image.
+ The formats used for the root filesystem depend on the
+ <filename>IMAGE_FSTYPES</filename> variable.
+ Compression depends on whether the formats support
+ compression.
+ </para>
+
+ <para>
+ As an example, a dynamically created task when creating a
+ particular image <replaceable>type</replaceable> would
+ take the following form:
+ <literallayout class='monospaced'>
+ do_image_<replaceable>type</replaceable>
+ </literallayout>
+ So, if the <replaceable>type</replaceable> as specified by
+ the <filename>IMAGE_FSTYPES</filename> were
+ <filename>ext4</filename>, the dynamically generated task
+ would be as follows:
+ <literallayout class='monospaced'>
+ do_image_ext4
+ </literallayout>
+ </para>
+
+ <para>
+ The final task involved in image creation is the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image-complete'><filename>do_image_complete</filename></ulink>
+ task.
+ This task completes the image by applying any image
+ post processing as defined through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></ulink>
+ variable.
+ The variable specifies a list of functions to call once the
+ build system has created the final image output files.
+ <note>
+ The entire image generation process is run under
+ <link linkend='fakeroot-and-pseudo'>Pseudo</link>.
+ Running under Pseudo ensures that the files in the
+ root filesystem have correct ownership.
+ </note>
+ </para>
+ </section>
+
+ <section id='sdk-generation-dev-environment'>
+ <title>SDK Generation</title>
+
+ <para>
+ The OpenEmbedded build system uses BitBake to generate the
+ Software Development Kit (SDK) installer scripts for both
+ the standard SDK and the extensible SDK (eSDK):
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-generation.png" width="9in" align="center" />
+ <note>
+ For more information on the cross-development toolchain
+ generation, see the
+ "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+ section.
+ For information on advantages gained when building a
+ cross-development toolchain using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink>
+ task, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
+ section in the Yocto Project Application Development
+ and the Extensible Software Development Kit (eSDK)
+ manual.
+ </note>
+ </para>
+
+ <para>
+ Like image generation, the SDK script process consists of
+ several stages and depends on many variables.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sdk_ext'><filename>do_populate_sdk_ext</filename></ulink>
+ tasks use these key variables to help create the list of
+ packages to actually install.
+ For information on the variables listed in the figure,
+ see the
+ "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+ section.
+ </para>
+
+ <para>
+ The <filename>do_populate_sdk</filename> task helps create
+ the standard SDK and handles two parts: a target part and a
+ host part.
+ The target part is the part built for the target hardware
+ and includes libraries and headers.
+ The host part is the part of the SDK that runs on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>.
+ </para>
+
+ <para>
+ The <filename>do_populate_sdk_ext</filename> task helps
+ create the extensible SDK and handles host and target parts
+ differently than its counter part does for the standard SDK.
+ For the extensible SDK, the task encapsulates the build
+ system, which includes everything needed (host and target)
+ for the SDK.
+ </para>
+
+ <para>
+ Regardless of the type of SDK being constructed, the
+ tasks perform some cleanup after which a cross-development
+ environment setup script and any needed configuration files
+ are created.
+ The final output is the Cross-development
+ toolchain installation script (<filename>.sh</filename>
+ file), which includes the environment setup script.
+ </para>
+ </section>
+
+ <section id='stamp-files-and-the-rerunning-of-tasks'>
+ <title>Stamp Files and the Rerunning of Tasks</title>
+
+ <para>
+ For each task that completes successfully, BitBake writes a
+ stamp file into the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
+ directory.
+ The beginning of the stamp file's filename is determined
+ by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMP'><filename>STAMP</filename></ulink>
+ variable, and the end of the name consists of the task's
+ name and current
+ <link linkend='overview-checksums'>input checksum</link>.
+ <note>
+ This naming scheme assumes that
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
+ is "OEBasicHash", which is almost always the case in
+ current OpenEmbedded.
+ </note>
+ To determine if a task needs to be rerun, BitBake checks
+ if a stamp file with a matching input checksum exists
+ for the task.
+ If such a stamp file exists, the task's output is
+ assumed to exist and still be valid.
+ If the file does not exist, the task is rerun.
+ <note>
+ <para>The stamp mechanism is more general than the
+ shared state (sstate) cache mechanism described in the
+ "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
+ section.
+ BitBake avoids rerunning any task that has a valid
+ stamp file, not just tasks that can be accelerated
+ through the sstate cache.</para>
+
+ <para>However, you should realize that stamp files only
+ serve as a marker that some work has been done and that
+ these files do not record task output.
+ The actual task output would usually be somewhere in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ (e.g. in some recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.)
+ What the sstate cache mechanism adds is a way to cache
+ task output that can then be shared between build
+ machines.</para>
+ </note>
+ Since <filename>STAMPS_DIR</filename> is usually a
+ subdirectory of <filename>TMPDIR</filename>, removing
+ <filename>TMPDIR</filename> will also remove
+ <filename>STAMPS_DIR</filename>, which means tasks will
+ properly be rerun to repopulate
+ <filename>TMPDIR</filename>.
+ </para>
+
+ <para>
+ If you want some task to always be considered "out of
+ date", you can mark it with the
+ <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
+ varflag.
+ If some other task depends on such a task, then that
+ task will also always be considered out of date, which
+ might not be what you want.
+ </para>
+
+ <para>
+ For details on how to view information about a task's
+ signature, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
+
+ <section id='setscene-tasks-and-shared-state'>
+ <title>Setscene Tasks and Shared State</title>
+
+ <para>
+ The description of tasks so far assumes that BitBake needs
+ to build everything and no available prebuilt objects
+ exist.
+ BitBake does support skipping tasks if prebuilt objects are
+ available.
+ These objects are usually made available in the form of a
+ shared state (sstate) cache.
+ <note>
+ For information on variables affecting sstate, see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
+ variables.
+ </note>
+ </para>
+
+ <para>
+ The idea of a setscene task (i.e
+ <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
+ is a version of the task where
+ instead of building something, BitBake can skip to the end
+ result and simply place a set of files into specific
+ locations as needed.
+ In some cases, it makes sense to have a setscene task
+ variant (e.g. generating package files in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write_*</filename></ulink>
+ task).
+ In other cases, it does not make sense (e.g. a
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>
+ task or a
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>
+ task) since the work involved would be equal to or greater
+ than the underlying task.
+ </para>
+
+ <para>
+ In the build system, the common tasks that have setscene
+ variants are
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>,
+ <filename>do_package_write_*</filename>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>.
+ Notice that these tasks represent most of the tasks whose
+ output is an end result.
+ </para>
+
+ <para>
+ The build system has knowledge of the relationship between
+ these tasks and other preceding tasks.
+ For example, if BitBake runs
+ <filename>do_populate_sysroot_setscene</filename> for
+ something, it does not make sense to run any of the
+ <filename>do_fetch</filename>,
+ <filename>do_unpack</filename>,
+ <filename>do_patch</filename>,
+ <filename>do_configure</filename>,
+ <filename>do_compile</filename>, and
+ <filename>do_install</filename> tasks.
+ However, if <filename>do_package</filename> needs to be
+ run, BitBake needs to run those other tasks.
+ </para>
+
+ <para>
+ It becomes more complicated if everything can come
+ from an sstate cache because some objects are simply
+ not required at all.
+ For example, you do not need a compiler or native tools,
+ such as quilt, if nothing exists to compile or patch.
+ If the <filename>do_package_write_*</filename> packages
+ are available from sstate, BitBake does not need the
+ <filename>do_package</filename> task data.
+ </para>
+
+ <para>
+ To handle all these complexities, BitBake runs in two
+ phases.
+ The first is the "setscene" stage.
+ During this stage, BitBake first checks the sstate cache
+ for any targets it is planning to build.
+ BitBake does a fast check to see if the object exists
+ rather than a complete download.
+ If nothing exists, the second phase, which is the setscene
+ stage, completes and the main build proceeds.
+ </para>
+
+ <para>
+ If objects are found in the sstate cache, the build system
+ works backwards from the end targets specified by the user.
+ For example, if an image is being built, the build system
+ first looks for the packages needed for that image and the
+ tools needed to construct an image.
+ If those are available, the compiler is not needed.
+ Thus, the compiler is not even downloaded.
+ If something was found to be unavailable, or the
+ download or setscene task fails, the build system then
+ tries to install dependencies, such as the compiler, from
+ the cache.
+ </para>
+
+ <para>
+ The availability of objects in the sstate cache is
+ handled by the function specified by the
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
+ variable and returns a list of available objects.
+ The function specified by the
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
+ variable is the function that determines whether a given
+ dependency needs to be followed, and whether for any given
+ relationship the function needs to be passed.
+ The function returns a True or False value.
+ </para>
+ </section>
+ </section>
+
+ <section id='images-dev-environment'>
+ <title>Images</title>
+
+ <para>
+ The images produced by the build system are compressed forms
+ of the root filesystem and are ready to boot on a target
+ device.
+ You can see from the
+ <link linkend='general-workflow-figure'>general workflow figure</link>
+ that BitBake output, in part, consists of images.
+ This section takes a closer look at this output:
+ <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
+ </para>
+
+ <note>
+ For a list of example images that the Yocto Project provides,
+ see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual.
+ </note>
+
+ <para>
+ The build process writes images out to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ inside the
+ <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename>
+ folder as shown in the figure.
+ This folder contains any files expected to be loaded on the
+ target device.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>
+ variable points to the <filename>deploy</filename> directory,
+ while the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></ulink>
+ variable points to the appropriate directory containing images
+ for the current configuration.
+ <itemizedlist>
+ <listitem><para>
+ <replaceable>kernel-image</replaceable>:
+ A kernel binary file.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>
+ variable determines the naming scheme for the
+ kernel image file.
+ Depending on this variable, the file could begin with
+ a variety of naming strings.
+ The
+ <filename>deploy/images/</filename><replaceable>machine</replaceable>
+ directory can contain multiple image files for the
+ machine.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>root-filesystem-image</replaceable>:
+ Root filesystems for the target device (e.g.
+ <filename>*.ext3</filename> or
+ <filename>*.bz2</filename> files).
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
+ variable determines the root filesystem image type.
+ The
+ <filename>deploy/images/</filename><replaceable>machine</replaceable>
+ directory can contain multiple root filesystems for the
+ machine.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>kernel-modules</replaceable>:
+ Tarballs that contain all the modules built for the
+ kernel.
+ Kernel module tarballs exist for legacy purposes and
+ can be suppressed by setting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></ulink>
+ variable to "0".
+ The
+ <filename>deploy/images/</filename><replaceable>machine</replaceable>
+ directory can contain multiple kernel module tarballs
+ for the machine.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>bootloaders</replaceable>:
+ If applicable to the target machine, bootloaders
+ supporting the image.
+ The <filename>deploy/images/</filename><replaceable>machine</replaceable>
+ directory can contain multiple bootloaders for the
+ machine.
+ </para></listitem>
+ <listitem><para>
+ <replaceable>symlinks</replaceable>:
+ The
+ <filename>deploy/images/</filename><replaceable>machine</replaceable>
+ folder contains a symbolic link that points to the
+ most recently built file for each machine.
+ These links might be useful for external scripts that
+ need to obtain the latest version of each file.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='sdk-dev-environment'>
+ <title>Application Development SDK</title>
+
+ <para>
+ In the
+ <link linkend='general-workflow-figure'>general workflow figure</link>,
+ the output labeled "Application Development SDK" represents an
+ SDK.
+ The SDK generation process differs depending on whether you
+ build an extensible SDK (e.g.
+ <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>)
+ or a standard SDK (e.g.
+ <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>).
+ This section takes a closer look at this output:
+ <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" />
+ </para>
+
+ <para>
+ The specific form of this output is a set of files that
+ includes a self-extracting SDK installer
+ (<filename>*.sh</filename>), host and target manifest files,
+ and files used for SDK testing.
+ When the SDK installer file is run, it installs the SDK.
+ The SDK consists of a cross-development toolchain, a set of
+ libraries and headers, and an SDK environment setup script.
+ Running this installer essentially sets up your
+ cross-development environment.
+ You can think of the cross-toolchain as the "host"
+ part because it runs on the SDK machine.
+ You can think of the libraries and headers as the "target"
+ part because they are built for the target hardware.
+ The environment setup script is added so that you can
+ initialize the environment before using the tools.
+ </para>
+
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ The Yocto Project supports several methods by which
+ you can set up this cross-development environment.
+ These methods include downloading pre-built SDK
+ installers or building and installing your own SDK
+ installer.
+ </para></listitem>
+ <listitem><para>
+ For background information on cross-development
+ toolchains in the Yocto Project development
+ environment, see the
+ "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ For information on setting up a cross-development
+ environment, see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+
+ <para>
+ All the output files for an SDK are written to the
+ <filename>deploy/sdk</filename> folder inside the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ as shown in the previous figure.
+ Depending on the type of SDK, several variables exist that help
+ configure these files.
+ The following list shows the variables associated with an
+ extensible SDK:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
+ Points to the <filename>deploy</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>:
+ Controls whether or not shared state artifacts are
+ copied into the extensible SDK.
+ By default, all required shared state artifacts are
+ copied into the SDK.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink>:
+ Specifies whether or not packagedata is included in the
+ extensible SDK for all recipes in the "world" target.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>:
+ Specifies whether or not the toolchain is included
+ when building the extensible SDK.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>:
+ A list of variables allowed through from the build
+ system configuration into the extensible SDK
+ configuration.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink>:
+ A list of variables not allowed through from the build
+ system configuration into the extensible SDK
+ configuration.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink>:
+ A list of classes to remove from the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink>
+ value globally within the extensible SDK configuration.
+ </para></listitem>
+ </itemizedlist>
+ This next list, shows the variables associated with a standard
+ SDK:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></ulink>:
+ Points to the <filename>deploy</filename> directory.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>:
+ Specifies the architecture of the machine on which the
+ cross-development tools are run to create packages for
+ the target hardware.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></ulink>:
+ Lists the features to include in the "target" part
+ of the SDK.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></ulink>:
+ Lists packages that make up the host part of the SDK
+ (i.e. the part that runs on the
+ <filename>SDKMACHINE</filename>).
+ When you use
+ <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename>
+ to create the SDK, a set of default packages apply.
+ This variable allows you to add more packages.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink>:
+ Lists packages that make up the target part of the SDK
+ (i.e. the part built for the target hardware).
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKPATH'><filename>SDKPATH</filename></ulink>:
+ Defines the default SDK installation path offered by
+ the installation script.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_HOST_MANIFEST'><filename>SDK_HOST_MANIFEST</filename></ulink>:
+ Lists all the installed packages that make up the host
+ part of the SDK.
+ This variable also plays a minor role for extensible
+ SDK development as well.
+ However, it is mainly used for the standard SDK.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TARGET_MANIFEST'><filename>SDK_TARGET_MANIFEST</filename></ulink>:
+ Lists all the installed packages that make up the
+ target part of the SDK.
+ This variable also plays a minor role for extensible
+ SDK development as well.
+ However, it is mainly used for the standard SDK.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id="cross-development-toolchain-generation">
+ <title>Cross-Development Toolchain Generation</title>
+
+ <para>
+ The Yocto Project does most of the work for you when it comes to
+ creating
+ <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
+ This section provides some technical background on how
+ cross-development toolchains are created and used.
+ For more information on toolchains, you can also see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ </para>
+
+ <para>
+ In the Yocto Project development environment, cross-development
+ toolchains are used to build images and applications that run
+ on the target hardware.
+ With just a few commands, the OpenEmbedded build system creates
+ these necessary toolchains for you.
+ </para>
+
+ <para>
+ The following figure shows a high-level build environment regarding
+ toolchain construction and use.
+ </para>
+
+ <para>
+ <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
+ </para>
+
+ <para>
+ Most of the work occurs on the Build Host.
+ This is the machine used to build images and generally work within
+ the the Yocto Project environment.
+ When you run
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ to create an image, the OpenEmbedded build system
+ uses the host <filename>gcc</filename> compiler to bootstrap a
+ cross-compiler named <filename>gcc-cross</filename>.
+ The <filename>gcc-cross</filename> compiler is what BitBake uses to
+ compile source files when creating the target image.
+ You can think of <filename>gcc-cross</filename> simply as an
+ automatically generated cross-compiler that is used internally
+ within BitBake only.
+ <note>
+ The extensible SDK does not use
+ <filename>gcc-cross-canadian</filename> since this SDK
+ ships a copy of the OpenEmbedded build system and the sysroot
+ within it contains <filename>gcc-cross</filename>.
+ </note>
+ </para>
+
+ <para>
+ The chain of events that occurs when <filename>gcc-cross</filename> is
+ bootstrapped is as follows:
+ <literallayout class='monospaced'>
+ gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
+ </literallayout>
+ <itemizedlist>
+ <listitem><para>
+ <filename>gcc</filename>:
+ The build host's GNU Compiler Collection (GCC).
+ </para></listitem>
+ <listitem><para>
+ <filename>binutils-cross</filename>:
+ The bare minimum binary utilities needed in order to run
+ the <filename>gcc-cross-initial</filename> phase of the
+ bootstrap operation.
+ </para></listitem>
+ <listitem><para>
+ <filename>gcc-cross-initial</filename>:
+ An early stage of the bootstrap process for creating
+ the cross-compiler.
+ This stage builds enough of the <filename>gcc-cross</filename>,
+ the C library, and other pieces needed to finish building the
+ final cross-compiler in later stages.
+ This tool is a "native" package (i.e. it is designed to run on
+ the build host).
+ </para></listitem>
+ <listitem><para>
+ <filename>linux-libc-headers</filename>:
+ Headers needed for the cross-compiler.
+ </para></listitem>
+ <listitem><para>
+ <filename>glibc-initial</filename>:
+ An initial version of the Embedded GNU C Library
+ (GLIBC) needed to bootstrap <filename>glibc</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>glibc</filename>:
+ The GNU C Library.
+ </para></listitem>
+ <listitem><para>
+ <filename>gcc-cross</filename>:
+ The final stage of the bootstrap process for the
+ cross-compiler.
+ This stage results in the actual cross-compiler that
+ BitBake uses when it builds an image for a targeted
+ device.
+ <note>
+ If you are replacing this cross compiler toolchain
+ with a custom version, you must replace
+ <filename>gcc-cross</filename>.
+ </note>
+ This tool is also a "native" package (i.e. it is
+ designed to run on the build host).
+ </para></listitem>
+ <listitem><para>
+ <filename>gcc-runtime</filename>:
+ Runtime libraries resulting from the toolchain bootstrapping
+ process.
+ This tool produces a binary that consists of the
+ runtime libraries need for the targeted device.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ You can use the OpenEmbedded build system to build an installer for
+ the relocatable SDK used to develop applications.
+ When you run the installer, it installs the toolchain, which
+ contains the development tools (e.g.,
+ <filename>gcc-cross-canadian</filename>,
+ <filename>binutils-cross-canadian</filename>, and other
+ <filename>nativesdk-*</filename> tools),
+ which are tools native to the SDK (i.e. native to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>),
+ you need to cross-compile and test your software.
+ The figure shows the commands you use to easily build out this
+ toolchain.
+ This cross-development toolchain is built to execute on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>,
+ which might or might not be the same
+ machine as the Build Host.
+ <note>
+ If your target architecture is supported by the Yocto Project,
+ you can take advantage of pre-built images that ship with the
+ Yocto Project and already contain cross-development toolchain
+ installers.
+ </note>
+ </para>
+
+ <para>
+ Here is the bootstrap process for the relocatable toolchain:
+ <literallayout class='monospaced'>
+ gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers ->
+ glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
+ </literallayout>
+ <itemizedlist>
+ <listitem><para>
+ <filename>gcc</filename>:
+ The build host's GNU Compiler Collection (GCC).
+ </para></listitem>
+ <listitem><para>
+ <filename>binutils-crosssdk</filename>:
+ The bare minimum binary utilities needed in order to run
+ the <filename>gcc-crosssdk-initial</filename> phase of the
+ bootstrap operation.
+ </para></listitem>
+ <listitem><para>
+ <filename>gcc-crosssdk-initial</filename>:
+ An early stage of the bootstrap process for creating
+ the cross-compiler.
+ This stage builds enough of the
+ <filename>gcc-crosssdk</filename> and supporting pieces so that
+ the final stage of the bootstrap process can produce the
+ finished cross-compiler.
+ This tool is a "native" binary that runs on the build host.
+ </para></listitem>
+ <listitem><para>
+ <filename>linux-libc-headers</filename>:
+ Headers needed for the cross-compiler.
+ </para></listitem>
+ <listitem><para>
+ <filename>glibc-initial</filename>:
+ An initial version of the Embedded GLIBC needed to bootstrap
+ <filename>nativesdk-glibc</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>nativesdk-glibc</filename>:
+ The Embedded GLIBC needed to bootstrap the
+ <filename>gcc-crosssdk</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>gcc-crosssdk</filename>:
+ The final stage of the bootstrap process for the
+ relocatable cross-compiler.
+ The <filename>gcc-crosssdk</filename> is a transitory
+ compiler and never leaves the build host.
+ Its purpose is to help in the bootstrap process to create
+ the eventual <filename>gcc-cross-canadian</filename>
+ compiler, which is relocatable.
+ This tool is also a "native" package (i.e. it is
+ designed to run on the build host).
+ </para></listitem>
+ <listitem><para>
+ <filename>gcc-cross-canadian</filename>:
+ The final relocatable cross-compiler.
+ When run on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>,
+ this tool
+ produces executable code that runs on the target device.
+ Only one cross-canadian compiler is produced per architecture
+ since they can be targeted at different processor optimizations
+ using configurations passed to the compiler through the
+ compile commands.
+ This circumvents the need for multiple compilers and thus
+ reduces the size of the toolchains.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <note>
+ For information on advantages gained when building a
+ cross-development toolchain installer, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
+ appendix in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
+ </note>
+ </section>
+
+ <section id="shared-state-cache">
+ <title>Shared State Cache</title>
+
+ <para>
+ By design, the OpenEmbedded build system builds everything from
+ scratch unless
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ can determine that parts do not need to be rebuilt.
+ Fundamentally, building from scratch is attractive as it means all
+ parts are built fresh and no possibility of stale data exists that
+ can cause problems.
+ When developers hit problems, they typically default back to
+ building from scratch so they have a know state from the
+ start.
+ </para>
+
+ <para>
+ Building an image from scratch is both an advantage and a
+ disadvantage to the process.
+ As mentioned in the previous paragraph, building from scratch
+ ensures that everything is current and starts from a known state.
+ However, building from scratch also takes much longer as it
+ generally means rebuilding things that do not necessarily need
+ to be rebuilt.
+ </para>
+
+ <para>
+ The Yocto Project implements shared state code that supports
+ incremental builds.
+ The implementation of the shared state code answers the following
+ questions that were fundamental roadblocks within the OpenEmbedded
+ incremental build support system:
+ <itemizedlist>
+ <listitem><para>
+ What pieces of the system have changed and what pieces have
+ not changed?
+ </para></listitem>
+ <listitem><para>
+ How are changed pieces of software removed and replaced?
+ </para></listitem>
+ <listitem><para>
+ How are pre-built components that do not need to be rebuilt
+ from scratch used when they are available?
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For the first question, the build system detects changes in the
+ "inputs" to a given task by creating a checksum (or signature) of
+ the task's inputs.
+ If the checksum changes, the system assumes the inputs have changed
+ and the task needs to be rerun.
+ For the second question, the shared state (sstate) code tracks
+ which tasks add which output to the build process.
+ This means the output from a given task can be removed, upgraded
+ or otherwise manipulated.
+ The third question is partly addressed by the solution for the
+ second question assuming the build system can fetch the sstate
+ objects from remote locations and install them if they are deemed
+ to be valid.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ The build system does not maintain
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+ information as part of the shared state packages.
+ Consequently, considerations exist that affect
+ maintaining shared state feeds.
+ For information on how the build system works with
+ packages and can track incrementing
+ <filename>PR</filename> information, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ The code in the build system that supports incremental
+ builds is not simple code.
+ For techniques that help you work around issues related
+ to shared state code, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>Viewing Metadata Used to Create the Input Signature of a Shared State Task</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run'>Invalidating Shared State to Force a Task to Run</ulink>"
+ sections both in the Yocto Project Development Tasks
+ Manual.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The rest of this section goes into detail about the overall
+ incremental build architecture, the checksums (signatures), and
+ shared state.
+ </para>
+
+ <section id='concepts-overall-architecture'>
+ <title>Overall Architecture</title>
+
+ <para>
+ When determining what parts of the system need to be built,
+ BitBake works on a per-task basis rather than a per-recipe
+ basis.
+ You might wonder why using a per-task basis is preferred over
+ a per-recipe basis.
+ To help explain, consider having the IPK packaging backend
+ enabled and then switching to DEB.
+ In this case, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task outputs are still valid.
+ However, with a per-recipe approach, the build would not
+ include the <filename>.deb</filename> files.
+ Consequently, you would have to invalidate the whole build and
+ rerun it.
+ Rerunning everything is not the best solution.
+ Also, in this case, the core must be "taught" much about
+ specific tasks.
+ This methodology does not scale well and does not allow users
+ to easily add new tasks in layers or as external recipes
+ without touching the packaged-staging core.
+ </para>
+ </section>
+
+ <section id='overview-checksums'>
+ <title>Checksums (Signatures)</title>
+
+ <para>
+ The shared state code uses a checksum, which is a unique
+ signature of a task's inputs, to determine if a task needs to
+ be run again.
+ Because it is a change in a task's inputs that triggers a
+ rerun, the process needs to detect all the inputs to a given
+ task.
+ For shell tasks, this turns out to be fairly easy because
+ the build process generates a "run" shell script for each task
+ and it is possible to create a checksum that gives you a good
+ idea of when the task's data changes.
+ </para>
+
+ <para>
+ To complicate the problem, there are things that should not be
+ included in the checksum.
+ First, there is the actual specific build path of a given
+ task - the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
+ It does not matter if the work directory changes because it
+ should not affect the output for target packages.
+ Also, the build process has the objective of making native
+ or cross packages relocatable.
+ <note>
+ Both native and cross packages run on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
+ However, cross packages generate output for the target
+ architecture.
+ </note>
+ The checksum therefore needs to exclude
+ <filename>WORKDIR</filename>.
+ The simplistic approach for excluding the work directory is to
+ set <filename>WORKDIR</filename> to some fixed value and
+ create the checksum for the "run" script.
+ </para>
+
+ <para>
+ Another problem results from the "run" scripts containing
+ functions that might or might not get called.
+ The incremental build solution contains code that figures out
+ dependencies between shell functions.
+ This code is used to prune the "run" scripts down to the
+ minimum set, thereby alleviating this problem and making the
+ "run" scripts much more readable as a bonus.
+ </para>
+
+ <para>
+ So far, solutions for shell scripts exist.
+ What about Python tasks?
+ The same approach applies even though these tasks are more
+ difficult.
+ The process needs to figure out what variables a Python
+ function accesses and what functions it calls.
+ Again, the incremental build solution contains code that first
+ figures out the variable and function dependencies, and then
+ creates a checksum for the data used as the input to the task.
+ </para>
+
+ <para>
+ Like the <filename>WORKDIR</filename> case, situations exist
+ where dependencies should be ignored.
+ For these situations, you can instruct the build process to
+ ignore a dependency by using a line like the following:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
+ </literallayout>
+ This example ensures that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCHS'><filename>PACKAGE_ARCHS</filename></ulink>
+ variable does not depend on the value of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
+ even if it does reference it.
+ </para>
+
+ <para>
+ Equally, there are cases where you need to add dependencies
+ BitBake is not able to find.
+ You can accomplish this by using a line like the following:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCHS[vardeps] = "MACHINE"
+ </literallayout>
+ This example explicitly adds the <filename>MACHINE</filename>
+ variable as a dependency for
+ <filename>PACKAGE_ARCHS</filename>.
+ </para>
+
+ <para>
+ As an example, consider a case with in-line Python where
+ BitBake is not able to figure out dependencies.
+ When running in debug mode (i.e. using
+ <filename>-DDD</filename>), BitBake produces output when it
+ discovers something for which it cannot figure out dependencies.
+ The Yocto Project team has currently not managed to cover
+ those dependencies in detail and is aware of the need to fix
+ this situation.
+ </para>
+
+ <para>
+ Thus far, this section has limited discussion to the direct
+ inputs into a task.
+ Information based on direct inputs is referred to as the
+ "basehash" in the code.
+ However, the question of a task's indirect inputs still
+ exits - items already built and present in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ The checksum (or signature) for a particular task needs to add
+ the hashes of all the tasks on which the particular task
+ depends.
+ Choosing which dependencies to add is a policy decision.
+ However, the effect is to generate a master checksum that
+ combines the basehash and the hashes of the task's
+ dependencies.
+ </para>
+
+ <para>
+ At the code level, a variety of ways exist by which both the
+ basehash and the dependent task hashes can be influenced.
+ Within the BitBake configuration file, you can give BitBake
+ some extra information to help it construct the basehash.
+ The following statement effectively results in a list of
+ global variable dependency excludes (i.e. variables never
+ included in any checksum):
+ <literallayout class='monospaced'>
+ BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
+ SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
+ USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
+ PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
+ CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
+ </literallayout>
+ The previous example excludes
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+ since that variable is actually constructed as a path within
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
+ which is on the whitelist.
+ </para>
+
+ <para>
+ The rules for deciding which hashes of dependent tasks to
+ include through dependency chains are more complex and are
+ generally accomplished with a Python function.
+ The code in <filename>meta/lib/oe/sstatesig.py</filename> shows
+ two examples of this and also illustrates how you can insert
+ your own policy into the system if so desired.
+ This file defines the two basic signature generators
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OE-Core</ulink>
+ uses: "OEBasic" and "OEBasicHash".
+ By default, a dummy "noop" signature handler is enabled
+ in BitBake.
+ This means that behavior is unchanged from previous versions.
+ OE-Core uses the "OEBasicHash" signature handler by default
+ through this setting in the <filename>bitbake.conf</filename>
+ file:
+ <literallayout class='monospaced'>
+ BB_SIGNATURE_HANDLER ?= "OEBasicHash"
+ </literallayout>
+ The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename>
+ is the same as the "OEBasic" version but adds the task hash to
+ the
+ <link linkend='stamp-files-and-the-rerunning-of-tasks'>stamp files</link>.
+ This results in any metadata change that changes the task hash,
+ automatically causing the task to be run again.
+ This removes the need to bump
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+ values, and changes to metadata automatically ripple across
+ the build.
+ </para>
+
+ <para>
+ It is also worth noting that the end result of these
+ signature generators is to make some dependency and hash
+ information available to the build.
+ This information includes:
+ <itemizedlist>
+ <listitem><para>
+ <filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>:
+ The base hashes for each task in the recipe.
+ </para></listitem>
+ <listitem><para>
+ <filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
+ The base hashes for each dependent task.
+ </para></listitem>
+ <listitem><para>
+ <filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
+ The task dependencies for each task.
+ </para></listitem>
+ <listitem><para>
+ <filename>BB_TASKHASH</filename>:
+ The hash of the currently running task.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='shared-state'>
+ <title>Shared State</title>
+
+ <para>
+ Checksums and dependencies, as discussed in the previous
+ section, solve half the problem of supporting a shared state.
+ The other half of the problem is being able to use checksum
+ information during the build and being able to reuse or rebuild
+ specific components.
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink>
+ class is a relatively generic implementation of how to
+ "capture" a snapshot of a given task.
+ The idea is that the build process does not care about the
+ source of a task's output.
+ Output could be freshly built or it could be downloaded and
+ unpacked from somewhere.
+ In other words, the build process does not need to worry about
+ its origin.
+ </para>
+
+ <para>
+ Two types of output exist.
+ One type is just about creating a directory in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
+ A good example is the output of either
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>.
+ The other type of output occurs when a set of data is merged
+ into a shared directory tree such as the sysroot.
+ </para>
+
+ <para>
+ The Yocto Project team has tried to keep the details of the
+ implementation hidden in <filename>sstate</filename> class.
+ From a user's perspective, adding shared state wrapping to a
+ task is as simple as this
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>
+ example taken from the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-deploy'><filename>deploy</filename></ulink>
+ class:
+ <literallayout class='monospaced'>
+ DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
+ SSTATETASKS += "do_deploy"
+ do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
+ do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
+
+ python do_deploy_setscene () {
+ sstate_setscene(d)
+ }
+ addtask do_deploy_setscene
+ do_deploy[dirs] = "${DEPLOYDIR} ${B}"
+ do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"
+ </literallayout>
+ The following list explains the previous example:
+ <itemizedlist>
+ <listitem><para>
+ Adding "do_deploy" to <filename>SSTATETASKS</filename>
+ adds some required sstate-related processing, which is
+ implemented in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-sstate'><filename>sstate</filename></ulink>
+ class, to before and after the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-deploy'><filename>do_deploy</filename></ulink>
+ task.
+ </para></listitem>
+ <listitem><para>
+ The
+ <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename>
+ declares that <filename>do_deploy</filename> places its
+ output in <filename>${DEPLOYDIR}</filename> when run
+ normally (i.e. when not using the sstate cache).
+ This output becomes the input to the shared state cache.
+ </para></listitem>
+ <listitem><para>
+ The
+ <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename>
+ line causes the contents of the shared state cache to be
+ copied to <filename>${DEPLOY_DIR_IMAGE}</filename>.
+ <note>
+ If <filename>do_deploy</filename> is not already in
+ the shared state cache or if its input checksum
+ (signature) has changed from when the output was
+ cached, the task runs to populate the shared
+ state cache, after which the contents of the shared
+ state cache is copied to
+ <filename>${DEPLOY_DIR_IMAGE}</filename>.
+ If <filename>do_deploy</filename> is in the shared
+ state cache and its signature indicates that the
+ cached output is still valid (i.e. if no
+ relevant task inputs have changed), then the
+ contents of the shared state cache copies
+ directly to
+ <filename>${DEPLOY_DIR_IMAGE}</filename> by the
+ <filename>do_deploy_setscene</filename> task
+ instead, skipping the
+ <filename>do_deploy</filename> task.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ The following task definition is glue logic needed to
+ make the previous settings effective:
+ <literallayout class='monospaced'>
+ python do_deploy_setscene () {
+ sstate_setscene(d)
+ }
+ addtask do_deploy_setscene
+ </literallayout>
+ <filename>sstate_setscene()</filename> takes the flags
+ above as input and accelerates the
+ <filename>do_deploy</filename> task through the
+ shared state cache if possible.
+ If the task was accelerated,
+ <filename>sstate_setscene()</filename> returns True.
+ Otherwise, it returns False, and the normal
+ <filename>do_deploy</filename> task runs.
+ For more information, see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>"
+ section in the BitBake User Manual.
+ </para></listitem>
+ <listitem><para>
+ The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename>
+ line creates <filename>${DEPLOYDIR}</filename> and
+ <filename>${B}</filename> before the
+ <filename>do_deploy</filename> task runs, and also sets
+ the current working directory of
+ <filename>do_deploy</filename> to
+ <filename>${B}</filename>.
+ For more information, see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
+ section in the BitBake User Manual.
+ <note>
+ In cases where
+ <filename>sstate-inputdirs</filename> and
+ <filename>sstate-outputdirs</filename> would be the
+ same, you can use
+ <filename>sstate-plaindirs</filename>.
+ For example, to preserve the
+ <filename>${PKGD}</filename> and
+ <filename>${PKGDEST}</filename> output from the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task, use the following:
+ <literallayout class='monospaced'>
+ do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
+ </literallayout>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ The <filename>do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"</filename>
+ line appends extra metadata to the
+ <link linkend='stamp-files-and-the-rerunning-of-tasks'>stamp file</link>.
+ In this case, the metadata makes the task specific
+ to a machine's architecture.
+ See
+ "<ulink url='&YOCTO_DOCS_BB_URL;#ref-bitbake-tasklist'>The Task List</ulink>"
+ section in the BitBake User Manual for more
+ information on the <filename>stamp-extra-info</filename>
+ flag.
+ </para></listitem>
+ <listitem><para>
+ <filename>sstate-inputdirs</filename> and
+ <filename>sstate-outputdirs</filename> can also be used
+ with multiple directories.
+ For example, the following declares
+ <filename>PKGDESTWORK</filename> and
+ <filename>SHLIBWORK</filename> as shared state
+ input directories, which populates the shared state
+ cache, and <filename>PKGDATA_DIR</filename> and
+ <filename>SHLIBSDIR</filename> as the corresponding
+ shared state output directories:
+ <literallayout class='monospaced'>
+ do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
+ do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ These methods also include the ability to take a
+ lockfile when manipulating shared state directory
+ structures, for cases where file additions or removals
+ are sensitive:
+ <literallayout class='monospaced'>
+ do_package[sstate-lockfile] = "${PACKAGELOCK}"
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Behind the scenes, the shared state code works by looking in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>
+ for shared state files.
+ Here is an example:
+ <literallayout class='monospaced'>
+ SSTATE_MIRRORS ?= "\
+ file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
+ file://.* file:///some/local/dir/sstate/PATH"
+ </literallayout>
+ <note>
+ The shared state directory
+ (<filename>SSTATE_DIR</filename>) is organized into
+ two-character subdirectories, where the subdirectory
+ names are based on the first two characters of the hash.
+ If the shared state directory structure for a mirror has the
+ same structure as <filename>SSTATE_DIR</filename>, you must
+ specify "PATH" as part of the URI to enable the build system
+ to map to the appropriate subdirectory.
+ </note>
+ </para>
+
+ <para>
+ The shared state package validity can be detected just by
+ looking at the filename since the filename contains the task
+ checksum (or signature) as described earlier in this section.
+ If a valid shared state package is found, the build process
+ downloads it and uses it to accelerate the task.
+ </para>
+
+ <para>
+ The build processes use the <filename>*_setscene</filename>
+ tasks for the task acceleration phase.
+ BitBake goes through this phase before the main execution
+ code and tries to accelerate any tasks for which it can find
+ shared state packages.
+ If a shared state package for a task is available, the
+ shared state package is used.
+ This means the task and any tasks on which it is dependent
+ are not executed.
+ </para>
+
+ <para>
+ As a real world example, the aim is when building an IPK-based
+ image, only the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></ulink>
+ tasks would have their shared state packages fetched and
+ extracted.
+ Since the sysroot is not used, it would never get extracted.
+ This is another reason why a task-based approach is preferred
+ over a recipe-based approach, which would have to install the
+ output from every task.
+ </para>
+ </section>
+ </section>
+
+ <section id='automatically-added-runtime-dependencies'>
+ <title>Automatically Added Runtime Dependencies</title>
+
+ <para>
+ The OpenEmbedded build system automatically adds common types of
+ runtime dependencies between packages, which means that you do not
+ need to explicitly declare the packages using
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
+ Three automatic mechanisms exist (<filename>shlibdeps</filename>,
+ <filename>pcdeps</filename>, and <filename>depchains</filename>)
+ that handle shared libraries, package configuration (pkg-config)
+ modules, and <filename>-dev</filename> and
+ <filename>-dbg</filename> packages, respectively.
+ For other types of runtime dependencies, you must manually declare
+ the dependencies.
+ <itemizedlist>
+ <listitem><para>
+ <filename>shlibdeps</filename>:
+ During the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task of each recipe, all shared libraries installed by the
+ recipe are located.
+ For each shared library, the package that contains the
+ shared library is registered as providing the shared
+ library.
+ More specifically, the package is registered as providing
+ the
+ <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
+ of the library.
+ The resulting shared-library-to-package mapping
+ is saved globally in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+ by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
+ task.</para>
+
+ <para>Simultaneously, all executables and shared libraries
+ installed by the recipe are inspected to see what shared
+ libraries they link against.
+ For each shared library dependency that is found,
+ <filename>PKGDATA_DIR</filename> is queried to
+ see if some package (likely from a different recipe)
+ contains the shared library.
+ If such a package is found, a runtime dependency is added
+ from the package that depends on the shared library to the
+ package that contains the library.</para>
+
+ <para>The automatically added runtime dependency also
+ includes a version restriction.
+ This version restriction specifies that at least the
+ current version of the package that provides the shared
+ library must be used, as if
+ "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
+ had been added to <filename>RDEPENDS</filename>.
+ This forces an upgrade of the package containing the shared
+ library when installing the package that depends on the
+ library, if needed.</para>
+
+ <para>If you want to avoid a package being registered as
+ providing a particular shared library (e.g. because the library
+ is for internal use only), then add the library to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></ulink>
+ inside the package's recipe.
+ </para></listitem>
+ <listitem><para>
+ <filename>pcdeps</filename>:
+ During the <filename>do_package</filename> task of each
+ recipe, all pkg-config modules
+ (<filename>*.pc</filename> files) installed by the recipe
+ are located.
+ For each module, the package that contains the module is
+ registered as providing the module.
+ The resulting module-to-package mapping is saved globally in
+ <filename>PKGDATA_DIR</filename> by the
+ <filename>do_packagedata</filename> task.</para>
+
+ <para>Simultaneously, all pkg-config modules installed by
+ the recipe are inspected to see what other pkg-config
+ modules they depend on.
+ A module is seen as depending on another module if it
+ contains a "Requires:" line that specifies the other module.
+ For each module dependency,
+ <filename>PKGDATA_DIR</filename> is queried to see if some
+ package contains the module.
+ If such a package is found, a runtime dependency is added
+ from the package that depends on the module to the package
+ that contains the module.
+ <note>
+ The <filename>pcdeps</filename> mechanism most often
+ infers dependencies between <filename>-dev</filename>
+ packages.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <filename>depchains</filename>:
+ If a package <filename>foo</filename> depends on a package
+ <filename>bar</filename>, then <filename>foo-dev</filename>
+ and <filename>foo-dbg</filename> are also made to depend on
+ <filename>bar-dev</filename> and
+ <filename>bar-dbg</filename>, respectively.
+ Taking the <filename>-dev</filename> packages as an
+ example, the <filename>bar-dev</filename> package might
+ provide headers and shared library symlinks needed by
+ <filename>foo-dev</filename>, which shows the need
+ for a dependency between the packages.</para>
+
+ <para>The dependencies added by
+ <filename>depchains</filename> are in the form of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>.
+ <note>
+ By default, <filename>foo-dev</filename> also has an
+ <filename>RDEPENDS</filename>-style dependency on
+ <filename>foo</filename>, because the default value of
+ <filename>RDEPENDS_${PN}-dev</filename> (set in
+ <filename>bitbake.conf</filename>) includes
+ "${PN}".
+ </note></para>
+
+ <para>To ensure that the dependency chain is never broken,
+ <filename>-dev</filename> and <filename>-dbg</filename>
+ packages are always generated by default, even if the
+ packages turn out to be empty.
+ See the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></ulink>
+ variable for more information.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The <filename>do_package</filename> task depends on the
+ <filename>do_packagedata</filename> task of each recipe in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ through use of a
+ <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
+ declaration, which guarantees that the required
+ shared-library/module-to-package mapping information will be available
+ when needed as long as <filename>DEPENDS</filename> has been
+ correctly set.
+ </para>
+ </section>
+
+ <section id='fakeroot-and-pseudo'>
+ <title>Fakeroot and Pseudo</title>
+
+ <para>
+ Some tasks are easier to implement when allowed to perform certain
+ operations that are normally reserved for the root user (e.g.
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package_write_deb'><filename>do_package_write*</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-rootfs'><filename>do_rootfs</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-image'><filename>do_image*</filename></ulink>).
+ For example, the <filename>do_install</filename> task benefits
+ from being able to set the UID and GID of installed files to
+ arbitrary values.
+ </para>
+
+ <para>
+ One approach to allowing tasks to perform root-only operations
+ would be to require
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ to run as root.
+ However, this method is cumbersome and has security issues.
+ The approach that is actually used is to run tasks that benefit
+ from root privileges in a "fake" root environment.
+ Within this environment, the task and its child processes believe
+ that they are running as the root user, and see an internally
+ consistent view of the filesystem.
+ As long as generating the final output (e.g. a package or an image)
+ does not require root privileges, the fact that some earlier
+ steps ran in a fake root environment does not cause problems.
+ </para>
+
+ <para>
+ The capability to run tasks in a fake root environment is known as
+ "<ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>",
+ which is derived from the BitBake keyword/variable
+ flag that requests a fake root environment for a task.
+ </para>
+
+ <para>
+ In the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>,
+ the program that implements fakeroot is known as Pseudo.
+ Pseudo overrides system calls by using the environment variable
+ <filename>LD_PRELOAD</filename>, which results in the illusion
+ of running as root.
+ To keep track of "fake" file ownership and permissions resulting
+ from operations that require root permissions, Pseudo uses
+ an SQLite 3 database.
+ This database is stored in
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/pseudo/files.db</filename>
+ for individual recipes.
+ Storing the database in a file as opposed to in memory
+ gives persistence between tasks and builds, which is not
+ accomplished using fakeroot.
+ <note><title>Caution</title>
+ If you add your own task that manipulates the same files or
+ directories as a fakeroot task, then that task also needs to
+ run under fakeroot.
+ Otherwise, the task cannot run root-only operations, and
+ cannot see the fake file ownership and permissions set by the
+ other task.
+ You need to also add a dependency on
+ <filename>virtual/fakeroot-native:do_populate_sysroot</filename>,
+ giving the following:
+ <literallayout class='monospaced'>
+ fakeroot do_mytask () {
+ ...
+ }
+ do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
+ </literallayout>
+ </note>
+ For more information, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink>
+ variables in the BitBake User Manual.
+ You can also reference the
+ "<ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>"
+ and
+ "<ulink url='https://github.com/wrpseudo/pseudo/wiki/WhyNotFakeroot'>Why Not Fakeroot?</ulink>"
+ articles for background information on Pseudo.
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-customization.xsl b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-customization.xsl
similarity index 68%
copy from import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-customization.xsl
copy to import-layers/yocto-poky/documentation/overview-manual/overview-manual-customization.xsl
index dcc02dd..22360e7 100644
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-customization.xsl
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-customization.xsl
@@ -11,14 +11,17 @@
-->
- <xsl:import href="yocto-project-qs-titlepage.xsl"/>
-
<xsl:include href="../template/permalinks.xsl"/>
<xsl:include href="../template/section.title.xsl"/>
<xsl:include href="../template/component.title.xsl"/>
<xsl:include href="../template/division.title.xsl"/>
<xsl:include href="../template/formal.object.heading.xsl"/>
- <xsl:param name="generate.toc" select="'article nop'"></xsl:param>
- <xsl:param name="html.stylesheet" select="'qs-style.css'" />
+ <xsl:param name="html.stylesheet" select="'overview-manual-style.css'" />
+ <xsl:param name="chapter.autolabel" select="1" />
+ <xsl:param name="appendix.autolabel" select="A" />
+ <xsl:param name="section.autolabel" select="1" />
+ <xsl:param name="section.label.includes.component.label" select="1" />
+ <xsl:param name="generate.id.attributes" select="1" />
+
</xsl:stylesheet>
diff --git a/import-layers/yocto-poky/documentation/overview-manual/overview-manual-development-environment.xml b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-development-environment.xml
new file mode 100644
index 0000000..bba93cc
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-development-environment.xml
@@ -0,0 +1,970 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='overview-development-environment'>
+<title>The Yocto Project Development Environment</title>
+
+<para>
+ This chapter takes a look at the Yocto Project development
+ environment.
+ The chapter provides Yocto Project Development environment concepts that
+ help you understand how work is accomplished in an open source environment,
+ which is very different as compared to work accomplished in a closed,
+ proprietary environment.
+</para>
+
+<para>
+ Specifically, this chapter addresses open source philosophy, source
+ repositories, workflows, Git, and licensing.
+</para>
+
+<section id='open-source-philosophy'>
+ <title>Open Source Philosophy</title>
+
+ <para>
+ Open source philosophy is characterized by software development
+ directed by peer production and collaboration through an active
+ community of developers.
+ Contrast this to the more standard centralized development models
+ used by commercial software companies where a finite set of developers
+ produces a product for sale using a defined set of procedures that
+ ultimately result in an end product whose architecture and source
+ material are closed to the public.
+ </para>
+
+ <para>
+ Open source projects conceptually have differing concurrent agendas,
+ approaches, and production.
+ These facets of the development process can come from anyone in the
+ public (community) who has a stake in the software project.
+ The open source environment contains new copyright, licensing, domain,
+ and consumer issues that differ from the more traditional development
+ environment.
+ In an open source environment, the end product, source material,
+ and documentation are all available to the public at no cost.
+ </para>
+
+ <para>
+ A benchmark example of an open source project is the Linux kernel,
+ which was initially conceived and created by Finnish computer science
+ student Linus Torvalds in 1991.
+ Conversely, a good example of a non-open source project is the
+ <trademark class='registered'>Windows</trademark> family of operating
+ systems developed by
+ <trademark class='registered'>Microsoft</trademark> Corporation.
+ </para>
+
+ <para>
+ Wikipedia has a good historical description of the Open Source
+ Philosophy
+ <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
+ You can also find helpful information on how to participate in the
+ Linux Community
+ <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
+ </para>
+</section>
+
+<section id='gs-the-development-host'>
+ <title>The Development Host</title>
+
+ <para>
+ A development host or
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+ is key to using the Yocto Project.
+ Because the goal of the Yocto Project is to develop images or
+ applications that run on embedded hardware, development of those
+ images and applications generally takes place on a system not
+ intended to run the software - the development host.
+ </para>
+
+ <para>
+ You need to set up a development host in order to use it with the
+ Yocto Project.
+ Most find that it is best to have a native Linux machine function as
+ the development host.
+ However, it is possible to use a system that does not run Linux
+ as its operating system as your development host.
+ When you have a Mac or Windows-based system, you can set it up
+ as the development host by using
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
+ which leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
+ Once you take the steps to set up a CROPS machine, you effectively
+ have access to a shell environment that is similar to what you see
+ when using a Linux-based development host.
+ For the steps needed to set up a system using CROPS, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ If your development host is going to be a system that runs a Linux
+ distribution, steps still exist that you must take to prepare the
+ system for use with the Yocto Project.
+ You need to be sure that the Linux distribution on the system is
+ one that supports the Yocto Project.
+ You also need to be sure that the correct set of host packages are
+ installed that allow development using the Yocto Project.
+ For the steps needed to set up a development host that runs Linux,
+ see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ Once your development host is set up to use the Yocto Project,
+ several methods exist for you to do work in the Yocto Project
+ environment:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Command Lines, BitBake, and Shells:</emphasis>
+ Traditional development in the Yocto Project involves using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>,
+ which uses BitBake, in a command-line environment from a shell
+ on your development host.
+ You can accomplish this from a host that is a native Linux
+ machine or from a host that has been set up with CROPS.
+ Either way, you create, modify, and build images and
+ applications all within a shell-based environment using
+ components and tools available through your Linux distribution
+ and the Yocto Project.</para>
+
+ <para>For a general flow of the build procedures, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Board Support Package (BSP) Development:</emphasis>
+ Development of BSPs involves using the Yocto Project to
+ create and test layers that allow easy development of
+ images and applications targeted for specific hardware.
+ To development BSPs, you need to take some additional steps
+ beyond what was described in setting up a development host.
+ </para>
+
+ <para>The
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>
+ provides BSP-related development information.
+ For specifics on development host preparation, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>"
+ section in the Yocto Project Board Support Package (BSP)
+ Developer's Guide.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Kernel Development:</emphasis>
+ If you are going to be developing kernels using the Yocto
+ Project you likely will be using <filename>devtool</filename>.
+ A workflow using <filename>devtool</filename> makes kernel
+ development quicker by reducing iteration cycle times.</para>
+
+ <para>The
+ <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
+ provides kernel-related development information.
+ For specifics on development host preparation, see the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>"
+ section in the Yocto Project Linux Kernel Development Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Using the <trademark class='trade'>Eclipse</trademark> IDE:</emphasis>
+ One of two Yocto Project development methods that involves an
+ interface that effectively puts the Yocto Project into the
+ background is the popular Eclipse IDE.
+ This method of development is advantageous if you are already
+ familiar with working within Eclipse.
+ Development is supported through a plugin that you install
+ onto your development host.</para>
+
+ <para>For steps that show you how to set up your development
+ host to use the Eclipse Yocto Project plugin, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>"
+ Chapter in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Using Toaster:</emphasis>
+ The other Yocto Project development method that involves an
+ interface that effectively puts the Yocto Project into the
+ background is Toaster.
+ Toaster provides an interface to the OpenEmbedded build system.
+ The interface enables you to configure and run your builds.
+ Information about builds is collected and stored in a database.
+ You can use Toaster to configure and start builds on multiple
+ remote build servers.</para>
+
+ <para>For steps that show you how to set up your development
+ host to use Toaster and on how to use Toaster in general,
+ see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='yocto-project-repositories'>
+ <title>Yocto Project Source Repositories</title>
+
+ <para>
+ The Yocto Project team maintains complete source repositories for all
+ Yocto Project files at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ This web-based source code browser is organized into categories by
+ function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
+ so forth.
+ From the interface, you can click on any particular item in the "Name"
+ column and see the URL at the bottom of the page that you need to clone
+ a Git repository for that particular item.
+ Having a local Git repository of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
+ which is usually named "poky", allows
+ you to make changes, contribute to the history, and ultimately enhance
+ the Yocto Project's tools, Board Support Packages, and so forth.
+ </para>
+
+ <para>
+ For any supported release of Yocto Project, you can also go to the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
+ select the "DOWNLOADS" item from the "SOFTWARE" menu and get a
+ released tarball of the <filename>poky</filename> repository, any
+ supported BSP tarball, or Yocto Project tools.
+ Unpacking these tarballs gives you a snapshot of the released
+ files.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ The recommended method for setting up the Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ and the files for supported BSPs
+ (e.g., <filename>meta-intel</filename>) is to use
+ <link linkend='git'>Git</link> to create a local copy of
+ the upstream repositories.
+ </para></listitem>
+ <listitem><para>
+ Be sure to always work in matching branches for both
+ the selected BSP repository and the Source Directory
+ (i.e. <filename>poky</filename>) repository.
+ For example, if you have checked out the "master" branch
+ of <filename>poky</filename> and you are going to use
+ <filename>meta-intel</filename>, be sure to checkout the
+ "master" branch of <filename>meta-intel</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ In summary, here is where you can get the project files needed for
+ development:
+ <itemizedlist>
+ <listitem><para id='source-repositories'>
+ <emphasis>
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories:</ulink>
+ </emphasis>
+ This area contains IDE Plugins, Matchbox, Poky, Poky Support,
+ Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
+ You can create local copies of Git repositories for each of
+ these areas.</para>
+
+ <para>
+ <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
+ For steps on how to view and access these upstream Git
+ repositories, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>"
+ Section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para><anchor id='index-downloads' />
+ <emphasis>
+ <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
+ </emphasis>
+ This is an index of releases such as
+ the <trademark class='trade'>Eclipse</trademark>
+ Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers
+ for cross-development toolchains, and all released versions of
+ Yocto Project in the form of images or tarballs.
+ Downloading and extracting these files does not produce a local
+ copy of the Git repository but rather a snapshot of a
+ particular release or image.</para>
+
+ <para>
+ <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
+ For steps on how to view and access these files, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para id='downloads-page'>
+ <emphasis>"DOWNLOADS" page for the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
+ </emphasis></para>
+
+ <para>The Yocto Project website includes a "DOWNLOADS" page
+ accessible through the "SOFTWARE" menu that allows you to
+ download any Yocto Project release, tool, and Board Support
+ Package (BSP) in tarball form.
+ The tarballs are similar to those found in the
+ <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
+ area.</para>
+
+ <para>
+ <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
+ For steps on how to use the "DOWNLOADS" page, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='gs-git-workflows-and-the-yocto-project'>
+ <title>Git Workflows and the Yocto Project</title>
+
+ <para>
+ Developing using the Yocto Project likely requires the use of
+ <link linkend='git'>Git</link>.
+ Git is a free, open source distributed version control system
+ used as part of many collaborative design environments.
+ This section provides workflow concepts using the Yocto Project and
+ Git.
+ In particular, the information covers basic practices that describe
+ roles and actions in a collaborative development environment.
+ <note>
+ If you are familiar with this type of development environment, you
+ might not want to read this section.
+ </note>
+ </para>
+
+ <para>
+ The Yocto Project files are maintained using Git in "branches"
+ whose Git histories track every change and whose structures
+ provide branches for all diverging functionality.
+ Although there is no need to use Git, many open source projects do so.
+ <para>
+
+ </para>
+ For the Yocto Project, a key individual called the "maintainer" is
+ responsible for the integrity of the "master" branch of a given Git
+ repository.
+ The "master" branch is the “upstream” repository from which final or
+ most recent builds of a project occur.
+ The maintainer is responsible for accepting changes from other
+ developers and for organizing the underlying branch structure to
+ reflect release strategies and so forth.
+ <note>
+ For information on finding out who is responsible for (maintains)
+ a particular area of code in the Yocto Project, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </note>
+ </para>
+
+ <para>
+ The Yocto Project <filename>poky</filename> Git repository also has an
+ upstream contribution Git repository named
+ <filename>poky-contrib</filename>.
+ You can see all the branches in this repository using the web interface
+ of the
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
+ within the "Poky Support" area.
+ These branches hold changes (commits) to the project that have been
+ submitted or committed by the Yocto Project development team and by
+ community members who contribute to the project.
+ The maintainer determines if the changes are qualified to be moved
+ from the "contrib" branches into the "master" branch of the Git
+ repository.
+ </para>
+
+ <para>
+ Developers (including contributing community members) create and
+ maintain cloned repositories of upstream branches.
+ The cloned repositories are local to their development platforms and
+ are used to develop changes.
+ When a developer is satisfied with a particular feature or change,
+ they "push" the change to the appropriate "contrib" repository.
+ </para>
+
+ <para>
+ Developers are responsible for keeping their local repository
+ up-to-date with whatever upstream branch they are working against.
+ They are also responsible for straightening out any conflicts that
+ might arise within files that are being worked on simultaneously by
+ more than one person.
+ All this work is done locally on the development host before
+ anything is pushed to a "contrib" area and examined at the maintainer’s
+ level.
+ </para>
+
+ <para>
+ A somewhat formal method exists by which developers commit changes
+ and push them into the "contrib" area and subsequently request that
+ the maintainer include them into an upstream branch.
+ This process is called “submitting a patch” or "submitting a change."
+ For information on submitting patches and changes, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ In summary, a single point of entry
+ exists for changes into a "master" or development branch of the
+ Git repository, which is controlled by the project’s maintainer.
+ And, a set of developers exist who independently develop, test, and
+ submit changes to "contrib" areas for the maintainer to examine.
+ The maintainer then chooses which changes are going to become a
+ permanent part of the project.
+ </para>
+
+ <para>
+ <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
+ </para>
+
+ <para>
+ While each development environment is unique, there are some best
+ practices or methods that help development run smoothly.
+ The following list describes some of these practices.
+ For more information about Git workflows, see the workflow topics in
+ the
+ <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Make Small Changes:</emphasis>
+ It is best to keep the changes you commit small as compared to
+ bundling many disparate changes into a single commit.
+ This practice not only keeps things manageable but also allows
+ the maintainer to more easily include or refuse changes.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Complete Changes:</emphasis>
+ It is also good practice to leave the repository in a
+ state that allows you to still successfully build your project.
+ In other words, do not commit half of a feature,
+ then add the other half as a separate, later commit.
+ Each commit should take you from one buildable project state
+ to another buildable state.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use Branches Liberally:</emphasis>
+ It is very easy to create, use, and delete local branches in
+ your working Git repository on the development host.
+ You can name these branches anything you like.
+ It is helpful to give them names associated with the particular
+ feature or change on which you are working.
+ Once you are done with a feature or change and have merged it
+ into your local master branch, simply discard the temporary
+ branch.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Merge Changes:</emphasis>
+ The <filename>git merge</filename> command allows you to take
+ the changes from one branch and fold them into another branch.
+ This process is especially helpful when more than a single
+ developer might be working on different parts of the same
+ feature.
+ Merging changes also automatically identifies any collisions
+ or "conflicts" that might happen as a result of the same lines
+ of code being altered by two different developers.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Manage Branches:</emphasis>
+ Because branches are easy to use, you should use a system
+ where branches indicate varying levels of code readiness.
+ For example, you can have a "work" branch to develop in, a
+ "test" branch where the code or change is tested, a "stage"
+ branch where changes are ready to be committed, and so forth.
+ As your project develops, you can merge code across the
+ branches to reflect ever-increasing stable states of the
+ development.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use Push and Pull:</emphasis>
+ The push-pull workflow is based on the concept of developers
+ "pushing" local commits to a remote repository, which is
+ usually a contribution repository.
+ This workflow is also based on developers "pulling" known
+ states of the project down into their local development
+ repositories.
+ The workflow easily allows you to pull changes submitted by
+ other developers from the upstream repository into your
+ work area ensuring that you have the most recent software
+ on which to develop.
+ The Yocto Project has two scripts named
+ <filename>create-pull-request</filename> and
+ <filename>send-pull-request</filename> that ship with the
+ release to facilitate this workflow.
+ You can find these scripts in the <filename>scripts</filename>
+ folder of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ For information on how to use these scripts, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Patch Workflow:</emphasis>
+ This workflow allows you to notify the maintainer through an
+ email that you have a change (or patch) you would like
+ considered for the "master" branch of the Git repository.
+ To send this type of change, you format the patch and then
+ send the email using the Git commands
+ <filename>git format-patch</filename> and
+ <filename>git send-email</filename>.
+ For information on how to use these scripts, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='git'>
+ <title>Git</title>
+
+ <para>
+ The Yocto Project makes extensive use of Git, which is a
+ free, open source distributed version control system.
+ Git supports distributed development, non-linear development,
+ and can handle large projects.
+ It is best that you have some fundamental understanding
+ of how Git tracks projects and how to work with Git if
+ you are going to use the Yocto Project for development.
+ This section provides a quick overview of how Git works and
+ provides you with a summary of some essential Git commands.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ For more information on Git, see
+ <ulink url='http://git-scm.com/documentation'></ulink>.
+ </para></listitem>
+ <listitem><para>
+ If you need to download Git, it is recommended that you add
+ Git to your system through your distribution's "software
+ store" (e.g. for Ubuntu, use the Ubuntu Software feature).
+ For the Git download page, see
+ <ulink url='http://git-scm.com/download'></ulink>.
+ </para></listitem>
+ <listitem><para>
+ For information beyond the introductory nature in this
+ section, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <section id='repositories-tags-and-branches'>
+ <title>Repositories, Tags, and Branches</title>
+
+ <para>
+ As mentioned briefly in the previous section and also in the
+ "<link linkend='gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</link>"
+ section, the Yocto Project maintains source repositories at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ If you look at this web-interface of the repositories, each item
+ is a separate Git repository.
+ </para>
+
+ <para>
+ Git repositories use branching techniques that track content
+ change (not files) within a project (e.g. a new feature or updated
+ documentation).
+ Creating a tree-like structure based on project divergence allows
+ for excellent historical information over the life of a project.
+ This methodology also allows for an environment from which you can
+ do lots of local experimentation on projects as you develop
+ changes or new features.
+ </para>
+
+ <para>
+ A Git repository represents all development efforts for a given
+ project.
+ For example, the Git repository <filename>poky</filename> contains
+ all changes and developments for that repository over the course
+ of its entire life.
+ That means that all changes that make up all releases are captured.
+ The repository maintains a complete history of changes.
+ </para>
+
+ <para>
+ You can create a local copy of any repository by "cloning" it
+ with the <filename>git clone</filename> command.
+ When you clone a Git repository, you end up with an identical
+ copy of the repository on your development system.
+ Once you have a local copy of a repository, you can take steps to
+ develop locally.
+ For examples on how to clone Git repositories, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ It is important to understand that Git tracks content change and
+ not files.
+ Git uses "branches" to organize different development efforts.
+ For example, the <filename>poky</filename> repository has
+ several branches that include the current "&DISTRO_NAME_NO_CAP;"
+ branch, the "master" branch, and many branches for past
+ Yocto Project releases.
+ You can see all the branches by going to
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
+ clicking on the
+ <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
+ link beneath the "Branch" heading.
+ </para>
+
+ <para>
+ Each of these branches represents a specific area of development.
+ The "master" branch represents the current or most recent
+ development.
+ All other branches represent offshoots of the "master" branch.
+ </para>
+
+ <para>
+ When you create a local copy of a Git repository, the copy has
+ the same set of branches as the original.
+ This means you can use Git to create a local working area
+ (also called a branch) that tracks a specific development branch
+ from the upstream source Git repository.
+ in other words, you can define your local Git environment to
+ work on any development branch in the repository.
+ To help illustrate, consider the following example Git commands:
+ <literallayout class='monospaced'>
+ $ cd ~
+ $ git clone git://git.yoctoproject.org/poky
+ $ cd poky
+ $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
+ </literallayout>
+ In the previous example after moving to the home directory, the
+ <filename>git clone</filename> command creates a
+ local copy of the upstream <filename>poky</filename> Git repository.
+ By default, Git checks out the "master" branch for your work.
+ After changing the working directory to the new local repository
+ (i.e. <filename>poky</filename>), the
+ <filename>git checkout</filename> command creates
+ and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which
+ tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.
+ Changes you make while in this branch would ultimately affect
+ the upstream "&DISTRO_NAME_NO_CAP;" branch of the
+ <filename>poky</filename> repository.
+ </para>
+
+ <para>
+ It is important to understand that when you create and checkout a
+ local working branch based on a branch name,
+ your local environment matches the "tip" of that particular
+ development branch at the time you created your local branch,
+ which could be different from the files in the "master" branch
+ of the upstream repository.
+ In other words, creating and checking out a local branch based on
+ the "&DISTRO_NAME_NO_CAP;" branch name is not the same as
+ checking out the "master" branch in the repository.
+ Keep reading to see how you create a local snapshot of a Yocto
+ Project Release.
+ </para>
+
+ <para>
+ Git uses "tags" to mark specific changes in a repository branch
+ structure.
+ Typically, a tag is used to mark a special point such as the final
+ change (or commit) before a project is released.
+ You can see the tags used with the <filename>poky</filename> Git
+ repository by going to
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
+ clicking on the
+ <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
+ link beneath the "Tag" heading.
+ </para>
+
+ <para>
+ Some key tags for the <filename>poky</filename> repository are
+ <filename>jethro-14.0.3</filename>,
+ <filename>morty-16.0.1</filename>,
+ <filename>pyro-17.0.0</filename>, and
+ <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
+ These tags represent Yocto Project releases.
+ </para>
+
+ <para>
+ When you create a local copy of the Git repository, you also
+ have access to all the tags in the upstream repository.
+ Similar to branches, you can create and checkout a local working
+ Git branch based on a tag name.
+ When you do this, you get a snapshot of the Git repository that
+ reflects the state of the files when the change was made associated
+ with that tag.
+ The most common use is to checkout a working branch that matches
+ a specific Yocto Project release.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ cd ~
+ $ git clone git://git.yoctoproject.org/poky
+ $ cd poky
+ $ git fetch --tags
+ $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
+ </literallayout>
+ In this example, the name of the top-level directory of your
+ local Yocto Project repository is <filename>poky</filename>.
+ After moving to the <filename>poky</filename> directory, the
+ <filename>git fetch</filename> command makes all the upstream
+ tags available locally in your repository.
+ Finally, the <filename>git checkout</filename> command
+ creates and checks out a branch named "my-rocko-18.0.0" that is
+ based on the upstream branch whose "HEAD" matches the
+ commit in the repository associated with the "rocko-18.0.0" tag.
+ The files in your repository now exactly match that particular
+ Yocto Project release as it is tagged in the upstream Git
+ repository.
+ It is important to understand that when you create and
+ checkout a local working branch based on a tag, your environment
+ matches a specific point in time and not the entire development
+ branch (i.e. from the "tip" of the branch backwards).
+ </para>
+ </section>
+
+ <section id='basic-commands'>
+ <title>Basic Commands</title>
+
+ <para>
+ Git has an extensive set of commands that lets you manage changes
+ and perform collaboration over the life of a project.
+ Conveniently though, you can manage with a small set of basic
+ operations and workflows once you understand the basic
+ philosophy behind Git.
+ You do not have to be an expert in Git to be functional.
+ A good place to look for instruction on a minimal set of Git
+ commands is
+ <ulink url='http://git-scm.com/documentation'>here</ulink>.
+ </para>
+
+ <para>
+ The following list of Git commands briefly describes some basic
+ Git operations as a way to get started.
+ As with any set of commands, this list (in most cases) simply shows
+ the base command and omits the many arguments it supports.
+ See the Git documentation for complete descriptions and strategies
+ on how to use these commands:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>git init</filename>:</emphasis>
+ Initializes an empty Git repository.
+ You cannot use Git commands unless you have a
+ <filename>.git</filename> repository.
+ </para></listitem>
+ <listitem><para id='git-commands-clone'>
+ <emphasis><filename>git clone</filename>:</emphasis>
+ Creates a local clone of a Git repository that is on
+ equal footing with a fellow developer’s Git repository
+ or an upstream repository.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git add</filename>:</emphasis>
+ Locally stages updated file contents to the index that
+ Git uses to track changes.
+ You must stage all files that have changed before you
+ can commit them.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git commit</filename>:</emphasis>
+ Creates a local "commit" that documents the changes you
+ made.
+ Only changes that have been staged can be committed.
+ Commits are used for historical purposes, for determining
+ if a maintainer of a project will allow the change,
+ and for ultimately pushing the change from your local
+ Git repository into the project’s upstream repository.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git status</filename>:</emphasis>
+ Reports any modified files that possibly need to be
+ staged and gives you a status of where you stand regarding
+ local commits as compared to the upstream repository.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis>
+ Changes your local working branch and in this form
+ assumes the local branch already exists.
+ This command is analogous to "cd".
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable> <replaceable>upstream-branch</replaceable>:</emphasis>
+ Creates and checks out a working branch on your local
+ machine.
+ The local branch tracks the upstream branch.
+ You can use your local branch to isolate your work.
+ It is a good idea to use local branches when adding
+ specific features or changes.
+ Using isolated branches facilitates easy removal of
+ changes if they do not work out.
+ </para></listitem>
+ <listitem><para><emphasis><filename>git branch</filename>:</emphasis>
+ Displays the existing local branches associated with your
+ local repository.
+ The branch that you have currently checked out is noted
+ with an asterisk character.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis>
+ Deletes an existing local branch.
+ You need to be in a local branch other than the one you
+ are deleting in order to delete
+ <replaceable>branch-name</replaceable>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git pull --rebase</filename>:</emphasis>
+ Retrieves information from an upstream Git repository
+ and places it in your local Git repository.
+ You use this command to make sure you are synchronized with
+ the repository from which you are basing changes
+ (.e.g. the "master" branch).
+ The "--rebase" option ensures that any local commits you
+ have in your branch are preserved at the top of your
+ local branch.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git push</filename> <replaceable>repo-name</replaceable> <replaceable>local-branch</replaceable><filename>:</filename><replaceable>upstream-branch</replaceable>:</emphasis>
+ Sends all your committed local changes to the upstream Git
+ repository that your local repository is tracking
+ (e.g. a contribution repository).
+ The maintainer of the project draws from these repositories
+ to merge changes (commits) into the appropriate branch
+ of project's upstream repository.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git merge</filename>:</emphasis>
+ Combines or adds changes from one
+ local branch of your repository with another branch.
+ When you create a local Git repository, the default branch
+ is named "master".
+ A typical workflow is to create a temporary branch that is
+ based off "master" that you would use for isolated work.
+ You would make your changes in that isolated branch,
+ stage and commit them locally, switch to the "master"
+ branch, and then use the <filename>git merge</filename>
+ command to apply the changes from your isolated branch
+ into the currently checked out branch (e.g. "master").
+ After the merge is complete and if you are done with
+ working in that isolated branch, you can safely delete
+ the isolated branch.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git cherry-pick</filename> <replaceable>commits</replaceable>:</emphasis>
+ Choose and apply specific commits from one branch
+ into another branch.
+ There are times when you might not be able to merge
+ all the changes in one branch with
+ another but need to pick out certain ones.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>gitk</filename>:</emphasis>
+ Provides a GUI view of the branches and changes in your
+ local Git repository.
+ This command is a good way to graphically see where things
+ have diverged in your local repository.
+ <note>
+ You need to install the <filename>gitk</filename>
+ package on your development system to use this
+ command.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git log</filename>:</emphasis>
+ Reports a history of your commits to the repository.
+ This report lists all commits regardless of whether you
+ have pushed them upstream or not.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>git diff</filename>:</emphasis>
+ Displays line-by-line differences between a local
+ working file and the same file as understood by Git.
+ This command is useful to see what you have changed
+ in any given file.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
+
+<section id='licensing'>
+ <title>Licensing</title>
+
+ <para>
+ Because open source projects are open to the public, they have
+ different licensing structures in place.
+ License evolution for both Open Source and Free Software has an
+ interesting history.
+ If you are interested in this history, you can find basic information
+ here:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
+ </para></listitem>
+ <listitem><para>
+ <ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license history</ulink>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ In general, the Yocto Project is broadly licensed under the
+ Massachusetts Institute of Technology (MIT) License.
+ MIT licensing permits the reuse of software within proprietary
+ software as long as the license is distributed with that software.
+ MIT is also compatible with the GNU General Public License (GPL).
+ Patches to the Yocto Project follow the upstream licensing scheme.
+ You can find information on the MIT license
+ <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
+ You can find information on the GNU GPL
+ <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>here</ulink>.
+ </para>
+
+ <para>
+ When you build an image using the Yocto Project, the build process
+ uses a known list of licenses to ensure compliance.
+ You can find this list in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ at <filename>meta/files/common-licenses</filename>.
+ Once the build completes, the list of all licenses found and used
+ during that build are kept in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ at <filename>tmp/deploy/licenses</filename>.
+ </para>
+
+ <para>
+ If a module requires a license that is not in the base list, the
+ build process generates a warning during the build.
+ These tools make it easier for a developer to be certain of the
+ licenses with which their shipped products must comply.
+ However, even with these tools it is still up to the developer to
+ resolve potential licensing issues.
+ </para>
+
+ <para>
+ The base list of licenses used by the build process is a combination
+ of the Software Package Data Exchange (SPDX) list and the Open
+ Source Initiative (OSI) projects.
+ <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of
+ the Linux Foundation that maintains a specification for a standard
+ format for communicating the components, licenses, and copyrights
+ associated with a software package.
+ <ulink url='http://opensource.org'>OSI</ulink> is a corporation
+ dedicated to the Open Source Definition and the effort for reviewing
+ and approving licenses that conform to the Open Source Definition
+ (OSD).
+ </para>
+
+ <para>
+ You can find a list of the combined SPDX and OSI licenses that the
+ Yocto Project uses in the
+ <filename>meta/files/common-licenses</filename> directory in your
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ </para>
+
+ <para>
+ For information that can help you maintain compliance with various
+ open source licensing during the lifecycle of a product created using
+ the Yocto Project, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-eclipse-customization.xsl
similarity index 71%
copy from import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl
copy to import-layers/yocto-poky/documentation/overview-manual/overview-manual-eclipse-customization.xsl
index 50e6830..aaf99ea 100644
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-eclipse-customization.xsl
@@ -16,19 +16,20 @@
-->
- <xsl:import href="yocto-project-qs-titlepage.xsl"/>
-
<xsl:param name="chunker.output.indent" select="'yes'"/>
<xsl:param name="chunk.quietly" select="1"/>
+ <xsl:param name="chunk.first.sections" select="1"/>
+ <xsl:param name="chunk.section.depth" select="10"/>
<xsl:param name="use.id.as.filename" select="1"/>
<xsl:param name="ulink.target" select="'_self'" />
- <xsl:param name="base.dir" select="'html/yocto-project-qs/'"/>
- <xsl:param name="chunk.section.depth" select="0"/>
+ <xsl:param name="base.dir" select="'html/overview-manual/'"/>
<xsl:param name="html.stylesheet" select="'../book.css'"/>
<xsl:param name="eclipse.manifest" select="0"/>
<xsl:param name="create.plugin.xml" select="0"/>
<xsl:param name="suppress.navigation" select="1"/>
<xsl:param name="generate.index" select="0"/>
- <xsl:param name="generate.toc" select="'article nop'"></xsl:param>
- <xsl:param name="html.stylesheet" select="'style.css'" />
+ <xsl:param name="chapter.autolabel" select="1" />
+ <xsl:param name="appendix.autolabel" select="1" />
+ <xsl:param name="section.autolabel" select="1" />
+ <xsl:param name="section.label.includes.component.label" select="1" />
</xsl:stylesheet>
diff --git a/import-layers/yocto-poky/documentation/overview-manual/overview-manual-intro.xml b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-intro.xml
new file mode 100644
index 0000000..39433aa
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-intro.xml
@@ -0,0 +1,112 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='overview-manual-intro'>
+
+<title>The Yocto Project Overview and Concepts Manual</title>
+ <section id='overview-manual-welcome'>
+ <title>Welcome</title>
+
+ <para>
+ Welcome to the Yocto Project Overview and Concepts Manual!
+ This manual introduces the Yocto Project by providing concepts,
+ software overviews, best-known-methods (BKMs), and any other
+ high-level introductory information suitable for a new Yocto
+ Project user.
+ </para>
+
+ <para>
+ The following list describes what you can get from this manual:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><link linkend='overview-yp'>Introducing the Yocto Project</link>:</emphasis>
+ This chapter provides an introduction to the Yocto
+ Project.
+ You will learn about features and challenges of the
+ Yocto Project, the layer model, components and tools,
+ development methods, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
+ reference distribution, the OpenEmbedded build system
+ workflow, and some basic Yocto terms.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><link linkend='overview-development-environment'>The Yocto Project Development Environment</link>:</emphasis>
+ This chapter helps you get started understanding the
+ Yocto Project development environment.
+ You will learn about open source, development hosts,
+ Yocto Project source repositories, workflows using Git
+ and the Yocto Project, a Git primer, and information
+ about licensing.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><link linkend='overview-manual-concepts'>Yocto Project Concepts</link>:</emphasis>
+ This chapter presents various concepts regarding the
+ Yocto Project.
+ You can find conceptual information about components,
+ development, cross-toolchains, and so forth.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ This manual does not give you the following:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Step-by-step Instructions for Development Tasks:</emphasis>
+ Instructional procedures reside in other manuals within
+ the Yocto Project documentation set.
+ For example, the
+ <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>
+ provides examples on how to perform various development
+ tasks.
+ As another example, the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual contains detailed instructions on how to install an
+ SDK, which is used to develop applications for target
+ hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Reference Material:</emphasis>
+ This type of material resides in an appropriate reference
+ manual.
+ For example, system variables are documented in the
+ <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.
+ As another example, the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>
+ contains reference information on BSPs.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Detailed Public Information Not Specific to the
+ Yocto Project:</emphasis>
+ For example, exhaustive information on how to use the
+ Source Control Manager Git is better covered with Internet
+ searches and official Git Documentation than through the
+ Yocto Project documentation.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='overview-manual-other-information'>
+ <title>Other Information</title>
+
+ <para>
+ Because this manual presents information for many different
+ topics, supplemental information is recommended for full
+ comprehension.
+ For additional introductory information on the Yocto Project, see
+ the <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
+ If you want to build an image with no knowledge of Yocto Project
+ as a way of quickly testing it out, see the
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+ document.
+ For a comprehensive list of links and other documentation, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/qs-style.css b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-style.css
similarity index 98%
rename from import-layers/yocto-poky/documentation/yocto-project-qs/qs-style.css
rename to import-layers/yocto-poky/documentation/overview-manual/overview-manual-style.css
index 948f1be..97a364b 100644
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/qs-style.css
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-style.css
@@ -118,12 +118,13 @@
background-color: transparent;
background-repeat: no-repeat;
padding-top: 256px;
- background-position: top;
+ background-image: url("figures/overview-manual-title.png");
+ background-position: left top;
margin-top: -256px;
padding-right: 50px;
- margin-left: 50px;
- text-align: center;
- width: 600px;
+ margin-left: 0px;
+ text-align: right;
+ width: 740px;
}
h3.author {
@@ -729,7 +730,6 @@
border-color: black;
}
-
.writernotes {
color: red;
}
diff --git a/import-layers/yocto-poky/documentation/overview-manual/overview-manual-yp-intro.xml b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-yp-intro.xml
new file mode 100644
index 0000000..ccf5e27
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual-yp-intro.xml
@@ -0,0 +1,1357 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='overview-yp'>
+ <title>Introducing the Yocto Project</title>
+
+ <section id='what-is-the-yocto-project'>
+ <title>What is the Yocto Project?</title>
+
+ <para>
+ The Yocto Project is an open source collaboration project
+ that helps developers create custom Linux-based systems that are
+ designed for embedded products regardless of the product's hardware
+ architecture.
+ Yocto Project provides a flexible toolset and a development
+ environment that allows embedded device developers across the
+ world to collaborate through shared technologies, software stacks,
+ configurations, and best practices used to create these tailored
+ Linux images.
+ </para>
+
+ <para>
+ Thousands of developers worldwide have discovered that Yocto
+ Project provides advantages in both systems and applications
+ development, archival and management benefits, and customizations
+ used for speed, footprint, and memory utilization.
+ The project is a standard when it comes to delivering embedded
+ software stacks.
+ The project allows software customizations and build interchange
+ for multiple hardware platforms as well as software stacks that
+ can be maintained and scaled.
+ </para>
+
+ <para id='yp-key-dev-elements'>
+ <imagedata fileref="figures/key-dev-elements.png" format="PNG" align='center' width="8in"/>
+ </para>
+
+ <para>
+ For further introductory information on the Yocto Project, you
+ might be interested in this
+ <ulink url='https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project-'>article</ulink>
+ by Drew Moseley and in this short introductory
+ <ulink url='https://www.youtube.com/watch?v=utZpKM7i5Z4'>video</ulink>.
+ </para>
+
+ <para>
+ The remainder of this section overviews advantages and challenges
+ tied to the Yocto Project.
+ </para>
+
+ <section id='gs-features'>
+ <title>Features</title>
+
+ <para>
+ The following list describes features and advantages of the
+ Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Widely Adopted Across the Industry:</emphasis>
+ Semiconductor, operating system, software, and
+ service vendors exist whose products and services
+ adopt and support the Yocto Project.
+ For a look at the Yocto Project community and
+ the companies involved with the Yocto
+ Project, see the "COMMUNITY" and "ECOSYSTEM" tabs
+ on the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
+ home page.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Architecture Agnostic:</emphasis>
+ Yocto Project supports Intel, ARM, MIPS, AMD, PPC
+ and other architectures.
+ Most ODMs, OSVs, and chip vendors create and supply
+ BSPs that support their hardware.
+ If you have custom silicon, you can create a BSP
+ that supports that architecture.</para>
+
+ <para>Aside from lots of architecture support, the
+ Yocto Project fully supports a wide range of device
+ emulation through the Quick EMUlator (QEMU).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Images and Code Transfer Easily:</emphasis>
+ Yocto Project output can easily move between
+ architectures without moving to new development
+ environments.
+ Additionally, if you have used the Yocto Project to
+ create an image or application and you find yourself
+ not able to support it, commercial Linux vendors such
+ as Wind River, Mentor Graphics, Timesys, and ENEA could
+ take it and provide ongoing support.
+ These vendors have offerings that are built using
+ the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Flexibility:</emphasis>
+ Corporations use the Yocto Project many different ways.
+ One example is to create an internal Linux distribution
+ as a code base the corporation can use across multiple
+ product groups.
+ Through customization and layering, a project group
+ can leverage the base Linux distribution to create
+ a distribution that works for their product needs.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Ideal for Constrained Embedded and IoT devices:</emphasis>
+ Unlike a full Linux distribution, you can use the
+ Yocto Project to create exactly what you need for
+ embedded devices.
+ You only add the feature support or packages that you
+ absolutely need for the device.
+ For devices that have display hardware, you can use
+ available system components such as X11, GTK+, Qt,
+ Clutter, and SDL (among others) to create a rich user
+ experience.
+ For devices that do not have a display or where you
+ want to use alternative UI frameworks, you can choose
+ to not install these components.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Comprehensive Toolchain Capabilities:</emphasis>
+ Toolchains for supported architectures satisfy most
+ use cases.
+ However, if your hardware supports features that are
+ not part of a standard toolchain, you can easily
+ customize that toolchain through specification of
+ platform-specific tuning parameters.
+ And, should you need to use a third-party toolchain,
+ mechanisms built into the Yocto Project allow for that.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Mechanism Rules Over Policy:</emphasis>
+ Focusing on mechanism rather than policy ensures that
+ you are free to set policies based on the needs of your
+ design instead of adopting decisions enforced by some
+ system software provider.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Uses a Layer Model:</emphasis>
+ The Yocto Project
+ <link linkend='the-yocto-project-layer-model'>layer infrastructure</link>
+ groups related functionality into separate bundles.
+ You can incrementally add these grouped functionalities
+ to your project as needed.
+ Using layers to isolate and group functionality
+ reduces project complexity and redundancy, allows you
+ to easily extend the system, make customizations,
+ and keep functionality organized.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Supports Partial Builds:</emphasis>
+ You can build and rebuild individual packages as
+ needed.
+ Yocto Project accomplishes this through its
+ <link linkend='shared-state-cache'>shared-state cache</link>
+ (sstate) scheme.
+ Being able to build and debug components individually
+ eases project development.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Releases According to a Strict Schedule:</emphasis>
+ Major releases occur on a
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>six-month cycle</ulink>
+ predictably in October and April.
+ The most recent two releases support point releases
+ to address common vulnerabilities and exposures.
+ This predictability is crucial for projects based on
+ the Yocto Project and allows development teams to
+ plan activities.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Rich Ecosystem of Individuals and Organizations:</emphasis>
+ For open source projects, the value of community is
+ very important.
+ Support forums, expertise, and active developers who
+ continue to push the Yocto Project forward are readily
+ available.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Binary Reproducibility:</emphasis>
+ The Yocto Project allows you to be very specific about
+ dependencies and achieves very high percentages of
+ binary reproducibility (e.g. 99.8% for
+ <filename>core-image-minimal</filename>).
+ When distributions are not specific about which
+ packages are pulled in and in what order to support
+ dependencies, other build systems can arbitrarily
+ include packages.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>License Manifest:</emphasis>
+ The Yocto Project provides a
+ <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>license manifest</ulink>
+ for review by people who need to track the use of open
+ source licenses (e.g.legal teams).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-challenges'>
+ <title>Challenges</title>
+
+ <para>
+ The following list presents challenges you might encounter
+ when developing using the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Steep Learning Curve:</emphasis>
+ The Yocto Project has a steep learning curve and has
+ many different ways to accomplish similar tasks.
+ It can be difficult to choose how to proceed when
+ varying methods exist by which to accomplish a given
+ task.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Understanding What Changes You Need to Make
+ For Your Design Requires Some Research:</emphasis>
+ Beyond the simple tutorial stage, understanding what
+ changes need to be made for your particular design
+ can require a significant amount of research and
+ investigation.
+ For information that helps you transition from
+ trying out the Yocto Project to using it for your
+ project, see the
+ "<ulink url='&YOCTO_HOME_URL;/docs/what-i-wish-id-known/'>What I wish I'd Known</ulink>"
+ and
+ "<ulink url='&YOCTO_HOME_URL;/docs/transitioning-to-a-custom-environment/'>Transitioning to a Custom Environment for Systems Development</ulink>"
+ documents on the Yocto Project website.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Project Workflow Could Be Confusing:</emphasis>
+ The
+ <link linkend='overview-development-environment'>Yocto Project workflow</link>
+ could be confusing if you are used to traditional
+ desktop and server software development.
+ In a desktop development environment, mechanisms exist
+ to easily pull and install new packages, which are
+ typically pre-compiled binaries from servers accessible
+ over the Internet.
+ Using the Yocto Project, you must modify your
+ configuration and rebuild to add additional packages.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Working in a Cross-Build Environment Can
+ Feel Unfamiliar:</emphasis>
+ When developing code to run on a target, compilation,
+ execution, and testing done on the actual target
+ can be faster than running a BitBake build on a
+ development host and then deploying binaries to the
+ target for test.
+ While the Yocto Project does support development tools
+ on the target, the additional step of integrating your
+ changes back into the Yocto Project build environment
+ would be required.
+ Yocto Project supports an intermediate approach that
+ involves making changes on the development system
+ within the BitBake environment and then deploying only
+ the updated packages to the target.</para>
+
+ <para>The Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ produces packages in standard formats (i.e. RPM,
+ DEB, IPK, and TAR).
+ You can deploy these packages into the running system
+ on the target by using utilities on the target such
+ as <filename>rpm</filename> or
+ <filename>ipk</filename>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initial Build Times Can be Significant:</emphasis>
+ Long initial build times are unfortunately unavoidable
+ due to the large number of packages initially built
+ from scratch for a fully functioning Linux system.
+ Once that initial build is completed, however, the
+ shared-state (sstate) cache mechanism Yocto Project
+ uses keeps the system from rebuilding packages that
+ have not been "touched" since the last build.
+ The sstate mechanism significantly reduces times
+ for successive builds.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='the-yocto-project-layer-model'>
+ <title>The Yocto Project Layer Model</title>
+
+ <para>
+ The Yocto Project's "Layer Model" is a development model for
+ embedded and IoT Linux creation that distinguishes the
+ Yocto Project from other simple build systems.
+ The Layer Model simultaneously supports collaboration and
+ customization.
+ Layers are repositories that contain related sets of instructions
+ that tell the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ what to do.
+ You can collaborate, share, and reuse layers.
+ </para>
+
+ <para>
+ Layers can contain changes to previous instructions or settings
+ at any time.
+ This powerful override capability is what allows you to customize
+ previously supplied collaborative or community layers to suit your
+ product requirements.
+ </para>
+
+ <para>
+ You use different layers to logically separate information in your
+ build.
+ As an example, you could have BSP, GUI, distro configuration,
+ middleware, or application layers.
+ Putting your entire build into one layer limits and complicates
+ future customization and reuse.
+ Isolating information into layers, on the other hand, helps
+ simplify future customizations and reuse.
+ You might find it tempting to keep everything in one layer when
+ working on a single project.
+ However, the more modular your Metadata, the easier
+ it is to cope with future changes.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Use Board Support Package (BSP) layers from silicon
+ vendors when possible.
+ </para></listitem>
+ <listitem><para>
+ Familiarize yourself with the
+ <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink>
+ or the
+ <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>.
+ The latter contains more layers but they are less
+ universally validated.
+ </para></listitem>
+ <listitem><para>
+ Layers support the inclusion of technologies, hardware
+ components, and software components.
+ The
+ <ulink url='&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project'>Yocto Project Compatible</ulink>
+ designation provides a minimum level of standardization
+ that contributes to a strong ecosystem.
+ "YP Compatible" is applied to appropriate products and
+ software components such as BSPs, other OE-compatible
+ layers, and related open-source projects, allowing the
+ producer to use Yocto Project badges and branding
+ assets.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ To illustrate how layers are used to keep things modular, consider
+ machine customizations.
+ These types of customizations typically reside in a special layer,
+ rather than a general layer, called a BSP Layer.
+ Furthermore, the machine customizations should be isolated from
+ recipes and Metadata that support a new GUI environment,
+ for example.
+ This situation gives you a couple of layers: one for the machine
+ configurations, and one for the GUI environment.
+ It is important to understand, however, that the BSP layer can
+ still make machine-specific additions to recipes within the GUI
+ environment layer without polluting the GUI layer itself
+ with those machine-specific changes.
+ You can accomplish this through a recipe that is a BitBake append
+ (<filename>.bbappend</filename>) file, which is described later
+ in this section.
+ <note>
+ For general information on BSP layer structure, see the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>.
+ </note>
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ contains both general layers and BSP layers right out of the box.
+ You can easily identify layers that ship with a Yocto Project
+ release in the Source Directory by their names.
+ Layers typically have names that begin with the string
+ <filename>meta-</filename>.
+ <note>
+ It is not a requirement that a layer name begin with the
+ prefix <filename>meta-</filename>, but it is a commonly
+ accepted standard in the Yocto Project community.
+ </note>
+ For example, if you were to examine the
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink>
+ of the <filename>poky</filename> repository, you will see several
+ layers: <filename>meta</filename>,
+ <filename>meta-skeleton</filename>,
+ <filename>meta-selftest</filename>,
+ <filename>meta-poky</filename>, and
+ <filename>meta-yocto-bsp</filename>.
+ Each of these repositories represents a distinct layer.
+ </para>
+
+ <para>
+ For procedures on how to create layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+ </section>
+
+ <section id='components-and-tools'>
+ <title>Components and Tools</title>
+
+ <para>
+ The Yocto Project employs a collection of components and
+ tools used by the project itself, by project developers,
+ and by those using the Yocto Project.
+ These components and tools are open source projects and
+ metadata that are separate from the reference distribution
+ (<ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>)
+ and the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+ Most of the components and tools are downloaded separately.
+ </para>
+
+ <para>
+ This section provides brief overviews of the components and
+ tools associated with the Yocto Project.
+ </para>
+
+ <section id='gs-development-tools'>
+ <title>Development Tools</title>
+
+ <para>
+ The following list consists of tools that help you develop
+ images and applications using the Yocto Project:
+ <itemizedlist>
+ <listitem><para id='gs-crops-overview'>
+ <emphasis>CROPS:</emphasis>
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>
+ is an open source, cross-platform development framework
+ that leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
+ CROPS provides an easily managed, extensible environment
+ that allows you to build binaries for a variety of
+ architectures on Windows, Linux and Mac OS X hosts.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>devtool</filename>:</emphasis>
+ This command-line tool is available as part of the
+ extensible SDK (eSDK) and is its cornerstone.
+ You can use <filename>devtool</filename> to help build,
+ test, and package software within the eSDK.
+ You can use the tool to optionally integrate what you
+ build into an image built by the OpenEmbedded build
+ system.</para>
+
+ <para>The <filename>devtool</filename> command employs
+ a number of sub-commands that allow you to add, modify,
+ and upgrade recipes.
+ As with the OpenEmbedded build system, “recipes”
+ represent software packages within
+ <filename>devtool</filename>.
+ When you use <filename>devtool add</filename>, a recipe
+ is automatically created.
+ When you use <filename>devtool modify</filename>, the
+ specified existing recipe is used in order to determine
+ where to get the source code and how to patch it.
+ In both cases, an environment is set up so that when
+ you build the recipe a source tree that is under your
+ control is used in order to allow you to make changes
+ to the source as desired.
+ By default, both new recipes and the source go into
+ a “workspace” directory under the eSDK.
+ The <filename>devtool upgrade</filename> command
+ updates an existing recipe so that you can build it
+ for an updated set of source files.</para>
+
+ <para>You can read about the
+ <filename>devtool</filename> workflow in the Yocto
+ Project Application Development and Extensible
+ Software Development Kit (eSDK) Manual in the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow'</ulink>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
+ The eSDK provides a cross-development toolchain and
+ libraries tailored to the contents of a specific image.
+ The eSDK makes it easy to add new applications and
+ libraries to an image, modify the source for an
+ existing component, test changes on the target
+ hardware, and integrate into the rest of the
+ OpenEmbedded build system.
+ The eSDK gives you a toolchain experience supplemented
+ with the powerful set of <filename>devtool</filename>
+ commands tailored for the Yocto Project environment.
+ </para>
+
+ <para>For information on the eSDK, see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><trademark class='trade'>Eclipse</trademark> IDE Plug-in:</emphasis>
+ This plug-in enables you to use the popular Eclipse
+ Integrated Development Environment (IDE), which allows
+ for development using the Yocto Project all within the
+ Eclipse IDE.
+ You can work within Eclipse to cross-compile, deploy,
+ and execute your output into a QEMU emulation session
+ as well as onto actual target hardware.</para>
+
+ <para>The environment also supports performance
+ enhancing tools that allow you to perform remote
+ profiling, tracing, collection of power data,
+ collection of latency data, and collection of
+ performance data.</para>
+
+ <para>Once you enable the plug-in, standard Eclipse
+ functions automatically use the cross-toolchain
+ and target system libraries.
+ You can build applications using any of these
+ libraries.</para>
+
+ <para>For more information on the Eclipse plug-in,
+ see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working Within Eclipse</ulink>"
+ section in the Yocto Project Application Development
+ and the Extensible Software Development Kit (eSDK)
+ manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Toaster:</emphasis>
+ Toaster is a web interface to the Yocto Project
+ OpenEmbedded build system.
+ Toaster allows you to configure, run, and view
+ information about builds.
+ For information on Toaster, see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-production-tools'>
+ <title>Production Tools</title>
+
+ <para>
+ The following list consists of tools that help production
+ related activities using the Yocto Project:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Auto Upgrade Helper:</emphasis>
+ This utility when used in conjunction with the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ (BitBake and OE-Core) automatically generates upgrades
+ for recipes that are based on new versions of the
+ recipes published upstream.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Recipe Reporting System:</emphasis>
+ The Recipe Reporting System tracks recipe versions
+ available for Yocto Project.
+ The main purpose of the system is to help you
+ manage the recipes you maintain and to offer a dynamic
+ overview of the project.
+ The Recipe Reporting System is built on top of the
+ <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Layer Index</ulink>,
+ which is a website that indexes OpenEmbedded-Core
+ layers.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Patchwork:</emphasis>
+ <ulink url='http://jk.ozlabs.org/projects/patchwork/'>Patchwork</ulink>
+ is a fork of a project originally started by
+ <ulink url='http://ozlabs.org/'>OzLabs</ulink>.
+ The project is a web-based tracking system designed
+ to streamline the process of bringing contributions
+ into a project.
+ The Yocto Project uses Patchwork as an organizational
+ tool to handle patches, which number in the thousands
+ for every release.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>AutoBuilder:</emphasis>
+ AutoBuilder is a project that automates build tests
+ and quality assurance (QA).
+ By using the public AutoBuilder, anyone can determine
+ the status of the current "master" branch of Poky.
+ <note>
+ AutoBuilder is based on
+ <ulink url='https://buildbot.net/'>buildbot</ulink>.
+ </note></para>
+
+ <para>A goal of the Yocto Project is to lead the
+ open source industry with a project that automates
+ testing and QA procedures.
+ In doing so, the project encourages a development
+ community that publishes QA and test plans, publicly
+ demonstrates QA and test plans, and encourages
+ development of tools that automate and test and QA
+ procedures for the benefit of the development
+ community.</para>
+
+ <para>You can learn more about the AutoBuilder used
+ by the Yocto Project
+ <ulink url='&YOCTO_AB_URL;'>here</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cross-Prelink:</emphasis>
+ Prelinking is the process of pre-computing the load
+ addresses and link tables generated by the dynamic
+ linker as compared to doing this at runtime.
+ Doing this ahead of time results in performance
+ improvements when the application is launched and
+ reduced memory usage for libraries shared by many
+ applications.</para>
+
+ <para>Historically, cross-prelink is a variant of
+ prelink, which was conceived by
+ <ulink url='http://people.redhat.com/jakub/prelink.pdf'>Jakub Jelínek</ulink>
+ a number of years ago.
+ Both prelink and cross-prelink are maintained in the
+ same repository albeit on separate branches.
+ By providing an emulated runtime dynamic linker
+ (i.e. <filename>glibc</filename>-derived
+ <filename>ld.so</filename> emulation), the
+ cross-prelink project extends the prelink software’s
+ ability to prelink a sysroot environment.
+ Additionally, the cross-prelink software enables the
+ ability to work in sysroot style environments.</para>
+
+ <para>The dynamic linker determines standard load
+ address calculations based on a variety of factors
+ such as mapping addresses, library usage, and library
+ function conflicts.
+ The prelink tool uses this information, from the
+ dynamic linker, to determine unique load addresses
+ for executable and linkable format (ELF) binaries
+ that are shared libraries and dynamically linked.
+ The prelink tool modifies these ELF binaries with the
+ pre-computed information.
+ The result is faster loading and often lower memory
+ consumption because more of the library code can
+ be re-used from shared Copy-On-Write (COW) pages.
+ </para>
+
+ <para>The original upstream prelink project only
+ supports running prelink on the end target device
+ due to the reliance on the target device’s dynamic
+ linker.
+ This restriction causes issues when developing a
+ cross-compiled system.
+ The cross-prelink adds a synthesized dynamic loader
+ that runs on the host, thus permitting cross-prelinking
+ without ever having to run on a read-write target
+ filesystem.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Pseudo:</emphasis>
+ Pseudo is the Yocto Project implementation of
+ <ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>,
+ which is used to run commands in an environment
+ that seemingly has root privileges.</para>
+
+ <para>During a build, it can be necessary to perform
+ operations that require system administrator
+ privileges.
+ For example, file ownership or permissions might need
+ definition.
+ Pseudo is a tool that you can either use directly or
+ through the environment variable
+ <filename>LD_PRELOAD</filename>.
+ Either method allows these operations to succeed as
+ if system administrator privileges exist even
+ when they do not.</para>
+
+ <para>You can read more about Pseudo in the
+ "<link linkend='fakeroot-and-pseudo'>Fakeroot and Pseudo</link>"
+ section.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-openembedded-build-system'>
+ <title>Open-Embedded Build System Components</title>
+
+ <para>
+ The following list consists of components associated with the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>BitBake:</emphasis>
+ BitBake is a core component of the Yocto Project and is
+ used by the OpenEmbedded build system to build images.
+ While BitBake is key to the build system, BitBake
+ is maintained separately from the Yocto Project.</para>
+
+ <para>BitBake is a generic task execution engine that
+ allows shell and Python tasks to be run efficiently
+ and in parallel while working within complex inter-task
+ dependency constraints.
+ In short, BitBake is a build engine that works
+ through recipes written in a specific format in order
+ to perform sets of tasks.</para>
+
+ <para>You can learn more about BitBake in the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>OpenEmbedded-Core:</emphasis>
+ OpenEmbedded-Core (OE-Core) is a common layer of
+ metadata (i.e. recipes, classes, and associated files)
+ used by OpenEmbedded-derived systems, which includes
+ the Yocto Project.
+ The Yocto Project and the OpenEmbedded Project both
+ maintain the OpenEmbedded-Core.
+ You can find the OE-Core metadata in the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta'>Source Repositories</ulink>.
+ </para>
+
+ <para>Historically, the Yocto Project integrated the
+ OE-Core metadata throughout the Yocto Project
+ source repository reference system (Poky).
+ After Yocto Project Version 1.0, the Yocto Project
+ and OpenEmbedded agreed to work together and share a
+ common core set of metadata (OE-Core), which contained
+ much of the functionality previously found in Poky.
+ This collaboration achieved a long-standing
+ OpenEmbedded objective for having a more tightly
+ controlled and quality-assured core.
+ The results also fit well with the Yocto Project
+ objective of achieving a smaller number of fully
+ featured tools as compared to many different ones.
+ </para>
+
+ <para>Sharing a core set of metadata results in Poky
+ as an integration layer on top of OE-Core.
+ You can see that in this
+ <link linkend='yp-key-dev-elements'>figure</link>.
+ The Yocto Project combines various components such as
+ BitBake, OE-Core, script “glue”, and documentation
+ for its build system.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-reference-distribution-poky'>
+ <title>Reference Distribution (Poky)</title>
+
+ <para>
+ Poky is the Yocto Project reference distribution.
+ It contains the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>
+ (BitBake and OE-Core) as well as a set of metadata to get you
+ started building your own distribution.
+ See the
+ <link linkend='what-is-the-yocto-project'>figure</link> in
+ "What is the Yocto Project?" section for an illustration
+ that shows Poky and its relationship with other parts of the
+ Yocto Project.</para>
+
+ <para>To use the Yocto Project tools and components, you
+ can download (<filename>clone</filename>) Poky and use it
+ to bootstrap your own distribution.
+ <note>
+ Poky does not contain binary files.
+ It is a working example of how to build your own custom
+ Linux distribution from source.
+ </note>
+ You can read more about Poky in the
+ "<link linkend='reference-embedded-distribution'>Reference Embedded Distribution (Poky)</link>"
+ section.
+ </para>
+ </section>
+
+ <section id='gs-packages-for-finished-targets'>
+ <title>Packages for Finished Targets</title>
+
+ <para>
+ The following lists components associated with packages
+ for finished targets:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Matchbox:</emphasis>
+ Matchbox is an Open Source, base environment for the
+ X Window System running on non-desktop, embedded
+ platforms such as handhelds, set-top boxes, kiosks,
+ and anything else for which screen space, input
+ mechanisms, or system resources are limited.</para>
+
+ <para>Matchbox consists of a number of interchangeable
+ and optional applications that you can tailor to a
+ specific, non-desktop platform to enhance usability
+ in constrained environments.</para>
+
+ <para>You can find the Matchbox source in the Yocto
+ Project
+ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Opkg</emphasis>
+ Open PacKaGe management (opkg) is a lightweight
+ package management system based on the itsy package
+ (ipkg) management system.
+ Opkg is written in C and resembles Advanced Package
+ Tool (APT) and Debian Package (dpkg) in operation.
+ </para>
+
+ <para>Opkg is intended for use on embedded Linux
+ devices and is used in this capacity in the
+ <ulink url='http://www.openembedded.org/wiki/Main_Page'>OpenEmbedded</ulink>
+ and
+ <ulink url='https://openwrt.org/'>OpenWrt</ulink>
+ projects, as well as the Yocto Project.
+ <note>
+ As best it can, opkg maintains backwards
+ compatibility with ipkg and conforms to a subset
+ of Debian’s policy manual regarding control files.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='gs-archived-components'>
+ <title>Archived Components</title>
+
+ <para>
+ The Build Appliance is a virtual machine image that enables
+ you to build and boot a custom embedded Linux image with
+ the Yocto Project using a non-Linux development system.
+ </para>
+
+ <para>
+ Historically, the Build Appliance was the second of three
+ methods by which you could use the Yocto Project on a system
+ that was not native to Linux.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Hob:</emphasis>
+ Hob, which is now deprecated and is no longer available
+ since the 2.1 release of the Yocto Project provided
+ a rudimentary, GUI-based interface to the Yocto
+ Project.
+ Toaster has fully replaced Hob.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build Appliance:</emphasis>
+ Post Hob, the Build Appliance became available.
+ It was never recommended that you use the Build
+ Appliance as a day-to-day production development
+ environment with the Yocto Project.
+ Build Appliance was useful as a way to try out
+ development in the Yocto Project environment.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>CROPS:</emphasis>
+ The final and best solution available now for
+ developing using the Yocto Project on a system
+ not native to Linux is with
+ <link linkend='gs-crops-overview'>CROPS</link>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='gs-development-methods'>
+ <title>Development Methods</title>
+
+ <para>
+ The Yocto Project development environment usually involves a
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
+ and target hardware.
+ You use the Build Host to build images and develop applications,
+ while you use the target hardware to test deployed software.
+ </para>
+
+ <para>
+ This section provides an introduction to the choices or
+ development methods you have when setting up your Build Host.
+ Depending on the your particular workflow preference and the
+ type of operating system your Build Host runs, several choices
+ exist that allow you to use the Yocto Project.
+ <note>
+ For additional detail about the Yocto Project development
+ environment, see the
+ "<link linkend='overview-development-environment'>The Yocto Project Development Environment</link>"
+ chapter.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Native Linux Host:</emphasis>
+ By far the best option for a Build Host.
+ A system running Linux as its native operating system
+ allows you to develop software by directly using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ tool.
+ You can accomplish all aspects of development from a
+ familiar shell of a supported Linux distribution.</para>
+
+ <para>For information on how to set up a Build Host on
+ a system running Linux as its native operating system,
+ see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>CROss PlatformS (CROPS):</emphasis>
+ Typically, you use
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
+ which leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
+ to set up a Build Host that is not running Linux (e.g.
+ <trademark class='registered'>Microsoft</trademark>
+ <trademark class='trademark'>Windows</trademark>
+ or
+ <trademark class='registered'>macOS</trademark>).
+ <note>
+ You can, however, use CROPS on a Linux-based system.
+ </note>
+ CROPS is an open source, cross-platform development
+ framework that provides an easily managed, extensible
+ environment for building binaries targeted for a variety
+ of architectures on Windows, macOS, or Linux hosts.
+ Once the Build Host is set up using CROPS, you can prepare
+ a shell environment to mimic that of a shell being used
+ on a system natively running Linux.</para>
+
+ <para>For information on how to set up a Build Host with
+ CROPS, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Toaster:</emphasis>
+ Regardless of what your Build Host is running, you can
+ use Toaster to develop software using the Yocto Project.
+ Toaster is a web interface to the Yocto Project's
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>.
+ The interface enables you to configure and run your
+ builds.
+ Information about builds is collected and stored in a
+ database.
+ You can use Toaster to configure and start builds on
+ multiple remote build servers.</para>
+
+ <para>For information about and how to use Toaster,
+ see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><trademark class='trade'>Eclipse</trademark> IDE:</emphasis>
+ If your Build Host supports and runs the popular
+ Eclipse IDE, you can install the Yocto Project Eclipse
+ plug-in and use the Yocto Project to develop software.
+ The plug-in integrates the Yocto Project functionality
+ into Eclipse development practices.</para>
+
+ <para>For information about how to install and use the
+ Yocto Project Eclipse plug-in, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using Eclipse</ulink>"
+ chapter in the Yocto Project Application Development and
+ the Extensible Software Development Kit (eSDK) Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='reference-embedded-distribution'>
+ <title>Reference Embedded Distribution (Poky)</title>
+
+ <para>
+ "Poky", which is pronounced <emphasis>Pock</emphasis>-ee, is the
+ name of the Yocto Project's reference distribution or Reference OS
+ Kit.
+ Poky contains the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink>
+ (<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> and
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>)
+ as well as a set of
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>metadata</ulink> to get
+ you started building your own distro.
+ In other words, Poky is a base specification of the functionality
+ needed for a typical embedded system as well as the components
+ from the Yocto Project that allow you to build a distribution into
+ a usable binary image.
+ </para>
+
+ <para>
+ Poky is a combined repository of BitBake, OpenEmbedded-Core
+ (which is found in <filename>meta</filename>),
+ <filename>meta-poky</filename>,
+ <filename>meta-yocto-bsp</filename>, and documentation provided
+ all together and known to work well together.
+ You can view these items that make up the Poky repository in the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/'>Source Repositories</ulink>.
+ <note>
+ If you are interested in all the contents of the
+ <filename>poky</filename> Git repository, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core'>Top-Level Core Components</ulink>"
+ section in the Yocto Project Reference Manual.
+ </note>
+ </para>
+
+ <para id='gs-poky-reference-distribution'>
+ The following figure illustrates what generally comprises Poky:
+ <imagedata fileref="figures/poky-reference-distribution.png" format="PNG" align='center' width="8in"/>
+ <itemizedlist>
+ <listitem><para>
+ BitBake is a task executor and scheduler that is the heart of
+ the OpenEmbedded build system.
+ </para></listitem>
+ <listitem><para>
+ <filename>meta-poky</filename>, which is Poky-specific
+ metadata.
+ </para></listitem>
+ <listitem><para>
+ <filename>meta-yocto-bsp</filename>, which are Yocto
+ Project-specific Board Support Packages (BSPs).
+ </para></listitem>
+ <listitem><para>
+ OpenEmbedded-Core (OE-Core) metadata, which includes
+ shared configurations, global variable definitions,
+ shared classes, packaging, and recipes.
+ Classes define the encapsulation and inheritance of build
+ logic.
+ Recipes are the logical units of software and images
+ to be built.
+ </para></listitem>
+ <listitem><para>
+ Documentation, which contains the Yocto Project source
+ files used to make the set of user manuals.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ While Poky is a "complete" distribution specification and is
+ tested and put through QA, you cannot use it as a product
+ "out of the box" in its current form.
+ </note>
+ </para>
+
+ <para>
+ To use the Yocto Project tools, you can use Git to clone (download)
+ the Poky repository then use your local copy of the reference
+ distribution to bootstrap your own distribution.
+ <note>
+ Poky does not contain binary files.
+ It is a working example of how to build your own custom Linux distribution
+ from source.
+ </note>
+ </para>
+
+ <para>
+ Poky has a regular, well established, six-month release cycle
+ under its own version.
+ Major releases occur at the same time major releases (point
+ releases) occur for the Yocto Project, which are typically in the
+ Spring and Fall.
+ For more information on the Yocto Project release schedule and
+ cadence, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>Yocto Project Releases and the Stable Release Process</ulink>"
+ chapter in the Yocto Project Reference Manual.
+ </para>
+
+ <para>
+ Much has been said about Poky being a "default configuration."
+ A default configuration provides a starting image footprint.
+ You can use Poky out of the box to create an image ranging from a
+ shell-accessible minimal image all the way up to a Linux
+ Standard Base-compliant image that uses a GNOME Mobile and
+ Embedded (GMAE) based reference user interface called Sato.
+ </para>
+
+ <para>
+ One of the most powerful properties of Poky is that every aspect
+ of a build is controlled by the metadata.
+ You can use metadata to augment these base image types by
+ adding metadata
+ <link linkend='the-yocto-project-layer-model'>layers</link>
+ that extend functionality.
+ These layers can provide, for example, an additional software
+ stack for an image type, add a board support package (BSP) for
+ additional hardware, or even create a new image type.
+ </para>
+
+ <para>
+ Metadata is loosely grouped into configuration files or package
+ recipes.
+ A recipe is a collection of non-executable metadata used by
+ BitBake to set variables or define additional build-time tasks.
+ A recipe contains fields such as the recipe description, the recipe
+ version, the license of the package and the upstream source
+ repository.
+ A recipe might also indicate that the build process uses autotools,
+ make, distutils or any other build process, in which case the basic
+ functionality can be defined by the classes it inherits from
+ the OE-Core layer's class definitions in
+ <filename>./meta/classes</filename>.
+ Within a recipe you can also define additional tasks as well as
+ task prerequisites.
+ Recipe syntax through BitBake also supports both
+ <filename>_prepend</filename> and <filename>_append</filename>
+ operators as a method of extending task functionality.
+ These operators inject code into the beginning or end of a task.
+ For information on these BitBake operators, see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending-override-style-syntax'>Appending and Prepending (Override Style Syntax)</ulink>"
+ section in the BitBake User's Manual.
+ </para>
+ </section>
+
+ <section id='openembedded-build-system-workflow'>
+ <title>The OpenEmbedded Build System Workflow</title>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ uses a "workflow" to accomplish image and SDK generation.
+ The following figure overviews that workflow:
+ <imagedata fileref="figures/YP-flow-diagram.png"
+ format="PNG" align='center' width="8in"/>
+ Following is a brief summary of the "workflow":
+ <orderedlist>
+ <listitem><para>
+ Developers specify architecture, policies, patches and
+ configuration details.
+ </para></listitem>
+ <listitem><para>
+ The build system fetches and downloads the source code
+ from the specified location.
+ The build system supports standard methods such as tarballs
+ or source code repositories systems such as Git.
+ </para></listitem>
+ <listitem><para>
+ Once source code is downloaded, the build system extracts
+ the sources into a local work area where patches are
+ applied and common steps for configuring and compiling
+ the software are run.
+ </para></listitem>
+ <listitem><para>
+ The build system then installs the software into a
+ temporary staging area where the binary package format you
+ select (DEB, RPM, or IPK) is used to roll up the software.
+ </para></listitem>
+ <listitem><para>
+ Different QA and sanity checks run throughout entire
+ build process.
+ </para></listitem>
+ <listitem><para>
+ After the binaries are created, the build system
+ generates a binary package feed that is used to create
+ the final root file image.
+ </para></listitem>
+ <listitem><para>
+ The build system generates the file system image and a
+ customized Extensible SDK (eSDSK) for application
+ development in parallel.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ For a very detailed look at this workflow, see the
+ "<link linkend='openembedded-build-system-build-concepts'>OpenEmbedded Build System Concepts</link>"
+ section.
+ </para>
+ </section>
+
+
+ <section id='some-basic-terms'>
+ <title>Some Basic Terms</title>
+
+ <para>
+ It helps to understand some basic fundamental terms when
+ learning the Yocto Project.
+ Although a list of terms exists in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-terms'>Yocto Project Terms</ulink>"
+ section of the Yocto Project Reference Manual, this section
+ provides the definitions of some terms helpful for getting started:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Configuration Files:</emphasis>
+ Files that hold global definitions of variables,
+ user-defined variables, and hardware configuration
+ information.
+ These files tell the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>
+ what to build and what to put into the image to support a
+ particular platform.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
+ A custom SDK for application developers.
+ This eSDK allows developers to incorporate their library
+ and programming changes back into the image to make
+ their code available to other application developers.
+ For information on the eSDK, see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Layer:</emphasis>
+ A collection of related recipes.
+ Layers allow you to consolidate related metadata to
+ customize your build.
+ Layers also isolate information used when building
+ for multiple architectures.
+ Layers are hierarchical in their ability to override
+ previous specifications.
+ You can include any number of available layers from the
+ Yocto Project and customize the build by adding your
+ layers after them.
+ You can search the Layer Index for layers used within
+ Yocto Project.</para>
+
+ <para>For more detailed information on layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ For a discussion specifically on BSP Layers, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+ section in the Yocto Project Board Support Packages (BSP)
+ Developer's Guide.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Metadata:</emphasis>
+ A key element of the Yocto Project is the Metadata that
+ is used to construct a Linux distribution and is contained
+ in the files that the OpenEmbedded build system parses
+ when building an image.
+ In general, Metadata includes recipes, configuration
+ files, and other information that refers to the build
+ instructions themselves, as well as the data used to
+ control what things get built and the effects of the
+ build.
+ Metadata also includes commands and data used to
+ indicate what versions of software are used, from
+ where they are obtained, and changes or additions to the
+ software itself (patches or auxiliary files) that
+ are used to fix bugs or customize the software for use
+ in a particular situation.
+ OpenEmbedded-Core is an important set of validated
+ metadata.
+ </para></listitem>
+ <listitem><para id='gs-term-openembedded-build-system'>
+ <emphasis>OpenEmbedded Build System:</emphasis>
+ The terms "BitBake" and "build system" are sometimes
+ used for the OpenEmbedded Build System.</para>
+
+ <para>BitBake is a task scheduler and execution engine
+ that parses instructions (i.e. recipes) and configuration
+ data.
+ After a parsing phase, BitBake creates a dependency tree
+ to order the compilation, schedules the compilation of
+ the included code, and finally executes the building
+ of the specified custom Linux image (distribution).
+ BitBake is similar to the <filename>make</filename>
+ tool.</para>
+
+ <para>During a build process, the build system tracks
+ dependencies and performs a native or cross-compilation
+ of the package.
+ As a first step in a cross-build setup, the framework
+ attempts to create a cross-compiler toolchain
+ (i.e. Extensible SDK) suited for the target platform.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>OpenEmbedded-Core (OE-Core):</emphasis>
+ OE-Core is metadata comprised of foundation recipes,
+ classes, and associated files that are meant to be
+ common among many different OpenEmbedded-derived systems,
+ including the Yocto Project.
+ OE-Core is a curated subset of an original repository
+ developed by the OpenEmbedded community that has been
+ pared down into a smaller, core set of continuously
+ validated recipes.
+ The result is a tightly controlled and quality-assured
+ core set of recipes.</para>
+
+ <para>You can see the Metadata in the
+ <filename>meta</filename> directory of the Yocto Project
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Packages:</emphasis>
+ In the context of the Yocto Project, this term refers to a
+ recipe's packaged output produced by BitBake (i.e. a
+ "baked recipe").
+ A package is generally the compiled binaries produced from the
+ recipe's sources.
+ You "bake" something by running it through BitBake.</para>
+
+ <para>It is worth noting that the term "package" can,
+ in general, have subtle meanings.
+ For example, the packages referred to in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
+ section in the Yocto Project Reference Manual are compiled
+ binaries that, when installed, add functionality to your
+ Linux distribution.</para>
+
+ <para>Another point worth noting is that historically within
+ the Yocto Project, recipes were referred to as packages - thus,
+ the existence of several BitBake variables that are seemingly
+ mis-named,
+ (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Poky:</emphasis>
+ Poky is a reference embedded distribution and a reference
+ test configuration.
+ Poky provides the following:
+ <itemizedlist>
+ <listitem><para>
+ A base-level functional distro used to illustrate
+ how to customize a distribution.
+ </para></listitem>
+ <listitem><para>
+ A means by which to test the Yocto Project
+ components (i.e. Poky is used to validate
+ the Yocto Project).
+ </para></listitem>
+ <listitem><para>
+ A vehicle through which you can download
+ the Yocto Project.
+ </para></listitem>
+ </itemizedlist>
+ Poky is not a product level distro.
+ Rather, it is a good starting point for customization.
+ <note>
+ Poky is an integration layer on top of OE-Core.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Recipe:</emphasis>
+ The most common form of metadata.
+ A recipe contains a list of settings and tasks
+ (i.e. instructions) for building packages that are then
+ used to build the binary image.
+ A recipe describes where you get source code and which
+ patches to apply.
+ Recipes describe dependencies for libraries or for other
+ recipes as well as configuration and compilation options.
+ Related recipes are consolidated into a layer.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/overview-manual/overview-manual.xml b/import-layers/yocto-poky/documentation/overview-manual/overview-manual.xml
new file mode 100644
index 0000000..c283f9a
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/overview-manual/overview-manual.xml
@@ -0,0 +1,108 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='overview-manual' lang='en'
+ xmlns:xi="http://www.w3.org/2003/XInclude"
+ xmlns="http://docbook.org/ns/docbook"
+ >
+ <bookinfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref='figures/overview-manual-title.png'
+ format='SVG'
+ align='left' scalefit='1' width='100%'/>
+ </imageobject>
+ </mediaobject>
+
+ <title>
+ Yocto Project Overview and Concepts Manual
+ </title>
+
+ <authorgroup>
+ <author>
+ <firstname>Scott</firstname> <surname>Rifenbark</surname>
+ <affiliation>
+ <orgname>Scotty's Documentation Services, INC</orgname>
+ </affiliation>
+ <email>srifenbark@gmail.com</email>
+ </author>
+ </authorgroup>
+
+ <revhistory>
+ <revision>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>The initial document released with the Yocto Project 2.5 Release.</revremark>
+ </revision>
+ </revhistory>
+
+ <copyright>
+ <year>©RIGHT_YEAR;</year>
+ <holder>Linux Foundation</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
+ Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by
+ Creative Commons.
+ </para>
+ <note><title>Manual Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ This version of the
+ <emphasis>Yocto Project Overview and Concepts Manual</emphasis>
+ is for the &YOCTO_DOC_VERSION; release of the
+ Yocto Project.
+ To be sure you have the latest version of the manual
+ for this release, go to the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
+ </para></listitem>
+ <listitem><para>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </legalnotice>
+
+ </bookinfo>
+
+ <xi:include href="overview-manual-intro.xml"/>
+
+ <xi:include href="overview-manual-yp-intro.xml"/>
+
+ <xi:include href="overview-manual-development-environment.xml"/>
+
+ <xi:include href="overview-manual-concepts.xml" />
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/poky.ent b/import-layers/yocto-poky/documentation/poky.ent
index db3eef0..49b1900 100644
--- a/import-layers/yocto-poky/documentation/poky.ent
+++ b/import-layers/yocto-poky/documentation/poky.ent
@@ -1,13 +1,17 @@
-<!ENTITY DISTRO "2.4.2">
-<!ENTITY DISTRO_COMPRESSED "242">
-<!ENTITY DISTRO_NAME_NO_CAP "rocko">
-<!ENTITY DISTRO_NAME "Rocko">
-<!ENTITY YOCTO_DOC_VERSION "2.4.2">
-<!ENTITY DISTRO_REL_TAG "yocto-2.4.2">
-<!ENTITY METAINTELVERSION "8.0">
+<!ENTITY DISTRO "2.5">
+<!ENTITY DISTRO_COMPRESSED "25">
+<!ENTITY DISTRO_NAME_NO_CAP "sumo">
+<!ENTITY DISTRO_NAME "Sumo">
+<!ENTITY DISTRO_NAME_NO_CAP_MINUS_ONE "rocko">
+<!ENTITY DISTRO_NAME_MINUS_ONE "Rocko">
+<!ENTITY YOCTO_DOC_VERSION "2.5">
+<!ENTITY YOCTO_DOC_VERSION_MINUS_ONE "2.4">
+<!ENTITY DISTRO_REL_TAG "yocto-2.5">
+<!ENTITY METAINTELVERSION "9.0">
+<!ENTITY REL_MONTH_YEAR "May 2018">
<!ENTITY META_INTEL_REL_TAG "&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;">
-<!ENTITY POKYVERSION "19.0.2">
-<!ENTITY POKYVERSION_COMPRESSED "1902">
+<!ENTITY POKYVERSION "20.0.0">
+<!ENTITY POKYVERSION_COMPRESSED "2000">
<!ENTITY YOCTO_POKY "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;">
<!ENTITY COPYRIGHT_YEAR "2010-2018">
<!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org">
@@ -18,7 +22,6 @@
<!ENTITY YOCTO_AB_URL "http://autobuilder.yoctoproject.org">
<!ENTITY YOCTO_GIT_URL "http://git.yoctoproject.org">
<!ENTITY YOCTO_ADTREPO_URL "http://adtrepo.yoctoproject.org">
-<!ENTITY YOCTO_RELEASE_NOTES "&YOCTO_HOME_URL;/downloads/core/&DISTRO_NAME_NO_CAP;&DISTRO_COMPRESSED;">
<!ENTITY OE_HOME_URL "http://www.openembedded.org">
<!ENTITY OE_LISTS_URL "http://lists.openembedded.org/mailman">
<!ENTITY OE_DOCS_URL "http://docs.openembedded.org">
@@ -35,8 +38,8 @@
<!ENTITY ECLIPSE_INDIGO_CDT_URL "&ECLIPSE_DL_URL;/tools/cdt/releases/indigo">
<!ENTITY YOCTO_DOCS_URL "&YOCTO_HOME_URL;/docs">
<!ENTITY YOCTO_SOURCES_URL "&YOCTO_HOME_URL;/sources/">
-<!ENTITY YOCTO_AB_PORT_URL "&YOCTO_AB_URL;:8010">
-<!ENTITY YOCTO_AB_NIGHTLY_URL "&YOCTO_AB_URL;/pub/nightly/">
+<!ENTITY YOCTO_AB_PORT_URL "https://autobuilder.yocto.io/">
+<!ENTITY YOCTO_AB_NIGHTLY_URL "&YOCTO_AB_PORT_URL;/pub/nightly/">
<!ENTITY YOCTO_POKY_URL "&YOCTO_DL_URL;/releases/poky/">
<!ENTITY YOCTO_RELEASE_DL_URL "&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;">
<!ENTITY YOCTO_TOOLCHAIN_DL_URL "&YOCTO_RELEASE_DL_URL;/toolchain/">
@@ -52,13 +55,14 @@
<!ENTITY YOCTO_DOCS_REF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/ref-manual/ref-manual.html">
<!ENTITY YOCTO_DOCS_BSP_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/bsp-guide/bsp-guide.html">
<!ENTITY YOCTO_DOCS_DEV_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/dev-manual/dev-manual.html">
-<!ENTITY YOCTO_DOCS_KERNEL_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-manual/kernel-manual.html">
<!ENTITY YOCTO_DOCS_KERNEL_DEV_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-dev/kernel-dev.html">
<!ENTITY YOCTO_DOCS_PROF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/profile-manual/profile-manual.html">
<!ENTITY YOCTO_DOCS_MM_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/mega-manual/mega-manual.html">
<!ENTITY YOCTO_DOCS_BB_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/bitbake-user-manual/bitbake-user-manual.html">
<!ENTITY YOCTO_DOCS_TOAST_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/toaster-manual/toaster-manual.html">
<!ENTITY YOCTO_DOCS_SDK_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/sdk-manual/sdk-manual.html">
+<!ENTITY YOCTO_DOCS_OM_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/overview-manual/overview-manual.html">
+<!ENTITY YOCTO_DOCS_BRIEF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/brief-yoctoprojectqs/brief-yoctoprojectqs.html">
<!ENTITY YOCTO_ADTPATH_DIR "/opt/poky/&DISTRO;">
<!ENTITY YOCTO_POKY_TARBALL "&YOCTO_POKY;.tar.bz2">
<!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env">
diff --git a/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml b/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml
index f742e88..b64875b 100644
--- a/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml
+++ b/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml
@@ -87,14 +87,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -118,24 +113,36 @@
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
</legalnotice>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/faq.xml b/import-layers/yocto-poky/documentation/ref-manual/faq.xml
index 11dfc5b..49ff862 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/faq.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/faq.xml
@@ -143,7 +143,7 @@
To add a package, you need to create a BitBake recipe.
For information on how to create a BitBake recipe, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
- in the Yocto Project Development Tasks Manual.
+ section in the Yocto Project Development Tasks Manual.
</para>
</answer>
</qandaentry>
@@ -417,10 +417,11 @@
<para>
You can find more information on licensing in the
- "<link linkend='licensing'>Licensing</link>" section and in the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
+ section in the Yocto Project Overview and Concepts Manual
+ and also in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
- section, which is in the Yocto Project Development Tasks
- Manual.
+ section in the Yocto Project Development Tasks Manual.
</para>
</answer>
</qandaentry>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/analysis-for-package-splitting.png b/import-layers/yocto-poky/documentation/ref-manual/figures/analysis-for-package-splitting.png
deleted file mode 100644
index 04f2794..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/analysis-for-package-splitting.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/building-an-image.png b/import-layers/yocto-poky/documentation/ref-manual/figures/building-an-image.png
deleted file mode 100755
index 1fbea5a..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/building-an-image.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/configuration-compile-autoreconf.png b/import-layers/yocto-poky/documentation/ref-manual/figures/configuration-compile-autoreconf.png
deleted file mode 100644
index a07464f..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/configuration-compile-autoreconf.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/cross-development-toolchains.png b/import-layers/yocto-poky/documentation/ref-manual/figures/cross-development-toolchains.png
deleted file mode 100644
index d36670a..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/cross-development-toolchains.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/image-generation.png b/import-layers/yocto-poky/documentation/ref-manual/figures/image-generation.png
deleted file mode 100644
index 71a48dc..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/image-generation.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/images.png b/import-layers/yocto-poky/documentation/ref-manual/figures/images.png
deleted file mode 100644
index d99eac1..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/images.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/layer-input.png b/import-layers/yocto-poky/documentation/ref-manual/figures/layer-input.png
deleted file mode 100644
index 0a4f2e7..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/layer-input.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/package-feeds.png b/import-layers/yocto-poky/documentation/ref-manual/figures/package-feeds.png
deleted file mode 100644
index 37c9c32..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/package-feeds.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/patching.png b/import-layers/yocto-poky/documentation/ref-manual/figures/patching.png
deleted file mode 100644
index 8ecd018..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/patching.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/sdk-generation.png b/import-layers/yocto-poky/documentation/ref-manual/figures/sdk-generation.png
deleted file mode 100755
index adbe1f4..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/sdk-generation.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/sdk.png b/import-layers/yocto-poky/documentation/ref-manual/figures/sdk.png
deleted file mode 100644
index 5c36b75..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/sdk.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/source-fetching.png b/import-layers/yocto-poky/documentation/ref-manual/figures/source-fetching.png
deleted file mode 100644
index 26aefb5..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/source-fetching.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/source-input.png b/import-layers/yocto-poky/documentation/ref-manual/figures/source-input.png
deleted file mode 100644
index f751505..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/source-input.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/source-repos.png b/import-layers/yocto-poky/documentation/ref-manual/figures/source-repos.png
deleted file mode 100644
index e9cff16..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/source-repos.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/user-configuration.png b/import-layers/yocto-poky/documentation/ref-manual/figures/user-configuration.png
deleted file mode 100755
index c298401..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/user-configuration.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/yocto-environment-ref.png b/import-layers/yocto-poky/documentation/ref-manual/figures/yocto-environment-ref.png
deleted file mode 100644
index 650c6c8..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/yocto-environment-ref.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/yp-download.png b/import-layers/yocto-poky/documentation/ref-manual/figures/yp-download.png
deleted file mode 100644
index 5770be6..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/figures/yp-download.png
+++ /dev/null
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml
deleted file mode 100644
index 29ef2d5..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml
+++ /dev/null
@@ -1,1084 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='ref-manual-intro'>
-<title>Introduction</title>
-
-<section id='ref-welcome'>
- <title>Welcome</title>
-
- <para>
- Welcome to the Yocto Project Reference Manual.
- This manual provides reference information for the current release
- of the Yocto Project.
- This manual is best used after you have an understanding
- of the basics of the Yocto Project.
- The manual is neither meant to be read as a starting point to the
- Yocto Project nor read from start to finish.
- Use this manual to find concepts, variable definitions, class
- descriptions, and so forth as needed during the course of using
- the Yocto Project.
- </para>
-
- <para>
- For introductory information on the Yocto Project, see the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the
- "<link linkend='yp-intro'>Introducing the Yocto Project Development Environment</link>"
- section.
- </para>
-
- <para>
- If you want to use the Yocto Project to test run building an image
- without having to understand concepts, work through the
- <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
- You can find "how-to" information in the
- <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>.
- <note><title>Tip</title>
- For more information about the Yocto Project Documentation set,
- see the
- "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
- section.
- </note>
- </para>
-</section>
-
-<section id='yp-intro'>
- <title>Introducing the Yocto Project Development Environment</title>
-
- <para>
- The Yocto Project is an open-source collaboration project whose
- focus is for developers of embedded Linux systems.
- Among other things, the Yocto Project uses an
- <link linkend='build-system-term'>OpenEmbedded build system</link>.
- The build system, which is based on the OpenEmbedded (OE) project and
- uses the
- <link linkend='bitbake-term'>BitBake</link> tool, constructs complete
- Linux images for architectures based on ARM, MIPS, PowerPC, x86 and
- x86-64.
- <note>
- Historically, the OpenEmbedded build system, which is the
- combination of BitBake and OE components, formed a reference
- build host that was known as
- "<link linkend='poky'>Poky</link>" (<emphasis>Pah</emphasis>-kee).
- The term "Poky", as used throughout the Yocto Project Documentation
- set, can have different meanings.
- </note>
- The Yocto Project provides various ancillary tools for the embedded
- developer and also features the Sato reference User Interface, which
- is optimized for stylus-driven, low-resolution screens.
- </para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/YP-flow-diagram.png"
- format="PNG" align='center' width="8in"/>
- </imageobject>
- </mediaobject>
-
- <para>
- Here are some highlights for the Yocto Project:
- </para>
-
- <itemizedlist>
- <listitem><para>
- Provides a recent Linux kernel along with a set of system
- commands and libraries suitable for the embedded
- environment.
- </para></listitem>
- <listitem><para>
- Makes available system components such as X11, GTK+, Qt,
- Clutter, and SDL (among others) so you can create a rich user
- experience on devices that have display hardware.
- For devices that do not have a display or where you wish to
- use alternative UI frameworks, these components need not be
- installed.
- </para></listitem>
- <listitem><para>
- Creates a focused and stable core compatible with the
- OpenEmbedded project with which you can easily and reliably
- build and develop.
- </para></listitem>
- <listitem><para>
- Fully supports a wide range of hardware and device emulation
- through the Quick EMUlator (QEMU).
- </para></listitem>
- <listitem><para>
- Provides a layer mechanism that allows you to easily extend
- the system, make customizations, and keep them organized.
- </para></listitem>
- </itemizedlist>
-
- <para>
- You can use the Yocto Project to generate images for many kinds
- of devices.
- As mentioned earlier, the Yocto Project supports creation of
- reference images that you can boot within and emulate using QEMU.
- The standard example machines target QEMU full-system
- emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and
- PowerPC architectures.
- Beyond emulation, you can use the layer mechanism to extend
- support to just about any platform that Linux can run on and that
- a toolchain can target.
- </para>
-
- <para>
- Another Yocto Project feature is the Sato reference User
- Interface.
- This optional UI that is based on GTK+ is intended for devices with
- restricted screen sizes and is included as part of the
- OpenEmbedded Core layer so that developers can test parts of the
- software stack.
- </para>
-
- <para>
- While the Yocto Project does not provide a strict testing framework,
- it does provide or generate for you artifacts that let you perform
- target-level and emulated testing and debugging.
- Additionally, if you are an
- <trademark class='trade'>Eclipse</trademark> IDE user, you can
- install an Eclipse Yocto Plug-in to allow you to develop within that
- familiar environment.
- </para>
-
- <para>
- By default, using the Yocto Project to build an image creates a Poky
- distribution.
- However, you can create your own distribution by providing key
- <link link='metadata'>Metadata</link>.
- A good example is Angstrom, which has had a distribution
- based on the Yocto Project since its inception.
- Other examples include commercial distributions like
- <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
- <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
- <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
- and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
- See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>"
- section in the Yocto Project Development Tasks Manual for more
- information.
- </para>
-</section>
-
-<section id='intro-requirements'>
-<title>System Requirements</title>
- <para>
- For general Yocto Project system requirements, see the
- "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section
- in the Yocto Project Quick Start.
- The remainder of this section provides details on system requirements
- not covered in the Yocto Project Quick Start.
- </para>
-
- <section id='detailed-supported-distros'>
- <title>Supported Linux Distributions</title>
-
- <para>
- Currently, the Yocto Project is supported on the following
- distributions:
- <note>
- <para>
- Yocto Project releases are tested against the stable Linux
- distributions in the following list.
- The Yocto Project should work on other distributions but
- validation is not performed against them.
- </para>
-
- <para>
- In particular, the Yocto Project does not support
- and currently has no plans to support
- rolling-releases or development distributions due to their
- constantly changing nature.
- We welcome patches and bug reports, but keep in mind that
- our priority is on the supported platforms listed below.
- </para>
-
- <para>
- If you encounter problems, please go to
- <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
- and submit a bug.
- We are interested in hearing about your experience.
- </para>
- </note>
- <itemizedlist>
-<!--
- <listitem><para>Ubuntu 10.04</para></listitem>
- <listitem><para>Ubuntu 11.10</para></listitem>
- <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
- <listitem><para>Ubuntu 13.10</para></listitem>
- <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> -->
- <listitem><para>Ubuntu 14.10</para></listitem>
- <listitem><para>Ubuntu 15.04</para></listitem>
- <listitem><para>Ubuntu 15.10</para></listitem>
- <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
-<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
- <listitem><para>Fedora 17 (Spherical)</para></listitem>
- <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
- <listitem><para>Fedora release 20 (Heisenbug)</para></listitem> -->
- <listitem><para>Fedora release 22</para></listitem>
- <listitem><para>Fedora release 23</para></listitem>
- <listitem><para>Fedora release 24</para></listitem>
-<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>
- <listitem><para>CentOS release 5.7 (Final)</para></listitem>
- <listitem><para>CentOS release 5.8 (Final)</para></listitem>
- <listitem><para>CentOS release 6.3 (Final)</para></listitem>
- <listitem><para>CentOS release 6.x</para></listitem> -->
- <listitem><para>CentOS release 7.x</para></listitem>
-<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>
- <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> -->
- <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
- <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
-<!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
- <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
- <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
- <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
- <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>
- <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem> -->
-<!-- <listitem><para>openSUSE 11.4</para></listitem>
- <listitem><para>openSUSE 12.1</para></listitem>
- <listitem><para>openSUSE 12.2</para></listitem>
- <listitem><para>openSUSE 12.3</para></listitem>
- <listitem><para>openSUSE 13.1</para></listitem> -->
- <listitem><para>openSUSE 13.2</para></listitem>
- <listitem><para>openSUSE 42.1</para></listitem>
- </itemizedlist>
- </para>
-
- <note>
- While the Yocto Project Team attempts to ensure all Yocto Project
- releases are one hundred percent compatible with each officially
- supported Linux distribution, instances might exist where you
- encounter a problem while using the Yocto Project on a specific
- distribution.
- </note>
- </section>
-
- <section id='required-packages-for-the-host-development-system'>
- <title>Required Packages for the Host Development System</title>
-
- <para>
- The list of packages you need on the host development system can
- be large when covering all build scenarios using the Yocto Project.
- This section provides required packages according to
- Linux distribution and function.
- </para>
-
- <section id='ubuntu-packages'>
- <title>Ubuntu and Debian</title>
-
- <para>
- The following list shows the required packages by function
- given a supported Ubuntu or Debian Linux distribution:
- <note>
- If your build system has the
- <filename>oss4-dev</filename> package installed, you
- might experience QEMU build failures due to the package
- installing its own custom
- <filename>/usr/include/linux/soundcard.h</filename> on
- the Debian system.
- If you run into this situation, either of the following
- solutions exist:
- <literallayout class='monospaced'>
- $ sudo apt-get build-dep qemu
- $ sudo apt-get remove oss4-dev
- </literallayout>
- </note>
- <itemizedlist>
- <listitem><para><emphasis>Essentials:</emphasis>
- Packages needed to build an image on a headless
- system:
- <literallayout class='monospaced'>
- $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
- </literallayout></para></listitem>
- <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
- Packages recommended if the host system has graphics
- support or if you are going to use the Eclipse
- IDE:
- <literallayout class='monospaced'>
- $ sudo apt-get install libsdl1.2-dev xterm
- </literallayout></para></listitem>
- <listitem><para><emphasis>Documentation:</emphasis>
- Packages needed if you are going to build out the
- Yocto Project documentation manuals:
- <literallayout class='monospaced'>
- $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
- </literallayout></para></listitem>
- <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
- Packages needed if you are going to run
- <filename>oe-selftest</filename>:
- <literallayout class='monospaced'>
- $ sudo apt-get install python-git
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='fedora-packages'>
- <title>Fedora Packages</title>
-
- <para>
- The following list shows the required packages by function
- given a supported Fedora Linux distribution:
- <itemizedlist>
- <listitem><para><emphasis>Essentials:</emphasis>
- Packages needed to build an image for a headless
- system:
- <literallayout class='monospaced'>
- $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
- </literallayout></para></listitem>
- <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
- Packages recommended if the host system has graphics
- support or if you are going to use the Eclipse
- IDE:
- <literallayout class='monospaced'>
- $ sudo dnf install SDL-devel xterm
- </literallayout></para></listitem>
- <listitem><para><emphasis>Documentation:</emphasis>
- Packages needed if you are going to build out the
- Yocto Project documentation manuals:
- <literallayout class='monospaced'>
- $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \
- docbook-dtds docbook-utils fop libxslt dblatex xmlto
- </literallayout></para></listitem>
- <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
- Packages needed if you are going to run
- <filename>oe-selftest</filename>:
- <literallayout class='monospaced'>
- $ sudo dnf install python3-GitPython
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='opensuse-packages'>
- <title>openSUSE Packages</title>
-
- <para>
- The following list shows the required packages by function
- given a supported openSUSE Linux distribution:
- <itemizedlist>
- <listitem><para><emphasis>Essentials:</emphasis>
- Packages needed to build an image for a headless
- system:
- <literallayout class='monospaced'>
- $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
- </literallayout></para></listitem>
- <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
- Packages recommended if the host system has graphics
- support or if you are going to use the Eclipse
- IDE:
- <literallayout class='monospaced'>
- $ sudo zypper install libSDL-devel xterm
- </literallayout></para></listitem>
- <listitem><para><emphasis>Documentation:</emphasis>
- Packages needed if you are going to build out the
- Yocto Project documentation manuals:
- <literallayout class='monospaced'>
- $ sudo zypper install make dblatex xmlto
- </literallayout></para></listitem>
- <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
- Packages needed if you are going to run
- <filename>oe-selftest</filename>:
- <literallayout class='monospaced'>
- $ sudo zypper install python-GitPython
- </literallayout></para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='centos-packages'>
- <title>CentOS Packages</title>
-
- <para>
- The following list shows the required packages by function
- given a supported CentOS Linux distribution:
- <itemizedlist>
- <listitem><para><emphasis>Essentials:</emphasis>
- Packages needed to build an image for a headless
- system:
- <literallayout class='monospaced'>
- $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
- </literallayout>
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- Extra Packages for Enterprise Linux
- (i.e. <filename>epel-release</filename>)
- is a collection of packages from Fedora
- built on RHEL/CentOS for easy installation
- of packages not included in enterprise
- Linux by default.
- You need to install these packages
- separately.
- </para></listitem>
- <listitem><para>
- The <filename>makecache</filename> command
- consumes additional Metadata from
- <filename>epel-release</filename>.
- </para></listitem>
- </itemizedlist>
- </note>
- </para></listitem>
- <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
- Packages recommended if the host system has graphics
- support or if you are going to use the Eclipse
- IDE:
- <literallayout class='monospaced'>
- $ sudo yum install SDL-devel xterm
- </literallayout></para></listitem>
- <listitem><para><emphasis>Documentation:</emphasis>
- Packages needed if you are going to build out the
- Yocto Project documentation manuals:
- <literallayout class='monospaced'>
- $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
- docbook-dtds docbook-utils fop libxslt dblatex xmlto
- </literallayout></para></listitem>
- <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
- Packages needed if you are going to run
- <filename>oe-selftest</filename>:
- <literallayout class='monospaced'>
- $ sudo yum install GitPython
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
-
- <section id='required-git-tar-and-python-versions'>
- <title>Required Git, tar, and Python Versions</title>
-
- <para>
- In order to use the build system, your host development system
- must meet the following version requirements for Git, tar, and
- Python:
- <itemizedlist>
- <listitem><para>Git 1.8.3.1 or greater</para></listitem>
- <listitem><para>tar 1.27 or greater</para></listitem>
- <listitem><para>Python 3.4.0 or greater</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- If your host development system does not meet all these requirements,
- you can resolve this by installing a <filename>buildtools</filename>
- tarball that contains these tools.
- You can get the tarball one of two ways: download a pre-built
- tarball or use BitBake to build the tarball.
- </para>
-
- <section id='downloading-a-pre-built-buildtools-tarball'>
- <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
-
- <para>
- Downloading and running a pre-built buildtools installer is
- the easiest of the two methods by which you can get these tools:
- <orderedlist>
- <listitem><para>
- Locate and download the <filename>*.sh</filename> at
- <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
- </para></listitem>
- <listitem><para>
- Execute the installation script.
- Here is an example:
- <literallayout class='monospaced'>
- $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
- </literallayout>
- During execution, a prompt appears that allows you to
- choose the installation directory.
- For example, you could choose the following:
- <literallayout class='monospaced'>
- /home/<replaceable>your-username</replaceable>/buildtools
- </literallayout>
- </para></listitem>
- <listitem><para>
- Source the tools environment setup script by using a
- command like the following:
- <literallayout class='monospaced'>
- $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
- </literallayout>
- Of course, you need to supply your installation directory and be
- sure to use the right file (i.e. i585 or x86-64).
- </para>
- <para>
- After you have sourced the setup script,
- the tools are added to <filename>PATH</filename>
- and any other environment variables required to run the
- tools are initialized.
- The results are working versions versions of Git, tar,
- Python and <filename>chrpath</filename>.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='building-your-own-buildtools-tarball'>
- <title>Building Your Own <filename>buildtools</filename> Tarball</title>
-
- <para>
- Building and running your own buildtools installer applies
- only when you have a build host that can already run BitBake.
- In this case, you use that machine to build the
- <filename>.sh</filename> file and then
- take steps to transfer and run it on a
- machine that does not meet the minimal Git, tar, and Python
- requirements.
- </para>
-
- <para>
- Here are the steps to take to build and run your own
- buildtools installer:
- <orderedlist>
- <listitem><para>
- On the machine that is able to run BitBake,
- be sure you have set up your build environment with
- the setup script
- (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
- </para></listitem>
- <listitem><para>
- Run the BitBake command to build the tarball:
- <literallayout class='monospaced'>
- $ bitbake buildtools-tarball
- </literallayout>
- <note>
- The
- <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
- variable in your <filename>local.conf</filename> file
- determines whether you build tools for a 32-bit
- or 64-bit system.
- </note>
- Once the build completes, you can find the
- <filename>.sh</filename> file that installs
- the tools in the <filename>tmp/deploy/sdk</filename>
- subdirectory of the
- <link linkend='build-directory'>Build Directory</link>.
- The installer file has the string "buildtools"
- in the name.
- </para></listitem>
- <listitem><para>
- Transfer the <filename>.sh</filename> file from the
- build host to the machine that does not meet the
- Git, tar, or Python requirements.
- </para></listitem>
- <listitem><para>
- On the machine that does not meet the requirements,
- run the <filename>.sh</filename> file
- to install the tools.
- Here is an example:
- <literallayout class='monospaced'>
- $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
- </literallayout>
- During execution, a prompt appears that allows you to
- choose the installation directory.
- For example, you could choose the following:
- <literallayout class='monospaced'>
- /home/<replaceable>your_username</replaceable>/buildtools
- </literallayout>
- </para></listitem>
- <listitem><para>
- Source the tools environment setup script by using a
- command like the following:
- <literallayout class='monospaced'>
- $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
- </literallayout>
- Of course, you need to supply your installation directory and be
- sure to use the right file (i.e. i585 or x86-64).
- </para>
- <para>
- After you have sourced the setup script,
- the tools are added to <filename>PATH</filename>
- and any other environment variables required to run the
- tools are initialized.
- The results are working versions versions of Git, tar,
- Python and <filename>chrpath</filename>.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
- </section>
-</section>
-
-<section id='intro-getit'>
- <title>Obtaining the Yocto Project</title>
- <para>
- The Yocto Project development team makes the Yocto Project available through a number
- of methods:
- <itemizedlist>
- <listitem><para><emphasis>Source Repositories:</emphasis>
- Working from a copy of the upstream
- <filename>poky</filename> repository is the
- preferred method for obtaining and using a Yocto Project
- release.
- You can view the Yocto Project Source Repositories at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
- In particular, you can find the
- <filename>poky</filename> repository at
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
- </para></listitem>
- <listitem><para><emphasis>Releases:</emphasis> Stable, tested
- releases are available as tarballs through
- <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
- <listitem><para><emphasis>Nightly Builds:</emphasis> These
- tarball releases are available at
- <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>.
- These builds include Yocto Project releases, SDK installation
- scripts, and experimental builds.
- </para></listitem>
- <listitem><para><emphasis>Yocto Project Website:</emphasis> You can
- find tarball releases of the Yocto Project and supported BSPs
- at the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
- Along with these downloads, you can find lots of other
- information at this site.
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-
-<section id='intro-getit-dev'>
- <title>Development Checkouts</title>
- <para>
- Development using the Yocto Project requires a local
- <link linkend='source-directory'>Source Directory</link>.
- You can set up the Source Directory by cloning a copy of the upstream
- <link linkend='poky'>poky</link> Git repository.
- For information on how to do this, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-</section>
-
-<section id='yocto-project-terms'>
- <title>Yocto Project Terms</title>
-
- <para>
- Following is a list of terms and definitions users new to the Yocto
- Project development environment might find helpful.
- While some of these terms are universal, the list includes them
- just in case:
- <itemizedlist>
- <listitem><para>
- <emphasis>Append Files:</emphasis>
- Files that append build information to a recipe file.
- Append files are known as BitBake append files and
- <filename>.bbappend</filename> files.
- The OpenEmbedded build system expects every append file to have
- a corresponding recipe (<filename>.bb</filename>) file.
- Furthermore, the append file and corresponding recipe file
- must use the same root filename.
- The filenames can differ only in the file type suffix used
- (e.g.
- <filename>formfactor_0.0.bb</filename> and
- <filename>formfactor_0.0.bbappend</filename>).</para>
-
- <para>Information in append files extends or overrides the
- information in the similarly-named recipe file.
- For an example of an append file in use, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual.
- <note>
- Append files can also use wildcard patterns in their
- version numbers so they can be applied to more than one
- version of the underlying recipe file.
- </note>
- </para></listitem>
- <listitem><para id='bitbake-term'>
- <emphasis>BitBake:</emphasis>
- The task executor and scheduler used by the OpenEmbedded build
- system to build images.
- For more information on BitBake, see the
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
- </para></listitem>
- <listitem><para id='board-support-package-bsp-term'>
- <emphasis>Board Support Package (BSP):</emphasis>
- A group of drivers, definitions, and other components that
- provide support for a specific hardware configuration.
- For more information on BSPs, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
- </para></listitem>
- <listitem>
- <para id='build-directory'>
- <emphasis>Build Directory:</emphasis>
- This term refers to the area used by the OpenEmbedded build
- system for builds.
- The area is created when you <filename>source</filename> the
- setup environment script that is found in the Source Directory
- (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
- The
- <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
- variable points to the Build Directory.</para>
-
- <para>You have a lot of flexibility when creating the Build
- Directory.
- Following are some examples that show how to create the
- directory.
- The examples assume your
- <link linkend='source-directory'>Source Directory</link> is
- named <filename>poky</filename>:
- <itemizedlist>
- <listitem><para>Create the Build Directory inside your
- Source Directory and let the name of the Build
- Directory default to <filename>build</filename>:
- <literallayout class='monospaced'>
- $ cd $HOME/poky
- $ source &OE_INIT_FILE;
- </literallayout>
- </para></listitem>
- <listitem><para>Create the Build Directory inside your
- home directory and specifically name it
- <filename>test-builds</filename>:
- <literallayout class='monospaced'>
- $ cd $HOME
- $ source poky/&OE_INIT_FILE; test-builds
- </literallayout>
- </para></listitem>
- <listitem><para>
- Provide a directory path and specifically name the
- Build Directory.
- Any intermediate folders in the pathname must exist.
- This next example creates a Build Directory named
- <filename>YP-&POKYVERSION;</filename>
- in your home directory within the existing
- directory <filename>mybuilds</filename>:
- <literallayout class='monospaced'>
- $cd $HOME
- $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
- </literallayout>
- </para></listitem>
- </itemizedlist>
- <note>
- By default, the Build Directory contains
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
- which is a temporary directory the build system uses for
- its work.
- <filename>TMPDIR</filename> cannot be under NFS.
- Thus, by default, the Build Directory cannot be under NFS.
- However, if you need the Build Directory to be under NFS,
- you can set this up by setting <filename>TMPDIR</filename>
- in your <filename>local.conf</filename> file
- to use a local drive.
- Doing so effectively separates <filename>TMPDIR</filename>
- from <filename>TOPDIR</filename>, which is the Build
- Directory.
- </note>
- </para></listitem>
- <listitem><para id='hardware-build-system-term'>
- <emphasis>Build System:</emphasis>
- The system used to build images in a Yocto Project
- Development environment.
- The build system is sometimes referred to as the
- development host.
- </para></listitem>
- <listitem><para>
- <emphasis>Classes:</emphasis>
- Files that provide for logic encapsulation and inheritance so
- that commonly used patterns can be defined once and then
- easily used in multiple recipes.
- For reference information on the Yocto Project classes, see the
- "<link linkend='ref-classes'>Classes</link>" chapter.
- Class files end with the <filename>.bbclass</filename>
- filename extension.
- </para></listitem>
- <listitem><para>
- <emphasis>Configuration File:</emphasis>
- Configuration information in various <filename>.conf</filename>
- files provides global definitions of variables.
- The <filename>conf/local.conf</filename> configuration file in
- the
- <link linkend='build-directory'>Build Directory</link>
- contains user-defined variables that affect every build.
- The <filename>meta-poky/conf/distro/poky.conf</filename>
- configuration file defines Yocto "distro" configuration
- variables used only when building with this policy.
- Machine configuration files, which
- are located throughout the
- <link linkend='source-directory'>Source Directory</link>, define
- variables for specific hardware and are only used when building
- for that target (e.g. the
- <filename>machine/beaglebone.conf</filename> configuration
- file defines variables for the Texas Instruments ARM Cortex-A8
- development board).
- Configuration files end with a <filename>.conf</filename>
- filename extension.
- </para></listitem>
- <listitem><para id='cross-development-toolchain'>
- <emphasis>Cross-Development Toolchain:</emphasis>
- In general, a cross-development toolchain is a collection of
- software development tools and utilities that run on one
- architecture and allow you to develop software for a
- different, or targeted, architecture.
- These toolchains contain cross-compilers, linkers, and
- debuggers that are specific to the target architecture.</para>
-
- <para>The Yocto Project supports two different cross-development
- toolchains:
- <itemizedlist>
- <listitem><para>
- A toolchain only used by and within
- BitBake when building an image for a target
- architecture.
- </para></listitem>
- <listitem><para>A relocatable toolchain used outside of
- BitBake by developers when developing applications
- that will run on a targeted device.
- </para></listitem>
- </itemizedlist></para>
-
- <para>Creation of these toolchains is simple and automated.
- For information on toolchain concepts as they apply to the
- Yocto Project, see the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section.
- You can also find more information on using the
- relocatable toolchain in the
- <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
- manual.
- </para></listitem>
- <listitem><para>
- <emphasis>Image:</emphasis>
- An image is an artifact of the BitBake build process given
- a collection of recipes and related Metadata.
- Images are the binary output that run on specific hardware or
- QEMU and are used for specific use-cases.
- For a list of the supported image types that the Yocto Project
- provides, see the
- "<link linkend='ref-images'>Images</link>"
- chapter.
- </para></listitem>
- <listitem><para>
- <emphasis>Layer:</emphasis>
- A collection of recipes representing the core,
- a BSP, or an application stack.
- For a discussion specifically on BSP Layers, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
- section in the Yocto Project Board Support Packages (BSP)
- Developer's Guide.
- </para></listitem>
- <listitem><para id='metadata'>
- <emphasis>Metadata:</emphasis>
- The files that BitBake parses when building an image.
- In general, Metadata includes recipes, classes, and
- configuration files.
- In the context of the kernel ("kernel Metadata"), the
- term refers to the kernel config fragments and features
- contained in the
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
- Git repository.
- </para></listitem>
- <listitem><para id='oe-core'>
- <emphasis>OE-Core:</emphasis>
- A core set of Metadata originating with OpenEmbedded (OE)
- that is shared between OE and the Yocto Project.
- This Metadata is found in the <filename>meta</filename>
- directory of the
- <link linkend='source-directory'>Source Directory</link>.
- </para></listitem>
- <listitem><para id='build-system-term'>
- <emphasis>OpenEmbedded Build System:</emphasis>
- The build system specific to the Yocto Project.
- The OpenEmbedded build system is based on another project known
- as "Poky", which uses
- <link linkend='bitbake-term'>BitBake</link> as the task
- executor.
- Throughout the Yocto Project documentation set, the
- OpenEmbedded build system is sometimes referred to simply
- as "the build system".
- If other build systems, such as a host or target build system
- are referenced, the documentation clearly states the
- difference.
- <note>
- For some historical information about Poky, see the
- <link linkend='poky'>Poky</link> term.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Package:</emphasis>
- In the context of the Yocto Project, this term refers to a
- recipe's packaged output produced by BitBake (i.e. a
- "baked recipe").
- A package is generally the compiled binaries produced from the
- recipe's sources.
- You "bake" something by running it through BitBake.</para>
-
- <para>It is worth noting that the term "package" can,
- in general, have subtle meanings.
- For example, the packages referred to in the
- "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
- section in the Yocto Project Quick Start are compiled binaries
- that, when installed, add functionality to your Linux
- distribution.</para>
-
- <para>Another point worth noting is that historically within
- the Yocto Project, recipes were referred to as packages - thus,
- the existence of several BitBake variables that are seemingly
- mis-named,
- (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
- <link linkend='var-PV'><filename>PV</filename></link>, and
- <link linkend='var-PE'><filename>PE</filename></link>).
- </para></listitem>
- <listitem><para>
- <emphasis>Package Groups:</emphasis>
- Arbitrary groups of software Recipes.
- You use package groups to hold recipes that, when built,
- usually accomplish a single task.
- For example, a package group could contain the recipes for a
- company’s proprietary or value-add software.
- Or, the package group could contain the recipes that enable
- graphics.
- A package group is really just another recipe.
- Because package group files are recipes, they end with the
- <filename>.bb</filename> filename extension.
- </para></listitem>
- <listitem><para id='poky'>
- <emphasis>Poky:</emphasis>
- The term "poky", which is pronounced
- <emphasis>Pah</emphasis>-kee, can mean several things:
- <itemizedlist>
- <listitem><para>
- In its most general sense, poky is an open-source
- project that was initially developed by OpenedHand.
- OpenedHand developed poky off of the existing
- OpenEmbedded build system to create a commercially
- supportable build system for embedded Linux.
- After Intel Corporation acquired OpenedHand, the
- poky project became the basis for the Yocto Project's
- build system.
- </para></listitem>
- <listitem><para>
- Within the Yocto Project
- <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
- "poky" exists as a separate Git
- repository from which you can clone to yield a local
- Git repository that is a copy on your host system.
- Thus, "poky" can refer to the upstream or
- local copy of the files used for development within
- the Yocto Project.
- </para></listitem>
- <listitem><para>
- Finally, "poky" can refer to the default
- <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
- (i.e. distribution) created when you use the Yocto
- Project in conjunction with the
- <filename>poky</filename> repository to build an image.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Recipe:</emphasis>
- A set of instructions for building packages.
- A recipe describes where you get source code, which patches
- to apply, how to configure the source, how to compile it and so on.
- Recipes also describe dependencies for libraries or for other
- recipes.
- Recipes represent the logical unit of execution, the software
- to build, the images to build, and use the
- <filename>.bb</filename> file extension.
- </para></listitem>
- <listitem><para id='reference-kit-term'>
- <emphasis>Reference Kit:</emphasis>
- A working example of a system, which includes a
- <link linkend='board-support-package-bsp-term'>BSP</link>
- as well as a
- <link linkend='hardware-build-system-term'>build system</link>
- and other components, that can work on specific hardware.
- </para></listitem>
- <listitem>
- <para id='source-directory'>
- <emphasis>Source Directory:</emphasis>
- This term refers to the directory structure created as a result
- of creating a local copy of the <filename>poky</filename> Git
- repository <filename>git://git.yoctoproject.org/poky</filename>
- or expanding a released <filename>poky</filename> tarball.
- <note>
- Creating a local copy of the <filename>poky</filename>
- Git repository is the recommended method for setting up
- your Source Directory.
- </note>
- Sometimes you might hear the term "poky directory" used to refer
- to this directory structure.
- <note>
- The OpenEmbedded build system does not support file or
- directory names that contain spaces.
- Be sure that the Source Directory you use does not contain
- these types of names.
- </note></para>
-
- <para>The Source Directory contains BitBake, Documentation,
- Metadata and other files that all support the Yocto Project.
- Consequently, you must have the Source Directory in place on
- your development system in order to do any development using
- the Yocto Project.</para>
-
- <para>When you create a local copy of the Git repository, you
- can name the repository anything you like.
- Throughout much of the documentation, "poky"
- is used as the name of the top-level folder of the local copy of
- the poky Git repository.
- So, for example, cloning the <filename>poky</filename> Git
- repository results in a local Git repository whose top-level
- folder is also named "poky".</para>
-
- <para>While it is not recommended that you use tarball expansion
- to set up the Source Directory, if you do, the top-level
- directory name of the Source Directory is derived from the
- Yocto Project release tarball.
- For example, downloading and unpacking
- <filename>&YOCTO_POKY_TARBALL;</filename> results in a
- Source Directory whose root folder is named
- <filename>&YOCTO_POKY;</filename>.</para>
-
- <para>It is important to understand the differences between the
- Source Directory created by unpacking a released tarball as
- compared to cloning
- <filename>git://git.yoctoproject.org/poky</filename>.
- When you unpack a tarball, you have an exact copy of the files
- based on the time of release - a fixed release point.
- Any changes you make to your local files in the Source Directory
- are on top of the release and will remain local only.
- On the other hand, when you clone the <filename>poky</filename>
- Git repository, you have an active development repository with
- access to the upstream repository's branches and tags.
- In this case, any local changes you make to the local
- Source Directory can be later applied to active development
- branches of the upstream <filename>poky</filename> Git
- repository.</para>
-
- <para>For more information on concepts related to Git
- repositories, branches, and tags, see the
- "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
- section.
- </para></listitem>
- <listitem><para><emphasis>Task:</emphasis>
- A unit of execution for BitBake (e.g.
- <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
- <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
- <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
- and so forth).
- </para></listitem>
- <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
- A web interface to the Yocto Project's
- <link linkend='build-system-term'>OpenEmbedded Build System</link>.
- The interface enables you to configure and run your builds.
- Information about builds is collected and stored in a database.
- For information on Toaster, see the
- <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
- </para></listitem>
- <listitem><para>
- <emphasis>Upstream:</emphasis>
- A reference to source code or repositories
- that are not local to the development system but located in a
- master area that is controlled by the maintainer of the source
- code.
- For example, in order for a developer to work on a particular
- piece of code, they need to first get a copy of it from an
- "upstream" source.
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/import-layers/yocto-poky/documentation/ref-manual/migration.xml b/import-layers/yocto-poky/documentation/ref-manual/migration.xml
index 811577b..b060968 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/migration.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/migration.xml
@@ -293,7 +293,7 @@
For the remainder, you can now find them in the
<filename>meta-extras</filename> repository, which is in the
Yocto Project
- <link linkend='source-repositories'>Source Repositories</link>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
</para>
</section>
</section>
@@ -442,7 +442,7 @@
at <filename>meta/recipes-core/init-ifupdown</filename>.
For information on how to use append files, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
- in the Yocto Project Development Tasks Manual.
+ section in the Yocto Project Development Tasks Manual.
</para>
</section>
@@ -866,10 +866,8 @@
<link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
<itemizedlist>
<listitem><para>
- The value of
- <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
- is now validated to ensure invalid feature items are not
- added.
+ The value of <filename>IMAGE_FEATURES</filename> is now
+ validated to ensure invalid feature items are not added.
Some users mistakenly add package names to this variable
instead of using
<link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
@@ -1022,8 +1020,8 @@
</para></listitem>
</itemizedlist>
For more information on Build History, see the
- "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</section>
@@ -1116,8 +1114,8 @@
supports pre-renamed package names.</para></listitem>
<listitem><para>
<filename>classes/rootfs_rpm</filename>: Implement
- <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
- for RPM.</para></listitem>
+ <filename>BAD_RECOMMENDATIONS</filename> for RPM.
+ </para></listitem>
<listitem><para>
<filename>systemd</filename>: Remove
<filename>systemd_unitdir</filename> if
@@ -1452,7 +1450,7 @@
<para>
Package Tests (ptest) are built but not installed by default.
For information on using Package Tests, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Setting up and running package test (ptest)</ulink>"
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages with ptest</ulink>"
section in the Yocto Project Development Tasks Manual.
For information on the <filename>ptest</filename> class, see the
"<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
@@ -1748,8 +1746,8 @@
<para>
The minimum
- <link linkend='git'>Git</link> version required
- on the build host is now 1.7.8 because the
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> version
+ required on the build host is now 1.7.8 because the
<filename>--list</filename> option is now required by
BitBake's Git fetcher.
As always, if your host distribution does not provide a version of
@@ -1909,14 +1907,6 @@
for which <filename>module_conf_*</filename> is specified to
<filename>KERNEL_MODULE_PROBECONF</filename>.
</para>
-
- <para>
- For more information, see the
- <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
- and
- <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
- variables.
- </para>
</section>
<section id='migration-1.7-qa-check-changes'>
@@ -2026,8 +2016,8 @@
You should manually remove old "build-id" files from your
existing build history repositories to avoid confusion.
For information on the build history feature, see the
- "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para></listitem>
</itemizedlist>
</para>
@@ -3037,7 +3027,7 @@
actively maintained.
See the
"<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>"
- section in the Yocto Project Toaster User Manual for more
+ section in the Toaster User Manual for more
information on this interface.
</para></listitem>
<listitem><para><emphasis>"puccho" BitBake UI</emphasis>:
@@ -3057,7 +3047,8 @@
and the
<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
For information on these SDKs and how to build and use them, see the
- <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
<note>
The Yocto Project Eclipse IDE Plug-in is still supported and
is not affected by this change.
@@ -4038,7 +4029,7 @@
<para>For an example, see the
<filename>pixbufcache</filename> class in
<filename>meta/classes/</filename> in the Yocto Project
- <link linkend='source-repositories'>Source Repositories</link>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
<note>
The <filename>SSTATEPOSTINSTFUNCS</filename> variable
itself is now deprecated in favor of the
@@ -4251,8 +4242,8 @@
<para>See the
"<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>"
- section in the Yocto Project BitBake User Manual for
- additional information.
+ section in the BitBake User Manual for additional
+ information.
</para></listitem>
<listitem><para>
<emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
@@ -4625,8 +4616,7 @@
<listitem><para>
The <filename>USE_LDCONFIG</filename> variable has been
replaced with the "ldconfig"
- <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
- feature.
+ <filename>DISTRO_FEATURES</filename> feature.
Distributions that previously set:
<literallayout class='monospaced'>
USE_LDCONFIG = "0"
@@ -4685,9 +4675,9 @@
</para></listitem>
<listitem><para>
All native and nativesdk recipes now use a separate
- <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
- value instead of sharing the value used by recipes for the
- target, in order to avoid unnecessary rebuilds.</para>
+ <filename>DISTRO_FEATURES</filename> value instead of
+ sharing the value used by recipes for the target, in order
+ to avoid unnecessary rebuilds.</para>
<para>The <filename>DISTRO_FEATURES</filename> for
<filename>native</filename> recipes is
@@ -4738,9 +4728,9 @@
replacing its previous "memory resident mode" (i.e.
<filename>oe-init-build-env-memres</filename>).
Now you only need to set
- <filename>BB_SERVER_TIMEOUT</filename> to a timeout
- (in seconds) and BitBake's server stays resident for that
- amount of time between invocations.
+ <link linkend='var-BB_SERVER_TIMEOUT'><filename>BB_SERVER_TIMEOUT</filename></link>
+ to a timeout (in seconds) and BitBake's server stays resident for
+ that amount of time between invocations.
The <filename>oe-init-build-env-memres</filename> script has been
removed since a separate environment setup script is no longer
needed.
@@ -4805,7 +4795,7 @@
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
on the <filename>util-linux-su</filename> package
when "pam" is in
- <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+ <filename>DISTRO_FEATURES</filename>.
</para></listitem>
<listitem><para>
The <filename>switch_root</filename> program is now
@@ -4824,7 +4814,7 @@
packaged in a separate "util-linux-ionice" package.
The main <filename>util-linux</filename> package has
a recommended runtime dependency (i.e.
- <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
+ <filename>RRECOMMENDS</filename>)
on the <filename>util-linux-ionice</filename> package.
</para></listitem>
</itemizedlist>
@@ -4839,18 +4829,15 @@
The change also eliminates needing to pull in the entire
<filename>initscripts</filename> package.
The main <filename>initscripts</filename> package has a
- runtime dependency (i.e.
- <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
+ runtime dependency (i.e. <filename>RDEPENDS</filename>)
on the <filename>sushell</filename> package when
- "selinux" is in
- <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+ "selinux" is in <filename>DISTRO_FEATURES</filename>.
</para></listitem>
<listitem><para>
<emphasis><filename>glib-2.0</filename>:</emphasis>
The <filename>glib-2.0</filename> package now has a
recommended runtime dependency (i.e.
- <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
- on the
+ <filename>RRECOMMENDS</filename>) on the
<filename>shared-mime-info</filename> package, since large
portions of GIO are not useful without the MIME database.
You can remove the dependency by using the
@@ -5045,7 +5032,8 @@
Kernel Device Tree support is now easier to enable in a kernel
recipe.
The Device Tree code has moved to a
- <filename>kernel-devicetree</filename> class.
+ <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
+ class.
Functionality is automatically enabled for any recipe that inherits
the
<link linkend='ref-classes-kernel'><filename>kernel</filename></link>
@@ -5177,13 +5165,14 @@
multiconfig is enabled (one per configuration).
For more information, see the
"<ulink url='&YOCTO_DOCS_BB_URL;#events'>Events</ulink>"
- in the BitBake User Manual.
+ section in the BitBake User Manual.
</para></listitem>
<listitem><para>
By default, the <filename>security_flags.inc</filename> file
- sets a <filename>GCCPIE</filename> variable with an option
- to enable Position Independent Executables (PIE) within
- <filename>gcc</filename>.
+ sets a
+ <link linkend='var-GCCPIE'><filename>GCCPIE</filename></link>
+ variable with an option to enable Position Independent
+ Executables (PIE) within <filename>gcc</filename>.
Enabling PIE in the GNU C Compiler (GCC), makes Return
Oriented Programming (ROP) attacks much more difficult to
execute.
@@ -5238,6 +5227,457 @@
</para>
</section>
</section>
+
+<section id='moving-to-the-yocto-project-2.5-release'>
+ <title>Moving to the Yocto Project 2.5 Release</title>
+
+ <para>
+ This section provides migration information for moving to the
+ Yocto Project 2.5 Release from the prior release.
+ </para>
+
+ <section id='migration-2.5-packaging-changes'>
+ <title>Packaging Changes</title>
+
+ <para>
+ This section provides information about packaging changes that have
+ occurred:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>bind-libs</filename>:</emphasis>
+ The libraries packaged by the bind recipe are in a
+ separate <filename>bind-libs</filename> package.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>libfm-gtk</filename>:</emphasis>
+ The <filename>libfm</filename> GTK+ bindings are split into
+ a separate <filename>libfm-gtk</filename> package.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>flex-libfl</filename>:</emphasis>
+ The flex recipe splits out libfl into a separate
+ <filename>flex-libfl</filename> package to avoid too many
+ dependencies being pulled in where only the library is
+ needed.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>grub-efi</filename>:</emphasis>
+ The <filename>grub-efi</filename> configuration is split
+ into a separate <filename>grub-bootconf</filename>
+ recipe.
+ However, the dependency relationship from
+ <filename>grub-efi</filename> is through a
+ virtual/grub-bootconf provider making it possible to have
+ your own recipe provide the dependency.
+ Alternatively, you can use a BitBake append file to bring
+ the configuration back into the
+ <filename>grub-efi</filename> recipe.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>armv7a Legacy Package Feed Support:</emphasis>
+ Legacy support is removed for transitioning from
+ <filename>armv7a</filename> to
+ <filename>armv7a-vfp-neon</filename> in package feeds,
+ which was previously enabled by setting
+ <filename>PKGARCHCOMPAT_ARMV7A</filename>.
+ This transition occurred in 2011 and active package feeds
+ should by now be updated to the new naming.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='migration-2.5-removed-recipes'>
+ <title>Removed Recipes</title>
+
+ <para>
+ The following recipes have been removed:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>gcc</filename>:</emphasis>
+ The version 6.4 recipes are replaced by 7.x.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>gst-player</filename>:</emphasis>
+ Renamed to <filename>gst-examples</filename> as per
+ upstream.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>hostap-utils</filename>:</emphasis>
+ This software package is obsolete.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>latencytop</filename>:</emphasis>
+ This recipe is no longer maintained upstream.
+ The last release was in 2009.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>libpfm4</filename>:</emphasis>
+ The only file that requires this recipe is
+ <filename>oprofile</filename>, which has been removed.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>linux-yocto</filename>:</emphasis>
+ The version 4.4, 4.9, and 4.10 recipes have been removed.
+ Versions 4.12, 4.14, and 4.15 remain.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>man</filename>:</emphasis>
+ This recipe has been replaced by modern
+ <filename>man-db</filename>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>mkelfimage</filename>:</emphasis>
+ This tool has been removed in the upstream coreboot project,
+ and is no longer needed with the removal of the ELF image
+ type.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>nativesdk-postinst-intercept</filename>:</emphasis>
+ This recipe is not maintained.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>neon</filename>:</emphasis>
+ This software package is no longer maintained upstream and
+ is no longer needed by anything in OpenEmbedded-Core.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>oprofile</filename>:</emphasis>
+ The functionality of this recipe is replaced by
+ <filename>perf</filename> and keeping compatibility on
+ an ongoing basis with <filename>musl</filename> is
+ difficult.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>pax</filename>:</emphasis>
+ This software package is obsolete.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>stat</filename>:</emphasis>
+ This software package is not maintained upstream.
+ <filename>coreutils</filename> provides a modern stat binary.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>zisofs-tools-native</filename>:</emphasis>
+ This recipe is no longer needed because the compressed
+ ISO image feature has been removed.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='migration-2.5-scripts-and-tools-changes'>
+ <title>Scripts and Tools Changes</title>
+
+ <para>
+ The following are changes to scripts and tools:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>yocto-bsp</filename>,
+ <filename>yocto-kernel</filename>, and
+ <filename>yocto-layer</filename></emphasis>:
+ The <filename>yocto-bsp</filename>,
+ <filename>yocto-kernel</filename>, and
+ <filename>yocto-layer</filename> scripts previously shipped
+ with poky but not in OpenEmbedded-Core have been removed.
+ These scripts are not maintained and are outdated.
+ In many cases, they are also limited in scope.
+ The <filename>bitbake-layers create-layer</filename> command
+ is a direct replacement for <filename>yocto-layer</filename>.
+ See the documentation to create a BSP or kernel recipe in
+ the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example'>BSP Kernel Recipe Example</ulink>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>devtool finish</filename>:</emphasis>
+ <filename>devtool finish</filename> now exits with an error
+ if there are uncommitted changes or a rebase/am in progress
+ in the recipe's source repository.
+ If this error occurs, there might be uncommitted changes
+ that will not be included in updates to the patches applied
+ by the recipe.
+ A -f/--force option is provided for situations that the
+ uncommitted changes are inconsequential and you want to
+ proceed regardless.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>scripts/oe-setup-rpmrepo</filename> script:</emphasis>
+ The functionality of
+ <filename>scripts/oe-setup-rpmrepo</filename> is replaced by
+ <filename>bitbake package-index</filename>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>scripts/test-dependencies.sh</filename> script:</emphasis>
+ The script is largely made obsolete by the
+ recipe-specific sysroots functionality introduced in the
+ previous release.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='migration-2.5-bitbake-changes'>
+ <title>BitBake Changes</title>
+
+ <para>
+ The following are BitBake changes:
+ <itemizedlist>
+ <listitem><para>
+ The <filename>--runall</filename> option has changed.
+ There are two different behaviors people might want:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Behavior A:</emphasis>
+ For a given target (or set of targets) look through
+ the task graph and run task X only if it is present
+ and will be built.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Behavior B:</emphasis>
+ For a given target (or set of targets) look through
+ the task graph and run task X if any recipe in the
+ taskgraph has such a target, even if it is not in
+ the original task graph.
+ </para></listitem>
+ </itemizedlist>
+ The <filename>--runall</filename> option now performs
+ "Behavior B".
+ Previously <filename>--runall</filename> behaved like
+ "Behavior A".
+ A <filename>--runonly</filename> option has been added to
+ retain the ability to perform "Behavior A".
+ </para></listitem>
+ <listitem><para>
+ Several explicit "run this task for all recipes in the
+ dependency tree" tasks have been removed (e.g.
+ <filename>fetchall</filename>,
+ <filename>checkuriall</filename>, and the
+ <filename>*all</filename> tasks provided by the
+ <filename>distrodata</filename> and
+ <filename>archiver</filename> classes).
+ There is a BitBake option to complete this for any arbitrary
+ task. For example:
+ <literallayout class='monospaced'>
+ bitbake <target> -c fetchall
+ </literallayout>
+ should now be replaced with:
+ <literallayout class='monospaced'>
+ bitbake <target> --runall=fetch
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='migration-2.5-python-and-python3-changes'>
+ <title>Python and Python 3 Changes</title>
+
+ <para>
+ The following are auto-packaging changes to Python and Python 3:
+ </para>
+ <para>
+ The script-managed <filename>python-*-manifest.inc</filename> files
+ that were previously used to generate Python and Python 3
+ packages have been replaced with a JSON-based file that is
+ easier to read and maintain.
+ A new task is available for maintainers of the Python recipes to
+ update the JSON file when upgrading to new Python versions.
+ You can now edit the file directly instead of having to edit a
+ script and run it to update the file.
+ </para>
+ <para>
+ One particular change to note is that the Python recipes no longer
+ have build-time provides for their packages.
+ This assumes <filename>python-foo</filename> is one of the packages
+ provided by the Python recipe.
+ You can no longer run <filename>bitbake python-foo</filename> or
+ have a <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> on
+ <filename>python-foo</filename>, but doing either of the following
+ causes the package to work as expected:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = " python-foo"
+ </literallayout>
+ or
+ <literallayout class='monospaced'>
+ RDEPENDS_${PN} = "python-foo"
+ </literallayout>
+ The earlier build-time provides behavior was a quirk of the way the
+ Python manifest file was created.
+ For more information on this change please see
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce'>this commit</ulink>.
+ </para>
+ </section>
+
+ <section id='migration-2.5-miscellaneous-changes'>
+ <title>Miscellaneous Changes</title>
+
+ <para>
+ The following are additional changes:
+ <itemizedlist>
+ <listitem><para>
+ The <filename>kernel</filename> class supports building
+ packages for multiple kernels.
+ If your kernel recipe or <filename>.bbappend</filename> file
+ mentions packaging at all, you should replace references to
+ the kernel in package names with
+ <filename>${KERNEL_PACKAGE_NAME}</filename>.
+ For example, if you disable automatic installation of the
+ kernel image using
+ <filename>RDEPENDS_kernel-base = ""</filename> you can avoid
+ warnings using
+ <filename>RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""</filename>
+ instead.
+ </para></listitem>
+ <listitem><para>
+ The <filename>buildhistory</filename> class commits changes
+ to the repository by default so you no longer need to set
+ <filename>BUILDHISTORY_COMMIT = "1"</filename>.
+ If you want to disable commits you need to set
+ <filename>BUILDHISTORY_COMMIT = "0"</filename> in your
+ configuration.
+ </para></listitem>
+ <listitem><para>
+ The <filename>beaglebone</filename> reference machine has
+ been renamed to <filename>beaglebone-yocto</filename>.
+ The <filename>beaglebone-yocto</filename> BSP is a reference
+ implementation using only mainline components available in
+ OpenEmbedded-Core and <filename>meta-yocto-bsp</filename>,
+ whereas Texas Instruments maintains a full-featured BSP in
+ the <filename>meta-ti</filename> layer.
+ This rename avoids the previous name clash that existed
+ between the two BSPs.
+ </para></listitem>
+ <listitem><para>
+ The <filename>update-alternatives</filename> class no longer
+ works with SysV <filename>init</filename> scripts because
+ this usage has been problematic.
+ Also, the <filename>sysklogd</filename> recipe no longer
+ uses <filename>update-alternatives</filename> because it is
+ incompatible with other implementations.
+ </para></listitem>
+ <listitem><para>
+ By default, the <filename>cmake</filename> class uses
+ <filename>ninja</filename> instead of
+ <filename>make</filename> for building.
+ This improves build performance.
+ If a recipe is broken with <filename>ninja</filename>, then
+ the recipe can set
+ <filename>OECMAKE_GENERATOR = "Unix Makefiles"</filename>
+ to change back to <filename>make</filename>.
+ </para></listitem>
+ <listitem><para>
+ The previously deprecated <filename>base_*</filename>
+ functions have been removed in favor of their replacements
+ in <filename>meta/lib/oe</filename> and
+ <filename>bitbake/lib/bb</filename>.
+ These are typically used from recipes and classes.
+ Any references to the old functions must be updated.
+ The following table shows the removed functions and their
+ replacements:
+
+ <literallayout class='monospaced'>
+ <emphasis>Removed</emphasis> <emphasis>Replacement</emphasis>
+ ============================ ============================
+ base_path_join() oe.path.join()
+ base_path_relative() oe.path.relative()
+ base_path_out() oe.path.format_display()
+ base_read_file() oe.utils.read_file()
+ base_ifelse() oe.utils.ifelse()
+ base_conditional() oe.utils.conditional()
+ base_less_or_equal() oe.utils.less_or_equal()
+ base_version_less_or_equal() oe.utils.version_less_or_equal()
+ base_contains() bb.utils.contains()
+ base_both_contain() oe.utils.both_contain()
+ base_prune_suffix() oe.utils.prune_suffix()
+ oe_filter() oe.utils.str_filter()
+ oe_filter_out() oe.utils.str_filter_out() (or use the _remove operator).
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Using <filename>exit 1</filename> to explicitly defer a
+ postinstall script until first boot is now deprecated since
+ it is not an obvious mechanism and can mask actual errors.
+ If you want to explicitly defer a postinstall to first boot
+ on the target rather than at <filename>rootfs</filename>
+ creation time, use
+ <filename>pkg_postinst_ontarget()</filename>
+ or call
+ <filename>postinst-intercepts defer_to_first_boot</filename>
+ from <filename>pkg_postinst()</filename>.
+ Any failure of a <filename>pkg_postinst()</filename>
+ script (including <filename>exit 1</filename>)
+ will trigger a warning during
+ <filename>do_rootfs</filename>.
+ </para></listitem>
+ <listitem><para>
+ The <filename>elf</filename> image type has been removed.
+ This image type was removed because the
+ <filename>mkelfimage</filename> tool
+ that was required to create it is no longer provided by
+ coreboot upstream and required updating every time
+ <filename>binutils</filename> updated.
+ </para></listitem>
+ <listitem><para>
+ Support for .iso image compression (previously enabled
+ through <filename>COMPRESSISO = "1"</filename>) has been
+ removed.
+ The userspace tools (<filename>zisofs-tools</filename>) are
+ unmaintained and <filename>squashfs</filename> provides
+ better performance and compression.
+ In order to build a live image with squashfs+lz4 compression
+ enabled you should now set
+ <filename>LIVE_ROOTFS_TYPE = "squashfs-lz4"</filename>
+ and ensure that <filename>live</filename>
+ is in <filename>IMAGE_FSTYPES</filename>.
+ </para></listitem>
+ <listitem><para>
+ Recipes with an unconditional dependency on
+ <filename>libpam</filename> are only buildable with
+ <filename>pam</filename> in
+ <filename>DISTRO_FEATURES</filename>.
+ If the dependency is truly optional then it is recommended
+ that the dependency be conditional upon
+ <filename>pam</filename> being in
+ <filename>DISTRO_FEATURES</filename>.
+ </para></listitem>
+ <listitem><para>
+ For EFI-based machines, the bootloader
+ (<filename>grub-efi</filename> by default) is installed into
+ the image at /boot.
+ Wic can be used to split the bootloader into separate boot
+ and rootfs partitions if necessary.
+ </para></listitem>
+ <listitem><para>
+ Patches whose context does not match exactly (i.e. where
+ patch reports "fuzz" when applying) will generate a
+ warning.
+ For an example of this see
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57'>this commit</ulink>.
+ </para></listitem>
+ <listitem><para>
+ Layers are expected to set
+ <filename>LAYERSERIES_COMPAT_layername</filename>
+ to match the version(s) of OpenEmbedded-Core they are
+ compatible with.
+ This is specified as codenames using spaces to separate
+ multiple values (e.g. "rocko sumo").
+ If a layer does not set
+ <filename>LAYERSERIES_COMPAT_layername</filename>, a warning
+ will is shown.
+ If a layer sets a value that does not include the current
+ version ("sumo" for the 2.5 release), then an error will be
+ produced.
+ </para></listitem>
+ <listitem><para>
+ The <filename>TZ</filename> environment variable is set to
+ "UTC" within the build environment in order to fix
+ reproducibility problems in some recipes.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml
deleted file mode 100644
index 17f4c54..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml
+++ /dev/null
@@ -1,477 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='ref-bitbake'>
-
- <title>BitBake</title>
-
- <para>
- BitBake is a program written in Python that interprets the
- <link linkend='metadata'>Metadata</link> used by
- the OpenEmbedded build system.
- At some point, developers wonder what actually happens when you enter:
- <literallayout class='monospaced'>
- $ bitbake core-image-sato
- </literallayout>
- </para>
-
- <para>
- This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
- </para>
-
- <note>
- BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
- As such, it has no real knowledge of what the tasks being executed actually do.
- BitBake just considers a list of tasks with dependencies and handles
- <link linkend='metadata'>Metadata</link>
- consisting of variables in a certain format that get passed to the tasks.
- </note>
-
- <section id='ref-bitbake-parsing'>
- <title>Parsing</title>
-
- <para>
- BitBake parses configuration files, classes, and <filename>.bb</filename> files.
- </para>
-
- <para>
- The first thing BitBake does is look for the
- <filename>bitbake.conf</filename> file.
- This file resides in the
- <link linkend='source-directory'>Source Directory</link>
- within the <filename>meta/conf/</filename> directory.
- BitBake finds it by examining its
- <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment
- variable and looking for the <filename>meta/conf/</filename>
- directory.
- </para>
-
- <para>
- The <filename>bitbake.conf</filename> file lists other configuration
- files to include from a <filename>conf/</filename>
- directory below the directories listed in <filename>BBPATH</filename>.
- In general, the most important configuration file from a user's perspective
- is <filename>local.conf</filename>, which contains a user's customized
- settings for the OpenEmbedded build environment.
- Other notable configuration files are the distribution
- configuration file (set by the
- <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable)
- and the machine configuration file
- (set by the
- <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable).
- The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment
- variables are both usually set in
- the <filename>local.conf</filename> file.
- Valid distribution
- configuration files are available in the <filename>meta/conf/distro/</filename> directory
- and valid machine configuration
- files in the <filename>meta/conf/machine/</filename> directory.
- Within the <filename>meta/conf/machine/include/</filename>
- directory are various <filename>tune-*.inc</filename> configuration files that provide common
- "tuning" settings specific to and shared between particular architectures and machines.
- </para>
-
- <para>
- After the parsing of the configuration files, some standard classes are included.
- The <filename>base.bbclass</filename> file is always included.
- Other classes that are specified in the configuration using the
- <filename><link linkend='var-INHERIT'>INHERIT</link></filename>
- variable are also included.
- Class files are searched for in a <filename>classes</filename> subdirectory
- under the paths in <filename>BBPATH</filename> in the same way as
- configuration files.
- </para>
-
- <para>
- After classes are included, the variable
- <filename><link linkend='var-BBFILES'>BBFILES</link></filename>
- is set, usually in
- <filename>local.conf</filename>, and defines the list of places to search for
- <filename>.bb</filename> files.
- By default, the <filename>BBFILES</filename> variable specifies the
- <filename>meta/recipes-*/</filename> directory within Poky.
- Adding extra content to <filename>BBFILES</filename> is best achieved through the use of
- BitBake layers as described in the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section of the Yocto Project Development Tasks Manual.
- </para>
-
- <para>
- BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and
- stores the values of various variables.
- In summary, for each <filename>.bb</filename>
- file the configuration plus the base class of variables are set, followed
- by the data in the <filename>.bb</filename> file
- itself, followed by any inherit commands that
- <filename>.bb</filename> file might contain.
- </para>
-
- <para>
- Because parsing <filename>.bb</filename> files is a time
- consuming process, a cache is kept to speed up subsequent parsing.
- This cache is invalid if the timestamp of the <filename>.bb</filename>
- file itself changes, or if the timestamps of any of the include,
- configuration files or class files on which the
- <filename>.bb</filename> file depends change.
- </para>
-
- <note>
- <para>
- You need to be aware of how BitBake parses curly braces.
- If a recipe uses a closing curly brace within the function and
- the character has no leading spaces, BitBake produces a parsing
- error.
- If you use a pair of curly brace in a shell function, the
- closing curly brace must not be located at the start of the line
- without leading spaces.
- </para>
-
- <para>
- Here is an example that causes BitBake to produce a parsing
- error:
- <literallayout class='monospaced'>
- fakeroot create_shar() {
- cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
- usage()
- {
- echo "test"
- ###### The following "}" at the start of the line causes a parsing error ######
- }
- EOF
- }
- </literallayout>
- Writing the recipe this way avoids the error:
- <literallayout class='monospaced'>
- fakeroot create_shar() {
- cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
- usage()
- {
- echo "test"
- ######The following "}" with a leading space at the start of the line avoids the error ######
- }
- EOF
- }
- </literallayout>
- </para>
- </note>
- </section>
-
- <section id='ref-bitbake-providers'>
- <title>Preferences and Providers</title>
-
- <para>
- Once all the <filename>.bb</filename> files have been
- parsed, BitBake starts to build the target (<filename>core-image-sato</filename>
- in the previous section's example) and looks for providers of that target.
- Once a provider is selected, BitBake resolves all the dependencies for
- the target.
- In the case of <filename>core-image-sato</filename>, it would lead to
- <filename>packagegroup-core-x11-sato</filename>,
- which in turn leads to recipes like <filename>matchbox-terminal</filename>,
- <filename>pcmanfm</filename> and <filename>gthumb</filename>.
- These recipes in turn depend on <filename>glibc</filename> and the toolchain.
- </para>
-
- <para>
- Sometimes a target might have multiple providers.
- A common example is "virtual/kernel", which is provided by each kernel package.
- Each machine often selects the best kernel provider by using a line similar to the
- following in the machine configuration file:
- </para>
-
- <literallayout class='monospaced'>
- PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
- </literallayout>
-
- <para>
- The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
- is the provider with the same name as the target.
- </para>
-
- <para>
- Understanding how providers are chosen is made complicated by the fact
- that multiple versions might exist.
- BitBake defaults to the highest version of a provider.
- Version comparisons are made using the same method as Debian.
- You can use the
- <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
- variable to specify a particular version (usually in the distro configuration).
- You can influence the order by using the
- <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
- variable.
- By default, files have a preference of "0".
- Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
- package unlikely to be used unless it is explicitly referenced.
- Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
- <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
- <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
- versions until they have undergone sufficient testing to be considered stable.
- </para>
-
- <para>
- In summary, BitBake has created a list of providers, which is prioritized, for each target.
- </para>
- </section>
-
- <section id='ref-bitbake-dependencies'>
- <title>Dependencies</title>
-
- <para>
- Each target BitBake builds consists of multiple tasks such as
- <filename>fetch</filename>, <filename>unpack</filename>,
- <filename>patch</filename>, <filename>configure</filename>,
- and <filename>compile</filename>.
- For best performance on multi-core systems, BitBake considers each task as an independent
- entity with its own set of dependencies.
- </para>
-
- <para>
- Dependencies are defined through several variables.
- You can find information about variables BitBake uses in the
- BitBake documentation, which is found in the
- <filename>bitbake/doc/manual</filename> directory within the
- <link linkend='source-directory'>Source Directory</link>.
- At a basic level, it is sufficient to know that BitBake uses the
- <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
- <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
- variables when calculating dependencies.
- </para>
- </section>
-
- <section id='ref-bitbake-tasklist'>
- <title>The Task List</title>
-
- <para>
- Based on the generated list of providers and the dependency information,
- BitBake can now calculate exactly what tasks it needs to run and in what
- order it needs to run them.
- The build now starts with BitBake forking off threads up to the limit set in the
- <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable.
- BitBake continues to fork threads as long as there are tasks ready to run,
- those tasks have all their dependencies met, and the thread threshold has not been
- exceeded.
- </para>
-
- <para>
- It is worth noting that you can greatly speed up the build time by properly setting
- the <filename>BB_NUMBER_THREADS</filename> variable.
- See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section in the Yocto Project Quick Start for more information.
- </para>
-
- <para>
- As each task completes, a timestamp is written to the directory specified by the
- <filename><link linkend='var-STAMP'>STAMP</link></filename> variable.
- On subsequent runs, BitBake looks within the <filename>build/tmp/stamps</filename>
- directory and does not rerun
- tasks that are already completed unless a timestamp is found to be invalid.
- Currently, invalid timestamps are only considered on a per
- <filename>.bb</filename> file basis.
- So, for example, if the configure stamp has a timestamp greater than the
- compile timestamp for a given target, then the compile task would rerun.
- Running the compile task again, however, has no effect on other providers
- that depend on that target.
- This behavior could change or become configurable in future versions of BitBake.
- </para>
-
- <note>
- Some tasks are marked as "nostamp" tasks.
- No timestamp file is created when these tasks are run.
- Consequently, "nostamp" tasks are always rerun.
- </note>
- </section>
-
- <section id='ref-bitbake-runtask'>
- <title>Running a Task</title>
-
- <para>
- Tasks can either be a shell task or a Python task.
- For shell tasks, BitBake writes a shell script to
- <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
- The generated shell script contains all the exported variables, and the shell functions
- with all variables expanded.
- Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
- Looking at the expanded shell functions in the run file and the output in the log files
- is a useful debugging technique.
- </para>
-
- <para>
- For Python tasks, BitBake executes the task internally and logs information to the
- controlling terminal.
- Future versions of BitBake will write the functions to files similar to the way
- shell tasks are handled.
- Logging will be handled in a way similar to shell tasks as well.
- </para>
-
- <para>
- Once all the tasks have been completed BitBake exits.
- </para>
-
- <para>
- When running a task, BitBake tightly controls the execution environment
- of the build tasks to make sure unwanted contamination from the build machine
- cannot influence the build.
- Consequently, if you do want something to get passed into the build
- task's environment, you must take a few steps:
- <orderedlist>
- <listitem><para>Tell BitBake to load what you want from the environment
- into the data store.
- You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
- variable.
- For example, assume you want to prevent the build system from
- accessing your <filename>$HOME/.ccache</filename> directory.
- The following command tells BitBake to load
- <filename>CCACHE_DIR</filename> from the environment into the data
- store:
- <literallayout class='monospaced'>
- export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
- </literallayout></para></listitem>
- <listitem><para>Tell BitBake to export what you have loaded into the
- environment store to the task environment of every running task.
- Loading something from the environment into the data store
- (previous step) only makes it available in the datastore.
- To export it to the task environment of every running task,
- use a command similar to the following in your
- <filename>local.conf</filename> or distro configuration file:
- <literallayout class='monospaced'>
- export CCACHE_DIR
- </literallayout></para></listitem>
- </orderedlist>
- </para>
-
- <note>
- A side effect of the previous steps is that BitBake records the variable
- as a dependency of the build process in things like the shared state
- checksums.
- If doing so results in unnecessary rebuilds of tasks, you can whitelist the
- variable so that the shared state code ignores the dependency when it creates
- checksums.
- For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
- example in the "<link linkend='checksums'>Checksums (Signatures)</link>" section.
- </note>
- </section>
-
- <section id='ref-bitbake-commandline'>
- <title>BitBake Command Line</title>
-
- <para>
- Following is the BitBake help output:
- </para>
-
- <screen>
-$ bitbake --help
-Usage: bitbake [options] [recipename/target ...]
-
- Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
- It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
- will provide the layer, BBFILES and other configuration information.
-
-Options:
- --version show program's version number and exit
- -h, --help show this help message and exit
- -b BUILDFILE, --buildfile=BUILDFILE
- Execute tasks from a specific .bb recipe directly.
- WARNING: Does not handle any dependencies from other
- recipes.
- -k, --continue Continue as much as possible after an error. While the
- target that failed and anything depending on it cannot
- be built, as much as possible will be built before
- stopping.
- -a, --tryaltconfigs Continue with builds by trying to use alternative
- providers where possible.
- -f, --force Force the specified targets/task to run (invalidating
- any existing stamp file).
- -c CMD, --cmd=CMD Specify the task to execute. The exact options
- available depend on the metadata. Some examples might
- be 'compile' or 'populate_sysroot' or 'listtasks' may
- give a list of the tasks available.
- -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
- Invalidate the stamp for the specified task such as
- 'compile' and then run the default task for the
- specified target(s).
- -r PREFILE, --read=PREFILE
- Read the specified file before bitbake.conf.
- -R POSTFILE, --postread=POSTFILE
- Read the specified file after bitbake.conf.
- -v, --verbose Output more log message data to the terminal.
- -D, --debug Increase the debug level. You can specify this more
- than once.
- -n, --dry-run Don't execute, just go through the motions.
- -S, --dump-signatures
- Don't execute, just dump out the signature
- construction information.
- -p, --parse-only Quit after parsing the BB recipes.
- -s, --show-versions Show current and preferred versions of all recipes.
- -e, --environment Show the global or per-package environment complete
- with information about where variables were
- set/changed.
- -g, --graphviz Save dependency tree information for the specified
- targets in the dot syntax.
- -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
- Assume these dependencies don't exist and are already
- provided (equivalent to ASSUME_PROVIDED). Useful to
- make dependency graphs more appealing
- -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
- Show debug logging for the specified logging domains
- -P, --profile Profile the command and save reports.
- -u UI, --ui=UI The user interface to use (e.g. knotty and taskexp).
- -t SERVERTYPE, --servertype=SERVERTYPE
- Choose which server to use, process or xmlrpc.
- --revisions-changed Set the exit code depending on whether upstream
- floating revisions have changed or not.
- --server-only Run bitbake without a UI, only starting a server
- (cooker) process.
- -B BIND, --bind=BIND The name/address for the bitbake server to bind to.
- --no-setscene Do not run any setscene tasks. sstate will be ignored
- and everything needed, built.
- --remote-server=REMOTE_SERVER
- Connect to the specified server.
- -m, --kill-server Terminate the remote server.
- --observe-only Connect to a server as an observing-only client.
- </screen>
- </section>
-
- <section id='ref-bitbake-fetchers'>
- <title>Fetchers</title>
-
- <para>
- BitBake also contains a set of "fetcher" modules that allow
- retrieval of source code from various types of sources.
- For example, BitBake can get source code from a disk with the metadata, from websites,
- from remote shell accounts, or from Source Code Management (SCM) systems
- like <filename>cvs/subversion/git</filename>.
- </para>
-
- <para>
- Fetchers are usually triggered by entries in
- <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
- You can find information about the options and formats of entries for specific
- fetchers in the BitBake manual located in the
- <filename>bitbake/doc/manual</filename> directory of the
- <link linkend='source-directory'>Source Directory</link>.
- </para>
-
- <para>
- One useful feature for certain Source Code Manager (SCM) fetchers
- is the ability to "auto-update" when the upstream SCM changes
- version.
- Since this ability requires certain functionality from the SCM,
- not all systems support it.
- Currently Subversion, Bazaar and to a limited extent, Git support
- the ability to "auto-update".
- This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
- variable.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>"
- section in the Yocto Project Development Tasks Manual for more
- information.
- </para>
-
- </section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4 spell spelllang=en_gb
--->
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml
index 5961d3e..77f21ed 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml
@@ -35,8 +35,7 @@
<para>
This chapter discusses only the most useful and important classes.
Other classes do exist within the <filename>meta/classes</filename>
- directory in the
- <link linkend='source-directory'>Source Directory</link>.
+ directory in the Source Directory.
You can reference the <filename>.bbclass</filename> files directly
for more information.
</para>
@@ -128,9 +127,8 @@
<para>
By default, the <filename>autotools*</filename> classes
use out-of-tree builds (i.e.
- <filename>autotools.bbclass</filename>).
- (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
- <link linkend='var-S'><filename>S</filename></link>).
+ <filename>autotools.bbclass</filename> building with
+ <filename>B != S</filename>).
</para>
<para>
@@ -357,8 +355,8 @@
history of build output metadata, which can be used to detect possible
regressions as well as used for analysis of the build output.
For more information on using Build History, see the
- "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</section>
@@ -407,8 +405,7 @@
<title><filename>ccache.bbclass</filename></title>
<para>
- The <filename>ccache</filename> class enables the
- <ulink url='http://ccache.samba.org/'>C/C++ Compiler Cache</ulink>
+ The <filename>ccache</filename> class enables the C/C++ Compiler Cache
for the build.
This class is used to give a minor performance boost during the build.
However, using the class can lead to unexpected side-effects.
@@ -568,8 +565,9 @@
provides support for the recipes that build the Canadian
Cross-compilation tools for SDKs.
See the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section for more discussion on these cross-compilation tools.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for more
+ discussion on these cross-compilation tools.
</para>
</section>
@@ -581,8 +579,9 @@
provides support for the recipes that build the cross-compilation
tools used for building SDKs.
See the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section for more discussion on these cross-compilation tools.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for more
+ discussion on these cross-compilation tools.
</para>
</section>
@@ -1249,8 +1248,8 @@
"<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
section in the Yocto Project Development Tasks Manual.
For information on how images are created, see the
- "<link linkend='images-dev-environment'>Images</link>" section elsewhere
- in this manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
+ section in the Yocto Project Overview and Concpets Manual.
</para>
</section>
@@ -1291,7 +1290,7 @@
This class also handles conversion and compression of images.
<note>
To build a VMware VMDK image, you need to add "wic.vmdk" to
- <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
+ <filename>IMAGE_FSTYPES</filename>.
This would also be similar for Virtual Box Virtual Disk Image
("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
</note>
@@ -1552,7 +1551,8 @@
<link linkend='var-FILES'><filename>FILES</filename></link>
variable values that contain "//", which is invalid.
</para></listitem>
- <listitem><para><emphasis><filename>host-user-contaminated:</filename></emphasis>
+ <listitem><para id='insane-host-user-contaminated'>
+ <emphasis><filename>host-user-contaminated:</filename></emphasis>
Checks that no package produced by the recipe contains any
files outside of <filename>/home</filename> with a user or
group ID that matches the user running BitBake.
@@ -1883,6 +1883,17 @@
</para>
</section>
+<section id='ref-classes-kernel-devicetree'>
+ <title><filename>kernel-devicetree.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-devicetree</filename> class, which is inherited by
+ the
+ <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
+ class, supports device tree generation.
+ </para>
+</section>
+
<section id='ref-classes-kernel-fitimage'>
<title><filename>kernel-fitimage.bbclass</filename></title>
@@ -2122,7 +2133,7 @@
<para>
For general information on out-of-tree Linux kernel modules, see the
- "<ulink url='&YOCTO_DOCS_KERNEL_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
section in the Yocto Project Linux Kernel Development Manual.
</para>
</section>
@@ -2709,8 +2720,8 @@
<para>
For more information on the cross-development toolchain
generation, see the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
For information on advantages gained when building a
cross-development toolchain using the
<link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
@@ -3007,8 +3018,8 @@
<para>
For information on how root filesystem images are created, see the
- "<link linkend='image-generation-dev-environment'>Image Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -3169,8 +3180,8 @@
<para>
For more information on sstate, see the
- "<link linkend='shared-state-cache'>Shared State Cache</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-development-environment.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-development-environment.xml
deleted file mode 100644
index 52197d1..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-development-environment.xml
+++ /dev/null
@@ -1,2761 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='ref-development-environment'>
-<title>The Yocto Project Development Environment</title>
-
-<para>
- This chapter takes a look at the Yocto Project development
- environment and also provides a detailed look at what goes on during
- development in that environment.
- The chapter provides Yocto Project Development environment concepts that
- help you understand how work is accomplished in an open source environment,
- which is very different as compared to work accomplished in a closed,
- proprietary environment.
-</para>
-
-<para>
- Specifically, this chapter addresses open source philosophy, workflows,
- Git, source repositories, licensing, recipe syntax, and development
- syntax.
-</para>
-
-<section id='open-source-philosophy'>
- <title>Open Source Philosophy</title>
-
- <para>
- Open source philosophy is characterized by software development
- directed by peer production and collaboration through an active
- community of developers.
- Contrast this to the more standard centralized development models
- used by commercial software companies where a finite set of developers
- produces a product for sale using a defined set of procedures that
- ultimately result in an end product whose architecture and source
- material are closed to the public.
- </para>
-
- <para>
- Open source projects conceptually have differing concurrent agendas,
- approaches, and production.
- These facets of the development process can come from anyone in the
- public (community) that has a stake in the software project.
- The open source environment contains new copyright, licensing, domain,
- and consumer issues that differ from the more traditional development
- environment.
- In an open source environment, the end product, source material,
- and documentation are all available to the public at no cost.
- </para>
-
- <para>
- A benchmark example of an open source project is the Linux kernel,
- which was initially conceived and created by Finnish computer science
- student Linus Torvalds in 1991.
- Conversely, a good example of a non-open source project is the
- <trademark class='registered'>Windows</trademark> family of operating
- systems developed by
- <trademark class='registered'>Microsoft</trademark> Corporation.
- </para>
-
- <para>
- Wikipedia has a good historical description of the Open Source
- Philosophy
- <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
- You can also find helpful information on how to participate in the
- Linux Community
- <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
- </para>
-</section>
-
-<section id='workflows'>
- <title>Workflows</title>
-
- <para>
- This section provides workflow concepts using the Yocto Project and
- Git.
- In particular, the information covers basic practices that describe
- roles and actions in a collaborative development environment.
- <note>
- If you are familiar with this type of development environment, you
- might not want to read this section.
- </note>
- </para>
-
- <para>
- The Yocto Project files are maintained using Git in "master"
- branches whose Git histories track every change and whose structures
- provides branches for all diverging functionality.
- Although there is no need to use Git, many open source projects do so.
- <para>
-
- </para>
- For the Yocto Project, a key individual called the "maintainer" is
- responsible for the "master" branch of a given Git repository.
- The "master" branch is the “upstream” repository from which final or
- most recent builds of the project occur.
- The maintainer is responsible for accepting changes from other
- developers and for organizing the underlying branch structure to
- reflect release strategies and so forth.
- <note>For information on finding out who is responsible for (maintains)
- a particular area of code, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
- section of the Yocto Project Development Tasks Manual.
- </note>
- </para>
-
- <para>
- The Yocto Project <filename>poky</filename> Git repository also has an
- upstream contribution Git repository named
- <filename>poky-contrib</filename>.
- You can see all the branches in this repository using the web interface
- of the
- <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
- within the "Poky Support" area.
- These branches temporarily hold changes to the project that have been
- submitted or committed by the Yocto Project development team and by
- community members who contribute to the project.
- The maintainer determines if the changes are qualified to be moved
- from the "contrib" branches into the "master" branch of the Git
- repository.
- </para>
-
- <para>
- Developers (including contributing community members) create and
- maintain cloned repositories of the upstream "master" branch.
- The cloned repositories are local to their development platforms and
- are used to develop changes.
- When a developer is satisfied with a particular feature or change,
- they "push" the changes to the appropriate "contrib" repository.
- </para>
-
- <para>
- Developers are responsible for keeping their local repository
- up-to-date with "master".
- They are also responsible for straightening out any conflicts that
- might arise within files that are being worked on simultaneously by
- more than one person.
- All this work is done locally on the developer’s machine before
- anything is pushed to a "contrib" area and examined at the maintainer’s
- level.
- </para>
-
- <para>
- A somewhat formal method exists by which developers commit changes
- and push them into the "contrib" area and subsequently request that
- the maintainer include them into "master".
- This process is called “submitting a patch” or "submitting a change."
- For information on submitting patches and changes, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <para>
- To summarize the development workflow: a single point of entry
- exists for changes into the project’s "master" branch of the
- Git repository, which is controlled by the project’s maintainer.
- And, a set of developers exist who independently develop, test, and
- submit changes to "contrib" areas for the maintainer to examine.
- The maintainer then chooses which changes are going to become a
- permanent part of the project.
- </para>
-
- <para>
- <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
- </para>
-
- <para>
- While each development environment is unique, there are some best
- practices or methods that help development run smoothly.
- The following list describes some of these practices.
- For more information about Git workflows, see the workflow topics in
- the
- <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
- <itemizedlist>
- <listitem><para>
- <emphasis>Make Small Changes:</emphasis>
- It is best to keep the changes you commit small as compared to
- bundling many disparate changes into a single commit.
- This practice not only keeps things manageable but also allows
- the maintainer to more easily include or refuse changes.</para>
-
- <para>It is also good practice to leave the repository in a
- state that allows you to still successfully build your project.
- In other words, do not commit half of a feature,
- then add the other half as a separate, later commit.
- Each commit should take you from one buildable project state
- to another buildable state.
- </para></listitem>
- <listitem><para>
- <emphasis>Use Branches Liberally:</emphasis>
- It is very easy to create, use, and delete local branches in
- your working Git repository.
- You can name these branches anything you like.
- It is helpful to give them names associated with the particular
- feature or change on which you are working.
- Once you are done with a feature or change and have merged it
- into your local master branch, simply discard the temporary
- branch.
- </para></listitem>
- <listitem><para>
- <emphasis>Merge Changes:</emphasis>
- The <filename>git merge</filename> command allows you to take
- the changes from one branch and fold them into another branch.
- This process is especially helpful when more than a single
- developer might be working on different parts of the same
- feature.
- Merging changes also automatically identifies any collisions
- or "conflicts" that might happen as a result of the same lines
- of code being altered by two different developers.
- </para></listitem>
- <listitem><para>
- <emphasis>Manage Branches:</emphasis>
- Because branches are easy to use, you should use a system
- where branches indicate varying levels of code readiness.
- For example, you can have a "work" branch to develop in, a
- "test" branch where the code or change is tested, a "stage"
- branch where changes are ready to be committed, and so forth.
- As your project develops, you can merge code across the
- branches to reflect ever-increasing stable states of the
- development.
- </para></listitem>
- <listitem><para>
- <emphasis>Use Push and Pull:</emphasis>
- The push-pull workflow is based on the concept of developers
- "pushing" local commits to a remote repository, which is
- usually a contribution repository.
- This workflow is also based on developers "pulling" known
- states of the project down into their local development
- repositories.
- The workflow easily allows you to pull changes submitted by
- other developers from the upstream repository into your
- work area ensuring that you have the most recent software
- on which to develop.
- The Yocto Project has two scripts named
- <filename>create-pull-request</filename> and
- <filename>send-pull-request</filename> that ship with the
- release to facilitate this workflow.
- You can find these scripts in the <filename>scripts</filename>
- folder of the
- <link linkend='source-directory'>Source Directory</link>.
- For information on how to use these scripts, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>
- <emphasis>Patch Workflow:</emphasis>
- This workflow allows you to notify the maintainer through an
- email that you have a change (or patch) you would like
- considered for the "master" branch of the Git repository.
- To send this type of change, you format the patch and then
- send the email using the Git commands
- <filename>git format-patch</filename> and
- <filename>git send-email</filename>.
- For information on how to use these scripts, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-
-<section id='git'>
- <title>Git</title>
-
- <para>
- The Yocto Project makes extensive use of Git, which is a
- free, open source distributed version control system.
- Git supports distributed development, non-linear development,
- and can handle large projects.
- It is best that you have some fundamental understanding
- of how Git tracks projects and how to work with Git if
- you are going to use the Yocto Project for development.
- This section provides a quick overview of how Git works and
- provides you with a summary of some essential Git commands.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- For more information on Git, see
- <ulink url='http://git-scm.com/documentation'></ulink>.
- </para></listitem>
- <listitem><para>
- If you need to download Git, it is recommended that you add
- Git to your system through your distribution's "software
- store" (e.g. for Ubuntu, use the Ubuntu Software feature).
- For the Git download page, see
- <ulink url='http://git-scm.com/download'></ulink>.
- </para></listitem>
- <listitem><para>
- For examples beyond the limited few in this section on how
- to use Git with the Yocto Project, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <section id='repositories-tags-and-branches'>
- <title>Repositories, Tags, and Branches</title>
-
- <para>
- As mentioned briefly in the previous section and also in the
- "<link linkend='workflows'>Workflows</link>" section,
- the Yocto Project maintains source repositories at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
- If you look at this web-interface of the repositories, each item
- is a separate Git repository.
- </para>
-
- <para>
- Git repositories use branching techniques that track content
- change (not files) within a project (e.g. a new feature or updated
- documentation).
- Creating a tree-like structure based on project divergence allows
- for excellent historical information over the life of a project.
- This methodology also allows for an environment from which you can
- do lots of local experimentation on projects as you develop
- changes or new features.
- </para>
-
- <para>
- A Git repository represents all development efforts for a given
- project.
- For example, the Git repository <filename>poky</filename> contains
- all changes and developments for Poky over the course of its
- entire life.
- That means that all changes that make up all releases are captured.
- The repository maintains a complete history of changes.
- </para>
-
- <para>
- You can create a local copy of any repository by "cloning" it
- with the <filename>git clone</filename> command.
- When you clone a Git repository, you end up with an identical
- copy of the repository on your development system.
- Once you have a local copy of a repository, you can take steps to
- develop locally.
- For examples on how to clone Git repositories, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <para>
- It is important to understand that Git tracks content change and
- not files.
- Git uses "branches" to organize different development efforts.
- For example, the <filename>poky</filename> repository has
- several branches that include the current "&DISTRO_NAME_NO_CAP;"
- branch, the "master" branch, and many branches for past
- Yocto Project releases.
- You can see all the branches by going to
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
- clicking on the
- <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
- link beneath the "Branch" heading.
- </para>
-
- <para>
- Each of these branches represents a specific area of development.
- The "master" branch represents the current or most recent
- development.
- All other branches represent offshoots of the "master" branch.
- </para>
-
- <para>
- When you create a local copy of a Git repository, the copy has
- the same set of branches as the original.
- This means you can use Git to create a local working area
- (also called a branch) that tracks a specific development branch
- from the upstream source Git repository.
- in other words, you can define your local Git environment to
- work on any development branch in the repository.
- To help illustrate, consider the following example Git commands:
- <literallayout class='monospaced'>
- $ cd ~
- $ git clone git://git.yoctoproject.org/poky
- $ cd poky
- $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
- </literallayout>
- In the previous example after moving to the home directory, the
- <filename>git clone</filename> command creates a
- local copy of the upstream <filename>poky</filename> Git repository.
- By default, Git checks out the "master" branch for your work.
- After changing the working directory to the new local repository
- (i.e. <filename>poky</filename>), the
- <filename>git checkout</filename> command creates
- and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which
- tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.
- Changes you make while in this branch would ultimately affect
- the upstream "&DISTRO_NAME_NO_CAP;" branch of the
- <filename>poky</filename> repository.
- </para>
-
- <para>
- It is important to understand that when you create and checkout a
- local working branch based on a branch name,
- your local environment matches the "tip" of that particular
- development branch at the time you created your local branch,
- which could be different from the files in the "master" branch
- of the upstream repository.
- In other words, creating and checking out a local branch based on
- the "&DISTRO_NAME_NO_CAP;" branch name is not the same as
- cloning and checking out the "master" branch if the repository.
- Keep reading to see how you create a local snapshot of a Yocto
- Project Release.
- </para>
-
- <para>
- Git uses "tags" to mark specific changes in a repository.
- Typically, a tag is used to mark a special point such as the final
- change before a project is released.
- You can see the tags used with the <filename>poky</filename> Git
- repository by going to
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
- clicking on the
- <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
- link beneath the "Tag" heading.
- </para>
-
- <para>
- Some key tags for the <filename>poky</filename> are
- <filename>jethro-14.0.3</filename>,
- <filename>morty-16.0.1</filename>,
- <filename>pyro-17.0.0</filename>, and
- <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>.
- These tags represent Yocto Project releases.
- </para>
-
- <para>
- When you create a local copy of the Git repository, you also
- have access to all the tags in the upstream repository.
- Similar to branches, you can create and checkout a local working
- Git branch based on a tag name.
- When you do this, you get a snapshot of the Git repository that
- reflects the state of the files when the change was made associated
- with that tag.
- The most common use is to checkout a working branch that matches
- a specific Yocto Project release.
- Here is an example:
- <literallayout class='monospaced'>
- $ cd ~
- $ git clone git://git.yoctoproject.org/poky
- $ cd poky
- $ git fetch --all --tags --prune
- $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0
- </literallayout>
- In this example, the name of the top-level directory of your
- local Yocto Project repository is <filename>poky</filename>.
- After moving to the <filename>poky</filename> directory, the
- <filename>git fetch</filename> command makes all the upstream
- tags available locally in your repository.
- Finally, the <filename>git checkout</filename> command
- creates and checks out a branch named "my-pyro-17.0.0" that is
- based on the specific change upstream in the repository
- associated with the "pyro-17.0.0" tag.
- The files in your repository now exactly match that particular
- Yocto Project release as it is tagged in the upstream Git
- repository.
- It is important to understand that when you create and
- checkout a local working branch based on a tag, your environment
- matches a specific point in time and not the entire development
- branch (i.e. the "tip" of the branch).
- </para>
- </section>
-
- <section id='basic-commands'>
- <title>Basic Commands</title>
-
- <para>
- Git has an extensive set of commands that lets you manage changes
- and perform collaboration over the life of a project.
- Conveniently though, you can manage with a small set of basic
- operations and workflows once you understand the basic
- philosophy behind Git.
- You do not have to be an expert in Git to be functional.
- A good place to look for instruction on a minimal set of Git
- commands is
- <ulink url='http://git-scm.com/documentation'>here</ulink>.
- </para>
-
- <para>
- If you do not know much about Git, you should educate
- yourself by visiting the links previously mentioned.
- </para>
-
- <para>
- The following list of Git commands briefly describes some basic
- Git operations as a way to get started.
- As with any set of commands, this list (in most cases) simply shows
- the base command and omits the many arguments they support.
- See the Git documentation for complete descriptions and strategies
- on how to use these commands:
- <itemizedlist>
- <listitem><para>
- <emphasis><filename>git init</filename>:</emphasis>
- Initializes an empty Git repository.
- You cannot use Git commands unless you have a
- <filename>.git</filename> repository.
- </para></listitem>
- <listitem><para id='git-commands-clone'>
- <emphasis><filename>git clone</filename>:</emphasis>
- Creates a local clone of a Git repository that is on
- equal footing with a fellow developer’s Git repository
- or an upstream repository.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git add</filename>:</emphasis>
- Locally stages updated file contents to the index that
- Git uses to track changes.
- You must stage all files that have changed before you
- can commit them.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git commit</filename>:</emphasis>
- Creates a local "commit" that documents the changes you
- made.
- Only changes that have been staged can be committed.
- Commits are used for historical purposes, for determining
- if a maintainer of a project will allow the change,
- and for ultimately pushing the change from your local
- Git repository into the project’s upstream repository.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git status</filename>:</emphasis>
- Reports any modified files that possibly need to be
- staged and gives you a status of where you stand regarding
- local commits as compared to the upstream repository.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis>
- Changes your working branch.
- This command is analogous to "cd".
- </para></listitem>
- <listitem><para><emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable>:</emphasis>
- Creates and checks out a working branch on your local
- machine that you can use to isolate your work.
- It is a good idea to use local branches when adding
- specific features or changes.
- Using isolated branches facilitates easy removal of
- changes if they do not work out.
- </para></listitem>
- <listitem><para><emphasis><filename>git branch</filename>:</emphasis>
- Displays the existing local branches associated with your
- local repository.
- The branch that you have currently checked out is noted
- with an asterisk character.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis>
- Deletes an existing local branch.
- You need to be in a local branch other than the one you
- are deleting in order to delete
- <replaceable>branch-name</replaceable>.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git pull</filename>:</emphasis>
- Retrieves information from an upstream Git repository
- and places it in your local Git repository.
- You use this command to make sure you are synchronized with
- the repository from which you are basing changes
- (.e.g. the "master" branch).
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git push</filename>:</emphasis>
- Sends all your committed local changes to the upstream Git
- repository that your local repository is tracking
- (e.g. a contribution repository).
- The maintainer of the project draws from these repositories
- to merge changes (commits) into the appropriate branch
- of project's upstream repository.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git merge</filename>:</emphasis>
- Combines or adds changes from one
- local branch of your repository with another branch.
- When you create a local Git repository, the default branch
- is named "master".
- A typical workflow is to create a temporary branch that is
- based off "master" that you would use for isolated work.
- You would make your changes in that isolated branch,
- stage and commit them locally, switch to the "master"
- branch, and then use the <filename>git merge</filename>
- command to apply the changes from your isolated branch
- into the currently checked out branch (e.g. "master").
- After the merge is complete and if you are done with
- working in that isolated branch, you can safely delete
- the isolated branch.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git cherry-pick</filename>:</emphasis>
- Choose and apply specific commits from one branch
- into another branch.
- There are times when you might not be able to merge
- all the changes in one branch with
- another but need to pick out certain ones.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>gitk</filename>:</emphasis>
- Provides a GUI view of the branches and changes in your
- local Git repository.
- This command is a good way to graphically see where things
- have diverged in your local repository.
- <note>
- You need to install the <filename>gitk</filename>
- package on your development system to use this
- command.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git log</filename>:</emphasis>
- Reports a history of your commits to the repository.
- This report lists all commits regardless of whether you
- have pushed them upstream or not.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>git diff</filename>:</emphasis>
- Displays line-by-line differences between a local
- working file and the same file as understood by Git.
- This command is useful to see what you have changed
- in any given file.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
-
-<section id='yocto-project-repositories'>
- <title>Yocto Project Source Repositories</title>
-
- <para>
- The Yocto Project team maintains complete source repositories for all
- Yocto Project files at
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
- This web-based source code browser is organized into categories by
- function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and
- so forth.
- From the interface, you can click on any particular item in the "Name"
- column and see the URL at the bottom of the page that you need to clone
- a Git repository for that particular item.
- Having a local Git repository of the
- <link linkend='source-directory'>Source Directory</link>, which is
- usually named "poky", allows
- you to make changes, contribute to the history, and ultimately enhance
- the Yocto Project's tools, Board Support Packages, and so forth.
- </para>
-
- <para>
- For any supported release of Yocto Project, you can also go to the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
- select the "Downloads" tab and get a released tarball of the
- <filename>poky</filename> repository or any supported BSP tarballs.
- Unpacking these tarballs gives you a snapshot of the released
- files.
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- The recommended method for setting up the Yocto Project
- <link linkend='source-directory'>Source Directory</link>
- and the files for supported BSPs
- (e.g., <filename>meta-intel</filename>) is to use
- <link linkend='git'>Git</link> to create a local copy of
- the upstream repositories.
- </para></listitem>
- <listitem><para>
- Be sure to always work in matching branches for both
- the selected BSP repository and the
- <link linkend='source-directory'>Source Directory</link>
- (i.e. <filename>poky</filename>) repository.
- For example, if you have checked out the "master" branch
- of <filename>poky</filename> and you are going to use
- <filename>meta-intel</filename>, be sure to checkout the
- "master" branch of <filename>meta-intel</filename>.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- In summary, here is where you can get the project files needed for
- development:
- <itemizedlist>
- <listitem><para id='source-repositories'>
- <emphasis>
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink>
- </emphasis>
- This area contains IDE Plugins, Matchbox, Poky, Poky Support,
- Tools, Yocto Linux Kernel, and Yocto Metadata Layers.
- You can create local copies of Git repositories for each of
- these areas.</para>
-
- <para>
- <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
- For steps on how to view and access these upstream Git
- repositories, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-source-repositories'>Accessing Source Repositories</ulink>"
- Section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para><anchor id='index-downloads' />
- <emphasis>
- <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink>
- </emphasis>
- This is an index of releases such as
- the <trademark class='trade'>Eclipse</trademark>
- Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers
- for cross-development toolchains, and all released versions of
- Yocto Project in the form of images or tarballs.
- Downloading and extracting these files does not produce a local
- copy of the Git repository but rather a snapshot of a
- particular release or image.</para>
-
- <para>
- <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
- For steps on how to view and access these files, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases'>Accessing Index of Releases</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para id='downloads-page'>
- <emphasis>"Downloads" page for the
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
- </emphasis></para>
-
- <para role="writernotes">This section will change due to
- reworking of the YP Website.</para>
-
- <para>The Yocto Project website includes a "Downloads" tab
- that allows you to download any Yocto Project
- release and Board Support Package (BSP) in tarball form.
- The tarballs are similar to those found in the
- <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
-
- <para>
- <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
- For steps on how to use the "Downloads" page, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-downloads-page'>Using the Downloads Page</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-
-<section id='licensing'>
- <title>Licensing</title>
-
- <para>
- Because open source projects are open to the public, they have
- different licensing structures in place.
- License evolution for both Open Source and Free Software has an
- interesting history.
- If you are interested in this history, you can find basic information
- here:
- <itemizedlist>
- <listitem><para>
- <ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
- </para></listitem>
- <listitem><para>
- <ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license history</ulink>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- In general, the Yocto Project is broadly licensed under the
- Massachusetts Institute of Technology (MIT) License.
- MIT licensing permits the reuse of software within proprietary
- software as long as the license is distributed with that software.
- MIT is also compatible with the GNU General Public License (GPL).
- Patches to the Yocto Project follow the upstream licensing scheme.
- You can find information on the MIT license
- <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
- You can find information on the GNU GPL
- <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>here</ulink>.
- </para>
-
- <para>
- When you build an image using the Yocto Project, the build process
- uses a known list of licenses to ensure compliance.
- You can find this list in the
- <link linkend='source-directory'>Source Directory</link> at
- <filename>meta/files/common-licenses</filename>.
- Once the build completes, the list of all licenses found and used
- during that build are kept in the
- <link linkend='build-directory'>Build Directory</link>
- at <filename>tmp/deploy/licenses</filename>.
- </para>
-
- <para>
- If a module requires a license that is not in the base list, the
- build process generates a warning during the build.
- These tools make it easier for a developer to be certain of the
- licenses with which their shipped products must comply.
- However, even with these tools it is still up to the developer to
- resolve potential licensing issues.
- </para>
-
- <para>
- The base list of licenses used by the build process is a combination
- of the Software Package Data Exchange (SPDX) list and the Open
- Source Initiative (OSI) projects.
- <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of
- the Linux Foundation that maintains a specification for a standard
- format for communicating the components, licenses, and copyrights
- associated with a software package.
- <ulink url='http://opensource.org'>OSI</ulink> is a corporation
- dedicated to the Open Source Definition and the effort for reviewing
- and approving licenses that conform to the Open Source Definition
- (OSD).
- </para>
-
- <para>
- You can find a list of the combined SPDX and OSI licenses that the
- Yocto Project uses in the
- <filename>meta/files/common-licenses</filename> directory in your
- <link linkend='source-directory'>Source Directory</link>.
- </para>
-
- <para>
- For information that can help you maintain compliance with various
- open source licensing during the lifecycle of a product created using
- the Yocto Project, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-</section>
-
-<section id='recipe-syntax'>
- <title>Recipe Syntax</title>
-
- <para>
- Understanding recipe file syntax is important for
- writing recipes.
- The following list overviews the basic items that make up a
- BitBake recipe file.
- For more complete BitBake syntax descriptions, see the
- "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
- chapter of the BitBake User Manual.
- <itemizedlist>
- <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
- Variable assignments allow a value to be assigned to a
- variable.
- The assignment can be static text or might include
- the contents of other variables.
- In addition to the assignment, appending and prepending
- operations are also supported.</para>
- <para>The following example shows some of the ways
- you can use variables in recipes:
- <literallayout class='monospaced'>
- S = "${WORKDIR}/postfix-${PV}"
- CFLAGS += "-DNO_ASM"
- SRC_URI_append = " file://fixup.patch"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Functions:</emphasis>
- Functions provide a series of actions to be performed.
- You usually use functions to override the default
- implementation of a task function or to complement
- a default function (i.e. append or prepend to an
- existing function).
- Standard functions use <filename>sh</filename> shell
- syntax, although access to OpenEmbedded variables and
- internal methods are also available.</para>
- <para>The following is an example function from the
- <filename>sed</filename> recipe:
- <literallayout class='monospaced'>
- do_install () {
- autotools_do_install
- install -d ${D}${base_bindir}
- mv ${D}${bindir}/sed ${D}${base_bindir}/sed
- rmdir ${D}${bindir}/
- }
- </literallayout>
- It is also possible to implement new functions that
- are called between existing tasks as long as the
- new functions are not replacing or complementing the
- default functions.
- You can implement functions in Python
- instead of shell.
- Both of these options are not seen in the majority of
- recipes.</para></listitem>
- <listitem><para><emphasis>Keywords:</emphasis>
- BitBake recipes use only a few keywords.
- You use keywords to include common
- functions (<filename>inherit</filename>), load parts
- of a recipe from other files
- (<filename>include</filename> and
- <filename>require</filename>) and export variables
- to the environment (<filename>export</filename>).</para>
- <para>The following example shows the use of some of
- these keywords:
- <literallayout class='monospaced'>
- export POSTCONF = "${STAGING_BINDIR}/postconf"
- inherit autoconf
- require otherfile.inc
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Comments:</emphasis>
- Any lines that begin with the hash character
- (<filename>#</filename>) are treated as comment lines
- and are ignored:
- <literallayout class='monospaced'>
- # This is a comment
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- This next list summarizes the most important and most commonly
- used parts of the recipe syntax.
- For more information on these parts of the syntax, you can
- reference the
- <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
- chapter in the BitBake User Manual.
- <itemizedlist>
- <listitem><para><emphasis>Line Continuation: <filename>\</filename></emphasis> -
- Use the backward slash (<filename>\</filename>)
- character to split a statement over multiple lines.
- Place the slash character at the end of the line that
- is to be continued on the next line:
- <literallayout class='monospaced'>
- VAR = "A really long \
- line"
- </literallayout>
- <note>
- You cannot have any characters including spaces
- or tabs after the slash character.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Using Variables: <filename>${...}</filename></emphasis> -
- Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to
- access the contents of a variable:
- <literallayout class='monospaced'>
- SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
- </literallayout>
- <note>
- It is important to understand that the value of a
- variable expressed in this form does not get
- substituted automatically.
- The expansion of these expressions happens
- on-demand later (e.g. usually when a function that
- makes reference to the variable executes).
- This behavior ensures that the values are most
- appropriate for the context in which they are
- finally used.
- On the rare occasion that you do need the variable
- expression to be expanded immediately, you can use
- the <filename>:=</filename> operator instead of
- <filename>=</filename> when you make the
- assignment, but this is not generally needed.
- </note>
- </para></listitem>
- <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> -
- Use double quotes around the value in all variable
- assignments.
- <literallayout class='monospaced'>
- VAR1 = "${OTHERVAR}"
- VAR2 = "The version is ${PV}"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Conditional Assignment: <filename>?=</filename></emphasis> -
- Conditional assignment is used to assign a value to
- a variable, but only when the variable is currently
- unset.
- Use the question mark followed by the equal sign
- (<filename>?=</filename>) to make a "soft" assignment
- used for conditional assignment.
- Typically, "soft" assignments are used in the
- <filename>local.conf</filename> file for variables
- that are allowed to come through from the external
- environment.
- </para>
- <para>Here is an example where
- <filename>VAR1</filename> is set to "New value" if
- it is currently empty.
- However, if <filename>VAR1</filename> has already been
- set, it remains unchanged:
- <literallayout class='monospaced'>
- VAR1 ?= "New value"
- </literallayout>
- In this next example, <filename>VAR1</filename>
- is left with the value "Original value":
- <literallayout class='monospaced'>
- VAR1 = "Original value"
- VAR1 ?= "New value"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Appending: <filename>+=</filename></emphasis> -
- Use the plus character followed by the equals sign
- (<filename>+=</filename>) to append values to existing
- variables.
- <note>
- This operator adds a space between the existing
- content of the variable and the new content.
- </note></para>
- <para>Here is an example:
- <literallayout class='monospaced'>
- SRC_URI += "file://fix-makefile.patch"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Prepending: <filename>=+</filename></emphasis> -
- Use the equals sign followed by the plus character
- (<filename>=+</filename>) to prepend values to existing
- variables.
- <note>
- This operator adds a space between the new content
- and the existing content of the variable.
- </note></para>
- <para>Here is an example:
- <literallayout class='monospaced'>
- VAR =+ "Starts"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Appending: <filename>_append</filename></emphasis> -
- Use the <filename>_append</filename> operator to
- append values to existing variables.
- This operator does not add any additional space.
- Also, the operator is applied after all the
- <filename>+=</filename>, and
- <filename>=+</filename> operators have been applied and
- after all <filename>=</filename> assignments have
- occurred.
- </para>
- <para>The following example shows the space being
- explicitly added to the start to ensure the appended
- value is not merged with the existing value:
- <literallayout class='monospaced'>
- SRC_URI_append = " file://fix-makefile.patch"
- </literallayout>
- You can also use the <filename>_append</filename>
- operator with overrides, which results in the actions
- only being performed for the specified target or
- machine:
- <literallayout class='monospaced'>
- SRC_URI_append_sh4 = " file://fix-makefile.patch"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Prepending: <filename>_prepend</filename></emphasis> -
- Use the <filename>_prepend</filename> operator to
- prepend values to existing variables.
- This operator does not add any additional space.
- Also, the operator is applied after all the
- <filename>+=</filename>, and
- <filename>=+</filename> operators have been applied and
- after all <filename>=</filename> assignments have
- occurred.
- </para>
- <para>The following example shows the space being
- explicitly added to the end to ensure the prepended
- value is not merged with the existing value:
- <literallayout class='monospaced'>
- CFLAGS_prepend = "-I${S}/myincludes "
- </literallayout>
- You can also use the <filename>_prepend</filename>
- operator with overrides, which results in the actions
- only being performed for the specified target or
- machine:
- <literallayout class='monospaced'>
- CFLAGS_prepend_sh4 = "-I${S}/myincludes "
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Overrides:</emphasis> -
- You can use overrides to set a value conditionally,
- typically based on how the recipe is being built.
- For example, to set the
- <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
- variable's value to "standard/base" for any target
- <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
- except for qemuarm where it should be set to
- "standard/arm-versatile-926ejs", you would do the
- following:
- <literallayout class='monospaced'>
- KBRANCH = "standard/base"
- KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
- </literallayout>
- Overrides are also used to separate alternate values
- of a variable in other situations.
- For example, when setting variables such as
- <link linkend='var-FILES'><filename>FILES</filename></link>
- and
- <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
- that are specific to individual packages produced by
- a recipe, you should always use an override that
- specifies the name of the package.
- </para></listitem>
- <listitem><para><emphasis>Indentation:</emphasis>
- Use spaces for indentation rather than than tabs.
- For shell functions, both currently work.
- However, it is a policy decision of the Yocto Project
- to use tabs in shell functions.
- Realize that some layers have a policy to use spaces
- for all indentation.
- </para></listitem>
- <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> -
- For more advanced processing, it is possible to use
- Python code during variable assignments (e.g.
- search and replacement on a variable).</para>
- <para>You indicate Python code using the
- <filename>${@<replaceable>python_code</replaceable>}</filename>
- syntax for the variable assignment:
- <literallayout class='monospaced'>
- SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Shell Function Syntax:</emphasis>
- Write shell functions as if you were writing a shell
- script when you describe a list of actions to take.
- You should ensure that your script works with a generic
- <filename>sh</filename> and that it does not require
- any <filename>bash</filename> or other shell-specific
- functionality.
- The same considerations apply to various system
- utilities (e.g. <filename>sed</filename>,
- <filename>grep</filename>, <filename>awk</filename>,
- and so forth) that you might wish to use.
- If in doubt, you should check with multiple
- implementations - including those from BusyBox.
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-
-<section id="development-concepts">
- <title>Development Concepts</title>
-
- <para>
- This section takes a more detailed look inside the development
- process.
- The following diagram represents development at a high level.
- The remainder of this chapter expands on the fundamental input, output,
- process, and
- <link linkend='metadata'>Metadata</link>) blocks
- that make up development in the Yocto Project environment.
- </para>
-
- <para id='general-yocto-environment-figure'>
- <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
- </para>
-
- <para>
- In general, development consists of several functional areas:
- <itemizedlist>
- <listitem><para><emphasis>User Configuration:</emphasis>
- Metadata you can use to control the build process.
- </para></listitem>
- <listitem><para><emphasis>Metadata Layers:</emphasis>
- Various layers that provide software, machine, and
- distro Metadata.</para></listitem>
- <listitem><para><emphasis>Source Files:</emphasis>
- Upstream releases, local projects, and SCMs.</para></listitem>
- <listitem><para><emphasis>Build System:</emphasis>
- Processes under the control of
- <link linkend='bitbake-term'>BitBake</link>.
- This block expands on how BitBake fetches source, applies
- patches, completes compilation, analyzes output for package
- generation, creates and tests packages, generates images, and
- generates cross-development tools.</para></listitem>
- <listitem><para><emphasis>Package Feeds:</emphasis>
- Directories containing output packages (RPM, DEB or IPK),
- which are subsequently used in the construction of an image or
- SDK, produced by the build system.
- These feeds can also be copied and shared using a web server or
- other means to facilitate extending or updating existing
- images on devices at runtime if runtime package management is
- enabled.</para></listitem>
- <listitem><para><emphasis>Images:</emphasis>
- Images produced by the development process.
- </para></listitem>
- <listitem><para><emphasis>Application Development SDK:</emphasis>
- Cross-development tools that are produced along with an image
- or separately with BitBake.</para></listitem>
- </itemizedlist>
- </para>
-
- <section id="user-configuration">
- <title>User Configuration</title>
-
- <para>
- User configuration helps define the build.
- Through user configuration, you can tell BitBake the
- target architecture for which you are building the image,
- where to store downloaded source, and other build properties.
- </para>
-
- <para>
- The following figure shows an expanded representation of the
- "User Configuration" box of the
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
- </para>
-
- <para>
- <imagedata fileref="figures/user-configuration.png" align="center" />
- </para>
-
- <para>
- BitBake needs some basic configuration files in order to complete
- a build.
- These files are <filename>*.conf</filename> files.
- The minimally necessary ones reside as example files in the
- <link linkend='source-directory'>Source Directory</link>.
- For simplicity, this section refers to the Source Directory as
- the "Poky Directory."
- </para>
-
- <para>
- When you clone the <filename>poky</filename> Git repository or you
- download and unpack a Yocto Project release, you can set up the
- Source Directory to be named anything you want.
- For this discussion, the cloned repository uses the default
- name <filename>poky</filename>.
- <note>
- The Poky repository is primarily an aggregation of existing
- repositories.
- It is not a canonical upstream source.
- </note>
- </para>
-
- <para>
- The <filename>meta-poky</filename> layer inside Poky contains
- a <filename>conf</filename> directory that has example
- configuration files.
- These example files are used as a basis for creating actual
- configuration files when you source the build environment
- script
- (i.e.
- <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
- </para>
-
- <para>
- Sourcing the build environment script creates a
- <link linkend='build-directory'>Build Directory</link>
- if one does not already exist.
- BitBake uses the Build Directory for all its work during builds.
- The Build Directory has a <filename>conf</filename> directory that
- contains default versions of your <filename>local.conf</filename>
- and <filename>bblayers.conf</filename> configuration files.
- These default configuration files are created only if versions
- do not already exist in the Build Directory at the time you
- source the build environment setup script.
- </para>
-
- <para>
- Because the Poky repository is fundamentally an aggregation of
- existing repositories, some users might be familiar with running
- the <filename>&OE_INIT_FILE;</filename> script in the context
- of separate OpenEmbedded-Core and BitBake repositories rather than a
- single Poky repository.
- This discussion assumes the script is executed from within a cloned
- or unpacked version of Poky.
- </para>
-
- <para>
- Depending on where the script is sourced, different sub-scripts
- are called to set up the Build Directory (Yocto or OpenEmbedded).
- Specifically, the script
- <filename>scripts/oe-setup-builddir</filename> inside the
- poky directory sets up the Build Directory and seeds the directory
- (if necessary) with configuration files appropriate for the
- Yocto Project development environment.
- <note>
- The <filename>scripts/oe-setup-builddir</filename> script
- uses the <filename>$TEMPLATECONF</filename> variable to
- determine which sample configuration files to locate.
- </note>
- </para>
-
- <para>
- The <filename>local.conf</filename> file provides many
- basic variables that define a build environment.
- Here is a list of a few.
- To see the default configurations in a <filename>local.conf</filename>
- file created by the build environment script, see the
- <filename>local.conf.sample</filename> in the
- <filename>meta-poky</filename> layer:
- <itemizedlist>
- <listitem><para><emphasis>Parallelism Options:</emphasis>
- Controlled by the
- <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>,
- <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>,
- and
- <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
- variables.</para></listitem>
- <listitem><para><emphasis>Target Machine Selection:</emphasis>
- Controlled by the
- <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
- variable.</para></listitem>
- <listitem><para><emphasis>Download Directory:</emphasis>
- Controlled by the
- <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
- variable.</para></listitem>
- <listitem><para><emphasis>Shared State Directory:</emphasis>
- Controlled by the
- <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
- variable.</para></listitem>
- <listitem><para><emphasis>Build Output:</emphasis>
- Controlled by the
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
- variable.</para></listitem>
- </itemizedlist>
- <note>
- Configurations set in the <filename>conf/local.conf</filename>
- file can also be set in the
- <filename>conf/site.conf</filename> and
- <filename>conf/auto.conf</filename> configuration files.
- </note>
- </para>
-
- <para>
- The <filename>bblayers.conf</filename> file tells BitBake what
- layers you want considered during the build.
- By default, the layers listed in this file include layers
- minimally needed by the build system.
- However, you must manually add any custom layers you have created.
- You can find more information on working with the
- <filename>bblayers.conf</filename> file in the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <para>
- The files <filename>site.conf</filename> and
- <filename>auto.conf</filename> are not created by the environment
- initialization script.
- If you want the <filename>site.conf</filename> file, you need to
- create that yourself.
- The <filename>auto.conf</filename> file is typically created by
- an autobuilder:
- <itemizedlist>
- <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
- You can use the <filename>conf/site.conf</filename>
- configuration file to configure multiple build directories.
- For example, suppose you had several build environments and
- they shared some common features.
- You can set these default build properties here.
- A good example is perhaps the packaging format to use
- through the
- <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
- variable.</para>
- <para>One useful scenario for using the
- <filename>conf/site.conf</filename> file is to extend your
- <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
- variable to include the path to a
- <filename>conf/site.conf</filename>.
- Then, when BitBake looks for Metadata using
- <filename>BBPATH</filename>, it finds the
- <filename>conf/site.conf</filename> file and applies your
- common configurations found in the file.
- To override configurations in a particular build directory,
- alter the similar configurations within that build
- directory's <filename>conf/local.conf</filename> file.
- </para></listitem>
- <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
- The file is usually created and written to by
- an autobuilder.
- The settings put into the file are typically the same as
- you would find in the <filename>conf/local.conf</filename>
- or the <filename>conf/site.conf</filename> files.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- You can edit all configuration files to further define
- any particular build environment.
- This process is represented by the "User Configuration Edits"
- box in the figure.
- </para>
-
- <para>
- When you launch your build with the
- <filename>bitbake <replaceable>target</replaceable></filename>
- command, BitBake sorts out the configurations to ultimately
- define your build environment.
- It is important to understand that the OpenEmbedded build system
- reads the configuration files in a specific order:
- <filename>site.conf</filename>, <filename>auto.conf</filename>,
- and <filename>local.conf</filename>.
- And, the build system applies the normal assignment statement
- rules.
- Because the files are parsed in a specific order, variable
- assignments for the same variable could be affected.
- For example, if the <filename>auto.conf</filename> file and
- the <filename>local.conf</filename> set
- <replaceable>variable1</replaceable> to different values, because
- the build system parses <filename>local.conf</filename> after
- <filename>auto.conf</filename>,
- <replaceable>variable1</replaceable> is assigned the value from
- the <filename>local.conf</filename> file.
- </para>
- </section>
-
- <section id="metadata-machine-configuration-and-policy-configuration">
- <title>Metadata, Machine Configuration, and Policy Configuration</title>
-
- <para>
- The previous section described the user configurations that
- define BitBake's global behavior.
- This section takes a closer look at the layers the build system
- uses to further control the build.
- These layers provide Metadata for the software, machine, and
- policy.
- </para>
-
- <para>
- In general, three types of layer input exist:
- <itemizedlist>
- <listitem><para><emphasis>Policy Configuration:</emphasis>
- Distribution Layers provide top-level or general
- policies for the image or SDK being built.
- For example, this layer would dictate whether BitBake
- produces RPM or IPK packages.</para></listitem>
- <listitem><para><emphasis>Machine Configuration:</emphasis>
- Board Support Package (BSP) layers provide machine
- configurations.
- This type of information is specific to a particular
- target architecture.</para></listitem>
- <listitem><para><emphasis>Metadata:</emphasis>
- Software layers contain user-supplied recipe files,
- patches, and append files.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The following figure shows an expanded representation of the
- Metadata, Machine Configuration, and Policy Configuration input
- (layers) boxes of the
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
- </para>
-
- <para>
- <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
- </para>
-
- <para>
- In general, all layers have a similar structure.
- They all contain a licensing file
- (e.g. <filename>COPYING</filename>) if the layer is to be
- distributed, a <filename>README</filename> file as good practice
- and especially if the layer is to be distributed, a
- configuration directory, and recipe directories.
- </para>
-
- <para>
- The Yocto Project has many layers that can be used.
- You can see a web-interface listing of them on the
- <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
- page.
- The layers are shown at the bottom categorized under
- "Yocto Metadata Layers."
- These layers are fundamentally a subset of the
- <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
- which lists all layers provided by the OpenEmbedded community.
- <note>
- Layers exist in the Yocto Project Source Repositories that
- cannot be found in the OpenEmbedded Metadata Index.
- These layers are either deprecated or experimental in nature.
- </note>
- </para>
-
- <para>
- BitBake uses the <filename>conf/bblayers.conf</filename> file,
- which is part of the user configuration, to find what layers it
- should be using as part of the build.
- </para>
-
- <para>
- For more information on layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <section id="distro-layer">
- <title>Distro Layer</title>
-
- <para>
- The distribution layer provides policy configurations for your
- distribution.
- Best practices dictate that you isolate these types of
- configurations into their own layer.
- Settings you provide in
- <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override
- similar
- settings that BitBake finds in your
- <filename>conf/local.conf</filename> file in the Build
- Directory.
- </para>
-
- <para>
- The following list provides some explanation and references
- for what you typically find in the distribution layer:
- <itemizedlist>
- <listitem><para><emphasis>classes:</emphasis>
- Class files (<filename>.bbclass</filename>) hold
- common functionality that can be shared among
- recipes in the distribution.
- When your recipes inherit a class, they take on the
- settings and functions for that class.
- You can read more about class files in the
- "<link linkend='ref-classes'>Classes</link>" section.
- </para></listitem>
- <listitem><para><emphasis>conf:</emphasis>
- This area holds configuration files for the
- layer (<filename>conf/layer.conf</filename>),
- the distribution
- (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>),
- and any distribution-wide include files.
- </para></listitem>
- <listitem><para><emphasis>recipes-*:</emphasis>
- Recipes and append files that affect common
- functionality across the distribution.
- This area could include recipes and append files
- to add distribution-specific configuration,
- initialization scripts, custom image recipes,
- and so forth.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="bsp-layer">
- <title>BSP Layer</title>
-
- <para>
- The BSP Layer provides machine configurations.
- Everything in this layer is specific to the machine for which
- you are building the image or the SDK.
- A common structure or form is defined for BSP layers.
- You can learn more about this structure in the
- <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
- <note>
- In order for a BSP layer to be considered compliant with the
- Yocto Project, it must meet some structural requirements.
- </note>
- </para>
-
- <para>
- The BSP Layer's configuration directory contains
- configuration files for the machine
- (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>) and,
- of course, the layer (<filename>conf/layer.conf</filename>).
- </para>
-
- <para>
- The remainder of the layer is dedicated to specific recipes
- by function: <filename>recipes-bsp</filename>,
- <filename>recipes-core</filename>,
- <filename>recipes-graphics</filename>, and
- <filename>recipes-kernel</filename>.
- Metadata can exist for multiple formfactors, graphics
- support systems, and so forth.
- <note>
- While the figure shows several <filename>recipes-*</filename>
- directories, not all these directories appear in all
- BSP layers.
- </note>
- </para>
- </section>
-
- <section id="software-layer">
- <title>Software Layer</title>
-
- <para>
- The software layer provides the Metadata for additional
- software packages used during the build.
- This layer does not include Metadata that is specific to the
- distribution or the machine, which are found in their
- respective layers.
- </para>
-
- <para>
- This layer contains any new recipes that your project needs
- in the form of recipe files.
- </para>
- </section>
- </section>
-
- <section id="sources-dev-environment">
- <title>Sources</title>
-
- <para>
- In order for the OpenEmbedded build system to create an image or
- any target, it must be able to access source files.
- The
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
- represents source files using the "Upstream Project Releases",
- "Local Projects", and "SCMs (optional)" boxes.
- The figure represents mirrors, which also play a role in locating
- source files, with the "Source Mirror(s)" box.
- </para>
-
- <para>
- The method by which source files are ultimately organized is
- a function of the project.
- For example, for released software, projects tend to use tarballs
- or other archived files that can capture the state of a release
- guaranteeing that it is statically represented.
- On the other hand, for a project that is more dynamic or
- experimental in nature, a project might keep source files in a
- repository controlled by a Source Control Manager (SCM) such as
- Git.
- Pulling source from a repository allows you to control
- the point in the repository (the revision) from which you want to
- build software.
- Finally, a combination of the two might exist, which would give the
- consumer a choice when deciding where to get source files.
- </para>
-
- <para>
- BitBake uses the
- <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
- variable to point to source files regardless of their location.
- Each recipe must have a <filename>SRC_URI</filename> variable
- that points to the source.
- </para>
-
- <para>
- Another area that plays a significant role in where source files
- come from is pointed to by the
- <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
- variable.
- This area is a cache that can hold previously downloaded source.
- You can also instruct the OpenEmbedded build system to create
- tarballs from Git repositories, which is not the default behavior,
- and store them in the <filename>DL_DIR</filename> by using the
- <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
- variable.
- </para>
-
- <para>
- Judicious use of a <filename>DL_DIR</filename> directory can
- save the build system a trip across the Internet when looking
- for files.
- A good method for using a download directory is to have
- <filename>DL_DIR</filename> point to an area outside of your
- Build Directory.
- Doing so allows you to safely delete the Build Directory
- if needed without fear of removing any downloaded source file.
- </para>
-
- <para>
- The remainder of this section provides a deeper look into the
- source files and the mirrors.
- Here is a more detailed look at the source file area of the
- base figure:
- <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
- </para>
-
- <section id='upstream-project-releases'>
- <title>Upstream Project Releases</title>
-
- <para>
- Upstream project releases exist anywhere in the form of an
- archived file (e.g. tarball or zip file).
- These files correspond to individual recipes.
- For example, the figure uses specific releases each for
- BusyBox, Qt, and Dbus.
- An archive file can be for any released product that can be
- built using a recipe.
- </para>
- </section>
-
- <section id='local-projects'>
- <title>Local Projects</title>
-
- <para>
- Local projects are custom bits of software the user provides.
- These bits reside somewhere local to a project - perhaps
- a directory into which the user checks in items (e.g.
- a local directory containing a development source tree
- used by the group).
- </para>
-
- <para>
- The canonical method through which to include a local project
- is to use the
- <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
- class to include that local project.
- You use either the <filename>local.conf</filename> or a
- recipe's append file to override or set the
- recipe to point to the local directory on your disk to pull
- in the whole source tree.
- </para>
-
- <para>
- For information on how to use the
- <filename>externalsrc</filename> class, see the
- "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
- section.
- </para>
- </section>
-
- <section id='scms'>
- <title>Source Control Managers (Optional)</title>
-
- <para>
- Another place the build system can get source files from is
- through an SCM such as Git or Subversion.
- In this case, a repository is cloned or checked out.
- The
- <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
- task inside BitBake uses
- the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
- variable and the argument's prefix to determine the correct
- fetcher module.
- </para>
-
- <note>
- For information on how to have the OpenEmbedded build system
- generate tarballs for Git repositories and place them in the
- <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
- directory, see the
- <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
- variable.
- </note>
-
- <para>
- When fetching a repository, BitBake uses the
- <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
- variable to determine the specific revision from which to
- build.
- </para>
- </section>
-
- <section id='source-mirrors'>
- <title>Source Mirror(s)</title>
-
- <para>
- Two kinds of mirrors exist: pre-mirrors and regular mirrors.
- The <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
- and
- <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
- variables point to these, respectively.
- BitBake checks pre-mirrors before looking upstream for any
- source files.
- Pre-mirrors are appropriate when you have a shared directory
- that is not a directory defined by the
- <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
- variable.
- A Pre-mirror typically points to a shared directory that is
- local to your organization.
- </para>
-
- <para>
- Regular mirrors can be any site across the Internet that is
- used as an alternative location for source code should the
- primary site not be functioning for some reason or another.
- </para>
- </section>
- </section>
-
- <section id="package-feeds-dev-environment">
- <title>Package Feeds</title>
-
- <para>
- When the OpenEmbedded build system generates an image or an SDK,
- it gets the packages from a package feed area located in the
- <link linkend='build-directory'>Build Directory</link>.
- The
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
- shows this package feeds area in the upper-right corner.
- </para>
-
- <para>
- This section looks a little closer into the package feeds area used
- by the build system.
- Here is a more detailed look at the area:
- <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
- </para>
-
- <para>
- Package feeds are an intermediary step in the build process.
- The OpenEmbedded build system provides classes to generate
- different package types, and you specify which classes to enable
- through the
- <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
- variable.
- Before placing the packages into package feeds,
- the build process validates them with generated output quality
- assurance checks through the
- <link linkend='ref-classes-insane'><filename>insane</filename></link>
- class.
- </para>
-
- <para>
- The package feed area resides in the Build Directory.
- The directory the build system uses to temporarily store packages
- is determined by a combination of variables and the particular
- package manager in use.
- See the "Package Feeds" box in the illustration and note the
- information to the right of that area.
- In particular, the following defines where package files are
- kept:
- <itemizedlist>
- <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
- Defined as <filename>tmp/deploy</filename> in the Build
- Directory.
- </para></listitem>
- <listitem><para><filename>DEPLOY_DIR_*</filename>:
- Depending on the package manager used, the package type
- sub-folder.
- Given RPM, IPK, or DEB packaging and tarball creation, the
- <link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link>,
- <link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link>,
- <link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link>,
- or
- <link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link>,
- variables are used, respectively.
- </para></listitem>
- <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>:
- Defines architecture-specific sub-folders.
- For example, packages could exist for the i586 or qemux86
- architectures.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- BitBake uses the <filename>do_package_write_*</filename> tasks to
- generate packages and place them into the package holding area (e.g.
- <filename>do_package_write_ipk</filename> for IPK packages).
- See the
- "<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>",
- "<link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>",
- "<link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>",
- and
- "<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>"
- sections for additional information.
- As an example, consider a scenario where an IPK packaging manager
- is being used and package architecture support for both i586
- and qemux86 exist.
- Packages for the i586 architecture are placed in
- <filename>build/tmp/deploy/ipk/i586</filename>, while packages for
- the qemux86 architecture are placed in
- <filename>build/tmp/deploy/ipk/qemux86</filename>.
- </para>
- </section>
-
- <section id='bitbake-dev-environment'>
- <title>BitBake</title>
-
- <para>
- The OpenEmbedded build system uses
- <link linkend='bitbake-term'>BitBake</link>
- to produce images.
- You can see from the
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
- the BitBake area consists of several functional areas.
- This section takes a closer look at each of those areas.
- </para>
-
- <para>
- Separate documentation exists for the BitBake tool.
- See the
- <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>
- for reference material on BitBake.
- </para>
-
- <section id='source-fetching-dev-environment'>
- <title>Source Fetching</title>
-
- <para>
- The first stages of building a recipe are to fetch and unpack
- the source code:
- <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
- </para>
-
- <para>
- The
- <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
- and
- <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
- tasks fetch the source files and unpack them into the work
- directory.
- <note>
- For every local file (e.g. <filename>file://</filename>)
- that is part of a recipe's
- <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
- statement, the OpenEmbedded build system takes a checksum
- of the file for the recipe and inserts the checksum into
- the signature for the <filename>do_fetch</filename>.
- If any local file has been modified, the
- <filename>do_fetch</filename> task and all tasks that
- depend on it are re-executed.
- </note>
- By default, everything is accomplished in the
- <link linkend='build-directory'>Build Directory</link>,
- which has a defined structure.
- For additional general information on the Build Directory,
- see the
- "<link linkend='structure-core-build'><filename>build/</filename></link>"
- section.
- </para>
-
- <para>
- Unpacked source files are pointed to by the
- <link linkend='var-S'><filename>S</filename></link> variable.
- Each recipe has an area in the Build Directory where the
- unpacked source code resides.
- The name of that directory for any given recipe is defined from
- several different variables.
- You can see the variables that define these directories
- by looking at the figure:
- <itemizedlist>
- <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> -
- The base directory where the OpenEmbedded build system
- performs all its work during the build.
- </para></listitem>
- <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link> -
- The architecture of the built package or packages.
- </para></listitem>
- <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link> -
- The operating system of the target device.
- </para></listitem>
- <listitem><para><link linkend='var-PN'><filename>PN</filename></link> -
- The name of the built package.
- </para></listitem>
- <listitem><para><link linkend='var-PV'><filename>PV</filename></link> -
- The version of the recipe used to build the package.
- </para></listitem>
- <listitem><para><link linkend='var-PR'><filename>PR</filename></link> -
- The revision of the recipe used to build the package.
- </para></listitem>
- <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> -
- The location within <filename>TMPDIR</filename> where
- a specific package is built.
- </para></listitem>
- <listitem><para><link linkend='var-S'><filename>S</filename></link> -
- Contains the unpacked source files for a given recipe.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='patching-dev-environment'>
- <title>Patching</title>
-
- <para>
- Once source code is fetched and unpacked, BitBake locates
- patch files and applies them to the source files:
- <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
- </para>
-
- <para>
- The
- <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
- task processes recipes by
- using the
- <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
- variable to locate applicable patch files, which by default
- are <filename>*.patch</filename> or
- <filename>*.diff</filename> files, or any file if
- "apply=yes" is specified for the file in
- <filename>SRC_URI</filename>.
- </para>
-
- <para>
- BitBake finds and applies multiple patches for a single recipe
- in the order in which it finds the patches.
- Patches are applied to the recipe's source files located in the
- <link linkend='var-S'><filename>S</filename></link> directory.
- </para>
-
- <para>
- For more information on how the source directories are
- created, see the
- "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
- section.
- </para>
- </section>
-
- <section id='configuration-and-compilation-dev-environment'>
- <title>Configuration and Compilation</title>
-
- <para>
- After source code is patched, BitBake executes tasks that
- configure and compile the source code:
- <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
- </para>
-
- <para>
- This step in the build process consists of three tasks:
- <itemizedlist>
- <listitem><para>
- <emphasis><link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>:</emphasis>
- This task sets up the two sysroots in
- <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>
- (i.e. <filename>recipe-sysroot</filename> and
- <filename>recipe-sysroot-native</filename>) so that
- the sysroots contain the contents of the
- <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
- tasks of the recipes on which the recipe
- containing the tasks depends.
- A sysroot exists for both the target and for the native
- binaries, which run on the host system.
- </para></listitem>
- <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
- This task configures the source by enabling and
- disabling any build-time and configuration options for
- the software being built.
- Configurations can come from the recipe itself as well
- as from an inherited class.
- Additionally, the software itself might configure itself
- depending on the target for which it is being built.
- </para>
-
- <para>The configurations handled by the
- <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
- task are specific
- to source code configuration for the source code
- being built by the recipe.</para>
-
- <para>If you are using the
- <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
- class,
- you can add additional configuration options by using
- the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
- or
- <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
- variables.
- For information on how this variable works within
- that class, see the
- <filename>meta/classes/autotools.bbclass</filename> file.
- </para></listitem>
- <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
- Once a configuration task has been satisfied, BitBake
- compiles the source using the
- <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
- task.
- Compilation occurs in the directory pointed to by the
- <link linkend='var-B'><filename>B</filename></link>
- variable.
- Realize that the <filename>B</filename> directory is, by
- default, the same as the
- <link linkend='var-S'><filename>S</filename></link>
- directory.</para></listitem>
- <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
- Once compilation is done, BitBake executes the
- <link linkend='ref-tasks-install'><filename>do_install</filename></link>
- task.
- This task copies files from the <filename>B</filename>
- directory and places them in a holding area pointed to
- by the
- <link linkend='var-D'><filename>D</filename></link>
- variable.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='package-splitting-dev-environment'>
- <title>Package Splitting</title>
-
- <para>
- After source code is configured and compiled, the
- OpenEmbedded build system analyzes
- the results and splits the output into packages:
- <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
- </para>
-
- <para>
- The
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- and
- <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
- tasks combine to analyze
- the files found in the
- <link linkend='var-D'><filename>D</filename></link> directory
- and split them into subsets based on available packages and
- files.
- The analyzing process involves the following as well as other
- items: splitting out debugging symbols,
- looking at shared library dependencies between packages,
- and looking at package relationships.
- The <filename>do_packagedata</filename> task creates package
- metadata based on the analysis such that the
- OpenEmbedded build system can generate the final packages.
- Working, staged, and intermediate results of the analysis
- and package splitting process use these areas:
- <itemizedlist>
- <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link> -
- The destination directory for packages before they are
- split.
- </para></listitem>
- <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> -
- A shared, global-state directory that holds data
- generated during the packaging process.
- </para></listitem>
- <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link> -
- A temporary work area used by the
- <filename>do_package</filename> task.
- </para></listitem>
- <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link> -
- The parent directory for packages after they have
- been split.
- </para></listitem>
- </itemizedlist>
- The <link linkend='var-FILES'><filename>FILES</filename></link>
- variable defines the files that go into each package in
- <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
- If you want details on how this is accomplished, you can
- look at the
- <link linkend='ref-classes-package'><filename>package</filename></link>
- class.
- </para>
-
- <para>
- Depending on the type of packages being created (RPM, DEB, or
- IPK), the <filename>do_package_write_*</filename> task
- creates the actual packages and places them in the
- Package Feed area, which is
- <filename>${TMPDIR}/deploy</filename>.
- You can see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section for more detail on that part of the build process.
- <note>
- Support for creating feeds directly from the
- <filename>deploy/*</filename> directories does not exist.
- Creating such feeds usually requires some kind of feed
- maintenance mechanism that would upload the new packages
- into an official package feed (e.g. the
- Ångström distribution).
- This functionality is highly distribution-specific
- and thus is not provided out of the box.
- </note>
- </para>
- </section>
-
- <section id='image-generation-dev-environment'>
- <title>Image Generation</title>
-
- <para>
- Once packages are split and stored in the Package Feeds area,
- the OpenEmbedded build system uses BitBake to generate the
- root filesystem image:
- <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
- </para>
-
- <para>
- The image generation process consists of several stages and
- depends on several tasks and variables.
- The
- <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
- task creates the root filesystem (file and directory structure)
- for an image.
- This task uses several key variables to help create the list
- of packages to actually install:
- <itemizedlist>
- <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
- Lists out the base set of packages to install from
- the Package Feeds area.</para></listitem>
- <listitem><para><link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>:
- Specifies packages that should not be installed.
- </para></listitem>
- <listitem><para><link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
- Specifies features to include in the image.
- Most of these features map to additional packages for
- installation.</para></listitem>
- <listitem><para><link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>:
- Specifies the package backend to use and consequently
- helps determine where to locate packages within the
- Package Feeds area.</para></listitem>
- <listitem><para><link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>:
- Determines the language(s) for which additional
- language support packages are installed.
- </para></listitem>
- <listitem><para><link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>:
- The final list of packages passed to the package manager
- for installation into the image.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- With
- <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
- pointing to the location of the filesystem under construction and
- the <filename>PACKAGE_INSTALL</filename> variable providing the
- final list of packages to install, the root file system is
- created.
- </para>
-
- <para>
- Package installation is under control of the package manager
- (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or
- not package management is enabled for the target.
- At the end of the process, if package management is not
- enabled for the target, the package manager's data files
- are deleted from the root filesystem.
- As part of the final stage of package installation, postinstall
- scripts that are part of the packages are run.
- Any scripts that fail to run
- on the build host are run on the target when the target system
- is first booted.
- If you are using a
- <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
- all the post installation scripts must succeed during the
- package installation phase since the root filesystem is
- read-only.
- </para>
-
- <para>
- The final stages of the <filename>do_rootfs</filename> task
- handle post processing.
- Post processing includes creation of a manifest file and
- optimizations.
- </para>
-
- <para>
- The manifest file (<filename>.manifest</filename>) resides
- in the same directory as the root filesystem image.
- This file lists out, line-by-line, the installed packages.
- The manifest file is useful for the
- <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
- class, for example, to determine whether or not to run
- specific tests.
- See the
- <link linkend='var-IMAGE_MANIFEST'><filename>IMAGE_MANIFEST</filename></link>
- variable for additional information.
- </para>
-
- <para>
- Optimizing processes run across the image include
- <filename>mklibs</filename>, <filename>prelink</filename>,
- and any other post-processing commands as defined by the
- <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>
- variable.
- The <filename>mklibs</filename> process optimizes the size
- of the libraries, while the
- <filename>prelink</filename> process optimizes the dynamic
- linking of shared libraries to reduce start up time of
- executables.
- </para>
-
- <para>
- After the root filesystem is built, processing begins on
- the image through the
- <link linkend='ref-tasks-image'><filename>do_image</filename></link>
- task.
- The build system runs any pre-processing commands as defined
- by the
- <link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link>
- variable.
- This variable specifies a list of functions to call before
- the OpenEmbedded build system creates the final image output
- files.
- </para>
-
- <para>
- The OpenEmbedded build system dynamically creates
- <filename>do_image_*</filename> tasks as needed, based
- on the image types specified in the
- <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
- variable.
- The process turns everything into an image file or a set of
- image files and compresses the root filesystem image to reduce
- the overall size of the image.
- The formats used for the root filesystem depend on the
- <filename>IMAGE_FSTYPES</filename> variable.
- </para>
-
- <para>
- As an example, a dynamically created task when creating a
- particular image <replaceable>type</replaceable> would take the
- following form:
- <literallayout class='monospaced'>
- do_image_<replaceable>type</replaceable>[depends]
- </literallayout>
- So, if the <replaceable>type</replaceable> as specified by the
- <filename>IMAGE_FSTYPES</filename> were
- <filename>ext4</filename>, the dynamically generated task
- would be as follows:
- <literallayout class='monospaced'>
- do_image_ext4[depends]
- </literallayout>
- </para>
-
- <para>
- The final task involved in image creation is the
- <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link>
- task.
- This task completes the image by applying any image
- post processing as defined through the
- <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>
- variable.
- The variable specifies a list of functions to call once the
- OpenEmbedded build system has created the final image output
- files.
- </para>
-
- <note>
- The entire image generation process is run under Pseudo.
- Running under Pseudo ensures that the files in the root
- filesystem have correct ownership.
- </note>
- </section>
-
- <section id='sdk-generation-dev-environment'>
- <title>SDK Generation</title>
-
- <para>
- The OpenEmbedded build system uses BitBake to generate the
- Software Development Kit (SDK) installer script for both the
- standard and extensible SDKs:
- <imagedata fileref="figures/sdk-generation.png" align="center" />
- </para>
-
- <note>
- For more information on the cross-development toolchain
- generation, see the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section.
- For information on advantages gained when building a
- cross-development toolchain using the
- <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
- task, see the
- "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
- section in the Yocto Project Application Development and the
- Extensible Software Development Kit (SDK) manual.
- </note>
-
- <para>
- Like image generation, the SDK script process consists of
- several stages and depends on many variables.
- The <filename>do_populate_sdk</filename> and
- <filename>do_populate_sdk_ext</filename> tasks use these
- key variables to help create the list of packages to actually
- install.
- For information on the variables listed in the figure, see the
- "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
- section.
- </para>
-
- <para>
- The <filename>do_populate_sdk</filename> task helps create
- the standard SDK and handles two parts: a target part and a
- host part.
- The target part is the part built for the target hardware and
- includes libraries and headers.
- The host part is the part of the SDK that runs on the
- <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
- </para>
-
- <para>
- The <filename>do_populate_sdk_ext</filename> task helps create
- the extensible SDK and handles host and target parts
- differently than its counter part does for the standard SDK.
- For the extensible SDK, the task encapsulates the build system,
- which includes everything needed (host and target) for the SDK.
- </para>
-
- <para>
- Regardless of the type of SDK being constructed, the
- tasks perform some cleanup after which a cross-development
- environment setup script and any needed configuration files
- are created.
- The final output is the Cross-development
- toolchain installation script (<filename>.sh</filename> file),
- which includes the environment setup script.
- </para>
- </section>
-
- <section id='stamp-files-and-the-rerunning-of-tasks'>
- <title>Stamp Files and the Rerunning of Tasks</title>
-
- <para>
- For each task that completes successfully, BitBake writes a
- stamp file into the
- <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>
- directory.
- The beginning of the stamp file's filename is determined by the
- <link linkend='var-STAMP'><filename>STAMP</filename></link>
- variable, and the end of the name consists of the task's name
- and current
- <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksum</ulink>.
- <note>
- This naming scheme assumes that
- <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink>
- is "OEBasicHash", which is almost always the case in
- current OpenEmbedded.
- </note>
- To determine if a task needs to be rerun, BitBake checks if a
- stamp file with a matching input checksum exists for the task.
- If such a stamp file exists, the task's output is assumed to
- exist and still be valid.
- If the file does not exist, the task is rerun.
- <note>
- <para>The stamp mechanism is more general than the shared
- state (sstate) cache mechanism described in the
- "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>"
- section.
- BitBake avoids rerunning any task that has a valid
- stamp file, not just tasks that can be accelerated through
- the sstate cache.</para>
- <para>However, you should realize that stamp files only
- serve as a marker that some work has been done and that
- these files do not record task output.
- The actual task output would usually be somewhere in
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
- (e.g. in some recipe's
- <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.)
- What the sstate cache mechanism adds is a way to cache task
- output that can then be shared between build machines.
- </para>
- </note>
- Since <filename>STAMPS_DIR</filename> is usually a subdirectory
- of <filename>TMPDIR</filename>, removing
- <filename>TMPDIR</filename> will also remove
- <filename>STAMPS_DIR</filename>, which means tasks will
- properly be rerun to repopulate <filename>TMPDIR</filename>.
- </para>
-
- <para>
- If you want some task to always be considered "out of date",
- you can mark it with the
- <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink>
- varflag.
- If some other task depends on such a task, then that task will
- also always be considered out of date, which might not be what
- you want.
- </para>
-
- <para>
- For details on how to view information about a task's
- signature, see the
- "<link linkend='usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
- section.
- </para>
- </section>
-
- <section id='setscene-tasks-and-shared-state'>
- <title>Setscene Tasks and Shared State</title>
-
- <para>
- The description of tasks so far assumes that BitBake needs to
- build everything and there are no prebuilt objects available.
- BitBake does support skipping tasks if prebuilt objects are
- available.
- These objects are usually made available in the form of a
- shared state (sstate) cache.
- <note>
- For information on variables affecting sstate, see the
- <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
- and
- <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
- variables.
- </note>
- </para>
-
- <para>
- The idea of a setscene task (i.e
- <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>)
- is a version of the task where
- instead of building something, BitBake can skip to the end
- result and simply place a set of files into specific locations
- as needed.
- In some cases, it makes sense to have a setscene task variant
- (e.g. generating package files in the
- <filename>do_package_write_*</filename> task).
- In other cases, it does not make sense, (e.g. a
- <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
- task or
- <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
- task) since the work involved would be equal to or greater than
- the underlying task.
- </para>
-
- <para>
- In the OpenEmbedded build system, the common tasks that have
- setscene variants are <link linkend='ref-tasks-package'><filename>do_package</filename></link>,
- <filename>do_package_write_*</filename>,
- <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>,
- <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>,
- and
- <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>.
- Notice that these are most of the tasks whose output is an
- end result.
- </para>
-
- <para>
- The OpenEmbedded build system has knowledge of the relationship
- between these tasks and other tasks that precede them.
- For example, if BitBake runs
- <filename>do_populate_sysroot_setscene</filename> for
- something, there is little point in running any of the
- <filename>do_fetch</filename>, <filename>do_unpack</filename>,
- <filename>do_patch</filename>,
- <filename>do_configure</filename>,
- <filename>do_compile</filename>, and
- <filename>do_install</filename> tasks.
- However, if <filename>do_package</filename> needs to be run,
- BitBake would need to run those other tasks.
- </para>
-
- <para>
- It becomes more complicated if everything can come from an
- sstate cache because some objects are simply not required at
- all.
- For example, you do not need a compiler or native tools, such
- as quilt, if there is nothing to compile or patch.
- If the <filename>do_package_write_*</filename> packages are
- available from sstate, BitBake does not need the
- <filename>do_package</filename> task data.
- </para>
-
- <para>
- To handle all these complexities, BitBake runs in two phases.
- The first is the "setscene" stage.
- During this stage, BitBake first checks the sstate cache for
- any targets it is planning to build.
- BitBake does a fast check to see if the object exists rather
- than a complete download.
- If nothing exists, the second phase, which is the setscene
- stage, completes and the main build proceeds.
- </para>
-
- <para>
- If objects are found in the sstate cache, the OpenEmbedded
- build system works backwards from the end targets specified
- by the user.
- For example, if an image is being built, the OpenEmbedded build
- system first looks for the packages needed for that image and
- the tools needed to construct an image.
- If those are available, the compiler is not needed.
- Thus, the compiler is not even downloaded.
- If something was found to be unavailable, or the download or
- setscene task fails, the OpenEmbedded build system then tries
- to install dependencies, such as the compiler, from the cache.
- </para>
-
- <para>
- The availability of objects in the sstate cache is handled by
- the function specified by the
- <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
- variable and returns a list of the objects that are available.
- The function specified by the
- <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink>
- variable is the function that determines whether a given
- dependency needs to be followed, and whether for any given
- relationship the function needs to be passed.
- The function returns a True or False value.
- </para>
- </section>
- </section>
-
- <section id='images-dev-environment'>
- <title>Images</title>
-
- <para>
- The images produced by the OpenEmbedded build system
- are compressed forms of the
- root filesystem that are ready to boot on a target device.
- You can see from the
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
- that BitBake output, in part, consists of images.
- This section is going to look more closely at this output:
- <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
- </para>
-
- <para>
- For a list of example images that the Yocto Project provides,
- see the
- "<link linkend='ref-images'>Images</link>" chapter.
- </para>
-
- <para>
- Images are written out to the
- <link linkend='build-directory'>Build Directory</link>
- inside the <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename>
- folder as shown in the figure.
- This folder contains any files expected to be loaded on the
- target device.
- The
- <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
- variable points to the <filename>deploy</filename> directory,
- while the
- <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
- variable points to the appropriate directory containing images for
- the current configuration.
- <itemizedlist>
- <listitem><para><filename><replaceable>kernel-image</replaceable></filename>:
- A kernel binary file.
- The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
- variable setting determines the naming scheme for the
- kernel image file.
- Depending on that variable, the file could begin with
- a variety of naming strings.
- The <filename>deploy/images/<replaceable>machine</replaceable></filename>
- directory can contain multiple image files for the
- machine.</para></listitem>
- <listitem><para><filename><replaceable>root-filesystem-image</replaceable></filename>:
- Root filesystems for the target device (e.g.
- <filename>*.ext3</filename> or <filename>*.bz2</filename>
- files).
- The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
- variable setting determines the root filesystem image
- type.
- The <filename>deploy/images/<replaceable>machine</replaceable></filename>
- directory can contain multiple root filesystems for the
- machine.</para></listitem>
- <listitem><para><filename><replaceable>kernel-modules</replaceable></filename>:
- Tarballs that contain all the modules built for the kernel.
- Kernel module tarballs exist for legacy purposes and
- can be suppressed by setting the
- <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
- variable to "0".
- The <filename>deploy/images/<replaceable>machine</replaceable></filename>
- directory can contain multiple kernel module tarballs
- for the machine.</para></listitem>
- <listitem><para><filename><replaceable>bootloaders</replaceable></filename>:
- Bootloaders supporting the image, if applicable to the
- target machine.
- The <filename>deploy/images/<replaceable>machine</replaceable></filename>
- directory can contain multiple bootloaders for the
- machine.</para></listitem>
- <listitem><para><filename><replaceable>symlinks</replaceable></filename>:
- The <filename>deploy/images/<replaceable>machine</replaceable></filename>
- folder contains
- a symbolic link that points to the most recently built file
- for each machine.
- These links might be useful for external scripts that
- need to obtain the latest version of each file.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='sdk-dev-environment'>
- <title>Application Development SDK</title>
-
- <para>
- In the
- <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
- the output labeled "Application Development SDK" represents an
- SDK.
- The SDK generation process differs depending on whether you build
- a standard SDK
- (e.g. <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>)
- or an extensible SDK
- (e.g. <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>).
- This section is going to take a closer look at this output:
- <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" />
- </para>
-
- <para>
- The specific form of this output is a self-extracting
- SDK installer (<filename>*.sh</filename>) that, when run,
- installs the SDK, which consists of a cross-development
- toolchain, a set of libraries and headers, and an SDK
- environment setup script.
- Running this installer essentially sets up your
- cross-development environment.
- You can think of the cross-toolchain as the "host"
- part because it runs on the SDK machine.
- You can think of the libraries and headers as the "target"
- part because they are built for the target hardware.
- The environment setup script is added so that you can initialize
- the environment before using the tools.
- </para>
-
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- The Yocto Project supports several methods by which you can
- set up this cross-development environment.
- These methods include downloading pre-built SDK installers
- or building and installing your own SDK installer.
- </para></listitem>
- <listitem><para>
- For background information on cross-development toolchains
- in the Yocto Project development environment, see the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section.
- </para></listitem>
- <listitem><para>
- For information on setting up a cross-development
- environment, see the
- <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
- </para></listitem>
- </itemizedlist>
- </note>
- <para>
- Once built, the SDK installers are written out to the
- <filename>deploy/sdk</filename> folder inside the
- <link linkend='build-directory'>Build Directory</link>
- as shown in the figure at the beginning of this section.
- Depending on the type of SDK, several variables exist that help
- configure these files.
- The following list shows the variables associated with a standard
- SDK:
- <itemizedlist>
- <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
- Points to the <filename>deploy</filename>
- directory.</para></listitem>
- <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
- Specifies the architecture of the machine
- on which the cross-development tools are run to
- create packages for the target hardware.
- </para></listitem>
- <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
- Lists the features to include in the "target" part
- of the SDK.
- </para></listitem>
- <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
- Lists packages that make up the host
- part of the SDK (i.e. the part that runs on
- the <filename>SDKMACHINE</filename>).
- When you use
- <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename>
- to create the SDK, a set of default packages
- apply.
- This variable allows you to add more packages.
- </para></listitem>
- <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
- Lists packages that make up the target part
- of the SDK (i.e. the part built for the
- target hardware).
- </para></listitem>
- <listitem><para><link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>:
- Defines the default SDK installation path offered by the
- installation script.
- </para></listitem>
- </itemizedlist>
- This next list, shows the variables associated with an extensible
- SDK:
- <itemizedlist>
- <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
- Points to the <filename>deploy</filename> directory.
- </para></listitem>
- <listitem><para><link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>:
- Controls whether or not shared state artifacts are copied
- into the extensible SDK.
- By default, all required shared state artifacts are copied
- into the SDK.
- </para></listitem>
- <listitem><para><link linkend='var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></link>:
- Specifies whether or not packagedata will be included in
- the extensible SDK for all recipes in the "world" target.
- </para></listitem>
- <listitem><para><link linkend='var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></link>:
- Specifies whether or not the toolchain will be included
- when building the extensible SDK.
- </para></listitem>
- <listitem><para><link linkend='var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></link>:
- A list of variables allowed through from the build system
- configuration into the extensible SDK configuration.
- </para></listitem>
- <listitem><para><link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>:
- A list of variables not allowed through from the build
- system configuration into the extensible SDK configuration.
- </para></listitem>
- <listitem><para><link linkend='var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></link>:
- A list of classes to remove from the
- <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
- value globally within the extensible SDK configuration.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml
index e29bf89..b974d0f 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml
@@ -20,7 +20,7 @@
For more information on how to apply the command when using the
extensible SDK, see the
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
- section in the Yocto Project Application Development and the
+ chapter in the Yocto Project Application Development and the
Extensible Software Development Kit (eSDK) manual.
</para>
@@ -35,59 +35,51 @@
the commands:
<literallayout class='monospaced'>
$ devtool --help
- usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
- [--fetch-dev] [--version VERSION] [--no-git]
- [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH]
- [--binary] [--also-native] [--src-subdir SUBDIR]
- [--mirrors] [--provides PROVIDES]
- [recipename] [srctree] [fetchuri]
+ NOTE: Starting bitbake server...
+ usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
+ [--color COLOR] [-h]
+ <subcommand> ...
- Adds a new recipe to the workspace to build a specified source tree. Can
- optionally fetch a remote URI and unpack it to create the source tree.
-
- arguments:
- recipename Name for new recipe to add (just name - no version,
- path or extension). If not specified, will attempt
- to auto-detect it.
- srctree Path to external source tree. If not specified, a
- subdirectory of
- /home/<replaceable>user</replaceable>/poky/build/workspace/sources will be
- used.
- fetchuri Fetch the specified URI and extract it to create
- the source tree
+ OpenEmbedded development tool
options:
- -h, --help show this help message and exit
- --same-dir, -s Build in same directory as source
- --no-same-dir Force build in a separate build directory
- --fetch URI, -f URI Fetch the specified URI and extract it to create
- the source tree (deprecated - pass as positional
- argument instead)
- --fetch-dev For npm, also fetch devDependencies
- --version VERSION, -V VERSION
- Version to use within recipe (PV)
- --no-git, -g If fetching source, do not set up source tree as a
- git repository
- --srcrev SRCREV, -S SRCREV
- Source revision to fetch if fetching from an SCM
- such as git (default latest)
- --autorev, -a When fetching from a git repository, set SRCREV in
- the recipe to a floating revision instead of fixed
- --srcbranch SRCBRANCH, -B SRCBRANCH
- Branch in source repository if fetching from an SCM
- such as git (default master)
- --binary, -b Treat the source tree as something that should be
- installed verbatim (no compilation, same directory
- structure). Useful with binary packages e.g. RPMs.
- --also-native Also add native variant (i.e. support building
- recipe for the build host as well as the target
- machine)
- --src-subdir SUBDIR Specify subdirectory within source tree to use
- --mirrors Enable PREMIRRORS and MIRRORS for source tree
- fetching (disable by default).
- --provides PROVIDES, -p PROVIDES
- Specify an alias for the item provided by the
- recipe. E.g. virtual/libgl
+ --basepath BASEPATH Base directory of SDK / build directory
+ --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
+ from the metadata
+ -d, --debug Enable debug output
+ -q, --quiet Print only errors
+ --color COLOR Colorize output (where COLOR is auto, always, never)
+ -h, --help show this help message and exit
+
+ subcommands:
+ Beginning work on a recipe:
+ add Add a new recipe
+ modify Modify the source for an existing recipe
+ upgrade Upgrade an existing recipe
+ Getting information:
+ status Show workspace status
+ search Search available recipes
+ latest-version Report the latest version of an existing recipe
+ Working on a recipe in the workspace:
+ build Build a recipe
+ rename Rename a recipe file in the workspace
+ edit-recipe Edit a recipe file
+ find-recipe Find a recipe file
+ configure-help Get help on configure script options
+ update-recipe Apply changes from external source tree to recipe
+ reset Remove a recipe from your workspace
+ finish Finish working on a recipe in your workspace
+ Testing changes on target:
+ deploy-target Deploy recipe output files to live target machine
+ undeploy-target Undeploy recipe output files in live target machine
+ build-image Build image including workspace recipe packages
+ Advanced:
+ create-workspace Set up workspace in an alternative location
+ export Export workspace into a tar archive
+ import Import exported tar archive into workspace
+ extract Extract the source for an existing recipe
+ sync Synchronize the source tree for an existing recipe
+ Use devtool <subcommand> --help to get help on a specific command
</literallayout>
</para>
@@ -97,9 +89,12 @@
name and using <filename>--help</filename>:
<literallayout class='monospaced'>
$ devtool add --help
+ NOTE: Starting bitbake server...
usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
- [--version VERSION] [--no-git] [--autorev] [--binary]
- [--also-native] [--src-subdir SUBDIR]
+ [--fetch-dev] [--version VERSION] [--no-git]
+ [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH]
+ [--binary] [--also-native] [--src-subdir SUBDIR]
+ [--mirrors] [--provides PROVIDES]
[recipename] [srctree] [fetchuri]
Adds a new recipe to the workspace to build a specified source tree. Can
@@ -123,18 +118,30 @@
--fetch URI, -f URI Fetch the specified URI and extract it to create the
source tree (deprecated - pass as positional argument
instead)
+ --fetch-dev For npm, also fetch devDependencies
--version VERSION, -V VERSION
Version to use within recipe (PV)
--no-git, -g If fetching source, do not set up source tree as a git
repository
+ --srcrev SRCREV, -S SRCREV
+ Source revision to fetch if fetching from an SCM such
+ as git (default latest)
--autorev, -a When fetching from a git repository, set SRCREV in the
recipe to a floating revision instead of fixed
+ --srcbranch SRCBRANCH, -B SRCBRANCH
+ Branch in source repository if fetching from an SCM
+ such as git (default master)
--binary, -b Treat the source tree as something that should be
installed verbatim (no compilation, same directory
structure). Useful with binary packages e.g. RPMs.
--also-native Also add native variant (i.e. support building recipe
for the build host as well as the target machine)
--src-subdir SUBDIR Specify subdirectory within source tree to use
+ --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching
+ (disable by default).
+ --provides PROVIDES, -p PROVIDES
+ Specify an alias for the item provided by the recipe.
+ E.g. virtual/libgl
</literallayout>
</para>
</section>
@@ -161,7 +168,7 @@
<para>
<literallayout class='monospaced'>
- attic - A directory created if devtool believes it preserve
+ attic - A directory created if devtool believes it must preserve
anything when you run "devtool reset". For example, if you
run "devtool add", make changes to the recipe, and then
run "devtool reset", devtool takes notice that the file has
@@ -426,12 +433,27 @@
<title>Upgrading a Recipe</title>
<para>
- Use the <filename>devtool upgrade</filename> command
- to upgrade an existing recipe to a new upstream version.
- The command puts the upgraded recipe file into the
- workspace along with any associated files, and extracts
- the source tree to a specified location should patches
- need rebased or added to as a result of the upgrade.
+ As software matures, upstream recipes are upgraded to newer
+ versions.
+ As a developer, you need to keep your local recipes up-to-date
+ with the upstream version releases.
+ Several methods exist by which you can upgrade recipes.
+ You can read about them in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ This section overviews the <filename>devtool upgrade</filename>
+ command.
+ </para>
+
+ <para>
+ The <filename>devtool upgrade</filename> command
+ upgrades an existing recipe to a more recent version of the
+ recipe upstream.
+ The command puts the upgraded recipe file along with any associated
+ files into a "workspace" and, if necessary, extracts the source
+ tree to a specified location.
+ During the upgrade, patches associated with the recipe are
+ rebased or added as needed.
</para>
<para>
@@ -443,9 +465,21 @@
the version number to which you want to upgrade (i.e. the
<link linkend='var-PV'><filename>PV</filename></link>),
the source revision to which you want to upgrade (i.e. the
- <link linkend='var-SRCREV'><filename>SRCREV</filename></link>,
+ <link linkend='var-SRCREV'><filename>SRCREV</filename></link>),
whether or not to apply patches, and so forth.
</para>
+
+ <para>
+ You can read more on the <filename>devtool upgrade</filename>
+ workflow in the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
+ You can also see an example of how to use
+ <filename>devtool upgrade</filename> in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade'>Using <filename>devtool upgrade</filename></ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
</section>
<section id='devtool-resetting-a-recipe'>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml
index 02857dc..cb74df6 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml
@@ -161,9 +161,9 @@
protocols support.
<note>
The default value for the
- <link linkend='var-DISTRO_FEATURES'><filename>DISTRO FEATURES</filename></link>
- variable includes "bluetooth", which causes bluez5
- to be backfilled in for bluetooth support.
+ <filename>DISTRO FEATURES</filename> variable includes
+ "bluetooth", which causes bluez5 to be backfilled in
+ for bluetooth support.
If you do not want bluez5 backfilled and would rather
use bluez4, you need to use the
<link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml
index c752f94..1f96186 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml
@@ -40,15 +40,19 @@
<para>
Following is a list of supported recipes:
<itemizedlist>
- <listitem><para><filename>build-appliance-image</filename>:
- An example virtual machine that contains all the pieces required to
- run builds using the build system as well as the build system itself.
+ <listitem><para>
+ <filename>build-appliance-image</filename>:
+ An example virtual machine that contains all the pieces
+ required to run builds using the build system as well as the
+ build system itself.
You can boot and run the image using either the
<ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink>
- or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
+ or
+ <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
For more information on this image, see the
- <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on
- the Yocto Project website.</para></listitem>
+ <ulink url='&YOCTO_HOME_URL;/software-item/build-appliance/'>Build Appliance</ulink>
+ page on the Yocto Project website.
+ </para></listitem>
<listitem><para><filename>core-image-base</filename>:
A console-only image that fully supports the target device hardware.</para></listitem>
<listitem><para><filename>core-image-clutter</filename>:
@@ -151,7 +155,8 @@
This image provides the Wayland protocol libraries and the
reference Weston compositor.
For more information, see the
- "<link linkend='wayland'>Wayland</link>" section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-using-wayland-and-weston'>Using Wayland and Weston</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para></listitem>
<listitem><para><filename>core-image-x11</filename>:
A very basic X11 image with a terminal.
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-kickstart.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-kickstart.xml
index 1dd36b2..a58f9d7 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-kickstart.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-kickstart.xml
@@ -27,15 +27,10 @@
Kickstart commands are based on the Fedora kickstart versions but
with modifications to reflect Wic capabilities.
You can see the original documentation for those commands at the
- following links:
- <itemizedlist>
- <listitem><para>
- <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink>
- </para></listitem>
- <listitem><para>
- <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink>
- </para></listitem>
- </itemizedlist>
+ following link:
+ <literallayout class='monospaced'>
+ <ulink url='http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html'>http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html</ulink>
+ </literallayout>
</para>
</section>
@@ -43,7 +38,7 @@
<title>Command: part or partition</title>
<para>
- Either of these commands create a partition on the system and use
+ Either of these commands creates a partition on the system and uses
the following syntax:
<literallayout class='monospaced'>
part [<replaceable>mntpoint</replaceable>]
@@ -55,7 +50,7 @@
<para>
The <filename><replaceable>mntpoint</replaceable></filename> is
- where the partition will be mounted and must be of one of the
+ where the partition is mounted and must be in one of the
following forms:
<itemizedlist>
<listitem><para>
@@ -64,7 +59,7 @@
</para></listitem>
<listitem><para>
<filename>swap</filename>:
- The created partition is used as swap space.
+ The created partition is used as swap space
</para></listitem>
</itemizedlist>
</para>
@@ -74,13 +69,22 @@
partition to automatically be mounted.
Wic achieves this by adding entries to the filesystem table (fstab)
during image generation.
- In order for wic to generate a valid fstab, you must also provide
+ In order for Wic to generate a valid fstab, you must also provide
one of the <filename>--ondrive</filename>,
<filename>--ondisk</filename>, or
<filename>--use-uuid</filename> partition options as part of the
command.
- Here is an example using "/" as the mountpoint.
- The command uses "--ondisk" to force the partition onto the
+ <note>
+ The mount program must understand the PARTUUID syntax you use
+ with <filename>--use-uuid</filename> and non-root
+ <replaceable>mountpoint</replaceable>, including swap.
+ The busybox versions of these application are currently
+ excluded.
+ </note>
+ Here is an example that uses "/" as the
+ <replaceable>mountpoint</replaceable>.
+ The command uses <filename>--ondisk</filename> to force the
+ partition onto the
<filename>sdb</filename> disk:
<literallayout class='monospaced'>
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
@@ -101,17 +105,26 @@
<filename>--source</filename>.
</para></listitem>
<listitem><para>
+ <emphasis><filename>--fixed-size</filename>:</emphasis>
+ The exact partition size in MBytes.
+ You cannot specify with <filename>--size</filename>.
+ An error occurs when assembling the disk image if the
+ partition data is larger than
+ <filename>--fixed-size</filename>.
+ </para></listitem>
+ <listitem><para>
<emphasis><filename>--source</filename>:</emphasis>
This option is a Wic-specific option that names the source
of the data that populates the partition.
The most common value for this option is "rootfs", but you
can use any value that maps to a valid source plug-in.
For information on the source plug-ins, see the
- "<link linkend='wic-plug-ins-interface'>Wic Plug-Ins Interface</link>"
- section.</para>
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
<para>If you use <filename>--source rootfs</filename>, Wic
- creates a partition as large as needed and to fill it with
+ creates a partition as large as needed and fills it with
the contents of the root filesystem pointed to by the
<filename>-r</filename> command-line option or the
equivalent rootfs derived from the <filename>-e</filename>
@@ -130,8 +143,8 @@
<filename>-r</filename> command-line option or the
equivalent rootfs derived from the <filename>-e</filename>
command-line option.
- Exactly what those contents and filesystem type end up
- being are dependent on the given plug-in implementation.
+ Exactly what those contents are and filesystem type used are
+ dependent on the given plug-in implementation.
</para>
<para>If you do not use the <filename>--source</filename>
@@ -173,7 +186,7 @@
<emphasis><filename>--fsoptions</filename>:</emphasis>
Specifies a free-form string of options to be used when
mounting the filesystem.
- This string will be copied into the
+ This string is copied into the
<filename>/etc/fstab</filename> file of the installed
system and should be enclosed in quotes.
If not specified, the default string is "defaults".
@@ -191,9 +204,9 @@
</para></listitem>
<listitem><para>
<emphasis><filename>--align (in KBytes)</filename>:</emphasis>
- This option is a Wic-specific option that says to start a
- partition on an <replaceable>x</replaceable> KBytes
- boundary.
+ This option is a Wic-specific option that says to start
+ partitions on boundaries given
+ <replaceable>x</replaceable> KBytes.
</para></listitem>
<listitem><para>
<emphasis><filename>--no-table</filename>:</emphasis>
@@ -203,10 +216,17 @@
However, the partition is not added to the partition table.
</para></listitem>
<listitem><para>
+ <emphasis><filename>--exclude-path</filename>:</emphasis>
+ This option is a Wic-specific option that excludes the given
+ relative path from the resulting image.
+ This option is only effective with the rootfs source
+ plug-in.
+ </para></listitem>
+ <listitem><para>
<emphasis><filename>--extra-space</filename>:</emphasis>
This option is a Wic-specific option that adds extra space
after the space filled by the content of the partition.
- The final size can go beyond the size specified by the
+ The final size can exceed the size specified by the
<filename>--size</filename> option.
The default value is 10 Mbytes.
</para></listitem>
@@ -218,6 +238,11 @@
The default value is "1.3".
</para></listitem>
<listitem><para>
+ <emphasis><filename>--part-name</filename>:</emphasis>
+ This option is a Wic-specific option that specifies a name
+ for GPT partitions.
+ </para></listitem>
+ <listitem><para>
<emphasis><filename>--part-type</filename>:</emphasis>
This option is a Wic-specific option that specifies the
partition type globally unique identifier (GUID) for GPT
@@ -237,6 +262,31 @@
This option is a Wic-specific option that specifies the
partition UUID.
</para></listitem>
+ <listitem><para>
+ <emphasis><filename>--fsuuid</filename>:</emphasis>
+ This option is a Wic-specific option that specifies the
+ filesystem UUID.
+ You can generate or modify
+ <link linkend='var-WKS_FILE'><filename>WKS_FILE</filename></link>
+ with this option if a preconfigured filesystem UUID is
+ added to the kernel command line in the bootloader
+ configuration before you run Wic.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--system-id</filename>:</emphasis>
+ This option is a Wic-specific option that specifies the
+ partition system ID, which is a one byte long, hexadecimal
+ parameter with or without the 0x prefix.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>--mkfs-extraopts</filename>:</emphasis>
+ This option specifies additional options to pass to the
+ <filename>mkfs</filename> utility.
+ Some default options for certain filesystems do not take
+ effect.
+ See Wic's help on kickstart
+ (i.e. <filename>wic help kickstart</filename>).
+ </para></listitem>
</itemizedlist>
</para>
</section>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml
index d4b7bee..169a31e 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml
@@ -118,14 +118,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -147,37 +142,45 @@
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
</legalnotice>
</bookinfo>
- <xi:include href="introduction.xml"/>
+ <xi:include href="ref-system-requirements.xml"/>
- <xi:include href="usingpoky.xml"/>
-
- <xi:include href="ref-development-environment.xml"/>
-
- <xi:include href="technical-details.xml"/>
+ <xi:include href="ref-terms.xml"/>
<xi:include href="ref-release-process.xml"/>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml
index e2902eb..c665cd9 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml
@@ -61,7 +61,7 @@
<para>
Each major release receives a codename that identifies the release in
the
- <link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>.
The concept is that branches of
<link linkend='metadata'>Metadata</link>
with the same codename are likely to be compatible and thus
@@ -217,7 +217,7 @@
in the <filename>poky</filename> repository.
<note>
You can find all these branches in the Yocto Project
- <link linkend='source-repositories'>Source Repositories</link>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
</note>
Testing within these public branches ensures in a publicly visible way
that all of the main supposed architectures and recipes in OE-Core
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml
index 4bddc59..8e0c9f5 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml
@@ -18,7 +18,7 @@
<para>
For information on how to establish a local Source Directory on your
development system, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
@@ -114,7 +114,7 @@
<title><filename>meta/</filename></title>
<para>
- This directory contains the OpenEmbedded Core metadata.
+ This directory contains the OpenEmbedded-Core metadata.
The directory holds recipes, common classes, and machine
configuration for emulated targets (<filename>qemux86</filename>,
<filename>qemuarm</filename>, and so forth.)
@@ -137,8 +137,7 @@
This directory contains the Yocto Project reference
hardware Board Support Packages (BSPs).
For more information on BSPs, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support
- Package (BSP) Developer's Guide</ulink>.
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
</para>
</section>
@@ -234,8 +233,7 @@
</para>
<para>
- By default, running this script without a
- <link linkend='build-directory'>Build Directory</link>
+ By default, running this script without a Build Directory
argument creates the <filename>build</filename> directory
in your current working directory.
If you provide a Build Directory argument when you
@@ -306,8 +304,8 @@
The directory tracks build information into image, packages, and
SDK subdirectories.
For information on the build history feature, see the
- "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</section>
@@ -350,7 +348,7 @@
which defaults to <filename>meta-poky/conf</filename>
when you are building from the Yocto Project development
environment and defaults to <filename>meta/conf</filename> when
- you are building from the OpenEmbedded Core environment.
+ you are building from the OpenEmbedded-Core environment.
Because the script variable points to the source of the
<filename>local.conf.sample</filename> file, this implies that
you can configure your build environment from any layer by setting
@@ -402,7 +400,7 @@
which defaults to <filename>meta-poky/conf</filename>
when you are building from the Yocto Project development
environment and defaults to <filename>meta/conf</filename> when
- you are building from the OpenEmbedded Core environment.
+ you are building from the OpenEmbedded-Core environment.
Because the script variable points to the source of the
<filename>bblayers.conf.sample</filename> file, this implies that
you can base your build from any layer by setting the variable in
@@ -520,9 +518,10 @@
variable points to this directory.
For more detail on the contents of the <filename>deploy</filename>
directory, see the
- "<link linkend='images-dev-environment'>Images</link>" and
- "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
- sections.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
+ sections in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -695,8 +694,8 @@
<para>
For information on how BitBake uses stamp files to determine if
a task should be rerun, see the
- "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -735,8 +734,7 @@
built within the Yocto Project.
For this package, a work directory of
<filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....></filename>,
- referred to as the
- <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
+ referred to as the <filename>WORKDIR</filename>, is created.
Within this directory, the source is unpacked to
<filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
(See the
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-system-requirements.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-system-requirements.xml
new file mode 100644
index 0000000..aea1fdf
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-system-requirements.xml
@@ -0,0 +1,490 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-manual-system-requirements'>
+<title>System Requirements</title>
+
+ <para>
+ Welcome to the Yocto Project Reference Manual!
+ This manual provides reference information for the current release
+ of the Yocto Project.
+ The manual is best used after you have an understanding
+ of the basics of the Yocto Project.
+ The manual is neither meant to be read as a starting point to the
+ Yocto Project nor read from start to finish.
+ Use this manual to find variable definitions, class
+ descriptions, and so forth as needed during the course of using
+ the Yocto Project.
+ </para>
+
+ <para>
+ For introductory information on the Yocto Project, see the
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>Yocto Project Development Environment</ulink>"
+ chapter in the Yocto Project Overview and Concepts Manual.
+ </para>
+
+ <para>
+ If you want to use the Yocto Project to quickly build an image
+ without having to understand concepts, work through the
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+ document.
+ You can find "how-to" information in the
+ <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>.
+ You can find Yocto Project overview and conceptual information in the
+ <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
+ <note><title>Tip</title>
+ For more information about the Yocto Project Documentation set,
+ see the
+ "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
+ section.
+ </note>
+ </para>
+
+ <section id='detailed-supported-distros'>
+ <title>Supported Linux Distributions</title>
+
+ <para>
+ Currently, the Yocto Project is supported on the following
+ distributions:
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Yocto Project releases are tested against the stable
+ Linux distributions in the following list.
+ The Yocto Project should work on other distributions but
+ validation is not performed against them.
+ </para></listitem>
+ <listitem><para>
+ In particular, the Yocto Project does not support
+ and currently has no plans to support
+ rolling-releases or development distributions due to
+ their constantly changing nature.
+ We welcome patches and bug reports, but keep in mind
+ that our priority is on the supported platforms listed
+ below.
+ </para></listitem>
+ <listitem><para>
+ If you encounter problems, please go to
+ <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
+ and submit a bug.
+ We are interested in hearing about your experience.
+ For information on how to submit a bug, see the
+ Yocto Project
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>
+ and the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ <itemizedlist>
+<!--
+ <listitem><para>Ubuntu 10.04</para></listitem>
+ <listitem><para>Ubuntu 11.10</para></listitem>
+ <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
+ <listitem><para>Ubuntu 13.10</para></listitem>
+ <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> -->
+ <listitem><para>Ubuntu 14.10</para></listitem>
+ <listitem><para>Ubuntu 15.04</para></listitem>
+ <listitem><para>Ubuntu 15.10</para></listitem>
+ <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
+<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
+ <listitem><para>Fedora 17 (Spherical)</para></listitem>
+ <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
+ <listitem><para>Fedora release 20 (Heisenbug)</para></listitem> -->
+ <listitem><para>Fedora release 22</para></listitem>
+ <listitem><para>Fedora release 23</para></listitem>
+<!-- <listitem><para>Fedora release 24</para></listitem>
+ <listitem><para>CentOS release 5.6 (Final)</para></listitem>
+ <listitem><para>CentOS release 5.7 (Final)</para></listitem>
+ <listitem><para>CentOS release 5.8 (Final)</para></listitem>
+ <listitem><para>CentOS release 6.3 (Final)</para></listitem>
+ <listitem><para>CentOS release 6.x</para></listitem> -->
+ <listitem><para>CentOS release 7.x</para></listitem>
+<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>
+ <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> -->
+ <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
+ <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
+<!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
+ <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
+ <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
+ <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
+ <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>
+ <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem> -->
+<!-- <listitem><para>openSUSE 11.4</para></listitem>
+ <listitem><para>openSUSE 12.1</para></listitem>
+ <listitem><para>openSUSE 12.2</para></listitem>
+ <listitem><para>openSUSE 12.3</para></listitem>
+ <listitem><para>openSUSE 13.1</para></listitem> -->
+ <listitem><para>openSUSE 13.2</para></listitem>
+ <listitem><para>openSUSE 42.1</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <note>
+ While the Yocto Project Team attempts to ensure all Yocto Project
+ releases are one hundred percent compatible with each officially
+ supported Linux distribution, instances might exist where you
+ encounter a problem while using the Yocto Project on a specific
+ distribution.
+ </note>
+ </section>
+
+ <section id='required-packages-for-the-host-development-system'>
+ <title>Required Packages for the Host Development System</title>
+
+ <para>
+ The list of packages you need on the host development system can
+ be large when covering all build scenarios using the Yocto Project.
+ This section provides required packages according to
+ Linux distribution and function.
+ </para>
+
+ <section id='ubuntu-packages'>
+ <title>Ubuntu and Debian</title>
+
+ <para>
+ The following list shows the required packages by function
+ given a supported Ubuntu or Debian Linux distribution:
+ <note>
+ If your build system has the
+ <filename>oss4-dev</filename> package installed, you
+ might experience QEMU build failures due to the package
+ installing its own custom
+ <filename>/usr/include/linux/soundcard.h</filename> on
+ the Debian system.
+ If you run into this situation, either of the following
+ solutions exist:
+ <literallayout class='monospaced'>
+ $ sudo apt-get build-dep qemu
+ $ sudo apt-get remove oss4-dev
+ </literallayout>
+ </note>
+ <itemizedlist>
+ <listitem><para><emphasis>Essentials:</emphasis>
+ Packages needed to build an image on a headless
+ system:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
+ Packages recommended if the host system has graphics
+ support or if you are going to use the Eclipse
+ IDE:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install libsdl1.2-dev xterm
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Documentation:</emphasis>
+ Packages needed if you are going to build out the
+ Yocto Project documentation manuals:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
+ Packages needed if you are going to run
+ <filename>oe-selftest</filename>:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install python-git
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='fedora-packages'>
+ <title>Fedora Packages</title>
+
+ <para>
+ The following list shows the required packages by function
+ given a supported Fedora Linux distribution:
+ <itemizedlist>
+ <listitem><para><emphasis>Essentials:</emphasis>
+ Packages needed to build an image for a headless
+ system:
+ <literallayout class='monospaced'>
+ $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
+ Packages recommended if the host system has graphics
+ support or if you are going to use the Eclipse
+ IDE:
+ <literallayout class='monospaced'>
+ $ sudo dnf install SDL-devel xterm
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Documentation:</emphasis>
+ Packages needed if you are going to build out the
+ Yocto Project documentation manuals:
+ <literallayout class='monospaced'>
+ $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \
+ docbook-dtds docbook-utils fop libxslt dblatex xmlto
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
+ Packages needed if you are going to run
+ <filename>oe-selftest</filename>:
+ <literallayout class='monospaced'>
+ $ sudo dnf install python3-GitPython
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='opensuse-packages'>
+ <title>openSUSE Packages</title>
+
+ <para>
+ The following list shows the required packages by function
+ given a supported openSUSE Linux distribution:
+ <itemizedlist>
+ <listitem><para><emphasis>Essentials:</emphasis>
+ Packages needed to build an image for a headless
+ system:
+ <literallayout class='monospaced'>
+ $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
+ Packages recommended if the host system has graphics
+ support or if you are going to use the Eclipse
+ IDE:
+ <literallayout class='monospaced'>
+ $ sudo zypper install libSDL-devel xterm
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Documentation:</emphasis>
+ Packages needed if you are going to build out the
+ Yocto Project documentation manuals:
+ <literallayout class='monospaced'>
+ $ sudo zypper install make dblatex xmlto
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
+ Packages needed if you are going to run
+ <filename>oe-selftest</filename>:
+ <literallayout class='monospaced'>
+ $ sudo zypper install python-GitPython
+ </literallayout></para></listitem>
+ </itemizedlist>
+ <note>
+ Sanity testing, through the
+ <link linkend='ref-classes-testimage*'>testimage</link>
+ classes, does not work on systems using the
+ <ulink url='https://en.opensuse.org/Portal:Wicked'>Wicked</ulink>
+ network manager.
+ </note>
+ </para>
+ </section>
+
+ <section id='centos-packages'>
+ <title>CentOS Packages</title>
+
+ <para>
+ The following list shows the required packages by function
+ given a supported CentOS Linux distribution:
+ <itemizedlist>
+ <listitem><para><emphasis>Essentials:</emphasis>
+ Packages needed to build an image for a headless
+ system:
+ <literallayout class='monospaced'>
+ $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
+ </literallayout>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Extra Packages for Enterprise Linux
+ (i.e. <filename>epel-release</filename>)
+ is a collection of packages from Fedora
+ built on RHEL/CentOS for easy installation
+ of packages not included in enterprise
+ Linux by default.
+ You need to install these packages
+ separately.
+ </para></listitem>
+ <listitem><para>
+ The <filename>makecache</filename> command
+ consumes additional Metadata from
+ <filename>epel-release</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
+ <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
+ Packages recommended if the host system has graphics
+ support or if you are going to use the Eclipse
+ IDE:
+ <literallayout class='monospaced'>
+ $ sudo yum install SDL-devel xterm
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Documentation:</emphasis>
+ Packages needed if you are going to build out the
+ Yocto Project documentation manuals:
+ <literallayout class='monospaced'>
+ $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
+ docbook-dtds docbook-utils fop libxslt dblatex xmlto
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
+ Packages needed if you are going to run
+ <filename>oe-selftest</filename>:
+ <literallayout class='monospaced'>
+ $ sudo yum install GitPython
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+
+ <section id='required-git-tar-and-python-versions'>
+ <title>Required Git, tar, and Python Versions</title>
+
+ <para>
+ In order to use the build system, your host development system
+ must meet the following version requirements for Git, tar, and
+ Python:
+ <itemizedlist>
+ <listitem><para>Git 1.8.3.1 or greater</para></listitem>
+ <listitem><para>tar 1.27 or greater</para></listitem>
+ <listitem><para>Python 3.4.0 or greater</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If your host development system does not meet all these requirements,
+ you can resolve this by installing a <filename>buildtools</filename>
+ tarball that contains these tools.
+ You can get the tarball one of two ways: download a pre-built
+ tarball or use BitBake to build the tarball.
+ </para>
+
+ <section id='downloading-a-pre-built-buildtools-tarball'>
+ <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
+
+ <para>
+ Downloading and running a pre-built buildtools installer is
+ the easiest of the two methods by which you can get these tools:
+ <orderedlist>
+ <listitem><para>
+ Locate and download the <filename>*.sh</filename> at
+ <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
+ </para></listitem>
+ <listitem><para>
+ Execute the installation script.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
+ </literallayout>
+ During execution, a prompt appears that allows you to
+ choose the installation directory.
+ For example, you could choose the following:
+ <literallayout class='monospaced'>
+ /home/<replaceable>your-username</replaceable>/buildtools
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Source the tools environment setup script by using a
+ command like the following:
+ <literallayout class='monospaced'>
+ $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
+ </literallayout>
+ Of course, you need to supply your installation directory and be
+ sure to use the right file (i.e. i585 or x86-64).
+ </para>
+ <para>
+ After you have sourced the setup script,
+ the tools are added to <filename>PATH</filename>
+ and any other environment variables required to run the
+ tools are initialized.
+ The results are working versions versions of Git, tar,
+ Python and <filename>chrpath</filename>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='building-your-own-buildtools-tarball'>
+ <title>Building Your Own <filename>buildtools</filename> Tarball</title>
+
+ <para>
+ Building and running your own buildtools installer applies
+ only when you have a build host that can already run BitBake.
+ In this case, you use that machine to build the
+ <filename>.sh</filename> file and then
+ take steps to transfer and run it on a
+ machine that does not meet the minimal Git, tar, and Python
+ requirements.
+ </para>
+
+ <para>
+ Here are the steps to take to build and run your own
+ buildtools installer:
+ <orderedlist>
+ <listitem><para>
+ On the machine that is able to run BitBake,
+ be sure you have set up your build environment with
+ the setup script
+ (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
+ </para></listitem>
+ <listitem><para>
+ Run the BitBake command to build the tarball:
+ <literallayout class='monospaced'>
+ $ bitbake buildtools-tarball
+ </literallayout>
+ <note>
+ The
+ <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
+ variable in your <filename>local.conf</filename> file
+ determines whether you build tools for a 32-bit
+ or 64-bit system.
+ </note>
+ Once the build completes, you can find the
+ <filename>.sh</filename> file that installs
+ the tools in the <filename>tmp/deploy/sdk</filename>
+ subdirectory of the
+ <link linkend='build-directory'>Build Directory</link>.
+ The installer file has the string "buildtools"
+ in the name.
+ </para></listitem>
+ <listitem><para>
+ Transfer the <filename>.sh</filename> file from the
+ build host to the machine that does not meet the
+ Git, tar, or Python requirements.
+ </para></listitem>
+ <listitem><para>
+ On the machine that does not meet the requirements,
+ run the <filename>.sh</filename> file
+ to install the tools.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
+ </literallayout>
+ During execution, a prompt appears that allows you to
+ choose the installation directory.
+ For example, you could choose the following:
+ <literallayout class='monospaced'>
+ /home/<replaceable>your_username</replaceable>/buildtools
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Source the tools environment setup script by using a
+ command like the following:
+ <literallayout class='monospaced'>
+ $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
+ </literallayout>
+ Of course, you need to supply your installation directory and be
+ sure to use the right file (i.e. i585 or x86-64).
+ </para>
+ <para>
+ After you have sourced the setup script,
+ the tools are added to <filename>PATH</filename>
+ and any other environment variables required to run the
+ tools are initialized.
+ The results are working versions versions of Git, tar,
+ Python and <filename>chrpath</filename>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml
index c726cb9..e6cf686 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml
@@ -111,8 +111,7 @@
<link linkend='ref-classes-deploy'><filename>deploy</filename></link>
class and should write the output to
<filename>${</filename><link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link><filename>}</filename>,
- which is not to be confused with
- <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}</filename>.
+ which is not to be confused with <filename>${DEPLOY_DIR}</filename>.
The <filename>deploy</filename> class sets up
<filename>do_deploy</filename> as a shared state (sstate) task that
can be accelerated through sstate use.
@@ -220,8 +219,8 @@
<para>
For more information on image creation, see the
- "<link linkend='image-generation-dev-environment'>Image Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -232,7 +231,7 @@
Completes the image generation process.
The <filename>do_image_complete</filename> task runs after the
OpenEmbedded build system has run the
- <link linkend='ref-tasks-rootfs'><filename>do_image</filename></link>
+ <link linkend='ref-tasks-image'><filename>do_image</filename></link>
task during which image pre-processing occurs and through
dynamically generated <filename>do_image_*</filename> tasks the
image is constructed.
@@ -246,8 +245,8 @@
<para>
For more information on image creation, see the
- "<link linkend='image-generation-dev-environment'>Image Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -268,7 +267,7 @@
and
<link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>),
run under
- <link linkend='fakeroot-and-pseudo'>fakeroot</link>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
<note>
<title>Caution</title>
@@ -280,7 +279,7 @@
UID and/or GID of the original file, which is usually not
what you want.
The
- <link linkend='ref-classes-insane'><filename>host-user-contaminated</filename></link>
+ <link linkend='insane-host-user-contaminated'><filename>host-user-contaminated</filename></link>
QA check checks for files that probably have the wrong
ownership.
</para>
@@ -342,8 +341,8 @@
For additional information, see the
<link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
variable and the
- "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -367,8 +366,8 @@
<filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -381,8 +380,8 @@
<filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -395,8 +394,8 @@
<filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -408,8 +407,8 @@
<filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
directory in the package feeds area.
For more information, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -430,9 +429,87 @@
<para>
Locates patch files and applies them to the source code.
- See the
- "<link linkend='patching-dev-environment'>Patching</link>"
- section for more information.
+ </para>
+
+ <para>
+ After fetching and unpacking source files, the build system
+ uses the recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statements to locate and apply patch files to the source code.
+ <note>
+ The build system uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+ variable to determine the default set of directories when
+ searching for patches.
+ </note>
+ Patch files, by default, are <filename>*.patch</filename> and
+ <filename>*.diff</filename> files created and kept in a
+ subdirectory of the directory holding the recipe file.
+ For example, consider the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5'><filename>bluez5</filename></ulink>
+ recipe from the OE-Core layer (i.e.
+ <filename>poky/meta</filename>):
+ <literallayout class='monospaced'>
+ poky/meta/recipes-connectivity/bluez5
+ </literallayout>
+ This recipe has two patch files located here:
+ <literallayout class='monospaced'>
+ poky/meta/recipes-connectivity/bluez5/bluez5
+ </literallayout>
+ </para>
+
+ <para>
+ In the <filename>bluez5</filename> recipe, the
+ <filename>SRC_URI</filename> statements point to the source and
+ patch files needed to build the package.
+ <note>
+ In the case for the <filename>bluez5_5.48.bb</filename>
+ recipe, the <filename>SRC_URI</filename> statements are from an
+ include file <filename>bluez5.inc</filename>.
+ </note>
+ </para>
+
+ <para>
+ As mentioned earlier, the build system treats files whose file
+ types are <filename>.patch</filename> and
+ <filename>.diff</filename> as patch files.
+ However, you can use the "apply=yes" parameter with the
+ <filename>SRC_URI</filename> statement to indicate any file as a
+ patch file:
+ <literallayout class='monospaced'>
+ SRC_URI = " \
+ git://<replaceable>path_to_repo</replaceable>/<replaceable>some_package</replaceable> \
+ file://<replaceable>file</replaceable>;apply=yes \
+ "
+ </literallayout>
+ </para>
+
+ <para>
+ Conversely, if you have a directory full of patch files and you
+ want to exclude some so that the <filename>do_patch</filename>
+ task does not apply them during the patch phase, you can use
+ the "apply=no" parameter with the <filename>SRC_URI</filename>
+ statement:
+ <literallayout class='monospaced'>
+ SRC_URI = " \
+ git://<replaceable>path_to_repo</replaceable>/<replaceable>some_package</replaceable> \
+ file://<replaceable>path_to_lots_of_patch_files</replaceable> \
+ file://<replaceable>path_to_lots_of_patch_files</replaceable>/<replaceable>patch_file5</replaceable>;apply=no \
+ "
+ </literallayout>
+ In the previous example, assuming all the files in the directory
+ holding the patch files end with either <filename>.patch</filename>
+ or <filename>.diff</filename>, every file would be applied as a
+ patch by default except for the
+ <replaceable>patch_file5</replaceable> patch.
+ </para>
+
+ <para>
+ You can find out more about the patching process in the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
+ section in the Yocto Project Overview and Concepts Manual and the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</section>
@@ -451,8 +528,9 @@
<para>
Creates the file and directory structure for an installable SDK.
See the
- "<link linkend='sdk-generation-dev-environment'>SDK Generation</link>"
- section for more information.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for more
+ information.
</para>
</section>
@@ -538,8 +616,9 @@
<link linkend='var-S'><filename>S</filename></link> variable also
plays a role in where unpacked source files ultimately reside.
For more information on how source files are unpacked, see the
- "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
- section and the <filename>WORKDIR</filename> and
+ "<ulink url='&YOCTO_DOCS_OM_URL;#source-fetching-dev-environment'>Source Fetching</ulink>"
+ section in the Yocto Project Overview and Concepts Manual and also
+ see the <filename>WORKDIR</filename> and
<filename>S</filename> variable descriptions.
</para>
</section>
@@ -593,24 +672,13 @@
</para>
</section>
- <section id='ref-tasks-checkuriall'>
- <title><filename>do_checkuriall</filename></title>
-
- <para>
- Validates the
- <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
- value for all recipes required to build a target.
- </para>
- </section>
-
<section id='ref-tasks-clean'>
<title><filename>do_clean</filename></title>
<para>
Removes all output files for a target from the
<link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
- task forward (i.e.
- <link linkend='ref-tasks-patch'><filename>do_unpack</filename></link>,
+ task forward (i.e. <filename>do_unpack</filename>,
<link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
<link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
<link linkend='ref-tasks-install'><filename>do_install</filename></link>,
@@ -627,8 +695,8 @@
<para>
Running this task does not remove the
- <link linkend='shared-state-cache'>sstate</link>) cache
- files.
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>
+ cache files.
Consequently, if no changes have been made and the recipe is
rebuilt after cleaning, output files are simply restored from the
sstate cache.
@@ -644,8 +712,9 @@
<para>
Removes all output files, shared state
- (<link linkend='shared-state-cache'>sstate</link>) cache, and
- downloaded source files for a target (i.e. the contents of
+ (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
+ cache, and downloaded source files for a target (i.e. the contents
+ of
<link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>).
Essentially, the <filename>do_cleanall</filename> task is
identical to the
@@ -674,13 +743,14 @@
<para>
Removes all output files and shared state
- (<link linkend='shared-state-cache'>sstate</link>)
+ (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
cache for a target.
Essentially, the <filename>do_cleansstate</filename> task is
identical to the
<link linkend='ref-tasks-clean'><filename>do_clean</filename></link>
task with the added removal of shared state
- (<link linkend='shared-state-cache'>sstate</link>) cache.
+ (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
+ cache.
</para>
<para>
@@ -736,14 +806,6 @@
</para>
</section>
- <section id='ref-tasks-fetchall'>
- <title><filename>do_fetchall</filename></title>
-
- <para>
- Fetches all remote sources required to build a target.
- </para>
- </section>
-
<section id='ref-tasks-listtasks'>
<title><filename>do_listtasks</filename></title>
@@ -757,7 +819,7 @@
<para>
Creates or updates the index in the
- <link linkend='package-feeds-dev-environment'>Package Feeds</link>
+ <ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>
area.
<note>
This task is not triggered with the
@@ -809,8 +871,9 @@
Creates the root filesystem (file and directory structure) for an
image.
See the
- "<link linkend='image-generation-dev-environment'>Image Generation</link>"
- section for more information on how the root filesystem is created.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for more
+ information on how the root filesystem is created.
</para>
</section>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-terms.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-terms.xml
new file mode 100644
index 0000000..cc09d3f
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-terms.xml
@@ -0,0 +1,507 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-terms'>
+<title>Yocto Project Terms</title>
+
+ <para>
+ Following is a list of terms and definitions users new to the Yocto
+ Project development environment might find helpful.
+ While some of these terms are universal, the list includes them
+ just in case:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Append Files:</emphasis>
+ Files that append build information to a recipe file.
+ Append files are known as BitBake append files and
+ <filename>.bbappend</filename> files.
+ The OpenEmbedded build system expects every append file to have
+ a corresponding recipe (<filename>.bb</filename>) file.
+ Furthermore, the append file and corresponding recipe file
+ must use the same root filename.
+ The filenames can differ only in the file type suffix used
+ (e.g.
+ <filename>formfactor_0.0.bb</filename> and
+ <filename>formfactor_0.0.bbappend</filename>).</para>
+
+ <para>Information in append files extends or overrides the
+ information in the similarly-named recipe file.
+ For an example of an append file in use, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ <note>
+ Append files can also use wildcard patterns in their
+ version numbers so they can be applied to more than one
+ version of the underlying recipe file.
+ </note>
+ </para></listitem>
+ <listitem><para id='bitbake-term'>
+ <emphasis>BitBake:</emphasis>
+ The task executor and scheduler used by the OpenEmbedded build
+ system to build images.
+ For more information on BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </para></listitem>
+ <listitem><para id='board-support-package-bsp-term'>
+ <emphasis>Board Support Package (BSP):</emphasis>
+ A group of drivers, definitions, and other components that
+ provide support for a specific hardware configuration.
+ For more information on BSPs, see the
+ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+ </para></listitem>
+ <listitem>
+ <para id='build-directory'>
+ <emphasis>Build Directory:</emphasis>
+ This term refers to the area used by the OpenEmbedded build
+ system for builds.
+ The area is created when you <filename>source</filename> the
+ setup environment script that is found in the Source Directory
+ (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
+ The
+ <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
+ variable points to the Build Directory.</para>
+
+ <para>You have a lot of flexibility when creating the Build
+ Directory.
+ Following are some examples that show how to create the
+ directory.
+ The examples assume your
+ <link linkend='source-directory'>Source Directory</link> is
+ named <filename>poky</filename>:
+ <itemizedlist>
+ <listitem><para>Create the Build Directory inside your
+ Source Directory and let the name of the Build
+ Directory default to <filename>build</filename>:
+ <literallayout class='monospaced'>
+ $ cd $HOME/poky
+ $ source &OE_INIT_FILE;
+ </literallayout>
+ </para></listitem>
+ <listitem><para>Create the Build Directory inside your
+ home directory and specifically name it
+ <filename>test-builds</filename>:
+ <literallayout class='monospaced'>
+ $ cd $HOME
+ $ source poky/&OE_INIT_FILE; test-builds
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Provide a directory path and specifically name the
+ Build Directory.
+ Any intermediate folders in the pathname must exist.
+ This next example creates a Build Directory named
+ <filename>YP-&POKYVERSION;</filename>
+ in your home directory within the existing
+ directory <filename>mybuilds</filename>:
+ <literallayout class='monospaced'>
+ $cd $HOME
+ $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ By default, the Build Directory contains
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
+ which is a temporary directory the build system uses for
+ its work.
+ <filename>TMPDIR</filename> cannot be under NFS.
+ Thus, by default, the Build Directory cannot be under NFS.
+ However, if you need the Build Directory to be under NFS,
+ you can set this up by setting <filename>TMPDIR</filename>
+ in your <filename>local.conf</filename> file
+ to use a local drive.
+ Doing so effectively separates <filename>TMPDIR</filename>
+ from <filename>TOPDIR</filename>, which is the Build
+ Directory.
+ </note>
+ </para></listitem>
+ <listitem><para id='hardware-build-system-term'>
+ <emphasis>Build Host:</emphasis>
+ The system used to build images in a Yocto Project
+ Development environment.
+ The build system is sometimes referred to as the
+ development host.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Classes:</emphasis>
+ Files that provide for logic encapsulation and inheritance so
+ that commonly used patterns can be defined once and then
+ easily used in multiple recipes.
+ For reference information on the Yocto Project classes, see the
+ "<link linkend='ref-classes'>Classes</link>" chapter.
+ Class files end with the <filename>.bbclass</filename>
+ filename extension.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Configuration File:</emphasis>
+ Files that hold global definitions of variables,
+ user-defined variables, and hardware configuration
+ information.
+ These files tell the OpenEmbedded build system what to
+ build and what to put into the image to support a
+ particular platform.</para>
+
+ <para>Configuration files end with a <filename>.conf</filename>
+ filename extension.
+ The <filename>conf/local.conf</filename> configuration file in
+ the
+ <link linkend='build-directory'>Build Directory</link>
+ contains user-defined variables that affect every build.
+ The <filename>meta-poky/conf/distro/poky.conf</filename>
+ configuration file defines Yocto "distro" configuration
+ variables used only when building with this policy.
+ Machine configuration files, which
+ are located throughout the
+ <link linkend='source-directory'>Source Directory</link>, define
+ variables for specific hardware and are only used when building
+ for that target (e.g. the
+ <filename>machine/beaglebone.conf</filename> configuration
+ file defines variables for the Texas Instruments ARM Cortex-A8
+ development board).
+ </para></listitem>
+ <listitem><para id='term-container-layer'>
+ <emphasis>Container Layer:</emphasis>
+ Layers that hold other layers.
+ An example of a container layer is the
+ <filename>meta-intel</filename> layer.
+ This layer contains BSP layers for the Intel-core2-32
+ <trademark class='registered'>Intel</trademark> Common Core
+ (Intel-core2-32) and the Intel-corei7-64
+ <trademark class='registered'>Intel</trademark> Common Core
+ (Intel-corei7-64).
+ the <filename>meta-intel</filename> layer also contains
+ the <filename>common/</filename> directory, which contains
+ common content across those layers.
+ </para></listitem>
+ <listitem><para id='cross-development-toolchain'>
+ <emphasis>Cross-Development Toolchain:</emphasis>
+ In general, a cross-development toolchain is a collection of
+ software development tools and utilities that run on one
+ architecture and allow you to develop software for a
+ different, or targeted, architecture.
+ These toolchains contain cross-compilers, linkers, and
+ debuggers that are specific to the target architecture.</para>
+
+ <para>The Yocto Project supports two different cross-development
+ toolchains:
+ <itemizedlist>
+ <listitem><para>
+ A toolchain only used by and within
+ BitBake when building an image for a target
+ architecture.
+ </para></listitem>
+ <listitem><para>A relocatable toolchain used outside of
+ BitBake by developers when developing applications
+ that will run on a targeted device.
+ </para></listitem>
+ </itemizedlist></para>
+
+ <para>Creation of these toolchains is simple and automated.
+ For information on toolchain concepts as they apply to the
+ Yocto Project, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ You can also find more information on using the
+ relocatable toolchain in the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
+ A custom SDK for application developers.
+ This eSDK allows developers to incorporate their library
+ and programming changes back into the image to make
+ their code available to other application developers.</para>
+
+ <para>For information on the eSDK, see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Image:</emphasis>
+ An image is an artifact of the BitBake build process given
+ a collection of recipes and related Metadata.
+ Images are the binary output that run on specific hardware or
+ QEMU and are used for specific use-cases.
+ For a list of the supported image types that the Yocto Project
+ provides, see the
+ "<link linkend='ref-images'>Images</link>"
+ chapter.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Layer:</emphasis>
+ A collection of related recipes.
+ Layers allow you to consolidate related metadata to
+ customize your build.
+ Layers also isolate information used when building
+ for multiple architectures.
+ Layers are hierarchical in their ability to override
+ previous specifications.
+ You can include any number of available layers from the
+ Yocto Project and customize the build by adding your
+ layers after them.
+ You can search the Layer Index for layers used within
+ Yocto Project.</para>
+
+ <para>For introductory information on layers, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ For more detailed information on layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ For a discussion specifically on BSP Layers, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+ section in the Yocto Project Board Support Packages (BSP)
+ Developer's Guide.
+ </para></listitem>
+ <listitem><para id='metadata'>
+ <emphasis>Metadata:</emphasis>
+ A key element of the Yocto Project is the Metadata that
+ is used to construct a Linux distribution and is contained
+ in the files that the
+ <link linkend='build-system-term'>OpenEmbedded build system</link>
+ parses when building an image.
+ In general, Metadata includes recipes, configuration
+ files, and other information that refers to the build
+ instructions themselves, as well as the data used to
+ control what things get built and the effects of the
+ build.
+ Metadata also includes commands and data used to
+ indicate what versions of software are used, from
+ where they are obtained, and changes or additions to the
+ software itself (patches or auxiliary files) that
+ are used to fix bugs or customize the software for use
+ in a particular situation.
+ OpenEmbedded-Core is an important set of validated
+ metadata.</para>
+
+ <para>In the context of the kernel ("kernel Metadata"), the
+ term refers to the kernel config fragments and features
+ contained in the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
+ Git repository.
+ </para></listitem>
+ <listitem><para id='oe-core'>
+ <emphasis>OpenEmbedded-Core (OE-Core):</emphasis>
+ OE-Core is metadata comprised of foundational recipes,
+ classes, and associated files that are meant to be
+ common among many different OpenEmbedded-derived systems,
+ including the Yocto Project.
+ OE-Core is a curated subset of an original repository
+ developed by the OpenEmbedded community that has been
+ pared down into a smaller, core set of continuously
+ validated recipes.
+ The result is a tightly controlled and an quality-assured
+ core set of recipes.</para>
+
+ <para>You can see the Metadata in the
+ <filename>meta</filename> directory of the Yocto Project
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>.
+ </para></listitem>
+ <listitem><para id='build-system-term'>
+ <emphasis>OpenEmbedded Build System:</emphasis>
+ The build system specific to the Yocto Project.
+ The OpenEmbedded build system is based on another project known
+ as "Poky", which uses
+ <link linkend='bitbake-term'>BitBake</link> as the task
+ executor.
+ Throughout the Yocto Project documentation set, the
+ OpenEmbedded build system is sometimes referred to simply
+ as "the build system".
+ If other build systems, such as a host or target build system
+ are referenced, the documentation clearly states the
+ difference.
+ <note>
+ For some historical information about Poky, see the
+ <link linkend='poky'>Poky</link> term.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Package:</emphasis>
+ In the context of the Yocto Project, this term refers to a
+ recipe's packaged output produced by BitBake (i.e. a
+ "baked recipe").
+ A package is generally the compiled binaries produced from the
+ recipe's sources.
+ You "bake" something by running it through BitBake.</para>
+
+ <para>It is worth noting that the term "package" can,
+ in general, have subtle meanings.
+ For example, the packages referred to in the
+ "<link linkend='required-packages-for-the-host-development-system'>Required Packages for the Host Development System</link>"
+ section are compiled binaries that, when installed, add
+ functionality to your Linux distribution.</para>
+
+ <para>Another point worth noting is that historically within
+ the Yocto Project, recipes were referred to as packages - thus,
+ the existence of several BitBake variables that are seemingly
+ mis-named,
+ (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
+ <link linkend='var-PV'><filename>PV</filename></link>, and
+ <link linkend='var-PE'><filename>PE</filename></link>).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Package Groups:</emphasis>
+ Arbitrary groups of software Recipes.
+ You use package groups to hold recipes that, when built,
+ usually accomplish a single task.
+ For example, a package group could contain the recipes for a
+ company’s proprietary or value-add software.
+ Or, the package group could contain the recipes that enable
+ graphics.
+ A package group is really just another recipe.
+ Because package group files are recipes, they end with the
+ <filename>.bb</filename> filename extension.
+ </para></listitem>
+ <listitem><para id='poky'>
+ <emphasis>Poky:</emphasis>
+ Poky, which is pronounced <emphasis>Pock</emphasis>-ee,
+ is a reference embedded distribution and a reference
+ test configuration.
+ Poky provides the following:
+ <itemizedlist>
+ <listitem><para>
+ A base-level functional distro used to illustrate
+ how to customize a distribution.
+ </para></listitem>
+ <listitem><para>
+ A means by which to test the Yocto Project
+ components (i.e. Poky is used to validate
+ the Yocto Project).
+ </para></listitem>
+ <listitem><para>
+ A vehicle through which you can download
+ the Yocto Project.
+ </para></listitem>
+ </itemizedlist>
+ Poky is not a product level distro.
+ Rather, it is a good starting point for customization.
+ <note>
+ Poky began an open-source
+ project initially developed by OpenedHand.
+ OpenedHand developed Poky from the existing
+ OpenEmbedded build system to create a commercially
+ supportable build system for embedded Linux.
+ After Intel Corporation acquired OpenedHand, the
+ poky project became the basis for the Yocto Project's
+ build system.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Recipe:</emphasis>
+ A set of instructions for building packages.
+ A recipe describes where you get source code, which patches
+ to apply, how to configure the source, how to compile it and so on.
+ Recipes also describe dependencies for libraries or for other
+ recipes.
+ Recipes represent the logical unit of execution, the software
+ to build, the images to build, and use the
+ <filename>.bb</filename> file extension.
+ </para></listitem>
+ <listitem><para id='reference-kit-term'>
+ <emphasis>Reference Kit:</emphasis>
+ A working example of a system, which includes a
+ <link linkend='board-support-package-bsp-term'>BSP</link>
+ as well as a
+ <link linkend='hardware-build-system-term'>build host</link>
+ and other components, that can work on specific hardware.
+ </para></listitem>
+ <listitem>
+ <para id='source-directory'>
+ <emphasis>Source Directory:</emphasis>
+ This term refers to the directory structure created as a result
+ of creating a local copy of the <filename>poky</filename> Git
+ repository <filename>git://git.yoctoproject.org/poky</filename>
+ or expanding a released <filename>poky</filename> tarball.
+ <note>
+ Creating a local copy of the <filename>poky</filename>
+ Git repository is the recommended method for setting up
+ your Source Directory.
+ </note>
+ Sometimes you might hear the term "poky directory" used to refer
+ to this directory structure.
+ <note>
+ The OpenEmbedded build system does not support file or
+ directory names that contain spaces.
+ Be sure that the Source Directory you use does not contain
+ these types of names.
+ </note></para>
+
+ <para>The Source Directory contains BitBake, Documentation,
+ Metadata and other files that all support the Yocto Project.
+ Consequently, you must have the Source Directory in place on
+ your development system in order to do any development using
+ the Yocto Project.</para>
+
+ <para>When you create a local copy of the Git repository, you
+ can name the repository anything you like.
+ Throughout much of the documentation, "poky"
+ is used as the name of the top-level folder of the local copy of
+ the poky Git repository.
+ So, for example, cloning the <filename>poky</filename> Git
+ repository results in a local Git repository whose top-level
+ folder is also named "poky".</para>
+
+ <para>While it is not recommended that you use tarball expansion
+ to set up the Source Directory, if you do, the top-level
+ directory name of the Source Directory is derived from the
+ Yocto Project release tarball.
+ For example, downloading and unpacking
+ <filename>&YOCTO_POKY_TARBALL;</filename> results in a
+ Source Directory whose root folder is named
+ <filename>&YOCTO_POKY;</filename>.</para>
+
+ <para>It is important to understand the differences between the
+ Source Directory created by unpacking a released tarball as
+ compared to cloning
+ <filename>git://git.yoctoproject.org/poky</filename>.
+ When you unpack a tarball, you have an exact copy of the files
+ based on the time of release - a fixed release point.
+ Any changes you make to your local files in the Source Directory
+ are on top of the release and will remain local only.
+ On the other hand, when you clone the <filename>poky</filename>
+ Git repository, you have an active development repository with
+ access to the upstream repository's branches and tags.
+ In this case, any local changes you make to the local
+ Source Directory can be later applied to active development
+ branches of the upstream <filename>poky</filename> Git
+ repository.</para>
+
+ <para>For more information on concepts related to Git
+ repositories, branches, and tags, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para></listitem>
+ <listitem><para><emphasis>Task:</emphasis>
+ A unit of execution for BitBake (e.g.
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
+ <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
+ <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
+ and so forth).
+ </para></listitem>
+ <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
+ A web interface to the Yocto Project's
+ <link linkend='build-system-term'>OpenEmbedded Build System</link>.
+ The interface enables you to configure and run your builds.
+ Information about builds is collected and stored in a database.
+ For information on Toaster, see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upstream:</emphasis>
+ A reference to source code or repositories
+ that are not local to the development system but located in a
+ master area that is controlled by the maintainer of the source
+ code.
+ For example, in order for a developer to work on a particular
+ piece of code, they need to first get a copy of it from an
+ "upstream" source.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml
index 2b01723..1c55a92 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml
@@ -22,7 +22,7 @@
<link linkend='var-D'>D</link>
<link linkend='var-EFI_PROVIDER'>E</link>
<link linkend='var-FEATURE_PACKAGES'>F</link>
- <link linkend='var-GDB'>G</link>
+ <link linkend='var-GCCPIE'>G</link>
<link linkend='var-HOMEPAGE'>H</link>
<link linkend='var-ICECC_DISABLED'>I</link>
<!-- <link linkend='var-glossary-j'>J</link> -->
@@ -72,12 +72,13 @@
<glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
<info>
- ALLOW_EMPTY[doc] = "Specifies if an output package should still be produced if it is empty."
+ ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Specifies if an output package should still be produced if it is empty.
+ Specifies whether to produce an output package even if it is
+ empty.
By default, BitBake does not produce empty packages.
This default behavior can cause issues when there is an
<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
@@ -253,13 +254,14 @@
<glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
<info>
- APPEND[doc] = "An override list of append strings for each LABEL."
+ APPEND[doc] = "An override list of append strings for target specified using LABELS."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- An override list of append strings for each
- <link linkend='var-LABELS'><filename>LABEL</filename></link>.
+ An override list of append strings for each target
+ specified with
+ <link linkend='var-LABELS'><filename>LABELS</filename></link>.
</para>
<para>
@@ -354,7 +356,7 @@
</para>
<para>
- In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename>
+ In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
mostly specifies native tools that should not be built.
An example is <filename>git-native</filename>, which when
specified, allows for the Git binary from the host to be
@@ -775,10 +777,9 @@
WARN: Issue a warning but continue the
build when a threshold is broken.
Subsequent warnings are issued as
- defined by the
- <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
- which must be defined in the
- conf/local.conf file.
+ defined by the BB_DISKMON_WARNINTERVAL
+ variable, which must be defined in
+ the conf/local.conf file.
<replaceable>dir</replaceable> is:
Any directory you choose. You can specify one or
@@ -971,15 +972,41 @@
<para>
For more information on speeding up builds, see the
- "<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
+ <info>
+ BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Specifies the time (in seconds) after which to unload the
+ BitBake server due to inactivity.
+ Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
+ long the BitBake server stays resident between invocations.
+ </para>
+
+ <para>
+ For example, the following statement in your
+ <filename>local.conf</filename> file instructs the server
+ to be unloaded after 20 seconds of inactivity:
+ <literallayout class='monospaced'>
+ BB_SERVER_TIMEOUT = "20"
+ </literallayout>
+ If you want the server to never be unloaded, set
+ <filename>BB_SERVER_TIMEOUT</filename> to "-1".
</para>
</glossdef>
</glossentry>
<glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
<info>
- BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk' and multilibs."
+ BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk', and multilibs."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -1116,6 +1143,53 @@
</glossdef>
</glossentry>
+ <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
+ <info>
+ BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Activates content when identified layers are present.
+ You identify the layers by the collections that the layers
+ define.
+ </para>
+
+ <para>
+ Use the <filename>BBFILES_DYNAMIC</filename> variable to
+ avoid <filename>.bbappend</filename> files whose
+ corresponding <filename>.bb</filename> file is in a layer
+ that attempts to modify other layers through
+ <filename>.bbappend</filename> but does not want to
+ introduce a hard dependency on those other layers.
+ </para>
+
+ <para>
+ Use the following form for
+ <filename>BBFILES_DYNAMIC</filename>:
+ <literallayout class='monospaced'>
+ <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
+ </literallayout>
+ The following example identifies two collection names and
+ two filename patterns:
+ <literallayout class='monospaced'>
+ BBFILES_DYNAMIC += " \
+ clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
+ core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
+ "
+ </literallayout>
+ This next example shows an error message that occurs
+ because invalid entries are found, which cause parsing to
+ abort:
+ <literallayout class='monospaced'>
+ ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
+ /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
+ /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
<info>
BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
@@ -1200,8 +1274,8 @@
The expressions are compared against the full paths to
the files.
For complete syntax information, see Python's
- documentation at
- <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
+ documentation for the appropriate release at
+ <ulink url='http://docs.python.org/release/'></ulink>.
</para>
<para>
@@ -1520,12 +1594,12 @@
<glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
<info>
- BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the build host."
+ BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C preprocessor (i.e. to both the C and the C++ compilers) when building for the build host."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Specifies the flags to pass to the C pre-processor
+ Specifies the flags to pass to the C preprocessor
(i.e. to both the C and the C++ compilers) when building
for the build host.
When building in the <filename>-native</filename> context,
@@ -1797,7 +1871,7 @@
<para>
Git requires that the value you provide for the
<filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
- takes the form of "name <email@host>".
+ takes the form of "name <replaceable>email@host</replaceable>".
Providing an email address or host that is not valid does
not produce an error.
</para>
@@ -1849,12 +1923,12 @@
class, this variable specifies the build history features
to be enabled.
For more information on how build history works, see the
- "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
<para>
- You can specify three features in the form of a
+ You can specify these features in the form of a
space-separated list:
<itemizedlist>
<listitem><para><emphasis>image:</emphasis>
@@ -1869,12 +1943,20 @@
Analysis of the contents of the software
development kit (SDK).
</para></listitem>
+ <listitem><para><emphasis>task:</emphasis>
+ Save output file signatures for
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
+ (sstate) tasks.
+ This saves one file per task and lists the SHA-256
+ checksums for each file staged (i.e. the output of
+ the task).
+ </para></listitem>
</itemizedlist>
</para>
<para>
By default, the <filename>buildhistory</filename> class
- enables all three features:
+ enables the following features:
<literallayout class='monospaced'>
BUILDHISTORY_FEATURES ?= "image package sdk"
</literallayout>
@@ -2212,13 +2294,6 @@
level, in case the hardware supports Bluetooth but you
do not ever intend to use it.
</para>
-
- <para>
- For more information, see the
- <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
- and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
- variables.
- </para>
</glossdef>
</glossentry>
@@ -2732,13 +2807,13 @@
<glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
<info>
- COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded Core Metadata layer (i.e. meta)."
+ COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Specifies the parent directory of the OpenEmbedded
- Core Metadata layer (i.e. <filename>meta</filename>).
+ Specifies the parent directory of the OpenEmbedded-Core
+ Metadata layer (i.e. <filename>meta</filename>).
</para>
<para>
@@ -2938,12 +3013,12 @@
task.
This location defaults to:
<literallayout class='monospaced'>
- ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image
+ ${WORKDIR}/image
</literallayout>
<note><title>Caution</title>
Tasks that read from or write to this directory should
run under
- <link linkend='fakeroot-and-pseudo'>fakeroot</link>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
</note>
</para>
</glossdef>
@@ -3190,9 +3265,10 @@
add any runtime dependencies between the
packages produced by the two recipes.
However, as explained in the
- "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
- section, runtime dependencies will often be
- added automatically, meaning
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and
+ Concepts Manual, runtime dependencies will
+ often be added automatically, meaning
<filename>DEPENDS</filename> alone is
sufficient for most recipes.
</para></listitem>
@@ -3234,13 +3310,13 @@
<glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
<info>
- DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+ DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Points to the general area that the OpenEmbedded build
- system uses to place images, packages, SDKs and other output
+ system uses to place images, packages, SDKs, and other output
files that are ready to be used outside of the build system.
By default, this directory resides within the
<link linkend='build-directory'>Build Directory</link>
@@ -3254,18 +3330,19 @@
section.
For more detail on the contents of the
<filename>deploy</filename> directory, see the
- "<link linkend='images-dev-environment'>Images</link>",
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>",
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
and
- "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
- sections.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
+ sections all in the Yocto Project Overview and Concepts
+ Manual.
</para>
</glossdef>
</glossentry>
<glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
<info>
- DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+ DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -3297,8 +3374,8 @@
<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
task writes Debian packages into the appropriate folder.
For more information on how packaging works, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</glossdef>
</glossentry>
@@ -3327,16 +3404,18 @@
section.
For more detail on the contents of the
<filename>deploy</filename> directory, see the
- "<link linkend='images-dev-environment'>Images</link>" and
- "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
- sections.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
+ sections both in the Yocto Project Overview and Concepts
+ Manual.
</para>
</glossdef>
</glossentry>
<glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
<info>
- DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+ DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -3367,15 +3446,15 @@
<link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
task writes IPK packages into the appropriate folder.
For more information on how packaging works, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</glossdef>
</glossentry>
<glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
<info>
- DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+ DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -3406,15 +3485,15 @@
<link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
task writes RPM packages into the appropriate folder.
For more information on how packaging works, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</glossdef>
</glossentry>
<glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
<info>
- DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system."
+ DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -3445,8 +3524,8 @@
<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
task writes TAR packages into the appropriate folder.
For more information on how packaging works, see the
- "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</glossdef>
</glossentry>
@@ -3698,7 +3777,7 @@
It is not intended to be user-configurable.
It is best to just reference the variable to see which distro features are
being backfilled for all distro configurations.
- See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
+ See the <link linkend='ref-features-backfill'>Feature Backfilling</link> section for
more information.
</para>
</glossdef>
@@ -4386,7 +4465,7 @@
<glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
<info>
- EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated type."
+ EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated image type."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -4394,8 +4473,8 @@
Specifies additional options for the image
creation command that has been specified in
<link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
- When setting this variable, you should
- use an override for the associated type.
+ When setting this variable, use an override for the
+ associated image type.
Here is an example:
<literallayout class='monospaced'>
EXTRA_IMAGECMD_ext3 ?= "-i 4096"
@@ -4787,7 +4866,7 @@
The previous statement appears in the
<filename>linux-yocto-dev.bbappend</filename> file, which
is found in the Yocto Project
- <link linkend='source-repositories'>Source Repositories</link>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
in
<filename>meta-intel/common/recipes-kernel/linux</filename>.
Here, the machine override is a special
@@ -4821,7 +4900,7 @@
<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
You can find more information on how overrides are handled
in the
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>.
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</para>
<para>
@@ -4853,7 +4932,9 @@
During the build process, BitBake searches each directory in
<filename>FILESPATH</filename> in the specified order when
looking for files and patches specified by each
- <filename>file://</filename> URI in a recipe.
+ <filename>file://</filename> URI in a recipe's
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ statements.
</para>
<para>
@@ -4881,9 +4962,19 @@
If you want the build system to find patches or files
that reside with your append files, you need to extend
the <filename>FILESPATH</filename> variable by using
- the
- <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
- variable.
+ the <filename>FILESEXTRAPATHS</filename> variable.
+ </para>
+
+ <para>
+ You can find out more about the patching process in the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
+ section in the Yocto Project Overview and Concepts Manual
+ and the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ See the
+ <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
+ task as well.
</para>
</glossdef>
</glossentry>
@@ -5004,6 +5095,30 @@
<glossdiv id='var-glossary-g'><title>G</title>
+ <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
+ <info>
+ GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Enables Position Independent Executables (PIE) within the
+ GNU C Compiler (GCC).
+ Enabling PIE in the GCC makes Return Oriented Programming
+ (ROP) attacks much more difficult to
+ execute.
+ </para>
+
+ <para>
+ By default the <filename>security_flags.inc</filename>
+ file enables PIE by setting the variable as follows:
+ <literallayout class='monospaced'>
+ GCCPIE ?= "--enable-default-pie"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-GDB'><glossterm>GDB</glossterm>
<info>
GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
@@ -5031,13 +5146,13 @@
<glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
<info>
- GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish generate all LIBC locals, which can be time consuming."
+ GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish to generate all LIBC locals, which can be time consuming."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies the list of GLIBC locales to generate should you
- not wish generate all LIBC locals, which can be time
+ not wish to generate all LIBC locals, which can be time
consuming.
<note>
If you specifically remove the locale
@@ -5307,7 +5422,7 @@
<glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
<info>
- HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for with the build is occurring in the context of the current recipe."
+ HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the build is occurring in the context of the current recipe."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -5383,7 +5498,7 @@
contamination.
Unlike
<link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
- the OpenEmbedded build system does not produce and error
+ the OpenEmbedded build system does not produce an error
if a tool specified in the value of
<filename>HOSTTOOLS_NONFATAL</filename> is not found on the
build host.
@@ -5402,7 +5517,7 @@
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies the name of the vendor.
<filename>HOST_VENDOR</filename> is normally the same as
- <link linkend='var-TARGET_PREFIX'><filename>TARGET_VENDOR</filename></link>.
+ <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>.
</para>
</glossdef>
</glossentry>
@@ -5620,18 +5735,17 @@
<glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
<info>
- IMAGE_BOOT_FILES[doc] = "Whitespace separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition. Entries will be installed under a same name as the source file. To change the destination file name, pass a desired name after a semicolon (eg. u-boot.img;uboot)."
+ IMAGE_BOOT_FILES[doc] = "A space-separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
A space-separated list of files installed into the
- boot partition when preparing an image using the
- <filename>wic</filename> tool with the
- <filename>bootimg-partition</filename> source
+ boot partition when preparing an image using the Wic tool
+ with the <filename>bootimg-partition</filename> source
plugin.
- By default, the files are installed under
- the same name as the source files.
+ By default, the files are installed under the same name as
+ the source files.
To change the installed name, separate it from the
original name with a semi-colon (;).
Source files need to be located in
@@ -5647,9 +5761,8 @@
<para>
Alternatively, source files can be picked up using
a glob pattern.
- In this case, the destination file
- will have the same name as the base name of the source file
- path.
+ In this case, the destination file must have the same name
+ as the base name of the source file path.
To install files into a directory within the
target location, pass its name after a semi-colon
(;).
@@ -5665,6 +5778,15 @@
<filename>boot</filename> directory within the
target partition.
</para>
+
+ <para>
+ You can find information on how to use the Wic tool in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ Reference material for Wic is located in the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
+ chapter.
+ </para>
</glossdef>
</glossentry>
@@ -5840,70 +5962,86 @@
<glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
<info>
- IMAGE_INSTALL[doc] = "Specifies the packages to install into an image. Image recipes set IMAGE_INSTALL to specify the packages to install into an image through image.bbclass."
+ IMAGE_INSTALL[doc] = "Used by recipes to specify the packages to install into an image through image.bbclass."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Specifies the packages to install into an image.
- The <filename>IMAGE_INSTALL</filename> variable is a
- mechanism for an image recipe and you should use it
- with care to avoid ordering issues.
- <note>
- When working with an
- <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
- image, do not use the <filename>IMAGE_INSTALL</filename>
- variable to specify packages for installation.
- Instead, use the
- <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
- variable, which allows the initial RAM filesystem
- (initramfs) recipe to use a fixed set of packages and
- not be affected by <filename>IMAGE_INSTALL</filename>.
- For information on creating an initramfs, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </note>
+ Used by recipes to specify the packages to install into an
+ image through the
+ <link linkend='ref-classes-image'><filename>image</filename></link>
+ class.
+ Use the <filename>IMAGE_INSTALL</filename> variable with
+ care to avoid ordering issues.
</para>
<para>
Image recipes set <filename>IMAGE_INSTALL</filename>
to specify the packages to install into an image through
<filename>image.bbclass</filename>.
- Additionally, "helper" classes exist, such as
- <filename>core-image.bbclass</filename>, that can take
+ Additionally, "helper" classes such as the
+ <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
+ class exist that can take lists used with
<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
- lists and turn these into auto-generated entries in
+ and turn them into auto-generated entries in
<filename>IMAGE_INSTALL</filename> in addition to its
default contents.
</para>
<para>
- Using <filename>IMAGE_INSTALL</filename> with the
- <filename>+=</filename> operator from the
- <filename>/conf/local.conf</filename> file or from within
- an image recipe is not recommended as it can cause ordering
- issues.
- Since <filename>core-image.bbclass</filename> sets
- <filename>IMAGE_INSTALL</filename> to a default value using
- the <filename>?=</filename> operator, using a
- <filename>+=</filename> operation against
- <filename>IMAGE_INSTALL</filename> will result in
- unexpected behavior when used in
- <filename>conf/local.conf</filename>.
- Furthermore, the same operation from within an image
- recipe may or may not succeed depending on the specific
- situation.
- In both these cases, the behavior is contrary to how most
- users expect the <filename>+=</filename> operator to work.
- </para>
-
- <para>
When you use this variable, it is best to use it as follows:
<literallayout class='monospaced'>
IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
</literallayout>
Be sure to include the space between the quotation character
and the start of the package name or names.
+ <note><title>Caution</title>
+ <itemizedlist>
+ <listitem><para>
+ When working with a
+ <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
+ image, do not use the
+ <filename>IMAGE_INSTALL</filename> variable to
+ specify packages for installation.
+ Instead, use the
+ <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
+ variable, which allows the initial RAM
+ filesystem (initramfs) recipe to use a fixed
+ set of packages and not be affected by
+ <filename>IMAGE_INSTALL</filename>.
+ For information on creating an initramfs, see
+ the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual.
+ </para></listitem>
+ <listitem><para>
+ Using <filename>IMAGE_INSTALL</filename> with
+ the
+ <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
+ BitBake operator within the
+ <filename>/conf/local.conf</filename> file or
+ from within an image recipe is not recommended.
+ Use of this operator in these ways can cause
+ ordering issues.
+ Since <filename>core-image.bbclass</filename>
+ sets <filename>IMAGE_INSTALL</filename> to a
+ default value using the
+ <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
+ operator, using a <filename>+=</filename>
+ operation against
+ <filename>IMAGE_INSTALL</filename> results in
+ unexpected behavior when used within
+ <filename>conf/local.conf</filename>.
+ Furthermore, the same operation from within
+ an image recipe may or may not succeed
+ depending on the specific situation.
+ In both these cases, the behavior is contrary
+ to how most users expect the
+ <filename>+=</filename> operator to work.
+ </para></listitem>
+ </itemizedlist>
+ </note>
</para>
</glossdef>
</glossentry>
@@ -5981,8 +6119,8 @@
variables.
You can find information on how the image
is created in the
- "<link linkend='image-generation-dev-environment'>Image Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</glossdef>
</glossentry>
@@ -6056,12 +6194,12 @@
<glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
<info>
- IMAGE_PKGTYPE[doc] = "Defines the package type (DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."
+ IMAGE_PKGTYPE[doc] = "Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Defines the package type (DEB, RPM, IPK, or TAR) used
+ Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
by the OpenEmbedded build system.
The variable is defined appropriately by the
<link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
@@ -6108,13 +6246,13 @@
<glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
<info>
- IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the final image output files."
+ IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies a list of functions to call once the
- OpenEmbedded build system has created the final image
+ OpenEmbedded build system creates the final image
output files.
You can specify functions separated by semicolons:
<literallayout class='monospaced'>
@@ -6136,13 +6274,13 @@
<glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
<info>
- IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the final image output files."
+ IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies a list of functions to call before the
- OpenEmbedded build system has created the final image
+ OpenEmbedded build system creates the final image
output files.
You can specify functions separated by semicolons:
<literallayout class='monospaced'>
@@ -6488,7 +6626,7 @@
For more information on <filename>INHERIT</filename>, see
the
"<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
- section in the Yocto Project Bitbake User Manual.
+ section in the Bitbake User Manual.
</para>
</glossdef>
</glossentry>
@@ -6662,8 +6800,7 @@
<para>
You can also find more information by referencing the
<filename>meta-poky/conf/local.conf.sample.extended</filename>
- configuration file in the
- <link linkend='source-directory'>Source Directory</link>,
+ configuration file in the Source Directory,
the
<link linkend='ref-classes-image'><filename>image</filename></link>
class, and the
@@ -6729,8 +6866,7 @@
<para>
Setting the variable to "1" in a configuration file causes the
OpenEmbedded build system to generate a kernel image with the
- initramfs specified in
- <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
+ initramfs specified in <filename>INITRAMFS_IMAGE</filename>
bundled within:
<literallayout class='monospaced'>
INITRAMFS_IMAGE_BUNDLE = "1"
@@ -7008,7 +7144,7 @@
<glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
<info>
- KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched and configured during a build."
+ KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched, and configured during a build."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -7112,7 +7248,8 @@
For more information on how to use the
<filename>KBUILD_DEFCONFIG</filename> variable, see the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"
- section.
+ section in the Yocto Project Linux Kernel Development
+ Manual.
</para>
</glossdef>
</glossentry>
@@ -7155,7 +7292,7 @@
<glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
<info>
- KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the <filename>.dtb</filename>) file."
+ KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the .dtb) file."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -7415,7 +7552,8 @@
class.
For information on how this variable is used, see the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
- section.
+ section in the Yocto Project Linux Kernel Development
+ Manual.
</para>
<para>
@@ -7446,7 +7584,8 @@
class.
For information on how this variable is used, see the
"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
- section.
+ section in the Yocto Project Linux Kernel Development
+ Manual.
</para>
<para>
@@ -7696,6 +7835,53 @@
</glossdef>
</glossentry>
+ <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
+ <info>
+ LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ Lists the versions of the
+ <link linkend='oe-core'>OpenEmbedded-Core</link> for which
+ a layer is compatible.
+ Using the <filename>LAYERSERIES_COMPAT</filename> variable
+ allows the layer maintainer to indicate which combinations
+ of the layer and OE-Core can be expected to work.
+ The variable gives the system a way to detect when a layer
+ has not been tested with new releases of OE-Core (e.g.
+ the layer is not maintained).
+ </para>
+
+ <para>
+ To specify the OE-Core versions for which a layer is
+ compatible, use this variable in your layer's
+ <filename>conf/layer.conf</filename> configuration file.
+ For the list, use the Yocto Project
+ <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
+ (e.g. &DISTRO_NAME_NO_CAP;).
+ To specify multiple OE-Core versions for the layer,
+ use a space-separated list:
+ <literallayout class='monospaced'>
+ LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
+ </literallayout>
+ <note>
+ Setting <filename>LAYERSERIES_COMPAT</filename> is
+ required by the Yocto Project Compatible version 2
+ standard.
+ The OpenEmbedded build system produces a warning if
+ the variable is not set for any given layer.
+ </note>
+ </para>
+
+ <para>
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
<info>
LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
@@ -7766,13 +7952,13 @@
<glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
<info>
- LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (.so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."
+ LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (i.e. .so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies the lead (or primary) compiled library file
- (<filename>.so</filename>) that the
+ (i.e. <filename>.so</filename>) that the
<link linkend='ref-classes-debian'><filename>debian</filename></link>
class applies its naming policy to given a recipe that
packages multiple libraries.
@@ -7808,8 +7994,8 @@
<link linkend='var-LICENSE'><filename>LICENSE</filename></link>
is set to "CLOSED").</para>
<para>For more information, see the
- "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
- Tracking License Changes</link>" section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</glossdef>
</glossentry>
@@ -7944,8 +8130,8 @@
require additional licenses in order to be used in a
commercial product.
For more information, see the
- "<link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</glossdef>
</glossentry>
@@ -7964,8 +8150,8 @@
This practice is otherwise known as "whitelisting"
license flags.
For more information, see the
- <link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</glossdef>
</glossentry>
@@ -8186,7 +8372,7 @@
<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
<info>
- MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine essential' variable, the list of packages are essential for the machine to boot."
+ MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -8194,7 +8380,7 @@
A list of required machine-specific packages to install as part of
the image being built.
The build process depends on these packages being present.
- Furthermore, because this is a "machine essential" variable, the list of
+ Furthermore, because this is a "machine-essential" variable, the list of
packages are essential for the machine to boot.
The impact of this variable affects images based on
<filename>packagegroup-core-boot</filename>,
@@ -8223,7 +8409,7 @@
<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
<info>
- MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine essential' variable, the list of packages are essential for the machine to boot."
+ MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -8231,7 +8417,7 @@
A list of recommended machine-specific packages to install as part of
the image being built.
The build process does not depend on these packages being present.
- However, because this is a "machine essential" variable, the list of
+ However, because this is a "machine-essential" variable, the list of
packages are essential for the machine to boot.
The impact of this variable affects images based on
<filename>packagegroup-core-boot</filename>,
@@ -8421,7 +8607,7 @@
It is not intended to be user-configurable.
It is best to just reference the variable to see which machine features are
being backfilled for all machine configurations.
- See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
+ See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
more information.
</para>
</glossdef>
@@ -8439,7 +8625,7 @@
that should not be backfilled (i.e. added to
<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
during the build.
- See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
+ See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
more information.
</para>
</glossdef>
@@ -8529,14 +8715,14 @@
<glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
<info>
- MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package, such as a Multilib version."
+ MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package (i.e. a Multilib version)."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies a prefix has been added to
<link linkend='var-PN'><filename>PN</filename></link> to create a special version
- of a recipe or package, such as a Multilib version.
+ of a recipe or package (i.e. a Multilib version).
The variable is used in places where the prefix needs to be
added to or removed from a the name (e.g. the
<link linkend='var-BPN'><filename>BPN</filename></link> variable).
@@ -8827,7 +9013,7 @@
<glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
<info>
- NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Realize that some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed."
+ NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -9003,8 +9189,8 @@
for details on how this class applies these additional
sed command arguments.
For general information on the
- <filename>binconfig.bbclass</filename> class, see the
- "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
+ <filename>binconfig</filename> class, see the
+ "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
section.
</para>
</glossdef>
@@ -9183,8 +9369,9 @@
<filename>OVERRIDES</filename> in the output of the
<filename>bitbake -e</filename> command.
See the
- "<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>"
- section for more information.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
+ section in the Yocto Project Development Tasks
+ Manual for more information.
</note>
</para>
</glossdef>
@@ -9223,11 +9410,17 @@
By default, the value of this variable is set to
<link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
when building for the target,
- <filename>BUILD_ARCH</filename> when building for the
- build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
+ <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
+ when building for the
+ build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
for the SDK.
+ <note>
+ See
+ <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
+ for more information.
+ </note>
However, if your recipe's output packages are built
- specific to the target machine rather than general for
+ specific to the target machine rather than generally for
the architecture of the machine, you should set
<filename>PACKAGE_ARCH</filename> to the value of
<link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
@@ -9298,9 +9491,10 @@
</literallayout>
<note><title>Warning</title>
While it is a legal option, the
- <filename>package_tar</filename> class is broken
- and is not supported.
- It is recommended that you do not use it.
+ <filename>package_tar</filename> class has limited
+ functionality due to no support for package
+ dependencies by that backend.
+ Therefore, it is recommended that you do not use it.
</note>
The build system uses only the first argument in the list
as the package manager when creating your image or SDK.
@@ -9477,20 +9671,29 @@
<glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
<info>
- PACKAGE_FEED_ARCHS[doc] = "Specifies user-defined package architectures when constructing package feed URIs."
+ PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Specifies the package architectures used as part of the
- package feed URIs during the build.
- The <filename>PACKAGE_FEED_ARCHS</filename> variable is
- appended to the final package feed URI, which is constructed
- using the
+ Optionally specifies the package architectures used as
+ part of the package feed URIs during the build.
+ When used, the <filename>PACKAGE_FEED_ARCHS</filename>
+ variable is appended to the final package feed URI, which
+ is constructed using the
<link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
and
<link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
variables.
+ <note><title>Tip</title>
+ You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
+ variable to whitelist specific package architectures.
+ If you do not need to whitelist specific architectures,
+ which is a common case, you can omit this variable.
+ Omitting the variable results in all available
+ architectures for the current machine being included
+ into remote package feeds.
+ </note>
</para>
<para>
@@ -9798,7 +10001,7 @@
In this case, <filename>--with-croco</filename> is
added to the configure script argument list and
<filename>libcroco</filename> is added to
- <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
+ <filename>DEPENDS</filename>.
On the other hand, if the feature is disabled say through
a <filename>.bbappend</filename> file in another layer, then
the second argument <filename>--without-croco</filename> is
@@ -9870,8 +10073,8 @@
and
<link linkend='ref-classes-cmake'><filename>cmake</filename></link>
use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
- <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
- options to <filename>configure</filename> and
+ <filename>PACKAGECONFIG</filename> options to
+ <filename>configure</filename> and
<filename>cmake</filename>, respectively.
If you are using
<filename>PACKAGECONFIG</filename> but not a class that
@@ -9879,12 +10082,6 @@
you need to use
<filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
</para>
-
- <para>
- For additional information, see the
- <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
- variable.
- </para>
</glossdef>
</glossentry>
@@ -9911,12 +10108,12 @@
<glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
<info>
- PACKAGES[doc] = "The list of packages to be created from the recipe."
+ PACKAGES[doc] = "The list of packages the recipe creates."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- The list of packages to be created from the recipe.
+ The list of packages the recipe creates.
The default value is the following:
<literallayout class='monospaced'>
${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
@@ -10066,8 +10263,8 @@
<para>
For more information on speeding up builds, see the
- "<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</glossdef>
</glossentry>
@@ -10308,10 +10505,14 @@
${STAGING_DIR_HOST}/pkgdata
</literallayout>
For examples of how this data is used, see the
- "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
- section and the
- "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and Concepts Manual
+ and the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ For more information on the shared, global-state directory,
+ see
+ <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
</para>
</glossdef>
</glossentry>
@@ -10414,7 +10615,7 @@
<glossentry id='var-PN'><glossterm>PN</glossterm>
<info>
- PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package. It refers to a package name in the context of a file created or produced by the OpenEmbedded build system."
+ PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package.
</info>
<glossdef>
<para role="glossdeffirst">
@@ -10555,11 +10756,11 @@
<filename>PR</filename> to know when to rebuild a
recipe.
The build system uses the task
- <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksums</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
along with the
<link linkend='structure-build-tmp-stamps'>stamp</link>
and
- <link linkend='shared-state-cache'>shared state cache</link>
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
mechanisms.
</note>
The <filename>PR</filename> variable primarily becomes
@@ -10598,26 +10799,40 @@
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- If multiple recipes provide an item, this variable
- determines which recipe should be given preference.
- You should always suffix the variable with the name of the
- provided item, and you should set it to the
- <link linkend='var-PN'><filename>PN</filename></link>
- of the recipe to which you want to give precedence.
- Some examples:
+ If multiple recipes provide the same item, this variable
+ determines which recipe is preferred and thus provides
+ the item (i.e. the preferred provider).
+ You should always suffix this variable with the name of the
+ provided item.
+ And, you should define the variable using the preferred
+ recipe's name
+ (<link linkend='var-PN'><filename>PN</filename></link>).
+ Here is a common example:
<literallayout class='monospaced'>
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+ </literallayout>
+ In the previous example, multiple recipes are providing
+ "virtual/kernel".
+ The <filename>PREFERRED_PROVIDER</filename> variable is
+ set with the name (<filename>PN</filename>) of the recipe
+ you prefer to provide "virtual/kernel".
+ </para>
+
+ <para>
+ Following are more examples:
+ <literallayout class='monospaced'>
PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
</literallayout>
- For more information see:
- <link linkend='metadata-virtual-providers'>Metadata (Virtual Providers)</link>
+ For more information, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
+ section in the Yocto Project Development Tasks Manual.
<note>
- If you set <filename>PREFERRED_PROVIDER</filename>
- for a <filename>virtual/*</filename> item, then any
+ If you use a <filename>virtual/*</filename> item
+ with <filename>PREFERRED_PROVIDER</filename>, then any
recipe that
<link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
- that item that is not selected by
+ that item but is not selected (defined) by
<filename>PREFERRED_PROVIDER</filename> is prevented
from building, which is usually desirable since this
mechanism is designed to select between mutually
@@ -10696,8 +10911,8 @@
The <filename>_forcevariable</filename> override is
not handled specially.
This override only works because the default value of
- <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
- includes "forcevariable".
+ <filename>OVERRIDES</filename> includes
+ "forcevariable".
</note>
</para>
</glossdef>
@@ -10754,7 +10969,7 @@
<glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
<info>
- PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard' and 'extra'."
+ PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard', and 'extra'."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -10814,8 +11029,8 @@
<para>
For more information, see the
- "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
</glossdef>
</glossentry>
@@ -10860,8 +11075,7 @@
Recipes that provide the functionality in question list the
virtual target in <filename>PROVIDES</filename>.
Recipes that depend on the functionality in question can
- include the virtual target in
- <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ include the virtual target in <filename>DEPENDS</filename>
to leave the choice of provider open.
</para>
@@ -11001,8 +11215,7 @@
</para>
<para>
- Recipes that inherit the
- <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
+ Recipes that inherit the <filename>distutils</filename>
class during cross-builds also use this variable to
locate the headers and libraries of the appropriate Python
that the extension is targeting.
@@ -11131,8 +11344,8 @@
Therefore, most recipes do not need to set
<filename>RDEPENDS</filename>.
For more information, see the
- "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
<para>
@@ -11571,9 +11784,9 @@
In the example, the package name
(<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
must appear as it would in the
- <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
- namespace before any renaming of the output package by
- classes such as <filename>debian.bbclass</filename>.
+ <filename>PACKAGES</filename> namespace before any renaming
+ of the output package by classes such as
+ <filename>debian.bbclass</filename>.
</para>
<para>
@@ -11807,11 +12020,11 @@
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
The directory set up and used by the
<link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
- to which the SDK is deployed.
+ class to which the SDK is deployed.
The <filename>populate_sdk_base</filename> class defines
<filename>SDK_DEPLOY</filename> as follows:
<literallayout class='monospaced'>
- SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
+ SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
</literallayout>
</para>
</glossdef>
@@ -11830,7 +12043,7 @@
<link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
class defines the variable as follows:
<literallayout class='monospaced'>
- SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
+ SDK_DIR = "${WORKDIR}/sdk"
</literallayout>
<note>
The <filename>SDK_DIR</filename> directory is a
@@ -11876,7 +12089,7 @@
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
The manifest file for the host part of the SDK.
This file lists all the installed packages that make up
- the host part of SDK.
+ the host part of the SDK.
The file contains package information on a line-per-package
basis as follows:
<literallayout class='monospaced'>
@@ -12060,13 +12273,16 @@
<link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
class defines the variable as follows:
<literallayout class='monospaced'>
- SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
+ SDK_DIR = "${WORKDIR}/sdk"
+ SDK_OUTPUT = "${SDK_DIR}/image"
+ SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
</literallayout>
<note>
The <filename>SDK_OUTPUT</filename> directory is a
temporary directory as it is part of
- <filename>WORKDIR</filename> by way of
- <filename>SDK_DIR</filename>.
+ <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+ by way of
+ <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
The final output directory is
<link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
</note>
@@ -12096,13 +12312,13 @@
<glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
<info>
- SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the SDK."
+ SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the SDK."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies a list of functions to call once the
- OpenEmbedded build system has created the SDK.
+ OpenEmbedded build system creates the SDK.
You can specify functions separated by semicolons:
<literallayout class='monospaced'>
SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
@@ -12443,12 +12659,13 @@
<glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
<info>
- SERIAL_CONSOLE[doc] = "The speed and device for the serial port used to attach the serial console. This variable is given to the kernel as the 'console' parameter. After booting occurs, getty is started on that port so remote login is possible."
+ SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Defines a serial console (TTY) to enable using getty.
+ Defines a serial console (TTY) to enable using
+ <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Provide a value that specifies the baud rate followed by
the TTY device name separated by a space.
You cannot specify more than one TTY device:
@@ -12473,7 +12690,8 @@
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Defines the serial consoles (TTYs) to enable using getty.
+ Defines a serial console (TTY) to enable using
+ <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Provide a value that specifies the baud rate followed by
the TTY device name separated by a semicolon.
Use spaces to separate multiple devices:
@@ -12527,8 +12745,25 @@
</para>
<para>
- In this example, <filename>intone</filename> depends on
- <filename>mplayer2</filename>.
+ In the previous example, <filename>intone</filename>
+ depends on <filename>mplayer2</filename>.
+ </para>
+
+ <para>
+ You can use the special token <filename>"*"</filename> on
+ the left-hand side of the dependency to match all
+ recipes except the one on the right-hand side.
+ Here is an example:
+ <literallayout class='monospaced'>
+ SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
+ </literallayout>
+ </para>
+
+ <para>
+ In the previous example, all recipes except
+ <filename>quilt-native</filename> ignore task
+ signatures from the <filename>quilt-native</filename>
+ recipe when determining their task signatures.
</para>
<para>
@@ -12789,6 +13024,48 @@
</glossdef>
</glossentry>
+ <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
+ <info>
+ SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
+ </info>
+ <glossdef>
+ <para role="glossdeffirst">
+<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+ The file type for the Secondary Program Loader (SPL).
+ Some devices use an SPL from which to boot (e.g. the
+ BeagleBone development board).
+ For such cases, you can declare the file type of the
+ SPL binary in the <filename>u-boot.inc</filename> include
+ file, which is used in the U-Boot recipe.
+ </para>
+
+ <para>
+ The SPL file type is set to "null" by default in the
+ <filename>u-boot.inc</filename> file as follows:
+ <literallayout class='monospaced'>
+ # Some versions of u-boot build an SPL (Second Program Loader) image that
+ # should be packaged along with the u-boot binary as well as placed in the
+ # deploy directory. For those versions they can set the following variables
+ # to allow packaging the SPL.
+ SPL_BINARY ?= ""
+ SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
+ SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
+ SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
+ </literallayout>
+ The <filename>SPL_BINARY</filename> variable helps form
+ various <filename>SPL_*</filename> variables used by
+ the OpenEmbedded build system.
+ </para>
+
+ <para>
+ See the BeagleBone machine configuration example in the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section in the Yocto Project Board Support Package
+ Developer's Guide for additional information.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
<info>
SRC_URI[doc] = "The list of source files - local or remote. This variable tells the OpenEmbedded build system what bits to pull in for the build and how to pull them in."
@@ -12823,7 +13100,9 @@
Fetches files, which are usually files shipped with
the
<link linkend='metadata'>Metadata</link>,
- from the local machine.
+ from the local machine (e.g.
+ <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
+ files).
The path is relative to the
<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
variable.
@@ -12952,14 +13231,14 @@
</para></listitem>
<listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
(or extracts its contents) into the specified
- subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+ subdirectory of <filename>WORKDIR</filename>
when the local (<filename>file://</filename>)
fetcher is used.
</para></listitem>
<listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
(or extracts its contents) into the specified
- subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
- when the CVS fetcher is used.
+ subdirectory of <filename>WORKDIR</filename> when
+ the CVS fetcher is used.
</para></listitem>
<listitem><para><emphasis><filename>subpath</filename> -</emphasis>
Limits the checkout to a specific subpath of the
@@ -13046,13 +13325,13 @@
<glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
<info>
- SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial and Bazaar only."
+ SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial, and Bazaar only."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
The revision of the source code used to build the package.
- This variable applies to Subversion, Git, Mercurial and
+ This variable applies to Subversion, Git, Mercurial, and
Bazaar only.
Note that if you want to build a fixed revision and you
want to avoid performing a query on the remote repository
@@ -13088,7 +13367,7 @@
<glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
<info>
- SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network has been disabled by setting BB_NO_NETWORK to "1"."
+ SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network is disabled by setting BB_NO_NETWORK to "1"."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -13096,7 +13375,7 @@
If set to "1", allows fetches from
mirrors that are specified in
<link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
- to work even when fetching from the network has been
+ to work even when fetching from the network is
disabled by setting <filename>BB_NO_NETWORK</filename>
to "1".
Using the
@@ -13301,27 +13580,27 @@
<glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
<info>
- STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)."
+ STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
- Specifies the path to the top-level sysroots directory
- (i.e.
- <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).
+ Helps construct the <filename>recipe-sysroots</filename>
+ directory, which is used during packaging.
</para>
<para>
- <filename>STAGING_DIR</filename> contains the directories
- that are staged into the sysroot by the
+ For information on how staging for recipe-specific
+ sysroots occurs, see the
<link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
- task.
- See the
- <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
- variable and the
+ task, the
"<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
- section in the Yocto Project Development Tasks Manual
- for more information.
+ section in the Yocto Project Development Tasks Manual, the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
+ section in the Yocto Project Overview and Concepts Manual,
+ and the
+ <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
+ variable.
<note>
Recipes should never write files directly under
the <filename>STAGING_DIR</filename> directory because
@@ -13346,11 +13625,12 @@
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies the path to the sysroot directory for the system
- that the component is built to run on (the system that hosts
- the component).
- For most recipes, this sysroot is the one that the recipe's
+ on which the component is built to run (the system that
+ hosts the component).
+ For most recipes, this sysroot is the one in which that
+ recipe's
<link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
- task copies files into.
+ task copies files.
Exceptions include <filename>-native</filename> recipes,
where the <filename>do_populate_sysroot</filename> task
instead uses
@@ -13359,17 +13639,19 @@
<filename>STAGING_DIR_HOST</filename> can have the
following values:
<itemizedlist>
- <listitem><para>For recipes building for the target
- machine, the value is
+ <listitem><para>
+ For recipes building for the target machine, the
+ value is
"${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
</para></listitem>
- <listitem><para>For native recipes building
- for the build host, the value is empty given the
- assumption that when building for the build host,
- the build host's own directories should be used.
- <note><para>
- <filename>-native</filename> recipes are not
- installed into host paths like such as
+ <listitem><para>
+ For native recipes building for the build host, the
+ value is empty given the assumption that when
+ building for the build host, the build host's own
+ directories should be used.
+ <note>
+ <para><filename>-native</filename> recipes are
+ not installed into host paths like such as
<filename>/usr</filename>.
Rather, these recipes are installed into
<filename>STAGING_DIR_NATIVE</filename>.
@@ -13385,7 +13667,7 @@
example, GCC's <filename>-isystem</filename>
option.</para>
- <para>This emphasizes that the
+ <para>Thus, the emphasis is that the
<filename>STAGING_DIR*</filename> variables
should be viewed as input variables by tasks
such as
@@ -13399,7 +13681,7 @@
<filename>-native</filename> recipes, as
they make use of host headers and libraries.
</para>
- </note>
+ </note>
</para></listitem>
</itemizedlist>
</para>
@@ -13590,8 +13872,8 @@
<para>
For information on how BitBake uses stamp files to determine
if a task should be rerun, see the
- "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
<para>
@@ -13637,13 +13919,13 @@
<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
<info>
- SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe."
+ SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm, or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
The short (72 characters or less) summary of the binary package for packaging
- systems such as <filename>opkg</filename>, <filename>rpm</filename> or
+ systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
<filename>dpkg</filename>.
By default, <filename>SUMMARY</filename> is used to define
the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
@@ -13655,7 +13937,7 @@
<glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
<info>
- SVNDIR[doc] = "The directory where Subversion checkouts will be stored."
+ SVNDIR[doc] = "The directory where Subversion checkouts are stored."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -13724,7 +14006,7 @@
in your recipe.
The variable's default value is set in the
<link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
- as follows:
+ class as follows:
<literallayout class='monospaced'>
SYSLINUX_SERIAL ?= "0 115200"
</literallayout>
@@ -13738,13 +14020,13 @@
<glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
<info>
- SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you are using the boot menu."
+ SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you use the boot menu."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
An <filename>.LSS</filename> file used as the background
- for the VGA boot menu when you are using the boot menu.
+ for the VGA boot menu when you use the boot menu.
You need to set this variable in your recipe.
</para>
@@ -13767,7 +14049,7 @@
Specifies the alternate console=tty... kernel boot argument.
The variable's default value is set in the
<link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
- as follows:
+ class as follows:
<literallayout class='monospaced'>
SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
</literallayout>
@@ -13781,7 +14063,7 @@
<glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
<info>
- SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files that will be populated into the sysroot are assembled during the do_populate_sysroot task."
+ SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files populated into the sysroot are assembled during the do_populate_sysroot task."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -13789,8 +14071,7 @@
Points to the temporary directory under the work directory
(default
"<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
- where the files
- that will be populated into the sysroot are assembled
+ where the files populated into the sysroot are assembled
during the
<link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
task.
@@ -13905,17 +14186,17 @@
<glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
<info>
- SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the service you have specified in SYSTEMD_SERVICE should be started automatically or not."
+ SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the specified service in SYSTEMD_SERVICE should start automatically or not."
</info>
<glossdef>
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
When inheriting the
<link linkend='ref-classes-systemd'><filename>systemd</filename></link>
- class, this variable specifies whether the service you have
- specified in
+ class, this variable specifies whether the specified service
+ in
<link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
- should be started automatically or not.
+ should start automatically or not.
By default, the service is enabled to automatically start
at boot time.
The default setting is in the
@@ -13963,7 +14244,7 @@
<glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
<info>
- SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to be installed containing one boot entry per file."
+ SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to install that contain one boot entry per file."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -13973,8 +14254,8 @@
is set to "systemd-boot", the
<filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
a list of entry files
- (<filename>*.conf</filename>) to be installed
- containing one boot entry per file.
+ (<filename>*.conf</filename>) to install that contain
+ one boot entry per file.
By default, the
<link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
@@ -14076,7 +14357,7 @@
<glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
<info>
- SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should be running a getty, the default is '1'."
+ SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -14084,7 +14365,7 @@
When using
<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
specifies a space-separated list of the virtual terminals
- that should be running a
+ that should run a
<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
(allowing login), assuming
<link linkend='var-USE_VT'><filename>USE_VT</filename></link>
@@ -14250,10 +14531,8 @@
<para>
Additionally, the SDK's environment setup script sets
- the
- <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
- variable in the environment to the
- <filename>TARGET_CFLAGS</filename> value so that
+ the <filename>CFLAGS</filename> variable in the environment
+ to the <filename>TARGET_CFLAGS</filename> value so that
executables built using the SDK also have the flags
applied.
</para>
@@ -14277,12 +14556,10 @@
<para>
Additionally, the SDK's environment setup script sets
- the
- <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
- variable in the environment to the
- <filename>TARGET_CPPFLAGS</filename> value so that
- executables built using the SDK also have the flags
- applied.
+ the <filename>CPPFLAGS</filename> variable in the
+ environment to the <filename>TARGET_CPPFLAGS</filename>
+ value so that executables built using the SDK also have
+ the flags applied.
</para>
</glossdef>
</glossentry>
@@ -14303,12 +14580,10 @@
<para>
Additionally, the SDK's environment setup script sets
- the
- <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
- variable in the environment to the
- <filename>TARGET_CXXFLAGS</filename> value so that
- executables built using the SDK also have the flags
- applied.
+ the <filename>CXXFLAGS</filename> variable in the
+ environment to the <filename>TARGET_CXXFLAGS</filename>
+ value so that executables built using the SDK also have
+ the flags applied.
</para>
</glossdef>
</glossentry>
@@ -14382,10 +14657,10 @@
<para role="glossdeffirst">
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Specifies the target's operating system.
- The variable can be set to "linux" for <filename>glibc</filename>-based systems and
- to "linux-musl" for <filename>musl</filename>.
- For ARM/EABI targets, there are also "linux-gnueabi" and
- "linux-musleabi" values possible.
+ The variable can be set to "linux" for glibc-based systems
+ (GNU C Library) and to "linux-musl" for musl libc.
+ For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
+ possible values exist.
</para>
</glossdef>
</glossentry>
@@ -14553,10 +14828,14 @@
default toolchain.
Using older or newer versions of these components
might cause build problems.
- See the
- <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
+ See the Release Notes for the Yocto Project release
for the specific components with which the toolchain
must be compatible.
+ To access the Release Notes, go to the
+ <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
+ page on the Yocto Project website and click on the
+ "RELEASE INFORMATION" link for the appropriate
+ release.
</note>
</para>
@@ -14671,7 +14950,7 @@
<glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
<info>
- TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The <filename>TEST_LOG_DIR</filename> variable defaults to "${WORKDIR}/testimage"."
+ TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The TEST_LOG_DIR variable defaults to "${WORKDIR}/testimage"."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -15083,8 +15362,8 @@
<para>
For background information on cross-development toolchains
in the Yocto Project development environment, see the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
For information on setting up a cross-development
environment, see the
<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
@@ -15142,8 +15421,8 @@
<para>
For background information on cross-development toolchains
in the Yocto Project development environment, see the
- "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
- section.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
For information on setting up a cross-development
environment, see the
<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
@@ -15181,7 +15460,7 @@
a value where underscores are not allowed, for example
within package filenames.
In this case, dash characters replace any underscore
- characters used in TARGET_ARCH.
+ characters used in <filename>TARGET_ARCH</filename>.
</para>
<para>
@@ -15749,7 +16028,7 @@
<glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
<info>
- UPDATERCPN[doc] = "Specifies the package that contains the initscript that is to be enabled."
+ UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -15757,7 +16036,7 @@
For recipes inheriting the
<link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
class, <filename>UPDATERCPN</filename> specifies
- the package that contains the initscript that is to be
+ the package that contains the initscript that is
enabled.
</para>
@@ -16045,7 +16324,7 @@
<glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
<info>
- USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the useradd command if you wish to add a user to the system when the package is installed."
+ USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should pass to the useradd command if you add a user to the system when the package is installed."
</info>
<glossdef>
<para role="glossdeffirst">
@@ -16053,9 +16332,9 @@
When inheriting the
<link linkend='ref-classes-useradd'><filename>useradd</filename></link>
class, this variable
- specifies for a package what parameters should be passed
+ specifies for a package what parameters should pass
to the <filename>useradd</filename> command
- if you wish to add a user to the system when the package
+ if you add a user to the system when the package
is installed.
</para>
@@ -16266,7 +16545,7 @@
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
section in the Yocto Project Development Tasks Manual.
For details on the kickstart file format, see the
- "<link linkend='openembedded-kickstart-wks-reference'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>
+ "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>
Chapter.
</para>
</glossdef>
@@ -16295,7 +16574,7 @@
</literallayout>
The actual directory depends on several things:
<itemizedlist>
- <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
+ <listitem><filename>TMPDIR</filename>:
The top-level build output directory</listitem>
<listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
The target system identifier</listitem>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/resources.xml b/import-layers/yocto-poky/documentation/ref-manual/resources.xml
index d59bea2..be04696 100644
--- a/import-layers/yocto-poky/documentation/ref-manual/resources.xml
+++ b/import-layers/yocto-poky/documentation/ref-manual/resources.xml
@@ -37,8 +37,8 @@
<para>
The Yocto Project uses its own implementation of
- <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track
- defects (bugs).
+ <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink> to
+ track defects (bugs).
Implementations of Bugzilla work well for group development because
they track bugs and code changes, can be used to communicate changes
and problems with developers, can be used to submit and review patches,
@@ -68,6 +68,8 @@
<ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>
</para></listitem>
</itemizedlist>
+ For information on Bugzilla in general, see
+ <ulink url='http://www.bugzilla.org/about/'></ulink>.
</para>
</section>
@@ -160,10 +162,18 @@
</para></listitem>
<listitem><para>
<emphasis>
- <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>:
</emphasis>
- This short document lets you get started
- with the Yocto Project and quickly begin building an image.
+ This short document lets you experience building an image using
+ the Yocto Project without having to understand any concepts or
+ details.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>
+ <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>:
+ </emphasis>
+ This manual provides overview and conceptual information
+ about the Yocto Project.
</para></listitem>
<listitem><para>
<emphasis>
@@ -201,6 +211,23 @@
</para></listitem>
<listitem><para>
<emphasis>
+ <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:
+ </emphasis>
+ This manual provides reference material such as variable,
+ task, and class descriptions.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>
+ <ulink url='&YOCTO_DOCS_MM_URL;'>Yocto Project Mega-Manual</ulink>:
+ </emphasis>
+ This manual is simply a single HTML file comprised of the
+ bulk of the Yocto Project manuals.
+ The Mega-Manual primarily exists as a vehicle by which you can
+ easily search for phrases and terms used in the Yocto Project
+ documentation set.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>
<ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>:
</emphasis>
This manual presents a set of common and generally useful
@@ -209,7 +236,18 @@
</para></listitem>
<listitem><para>
<emphasis>
- <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-latest-yp-eclipse-plug-in'>Eclipse IDE Yocto Plug-in</ulink>:
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>:
+ </emphasis>
+ This manual introduces and describes how to set up and use
+ Toaster.
+ Toaster is an Application Programming Interface (API) and
+ web-based interface to the
+ <link linkend='build-system-term'>OpenEmbedded Build System</link>,
+ which uses BitBake, that reports build information.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>
+ <ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Eclipse IDE Yocto Plug-in</ulink>:
</emphasis>
Instructions that demonstrate how an application developer
uses the Eclipse Yocto Project Plug-in feature within
@@ -222,22 +260,13 @@
A list of commonly asked questions and their answers.
</para></listitem>
<listitem><para>
- <emphasis>
- <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>:
- </emphasis>
+ <emphasis>Release Notes:</emphasis>
Features, updates and known issues for the current
release of the Yocto Project.
- </para></listitem>
- <listitem><para>
- <emphasis>
- <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>:
- </emphasis>
- This manual introduces and describes how to set up and use
- Toaster.
- Toaster is an Application Programming Interface (API) and
- web-based interface to the
- <link linkend='build-system-term'>OpenEmbedded Build System</link>,
- which uses BitBake, that reports build information.
+ To access the Release Notes, go to the
+ <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
+ page on the Yocto Project website and click on the
+ "RELEASE INFORMATION" link for the appropriate release.
</para></listitem>
<listitem><para>
<emphasis>
diff --git a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml
deleted file mode 100644
index e9e76e4..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml
+++ /dev/null
@@ -1,2042 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='technical-details'>
-<title>Technical Details</title>
-
- <para>
- This chapter provides technical details for various parts of the
- Yocto Project.
- Currently, topics include Yocto Project components,
- cross-toolchain generation, shared state (sstate) cache,
- x32, Wayland support, and Licenses.
- </para>
-
-<section id='usingpoky-components'>
- <title>Yocto Project Components</title>
-
- <para>
- The
- <link linkend='bitbake-term'>BitBake</link>
- task executor together with various types of configuration files form
- the OpenEmbedded Core.
- This section overviews these components by describing their use and
- how they interact.
- </para>
-
- <para>
- BitBake handles the parsing and execution of the data files.
- The data itself is of various types:
- <itemizedlist>
- <listitem><para><emphasis>Recipes:</emphasis> Provides details
- about particular pieces of software.
- </para></listitem>
- <listitem><para><emphasis>Class Data:</emphasis> Abstracts
- common build information (e.g. how to build a Linux kernel).
- </para></listitem>
- <listitem><para><emphasis>Configuration Data:</emphasis> Defines
- machine-specific settings, policy decisions, and so forth.
- Configuration data acts as the glue to bind everything
- together.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- BitBake knows how to combine multiple data sources together and refers
- to each data source as a layer.
- For information on layers, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
- Creating Layers</ulink>" section of the Yocto Project Development
- Tasks Manual.
- </para>
-
- <para>
- Following are some brief details on these core components.
- For additional information on how these components interact during
- a build, see the
- "<link linkend='development-concepts'>Development Concepts</link>"
- section.
- </para>
-
- <section id='usingpoky-components-bitbake'>
- <title>BitBake</title>
-
- <para>
- BitBake is the tool at the heart of the OpenEmbedded build system
- and is responsible for parsing the
- <link linkend='metadata'>Metadata</link>,
- generating a list of tasks from it, and then executing those tasks.
- </para>
-
- <para>
- This section briefly introduces BitBake.
- If you want more information on BitBake, see the
- <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
- </para>
-
- <para>
- To see a list of the options BitBake supports, use either of
- the following commands:
- <literallayout class='monospaced'>
- $ bitbake -h
- $ bitbake --help
- </literallayout>
- </para>
-
- <para>
- The most common usage for BitBake is <filename>bitbake <replaceable>packagename</replaceable></filename>, where
- <filename>packagename</filename> is the name of the package you want to build
- (referred to as the "target" in this manual).
- The target often equates to the first part of a recipe's filename
- (e.g. "foo" for a recipe named
- <filename>foo_1.3.0-r0.bb</filename>).
- So, to process the <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
- might type the following:
- <literallayout class='monospaced'>
- $ bitbake matchbox-desktop
- </literallayout>
- Several different versions of <filename>matchbox-desktop</filename> might exist.
- BitBake chooses the one selected by the distribution configuration.
- You can get more details about how BitBake chooses between different
- target versions and providers in the
- "<ulink url='&YOCTO_DOCS_BB_URL;#bb-bitbake-preferences'>Preferences</ulink>"
- section of the BitBake User Manual.
- </para>
-
- <para>
- BitBake also tries to execute any dependent tasks first.
- So for example, before building <filename>matchbox-desktop</filename>, BitBake
- would build a cross compiler and <filename>glibc</filename> if they had not already
- been built.
- </para>
-
- <para>
- A useful BitBake option to consider is the <filename>-k</filename> or
- <filename>--continue</filename> option.
- This option instructs BitBake to try and continue processing the job
- as long as possible even after encountering an error.
- When an error occurs, the target that
- failed and those that depend on it cannot be remade.
- However, when you use this option other dependencies can still be
- processed.
- </para>
- </section>
-
- <section id='usingpoky-components-metadata'>
- <title>Metadata (Recipes)</title>
-
- <para>
- Files that have the <filename>.bb</filename> suffix are "recipes"
- files.
- In general, a recipe contains information about a single piece of
- software.
- This information includes the location from which to download the
- unaltered source, any source patches to be applied to that source
- (if needed), which special configuration options to apply,
- how to compile the source files, and how to package the compiled
- output.
- </para>
-
- <para>
- The term "package" is sometimes used to refer to recipes. However,
- since the word "package" is used for the packaged output from the OpenEmbedded
- build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
- this document avoids using the term "package" when referring to recipes.
- </para>
- </section>
-
- <section id='metadata-virtual-providers'>
- <title>Metadata (Virtual Providers)</title>
-
- <para>
- Prior to the build, if you know that several different recipes
- provide the same functionality, you can use a virtual provider
- (i.e. <filename>virtual/*</filename>) as a placeholder for the
- actual provider.
- The actual provider would be determined at build
- time.
- In this case, you should add <filename>virtual/*</filename>
- to <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
- rather than listing the specified provider.
- You would select the actual provider by setting the
- <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
- variable (i.e. <filename>PREFERRED_PROVIDER_virtual/*</filename>)
- in the build's configuration file (e.g.
- <filename>poky/build/conf/local.conf</filename>).
- <note>
- Any recipe that PROVIDES a <filename>virtual/*</filename> item
- that is ultimately not selected through
- <filename>PREFERRED_PROVIDER</filename> does not get built.
- Preventing these recipes from building is usually the desired
- behavior since this mechanism's purpose is to select between
- mutually exclusive alternative providers.
- </note>
- </para>
-
- <para>
- The following lists specific examples of virtual providers:
- <itemizedlist>
- <listitem><para>
- <filename>virtual/mesa</filename>:
- Provides <filename>gbm.pc</filename>.
- </para></listitem>
- <listitem><para>
- <filename>virtual/egl</filename>:
- Provides <filename>egl.pc</filename> and possibly
- <filename>wayland-egl.pc</filename>.
- </para></listitem>
- <listitem><para>
- <filename>virtual/libgl</filename>:
- Provides <filename>gl.pc</filename> (i.e. libGL).
- </para></listitem>
- <listitem><para>
- <filename>virtual/libgles1</filename>:
- Provides <filename>glesv1_cm.pc</filename>
- (i.e. libGLESv1_CM).
- </para></listitem>
- <listitem><para>
- <filename>virtual/libgles2</filename>:
- Provides <filename>glesv2.pc</filename> (i.e. libGLESv2).
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='usingpoky-components-classes'>
- <title>Classes</title>
-
- <para>
- Class files (<filename>.bbclass</filename>) contain information that
- is useful to share between
- <link linkend='metadata'>Metadata</link> files.
- An example is the
- <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
- class, which contains common settings for any application that
- Autotools uses.
- The "<link linkend='ref-classes'>Classes</link>" chapter provides
- details about classes and how to use them.
- </para>
- </section>
-
- <section id='usingpoky-components-configuration'>
- <title>Configuration</title>
-
- <para>
- The configuration files (<filename>.conf</filename>) define various configuration variables
- that govern the OpenEmbedded build process.
- These files fall into several areas that define machine configuration options,
- distribution configuration options, compiler tuning options, general common configuration
- options, and user configuration options in <filename>local.conf</filename>, which is found
- in the
- <link linkend='build-directory'>Build Directory</link>.
- </para>
- </section>
-</section>
-
-<section id="cross-development-toolchain-generation">
- <title>Cross-Development Toolchain Generation</title>
-
- <para>
- The Yocto Project does most of the work for you when it comes to
- creating
- <link linkend='cross-development-toolchain'>cross-development toolchains</link>.
- This section provides some technical background on how
- cross-development toolchains are created and used.
- For more information on toolchains, you can also see the
- <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
- manual.
- </para>
-
- <para>
- In the Yocto Project development environment, cross-development
- toolchains are used to build the image and applications that run on the
- target hardware.
- With just a few commands, the OpenEmbedded build system creates
- these necessary toolchains for you.
- </para>
-
- <para>
- The following figure shows a high-level build environment regarding
- toolchain construction and use.
- </para>
-
- <para>
- <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
- </para>
-
- <para>
- Most of the work occurs on the Build Host.
- This is the machine used to build images and generally work within the
- the Yocto Project environment.
- When you run BitBake to create an image, the OpenEmbedded build system
- uses the host <filename>gcc</filename> compiler to bootstrap a
- cross-compiler named <filename>gcc-cross</filename>.
- The <filename>gcc-cross</filename> compiler is what BitBake uses to
- compile source files when creating the target image.
- You can think of <filename>gcc-cross</filename> simply as an
- automatically generated cross-compiler that is used internally within
- BitBake only.
- <note>
- The extensible SDK does not use
- <filename>gcc-cross-canadian</filename> since this SDK
- ships a copy of the OpenEmbedded build system and the sysroot
- within it contains <filename>gcc-cross</filename>.
- </note>
- </para>
-
- <para>
- The chain of events that occurs when <filename>gcc-cross</filename> is
- bootstrapped is as follows:
- <literallayout class='monospaced'>
- gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
- </literallayout>
- <itemizedlist>
- <listitem><para><filename>gcc</filename>:
- The build host's GNU Compiler Collection (GCC).
- </para></listitem>
- <listitem><para><filename>binutils-cross</filename>:
- The bare minimum binary utilities needed in order to run
- the <filename>gcc-cross-initial</filename> phase of the
- bootstrap operation.
- </para></listitem>
- <listitem><para><filename>gcc-cross-initial</filename>:
- An early stage of the bootstrap process for creating
- the cross-compiler.
- This stage builds enough of the <filename>gcc-cross</filename>,
- the C library, and other pieces needed to finish building the
- final cross-compiler in later stages.
- This tool is a "native" package (i.e. it is designed to run on
- the build host).
- </para></listitem>
- <listitem><para><filename>linux-libc-headers</filename>:
- Headers needed for the cross-compiler.
- </para></listitem>
- <listitem><para><filename>glibc-initial</filename>:
- An initial version of the Embedded GLIBC needed to bootstrap
- <filename>glibc</filename>.
- </para></listitem>
- <listitem><para><filename>gcc-cross</filename>:
- The final stage of the bootstrap process for the
- cross-compiler.
- This stage results in the actual cross-compiler that
- BitBake uses when it builds an image for a targeted
- device.
- <note>
- If you are replacing this cross compiler toolchain
- with a custom version, you must replace
- <filename>gcc-cross</filename>.
- </note>
- This tool is also a "native" package (i.e. it is
- designed to run on the build host).
- </para></listitem>
- <listitem><para><filename>gcc-runtime</filename>:
- Runtime libraries resulting from the toolchain bootstrapping
- process.
- This tool produces a binary that consists of the
- runtime libraries need for the targeted device.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- You can use the OpenEmbedded build system to build an installer for
- the relocatable SDK used to develop applications.
- When you run the installer, it installs the toolchain, which contains
- the development tools (e.g., the
- <filename>gcc-cross-canadian</filename>),
- <filename>binutils-cross-canadian</filename>, and other
- <filename>nativesdk-*</filename> tools,
- which are tools native to the SDK (i.e. native to
- <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>),
- you need to cross-compile and test your software.
- The figure shows the commands you use to easily build out this
- toolchain.
- This cross-development toolchain is built to execute on the
- <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
- which might or might not be the same
- machine as the Build Host.
- <note>
- If your target architecture is supported by the Yocto Project,
- you can take advantage of pre-built images that ship with the
- Yocto Project and already contain cross-development toolchain
- installers.
- </note>
- </para>
-
- <para>
- Here is the bootstrap process for the relocatable toolchain:
- <literallayout class='monospaced'>
- gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers ->
- glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
- </literallayout>
- <itemizedlist>
- <listitem><para><filename>gcc</filename>:
- The build host's GNU Compiler Collection (GCC).
- </para></listitem>
- <listitem><para><filename>binutils-crosssdk</filename>:
- The bare minimum binary utilities needed in order to run
- the <filename>gcc-crosssdk-initial</filename> phase of the
- bootstrap operation.
- </para></listitem>
- <listitem><para><filename>gcc-crosssdk-initial</filename>:
- An early stage of the bootstrap process for creating
- the cross-compiler.
- This stage builds enough of the
- <filename>gcc-crosssdk</filename> and supporting pieces so that
- the final stage of the bootstrap process can produce the
- finished cross-compiler.
- This tool is a "native" binary that runs on the build host.
- </para></listitem>
- <listitem><para><filename>linux-libc-headers</filename>:
- Headers needed for the cross-compiler.
- </para></listitem>
- <listitem><para><filename>glibc-initial</filename>:
- An initial version of the Embedded GLIBC needed to bootstrap
- <filename>nativesdk-glibc</filename>.
- </para></listitem>
- <listitem><para><filename>nativesdk-glibc</filename>:
- The Embedded GLIBC needed to bootstrap the
- <filename>gcc-crosssdk</filename>.
- </para></listitem>
- <listitem><para><filename>gcc-crosssdk</filename>:
- The final stage of the bootstrap process for the
- relocatable cross-compiler.
- The <filename>gcc-crosssdk</filename> is a transitory compiler
- and never leaves the build host.
- Its purpose is to help in the bootstrap process to create the
- eventual relocatable <filename>gcc-cross-canadian</filename>
- compiler, which is relocatable.
- This tool is also a "native" package (i.e. it is
- designed to run on the build host).
- </para></listitem>
- <listitem><para><filename>gcc-cross-canadian</filename>:
- The final relocatable cross-compiler.
- When run on the
- <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
- this tool
- produces executable code that runs on the target device.
- Only one cross-canadian compiler is produced per architecture
- since they can be targeted at different processor optimizations
- using configurations passed to the compiler through the
- compile commands.
- This circumvents the need for multiple compilers and thus
- reduces the size of the toolchains.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <note>
- For information on advantages gained when building a
- cross-development toolchain installer, see the
- "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
- section in the Yocto Project Application Development and the
- Extensible Software Development Kit (eSDK) manual.
- </note>
-</section>
-
-<section id="shared-state-cache">
- <title>Shared State Cache</title>
-
- <para>
- By design, the OpenEmbedded build system builds everything from scratch unless
- BitBake can determine that parts do not need to be rebuilt.
- Fundamentally, building from scratch is attractive as it means all parts are
- built fresh and there is no possibility of stale data causing problems.
- When developers hit problems, they typically default back to building from scratch
- so they know the state of things from the start.
- </para>
-
- <para>
- Building an image from scratch is both an advantage and a disadvantage to the process.
- As mentioned in the previous paragraph, building from scratch ensures that
- everything is current and starts from a known state.
- However, building from scratch also takes much longer as it generally means
- rebuilding things that do not necessarily need to be rebuilt.
- </para>
-
- <para>
- The Yocto Project implements shared state code that supports incremental builds.
- The implementation of the shared state code answers the following questions that
- were fundamental roadblocks within the OpenEmbedded incremental build support system:
- <itemizedlist>
- <listitem><para>What pieces of the system have changed and what pieces have
- not changed?</para></listitem>
- <listitem><para>How are changed pieces of software removed and replaced?</para></listitem>
- <listitem><para>How are pre-built components that do not need to be rebuilt from scratch
- used when they are available?</para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- For the first question, the build system detects changes in the "inputs" to a given task by
- creating a checksum (or signature) of the task's inputs.
- If the checksum changes, the system assumes the inputs have changed and the task needs to be
- rerun.
- For the second question, the shared state (sstate) code tracks which tasks add which output
- to the build process.
- This means the output from a given task can be removed, upgraded or otherwise manipulated.
- The third question is partly addressed by the solution for the second question
- assuming the build system can fetch the sstate objects from remote locations and
- install them if they are deemed to be valid.
- </para>
-
- <note>
- The OpenEmbedded build system does not maintain
- <link linkend='var-PR'><filename>PR</filename></link> information
- as part of the shared state packages.
- Consequently, considerations exist that affect maintaining shared
- state feeds.
- For information on how the OpenEmbedded build system
- works with packages and can
- track incrementing <filename>PR</filename> information, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </note>
-
- <para>
- The rest of this section goes into detail about the overall incremental build
- architecture, the checksums (signatures), shared state, and some tips and tricks.
- </para>
-
- <section id='overall-architecture'>
- <title>Overall Architecture</title>
-
- <para>
- When determining what parts of the system need to be built, BitBake
- works on a per-task basis rather than a per-recipe basis.
- You might wonder why using a per-task basis is preferred over a per-recipe basis.
- To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
- In this case, the
- <link linkend='ref-tasks-install'><filename>do_install</filename></link>
- and
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- task outputs are still valid.
- However, with a per-recipe approach, the build would not include the
- <filename>.deb</filename> files.
- Consequently, you would have to invalidate the whole build and rerun it.
- Rerunning everything is not the best solution.
- Also, in this case, the core must be "taught" much about specific tasks.
- This methodology does not scale well and does not allow users to easily add new tasks
- in layers or as external recipes without touching the packaged-staging core.
- </para>
- </section>
-
- <section id='checksums'>
- <title>Checksums (Signatures)</title>
-
- <para>
- The shared state code uses a checksum, which is a unique signature of a task's
- inputs, to determine if a task needs to be run again.
- Because it is a change in a task's inputs that triggers a rerun, the process
- needs to detect all the inputs to a given task.
- For shell tasks, this turns out to be fairly easy because
- the build process generates a "run" shell script for each task and
- it is possible to create a checksum that gives you a good idea of when
- the task's data changes.
- </para>
-
- <para>
- To complicate the problem, there are things that should not be
- included in the checksum.
- First, there is the actual specific build path of a given task -
- the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
- It does not matter if the work directory changes because it should
- not affect the output for target packages.
- Also, the build process has the objective of making native
- or cross packages relocatable.
- <note>
- Both native and cross packages run on the build host.
- However, cross packages generate output for the target
- architecture.
- </note>
- The checksum therefore needs to exclude
- <filename>WORKDIR</filename>.
- The simplistic approach for excluding the work directory is to set
- <filename>WORKDIR</filename> to some fixed value and create the
- checksum for the "run" script.
- </para>
-
- <para>
- Another problem results from the "run" scripts containing functions that
- might or might not get called.
- The incremental build solution contains code that figures out dependencies
- between shell functions.
- This code is used to prune the "run" scripts down to the minimum set,
- thereby alleviating this problem and making the "run" scripts much more
- readable as a bonus.
- </para>
-
- <para>
- So far we have solutions for shell scripts.
- What about Python tasks?
- The same approach applies even though these tasks are more difficult.
- The process needs to figure out what variables a Python function accesses
- and what functions it calls.
- Again, the incremental build solution contains code that first figures out
- the variable and function dependencies, and then creates a checksum for the data
- used as the input to the task.
- </para>
-
- <para>
- Like the <filename>WORKDIR</filename> case, situations exist where dependencies
- should be ignored.
- For these cases, you can instruct the build process to ignore a dependency
- by using a line like the following:
- <literallayout class='monospaced'>
- PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
- </literallayout>
- This example ensures that the
- <link linkend='var-PACKAGE_ARCHS'><filename>PACKAGE_ARCHS</filename></link>
- variable does not
- depend on the value of
- <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
- even if it does reference it.
- </para>
-
- <para>
- Equally, there are cases where we need to add dependencies BitBake is not able to find.
- You can accomplish this by using a line like the following:
- <literallayout class='monospaced'>
- PACKAGE_ARCHS[vardeps] = "MACHINE"
- </literallayout>
- This example explicitly adds the <filename>MACHINE</filename> variable as a
- dependency for <filename>PACKAGE_ARCHS</filename>.
- </para>
-
- <para>
- Consider a case with in-line Python, for example, where BitBake is not
- able to figure out dependencies.
- When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
- produces output when it discovers something for which it cannot figure out
- dependencies.
- The Yocto Project team has currently not managed to cover those dependencies
- in detail and is aware of the need to fix this situation.
- </para>
-
- <para>
- Thus far, this section has limited discussion to the direct inputs into a task.
- Information based on direct inputs is referred to as the "basehash" in the
- code.
- However, there is still the question of a task's indirect inputs - the
- things that were already built and present in the
- <link linkend='build-directory'>Build Directory</link>.
- The checksum (or signature) for a particular task needs to add the hashes
- of all the tasks on which the particular task depends.
- Choosing which dependencies to add is a policy decision.
- However, the effect is to generate a master checksum that combines the basehash
- and the hashes of the task's dependencies.
- </para>
-
- <para>
- At the code level, there are a variety of ways both the basehash and the
- dependent task hashes can be influenced.
- Within the BitBake configuration file, we can give BitBake some extra information
- to help it construct the basehash.
- The following statement effectively results in a list of global variable
- dependency excludes - variables never included in any checksum:
- <literallayout class='monospaced'>
- BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
- SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
- USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
- PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
- CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
- </literallayout>
- The previous example excludes
- <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
- since that variable is actually constructed as a path within
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
- the whitelist.
- </para>
-
- <para>
- The rules for deciding which hashes of dependent tasks to include through
- dependency chains are more complex and are generally accomplished with a
- Python function.
- The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
- of this and also illustrates how you can insert your own policy into the system
- if so desired.
- This file defines the two basic signature generators
- <link linkend='oe-core'>OE-Core</link> uses: "OEBasic" and
- "OEBasicHash".
- By default, there is a dummy "noop" signature handler enabled in BitBake.
- This means that behavior is unchanged from previous versions.
- OE-Core uses the "OEBasicHash" signature handler by default
- through this setting in the <filename>bitbake.conf</filename> file:
- <literallayout class='monospaced'>
- BB_SIGNATURE_HANDLER ?= "OEBasicHash"
- </literallayout>
- The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
- "OEBasic" version but adds the task hash to the stamp files.
- This results in any
- <link linkend='metadata'>Metadata</link>
- change that changes the task hash, automatically
- causing the task to be run again.
- This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
- values, and changes to Metadata automatically ripple across the build.
- </para>
-
- <para>
- It is also worth noting that the end result of these signature generators is to
- make some dependency and hash information available to the build.
- This information includes:
- <itemizedlist>
- <listitem><para><filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>:
- The base hashes for each task in the recipe.
- </para></listitem>
- <listitem><para><filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
- The base hashes for each dependent task.
- </para></listitem>
- <listitem><para><filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>:
- The task dependencies for each task.
- </para></listitem>
- <listitem><para><filename>BB_TASKHASH</filename>:
- The hash of the currently running task.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='shared-state'>
- <title>Shared State</title>
-
- <para>
- Checksums and dependencies, as discussed in the previous section, solve half the
- problem of supporting a shared state.
- The other part of the problem is being able to use checksum information during the build
- and being able to reuse or rebuild specific components.
- </para>
-
- <para>
- The
- <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
- class is a relatively generic implementation of how to "capture"
- a snapshot of a given task.
- The idea is that the build process does not care about the source of a task's output.
- Output could be freshly built or it could be downloaded and unpacked from
- somewhere - the build process does not need to worry about its origin.
- </para>
-
- <para>
- There are two types of output, one is just about creating a directory
- in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
- A good example is the output of either
- <link linkend='ref-tasks-install'><filename>do_install</filename></link>
- or
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
- The other type of output occurs when a set of data is merged into a shared directory
- tree such as the sysroot.
- </para>
-
- <para>
- The Yocto Project team has tried to keep the details of the
- implementation hidden in <filename>sstate</filename> class.
- From a user's perspective, adding shared state wrapping to a task
- is as simple as this
- <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
- example taken from the
- <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
- class:
- <literallayout class='monospaced'>
- DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
- SSTATETASKS += "do_deploy"
- do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
- do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
-
- python do_deploy_setscene () {
- sstate_setscene(d)
- }
- addtask do_deploy_setscene
- do_deploy[dirs] = "${DEPLOYDIR} ${B}"
- </literallayout>
- The following list explains the previous example:
- <itemizedlist>
- <listitem><para>
- Adding "do_deploy" to <filename>SSTATETASKS</filename>
- adds some required sstate-related processing, which is
- implemented in the
- <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
- class, to before and after the
- <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
- task.
- </para></listitem>
- <listitem><para>
- The
- <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename>
- declares that <filename>do_deploy</filename> places its
- output in <filename>${DEPLOYDIR}</filename> when run
- normally (i.e. when not using the sstate cache).
- This output becomes the input to the shared state cache.
- </para></listitem>
- <listitem><para>
- The
- <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename>
- line causes the contents of the shared state cache to be
- copied to <filename>${DEPLOY_DIR_IMAGE}</filename>.
- <note>
- If <filename>do_deploy</filename> is not already in
- the shared state cache or if its input checksum
- (signature) has changed from when the output was
- cached, the task will be run to populate the shared
- state cache, after which the contents of the shared
- state cache is copied to
- <filename>${DEPLOY_DIR_IMAGE}</filename>.
- If <filename>do_deploy</filename> is in the shared
- state cache and its signature indicates that the
- cached output is still valid (i.e. if no
- relevant task inputs have changed), then the contents
- of the shared state cache will be copied directly to
- <filename>${DEPLOY_DIR_IMAGE}</filename> by the
- <filename>do_deploy_setscene</filename> task instead,
- skipping the <filename>do_deploy</filename> task.
- </note>
- </para></listitem>
- <listitem><para>
- The following task definition is glue logic needed to make
- the previous settings effective:
- <literallayout class='monospaced'>
- python do_deploy_setscene () {
- sstate_setscene(d)
- }
- addtask do_deploy_setscene
- </literallayout>
- <filename>sstate_setscene()</filename> takes the flags
- above as input and accelerates the
- <filename>do_deploy</filename> task through the
- shared state cache if possible.
- If the task was accelerated,
- <filename>sstate_setscene()</filename> returns True.
- Otherwise, it returns False, and the normal
- <filename>do_deploy</filename> task runs.
- For more information, see the
- "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>"
- section in the BitBake User Manual.
- </para></listitem>
- <listitem><para>
- The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename>
- line creates <filename>${DEPLOYDIR}</filename> and
- <filename>${B}</filename> before the
- <filename>do_deploy</filename> task runs, and also sets
- the current working directory of
- <filename>do_deploy</filename> to
- <filename>${B}</filename>.
- For more information, see the
- "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
- section in the BitBake User Manual.
- <note>
- In cases where
- <filename>sstate-inputdirs</filename> and
- <filename>sstate-outputdirs</filename> would be the
- same, you can use
- <filename>sstate-plaindirs</filename>.
- For example, to preserve the
- <filename>${PKGD}</filename> and
- <filename>${PKGDEST}</filename> output from the
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- task, use the following:
- <literallayout class='monospaced'>
- do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
- </literallayout>
- </note>
- </para></listitem>
- <listitem><para>
- <filename>sstate-inputdirs</filename> and
- <filename>sstate-outputdirs</filename> can also be used
- with multiple directories.
- For example, the following declares
- <filename>PKGDESTWORK</filename> and
- <filename>SHLIBWORK</filename> as shared state
- input directories, which populates the shared state
- cache, and <filename>PKGDATA_DIR</filename> and
- <filename>SHLIBSDIR</filename> as the corresponding
- shared state output directories:
- <literallayout class='monospaced'>
- do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
- do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
- </literallayout>
- </para></listitem>
- <listitem><para>
- These methods also include the ability to take a lockfile
- when manipulating shared state directory structures,
- for cases where file additions or removals are sensitive:
- <literallayout class='monospaced'>
- do_package[sstate-lockfile] = "${PACKAGELOCK}"
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para>
-
-<!--
- <para>
- In this example, we add some extra flags to the task, a name field ("deploy"), an
- input directory where the task sends data, and the output
- directory where the data from the task should eventually be copied.
- We also add a <filename>_setscene</filename> variant of the task and add the task
- name to the <filename>SSTATETASKS</filename> list.
- </para>
-
- <para>
- If you have a directory whose contents you need to preserve, you can do this with
- a line like the following:
- <literallayout class='monospaced'>
- do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
- </literallayout>
- This method, as well as the following example, also works for multiple directories.
- <literallayout class='monospaced'>
- do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
- do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
- do_package[sstate-lockfile] = "${PACKAGELOCK}"
- </literallayout>
- These methods also include the ability to take a lockfile when manipulating
- shared state directory structures since some cases are sensitive to file
- additions or removals.
- </para>
--->
-
- <para>
- Behind the scenes, the shared state code works by looking in
- <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
- <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
- for shared state files.
- Here is an example:
- <literallayout class='monospaced'>
- SSTATE_MIRRORS ?= "\
- file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
- file://.* file:///some/local/dir/sstate/PATH"
- </literallayout>
- <note>
- The shared state directory (<filename>SSTATE_DIR</filename>) is
- organized into two-character subdirectories, where the subdirectory
- names are based on the first two characters of the hash.
- If the shared state directory structure for a mirror has the
- same structure as <filename>SSTATE_DIR</filename>, you must
- specify "PATH" as part of the URI to enable the build system
- to map to the appropriate subdirectory.
- </note>
- </para>
-
- <para>
- The shared state package validity can be detected just by looking at the
- filename since the filename contains the task checksum (or signature) as
- described earlier in this section.
- If a valid shared state package is found, the build process downloads it
- and uses it to accelerate the task.
- </para>
-
- <para>
- The build processes use the <filename>*_setscene</filename> tasks
- for the task acceleration phase.
- BitBake goes through this phase before the main execution code and tries
- to accelerate any tasks for which it can find shared state packages.
- If a shared state package for a task is available, the shared state
- package is used.
- This means the task and any tasks on which it is dependent are not
- executed.
- </para>
-
- <para>
- As a real world example, the aim is when building an IPK-based image,
- only the
- <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
- tasks would have their
- shared state packages fetched and extracted.
- Since the sysroot is not used, it would never get extracted.
- This is another reason why a task-based approach is preferred over a
- recipe-based approach, which would have to install the output from every task.
- </para>
- </section>
-
- <section id='tips-and-tricks'>
- <title>Tips and Tricks</title>
-
- <para>
- The code in the build system that supports incremental builds is not
- simple code.
- This section presents some tips and tricks that help you work around
- issues related to shared state code.
- </para>
-
- <section id='debugging'>
- <title>Debugging</title>
-
- <para>
- Seeing what metadata went into creating the input signature
- of a shared state (sstate) task can be a useful debugging aid.
- This information is available in signature information
- (<filename>siginfo</filename>) files in
- <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>.
- For information on how to view and interpret information in
- <filename>siginfo</filename> files, see the
- "<link linkend='usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
- section.
- </para>
- </section>
-
- <section id='invalidating-shared-state'>
- <title>Invalidating Shared State</title>
-
- <para>
- The OpenEmbedded build system uses checksums and shared state
- cache to avoid unnecessarily rebuilding tasks.
- Collectively, this scheme is known as "shared state code."
- </para>
-
- <para>
- As with all schemes, this one has some drawbacks.
- It is possible that you could make implicit changes to your
- code that the checksum calculations do not take into
- account.
- These implicit changes affect a task's output but do not trigger
- the shared state code into rebuilding a recipe.
- Consider an example during which a tool changes its output.
- Assume that the output of <filename>rpmdeps</filename> changes.
- The result of the change should be that all the
- <filename>package</filename> and
- <filename>package_write_rpm</filename> shared state cache
- items become invalid.
- However, because the change to the output is
- external to the code and therefore implicit,
- the associated shared state cache items do not become
- invalidated.
- In this case, the build process uses the cached items rather
- than running the task again.
- Obviously, these types of implicit changes can cause problems.
- </para>
-
- <para>
- To avoid these problems during the build, you need to
- understand the effects of any changes you make.
- Realize that changes you make directly to a function
- are automatically factored into the checksum calculation.
- Thus, these explicit changes invalidate the associated area of
- shared state cache.
- However, you need to be aware of any implicit changes that
- are not obvious changes to the code and could affect the output
- of a given task.
- </para>
-
- <para>
- When you identify an implicit change, you can easily take steps
- to invalidate the cache and force the tasks to run.
- The steps you can take are as simple as changing a function's
- comments in the source code.
- For example, to invalidate package shared state files, change
- the comment statements of
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- or the comments of one of the functions it calls.
- Even though the change is purely cosmetic, it causes the
- checksum to be recalculated and forces the OpenEmbedded build
- system to run the task again.
- </para>
-
- <note>
- For an example of a commit that makes a cosmetic change to
- invalidate shared state, see this
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
- </note>
- </section>
- </section>
-</section>
-
-<section id='automatically-added-runtime-dependencies'>
- <title>Automatically Added Runtime Dependencies</title>
-
- <para>
- The OpenEmbedded build system automatically adds common types of
- runtime dependencies between packages, which means that you do not
- need to explicitly declare the packages using
- <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
- Three automatic mechanisms exist (<filename>shlibdeps</filename>,
- <filename>pcdeps</filename>, and <filename>depchains</filename>) that
- handle shared libraries, package configuration (pkg-config) modules,
- and <filename>-dev</filename> and <filename>-dbg</filename> packages,
- respectively.
- For other types of runtime dependencies, you must manually declare
- the dependencies.
- <itemizedlist>
- <listitem><para>
- <filename>shlibdeps</filename>:
- During the
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- task of each recipe, all shared libraries installed by the
- recipe are located.
- For each shared library, the package that contains the shared
- library is registered as providing the shared library.
- More specifically, the package is registered as providing the
- <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink>
- of the library.
- The resulting shared-library-to-package mapping
- is saved globally in
- <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
- by the
- <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
- task.</para>
-
- <para>Simultaneously, all executables and shared libraries
- installed by the recipe are inspected to see what shared
- libraries they link against.
- For each shared library dependency that is found,
- <filename>PKGDATA_DIR</filename> is queried to
- see if some package (likely from a different recipe) contains
- the shared library.
- If such a package is found, a runtime dependency is added from
- the package that depends on the shared library to the package
- that contains the library.</para>
-
- <para>The automatically added runtime dependency also includes
- a version restriction.
- This version restriction specifies that at least the current
- version of the package that provides the shared library must be
- used, as if
- "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
- had been added to
- <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
- This forces an upgrade of the package containing the shared
- library when installing the package that depends on the
- library, if needed.</para>
-
- <para>If you want to avoid a package being registered as
- providing a particular shared library (e.g. because the library
- is for internal use only), then add the library to
- <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
- inside the package's recipe.
- </para></listitem>
- <listitem><para>
- <filename>pcdeps</filename>:
- During the
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- task of each recipe, all pkg-config modules
- (<filename>*.pc</filename> files) installed by the recipe are
- located.
- For each module, the package that contains the module is
- registered as providing the module.
- The resulting module-to-package mapping is saved globally in
- <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
- by the
- <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
- task.</para>
-
- <para>Simultaneously, all pkg-config modules installed by the
- recipe are inspected to see what other pkg-config modules they
- depend on.
- A module is seen as depending on another module if it contains
- a "Requires:" line that specifies the other module.
- For each module dependency,
- <filename>PKGDATA_DIR</filename> is queried to see if some
- package contains the module.
- If such a package is found, a runtime dependency is added from
- the package that depends on the module to the package that
- contains the module.
- <note>
- The <filename>pcdeps</filename> mechanism most often infers
- dependencies between <filename>-dev</filename> packages.
- </note>
- </para></listitem>
- <listitem><para>
- <filename>depchains</filename>:
- If a package <filename>foo</filename> depends on a package
- <filename>bar</filename>, then <filename>foo-dev</filename>
- and <filename>foo-dbg</filename> are also made to depend on
- <filename>bar-dev</filename> and <filename>bar-dbg</filename>,
- respectively.
- Taking the <filename>-dev</filename> packages as an example,
- the <filename>bar-dev</filename> package might provide
- headers and shared library symlinks needed by
- <filename>foo-dev</filename>, which shows the need
- for a dependency between the packages.</para>
-
- <para>The dependencies added by <filename>depchains</filename>
- are in the form of
- <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>.
- <note>
- By default, <filename>foo-dev</filename> also has an
- <filename>RDEPENDS</filename>-style dependency on
- <filename>foo</filename>, because the default value of
- <filename>RDEPENDS_${PN}-dev</filename> (set in
- <filename>bitbake.conf</filename>) includes
- "${PN}".
- </note></para>
-
- <para>To ensure that the dependency chain is never broken,
- <filename>-dev</filename> and <filename>-dbg</filename>
- packages are always generated by default, even if the packages
- turn out to be empty.
- See the
- <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
- variable for more information.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The <filename>do_package</filename> task depends on the
- <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
- task of each recipe in
- <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
- through use of a
- <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
- declaration, which guarantees that the required
- shared-library/module-to-package mapping information will be available
- when needed as long as <filename>DEPENDS</filename> has been
- correctly set.
- </para>
-</section>
-
-<section id='fakeroot-and-pseudo'>
- <title>Fakeroot and Pseudo</title>
-
- <para>
- Some tasks are easier to implement when allowed to perform certain
- operations that are normally reserved for the root user.
- For example, the
- <link linkend='ref-tasks-install'><filename>do_install</filename></link>
- task benefits from being able to set the UID and GID of installed files
- to arbitrary values.
- </para>
-
- <para>
- One approach to allowing tasks to perform root-only operations
- would be to require BitBake to run as root.
- However, this method is cumbersome and has security issues.
- The approach that is actually used is to run tasks that benefit from
- root privileges in a "fake" root environment.
- Within this environment, the task and its child processes believe that
- they are running as the root user, and see an internally consistent
- view of the filesystem.
- As long as generating the final output (e.g. a package or an image)
- does not require root privileges, the fact that some earlier steps ran
- in a fake root environment does not cause problems.
- </para>
-
- <para>
- The capability to run tasks in a fake root environment is known as
- "fakeroot", which is derived from the BitBake keyword/variable
- flag that requests a fake root environment for a task.
- In current versions of the OpenEmbedded build system,
- the program that implements fakeroot is known as Pseudo.
- </para>
-
- <para>
- Pseudo overrides system calls through the
- <filename>LD_PRELOAD</filename> mechanism to give the
- illusion of running as root.
- To keep track of "fake" file ownership and permissions resulting from
- operations that require root permissions, an sqlite3
- database is used.
- This database is stored in
- <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename>
- for individual recipes.
- Storing the database in a file as opposed to in memory
- gives persistence between tasks, and even between builds.
- <note><title>Caution</title>
- If you add your own task that manipulates the same files or
- directories as a fakeroot task, then that task should also run
- under fakeroot.
- Otherwise, the task will not be able to run root-only operations,
- and will not see the fake file ownership and permissions set by the
- other task.
- You should also add a dependency on
- <filename>virtual/fakeroot-native:do_populate_sysroot</filename>,
- giving the following:
- <literallayout class='monospaced'>
- fakeroot do_mytask () {
- ...
- }
- do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
- </literallayout>
- </note>
- For more information, see the
- <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink>
- variables in the BitBake User Manual.
- You can also reference this
- <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink>
- article.
- </para>
-</section>
-
-<section id='wic-plug-ins-interface'>
- <title>Wic Plug-Ins Interface</title>
-
- <para>
- You can extend and specialize Wic functionality by using
- Wic plug-ins.
- This section explains the Wic plug-in interface.
- For information on using Wic in general, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
- section in the Yocto Project Development Tasks Manual.
- <note>
- Wic plug-ins consist of "source" and "imager" plug-ins.
- Imager plug-ins are beyond the scope of this section.
- </note>
- </para>
-
- <para>
- Source plug-ins provide a mechanism to customize partition
- content during the Wic image generation process.
- You can use source plug-ins to map values that you specify
- using <filename>--source</filename> commands in kickstart
- files (i.e. <filename>*.wks</filename>) to a plug-in
- implementation used to populate a given partition.
- <note>
- If you use plug-ins that have build-time dependencies
- (e.g. native tools, bootloaders, and so forth)
- when building a Wic image, you need to specify those
- dependencies using the
- <link linkend='var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></link>
- variable.
- </note>
- </para>
-
- <para>
- Source plug-ins are subclasses defined in plug-in files.
- As shipped, the Yocto Project provides several plug-in
- files.
- You can see the source plug-in files that ship with the
- Yocto Project
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
- Each of these plug-in files contain source plug-ins that
- are designed to populate a specific Wic image partition.
- </para>
-
- <para>
- Source plug-ins are subclasses of the
- <filename>SourcePlugin</filename> class, which is
- defined in the
- <filename>poky/scripts/lib/wic/pluginbase.py</filename>
- file.
- For example, the <filename>BootimgEFIPlugin</filename>
- source plug-in found in the
- <filename>bootimg-efi.py</filename> file is a subclass of
- the <filename>SourcePlugin</filename> class, which is found
- in the <filename>pluginbase.py</filename> file.
- </para>
-
- <para>
- You can also implement source plug-ins in a layer outside
- of the Source Repositories (external layer).
- To do so, be sure that your plug-in files are located in
- a directory whose path is
- <filename>scripts/lib/wic/plugins/source/</filename>
- within your external layer.
- When the plug-in files are located there, the source
- plug-ins they contain are made available to Wic.
- </para>
-
- <para>
- When the Wic implementation needs to invoke a
- partition-specific implementation, it looks for the plug-in
- with the same name as the <filename>--source</filename>
- parameter used in the kickstart file given to that
- partition.
- For example, if the partition is set up using the following
- command in a kickstart file:
- <literallayout class='monospaced'>
- part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
- </literallayout>
- The methods defined as class members of the matching
- source plug-in (i.e. <filename>bootimg-pcbios</filename>)
- in the <filename>bootimg-pcbios.py</filename> plug-in file
- are used.
- </para>
-
- <para>
- To be more concrete, here is the corresponding plug-in
- definition from the <filename>bootimg-pcbios.py</filename>
- file for the previous command along with an example
- method called by the Wic implementation when it needs to
- prepare a partition using an implementation-specific
- function:
- <literallayout class='monospaced'>
- bootimg-pcbios.py
- .
- .
- .
- class BootimgPcbiosPlugin(SourcePlugin):
- """
- Create MBR boot partition and install syslinux on it.
- """
-
- name = 'bootimg-pcbios'
- .
- .
- .
- @classmethod
- def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
- oe_builddir, bootimg_dir, kernel_dir,
- rootfs_dir, native_sysroot):
- """
- Called to do the actual content population for a partition i.e. it
- 'prepares' the partition to be incorporated into the image.
- In this case, prepare content for legacy bios boot partition.
- """
- .
- .
- .
- </literallayout>
- If a subclass (plug-in) itself does not implement a
- particular function, Wic locates and uses the default
- version in the superclass.
- It is for this reason that all source plug-ins are derived
- from the <filename>SourcePlugin</filename> class.
- </para>
-
- <para>
- The <filename>SourcePlugin</filename> class defined in
- the <filename>pluginbase.py</filename> file defines
- a set of methods that source plug-ins can implement or
- override.
- Any plug-ins (subclass of
- <filename>SourcePlugin</filename>) that do not implement
- a particular method inherit the implementation of the
- method from the <filename>SourcePlugin</filename> class.
- For more information, see the
- <filename>SourcePlugin</filename> class in the
- <filename>pluginbase.py</filename> file for details:
- </para>
-
- <para>
- The following list describes the methods implemented in the
- <filename>SourcePlugin</filename> class:
- <itemizedlist>
- <listitem><para>
- <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
- Called to populate a partition with actual content.
- In other words, the method prepares the final
- partition image that is incorporated into the
- disk image.
- </para></listitem>
- <listitem><para>
- <emphasis><filename>do_configure_partition()</filename>:</emphasis>
- Called before
- <filename>do_prepare_partition()</filename> to
- create custom configuration files for a partition
- (e.g. syslinux or grub configuration files).
- </para></listitem>
- <listitem><para>
- <emphasis><filename>do_install_disk()</filename>:</emphasis>
- Called after all partitions have been prepared and
- assembled into a disk image.
- This method provides a hook to allow finalization
- of a disk image (e.g. writing an MBR).
- </para></listitem>
- <listitem><para>
- <emphasis><filename>do_stage_partition()</filename>:</emphasis>
- Special content-staging hook called before
- <filename>do_prepare_partition()</filename>.
- This method is normally empty.</para>
-
- <para>Typically, a partition just uses the passed-in
- parameters (e.g. the unmodified value of
- <filename>bootimg_dir</filename>).
- However, in some cases, things might need to be
- more tailored.
- As an example, certain files might additionally
- need to be taken from
- <filename>bootimg_dir + /boot</filename>.
- This hook allows those files to be staged in a
- customized fashion.
- <note>
- <filename>get_bitbake_var()</filename>
- allows you to access non-standard variables
- that you might want to use for this
- behavior.
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- You can extend the source plug-in mechanism.
- To add more hooks, create more source plug-in methods
- within <filename>SourcePlugin</filename> and the
- corresponding derived subclasses.
- The code that calls the plug-in methods uses the
- <filename>plugin.get_source_plugin_methods()</filename>
- function to find the method or methods needed by the call.
- Retrieval of those methods is accomplished by filling up
- a dict with keys that contain the method names of interest.
- On success, these will be filled in with the actual
- methods.
- See the Wic implementation for examples and details.
- </para>
-</section>
-
-<section id='x32'>
- <title>x32</title>
-
- <para>
- x32 is a processor-specific Application Binary Interface (psABI) for x86_64.
- An ABI defines the calling conventions between functions in a processing environment.
- The interface determines what registers are used and what the sizes are for various C data types.
- </para>
-
- <para>
- Some processing environments prefer using 32-bit applications even when running
- on Intel 64-bit platforms.
- Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
- The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
- leaving the system underutilized.
- Now consider the x86_64 psABI.
- This ABI is newer and uses 64-bits for data sizes and program pointers.
- The extra bits increase the footprint size of the programs, libraries,
- and also increases the memory and file system size requirements.
- Executing under the x32 psABI enables user programs to utilize CPU and system resources
- more efficiently while keeping the memory footprint of the applications low.
- Extra bits are used for registers but not for addressing mechanisms.
- </para>
-
- <section id='support'>
- <title>Support</title>
-
- <para>
- This Yocto Project release supports the final specifications of x32
- psABI.
- Support for x32 psABI exists as follows:
- <itemizedlist>
- <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
- </para></listitem>
- <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
- <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
- <filename>core-image-sato</filename> images.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='completing-x32'>
- <title>Completing x32</title>
-
- <para>
- Future Plans for the x32 psABI in the Yocto Project include the following:
- <itemizedlist>
- <listitem><para>Enhance and fix the few remaining recipes so they
- work with and support x32 toolchains.</para></listitem>
- <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
- <listitem><para>Support larger images.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='using-x32-right-now'>
- <title>Using x32 Right Now</title>
-
- <para>
- Follow these steps to use the x32 spABI:
- <itemizedlist>
- <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
- machines by editing the <filename>conf/local.conf</filename> like this:
- <literallayout class='monospaced'>
- MACHINE = "qemux86-64"
- DEFAULTTUNE = "x86-64-x32"
- baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
- or 'INVALID'), True) or 'lib'}"
- #MACHINE = "genericx86"
- #DEFAULTTUNE = "core2-64-x32"
- </literallayout></para></listitem>
- <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
- Here is an example:
- <literallayout class='monospaced'>
- $ bitbake core-image-sato
- </literallayout></para></listitem>
- <listitem><para>As usual, run your image using QEMU:
- <literallayout class='monospaced'>
- $ runqemu qemux86-64 core-image-sato
- </literallayout></para></listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
-
-<section id="wayland">
- <title>Wayland</title>
-
- <para>
- <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink>
- is a computer display server protocol that
- provides a method for compositing window managers to communicate
- directly with applications and video hardware and expects them to
- communicate with input hardware using other libraries.
- Using Wayland with supporting targets can result in better control
- over graphics frame rendering than an application might otherwise
- achieve.
- </para>
-
- <para>
- The Yocto Project provides the Wayland protocol libraries and the
- reference
- <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink>
- compositor as part of its release.
- This section describes what you need to do to implement Wayland and
- use the compositor when building an image for a supporting target.
- </para>
-
- <section id="wayland-support">
- <title>Support</title>
-
- <para>
- The Wayland protocol libraries and the reference Weston compositor
- ship as integrated packages in the <filename>meta</filename> layer
- of the
- <link linkend='source-directory'>Source Directory</link>.
- Specifically, you can find the recipes that build both Wayland
- and Weston at <filename>meta/recipes-graphics/wayland</filename>.
- </para>
-
- <para>
- You can build both the Wayland and Weston packages for use only
- with targets that accept the
- <ulink url='http://dri.freedesktop.org/wiki/'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
- which is also known as Mesa DRI.
- This implies that you cannot build and use the packages if your
- target uses, for example, the
- <trademark class='registered'>Intel</trademark> Embedded Media and
- Graphics Driver (<trademark class='registered'>Intel</trademark>
- EMGD) that overrides Mesa DRI.
- </para>
-
- <note>
- Due to lack of EGL support, Weston 1.0.3 will not run directly on
- the emulated QEMU hardware.
- However, this version of Weston will run under X emulation without
- issues.
- </note>
- </section>
-
- <section id="enabling-wayland-in-an-image">
- <title>Enabling Wayland in an Image</title>
-
- <para>
- To enable Wayland, you need to enable it to be built and enable
- it to be included in the image.
- </para>
-
- <section id="enable-building">
- <title>Building</title>
-
- <para>
- To cause Mesa to build the <filename>wayland-egl</filename>
- platform and Weston to build Wayland with Kernel Mode
- Setting
- (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
- support, include the "wayland" flag in the
- <link linkend="var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></link>
- statement in your <filename>local.conf</filename> file:
- <literallayout class='monospaced'>
- DISTRO_FEATURES_append = " wayland"
- </literallayout>
- </para>
-
- <note>
- If X11 has been enabled elsewhere, Weston will build Wayland
- with X11 support
- </note>
- </section>
-
- <section id="enable-installation-in-an-image">
- <title>Installing</title>
-
- <para>
- To install the Wayland feature into an image, you must
- include the following
- <link linkend='var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></link>
- statement in your <filename>local.conf</filename> file:
- <literallayout class='monospaced'>
- CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
- </literallayout>
- </para>
- </section>
- </section>
-
- <section id="running-weston">
- <title>Running Weston</title>
-
- <para>
- To run Weston inside X11, enabling it as described earlier and
- building a Sato image is sufficient.
- If you are running your image under Sato, a Weston Launcher appears
- in the "Utility" category.
- </para>
-
- <para>
- Alternatively, you can run Weston through the command-line
- interpretor (CLI), which is better suited for development work.
- To run Weston under the CLI, you need to do the following after
- your image is built:
- <orderedlist>
- <listitem><para>Run these commands to export
- <filename>XDG_RUNTIME_DIR</filename>:
- <literallayout class='monospaced'>
- mkdir -p /tmp/$USER-weston
- chmod 0700 /tmp/$USER-weston
- export XDG_RUNTIME_DIR=/tmp/$USER-weston
- </literallayout></para></listitem>
- <listitem><para>Launch Weston in the shell:
- <literallayout class='monospaced'>
- weston
- </literallayout></para></listitem>
- </orderedlist>
- </para>
- </section>
-</section>
-
-<section id="licenses">
- <title>Licenses</title>
-
- <para>
- This section describes the mechanism by which the OpenEmbedded build system
- tracks changes to licensing text.
- The section also describes how to enable commercially licensed recipes,
- which by default are disabled.
- </para>
-
- <para>
- For information that can help you maintain compliance with various open
- source licensing during the lifecycle of the product, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
- <title>Tracking License Changes</title>
-
- <para>
- The license of an upstream project might change in the future.
- In order to prevent these changes going unnoticed, the
- <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
- variable tracks changes to the license text. The checksums are validated at the end of the
- configure step, and if the checksums do not match, the build will fail.
- </para>
-
- <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
- <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
-
- <para>
- The <filename>LIC_FILES_CHKSUM</filename>
- variable contains checksums of the license text in the source
- code for the recipe.
- Following is an example of how to specify
- <filename>LIC_FILES_CHKSUM</filename>:
- <literallayout class='monospaced'>
- LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
- file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
- file://licfile2.txt;endline=50;md5=zzzz \
- ..."
- </literallayout>
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- When using "beginline" and "endline", realize that
- line numbering begins with one and not zero.
- Also, the included lines are inclusive (i.e. lines
- five through and including 29 in the previous
- example for <filename>licfile1.txt</filename>).
- </para></listitem>
- <listitem><para>
- When a license check fails, the selected license
- text is included as part of the QA message.
- Using this output, you can determine the exact
- start and finish for the needed license text.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- The build system uses the
- <filename><link linkend='var-S'>S</link></filename> variable as
- the default directory when searching files listed in
- <filename>LIC_FILES_CHKSUM</filename>.
- The previous example employs the default directory.
- </para>
-
- <para>
- Consider this next example:
- <literallayout class='monospaced'>
- LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
- md5=bb14ed3c4cda583abc85401304b5cd4e"
- LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
- </literallayout>
- </para>
-
- <para>
- The first line locates a file in
- <filename>${S}/src/ls.c</filename> and isolates lines five
- through 16 as license text.
- The second line refers to a file in
- <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
- </para>
- <para>
- Note that <filename>LIC_FILES_CHKSUM</filename> variable is
- mandatory for all recipes, unless the
- <filename>LICENSE</filename> variable is set to "CLOSED".
- </para>
- </section>
-
- <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
- <title>Explanation of Syntax</title>
- <para>
- As mentioned in the previous section, the
- <filename>LIC_FILES_CHKSUM</filename> variable lists all the
- important files that contain the license text for the source code.
- It is possible to specify a checksum for an entire file, or a specific section of a
- file (specified by beginning and ending line numbers with the "beginline" and "endline"
- parameters, respectively).
- The latter is useful for source files with a license notice header,
- README documents, and so forth.
- If you do not use the "beginline" parameter, then it is assumed that the text begins on the
- first line of the file.
- Similarly, if you do not use the "endline" parameter, it is assumed that the license text
- ends with the last line of the file.
- </para>
-
- <para>
- The "md5" parameter stores the md5 checksum of the license text.
- If the license text changes in any way as compared to this parameter
- then a mismatch occurs.
- This mismatch triggers a build failure and notifies the developer.
- Notification allows the developer to review and address the license text changes.
- Also note that if a mismatch occurs during the build, the correct md5
- checksum is placed in the build log and can be easily copied to the recipe.
- </para>
-
- <para>
- There is no limit to how many files you can specify using the
- <filename>LIC_FILES_CHKSUM</filename> variable.
- Generally, however, every project requires a few specifications for license tracking.
- Many projects have a "COPYING" file that stores the license information for all the source
- code files.
- This practice allows you to just track the "COPYING" file as long as it is kept up to date.
- </para>
-
- <tip>
- If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
- error and displays the correct "md5" parameter value during the build.
- The correct parameter is also captured in the build log.
- </tip>
-
- <tip>
- If the whole file contains only license text, you do not need to use the "beginline" and
- "endline" parameters.
- </tip>
- </section>
- </section>
-
- <section id="enabling-commercially-licensed-recipes">
- <title>Enabling Commercially Licensed Recipes</title>
-
- <para>
- By default, the OpenEmbedded build system disables
- components that have commercial or other special licensing
- requirements.
- Such requirements are defined on a
- recipe-by-recipe basis through the
- <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
- variable definition in the affected recipe.
- For instance, the
- <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
- recipe contains the following statement:
- <literallayout class='monospaced'>
- LICENSE_FLAGS = "commercial"
- </literallayout>
- Here is a slightly more complicated example that contains both an
- explicit recipe name and version (after variable expansion):
- <literallayout class='monospaced'>
- LICENSE_FLAGS = "license_${PN}_${PV}"
- </literallayout>
- In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
- definition to be enabled and included in an image, it
- needs to have a matching entry in the global
- <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
- variable, which is a variable
- typically defined in your <filename>local.conf</filename> file.
- For example, to enable
- the <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
- package, you could add either the string
- "commercial_gst-plugins-ugly" or the more general string
- "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
- See the
- "<link linkend='license-flag-matching'>License Flag Matching</link>" section
- for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
- Here is the example:
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
- </literallayout>
- Likewise, to additionally enable the package built from the recipe containing
- <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
- that the actual recipe name was <filename>emgd_1.10.bb</filename>,
- the following string would enable that package as well as
- the original <filename>gst-plugins-ugly</filename> package:
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
- </literallayout>
- As a convenience, you do not need to specify the complete license string
- in the whitelist for every package.
- You can use an abbreviated form, which consists
- of just the first portion or portions of the license string before
- the initial underscore character or characters.
- A partial string will match
- any license that contains the given string as the first
- portion of its license.
- For example, the following
- whitelist string will also match both of the packages
- previously mentioned as well as any other packages that have
- licenses starting with "commercial" or "license".
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial license"
- </literallayout>
- </para>
-
- <section id="license-flag-matching">
- <title>License Flag Matching</title>
-
- <para>
- License flag matching allows you to control what recipes the
- OpenEmbedded build system includes in the build.
- Fundamentally, the build system attempts to match
- <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
- strings found in recipes against
- <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
- strings found in the whitelist.
- A match causes the build system to include a recipe in the
- build, while failure to find a match causes the build system to
- exclude a recipe.
- </para>
-
- <para>
- In general, license flag matching is simple.
- However, understanding some concepts will help you
- correctly and effectively use matching.
- </para>
-
- <para>
- Before a flag
- defined by a particular recipe is tested against the
- contents of the whitelist, the expanded string
- <filename>_${PN}</filename> is appended to the flag.
- This expansion makes each <filename>LICENSE_FLAGS</filename>
- value recipe-specific.
- After expansion, the string is then matched against the
- whitelist.
- Thus, specifying
- <filename>LICENSE_FLAGS = "commercial"</filename>
- in recipe "foo", for example, results in the string
- <filename>"commercial_foo"</filename>.
- And, to create a match, that string must appear in the
- whitelist.
- </para>
-
- <para>
- Judicious use of the <filename>LICENSE_FLAGS</filename>
- strings and the contents of the
- <filename>LICENSE_FLAGS_WHITELIST</filename> variable
- allows you a lot of flexibility for including or excluding
- recipes based on licensing.
- For example, you can broaden the matching capabilities by
- using license flags string subsets in the whitelist.
- <note>When using a string subset, be sure to use the part of
- the expanded string that precedes the appended underscore
- character (e.g. <filename>usethispart_1.3</filename>,
- <filename>usethispart_1.4</filename>, and so forth).
- </note>
- For example, simply specifying the string "commercial" in
- the whitelist matches any expanded
- <filename>LICENSE_FLAGS</filename> definition that starts with
- the string "commercial" such as "commercial_foo" and
- "commercial_bar", which are the strings the build system
- automatically generates for hypothetical recipes named
- "foo" and "bar" assuming those recipes simply specify the
- following:
- <literallayout class='monospaced'>
- LICENSE_FLAGS = "commercial"
- </literallayout>
- Thus, you can choose to exhaustively
- enumerate each license flag in the whitelist and
- allow only specific recipes into the image, or
- you can use a string subset that causes a broader range of
- matches to allow a range of recipes into the image.
- </para>
-
- <para>
- This scheme works even if the
- <filename>LICENSE_FLAGS</filename> string already
- has <filename>_${PN}</filename> appended.
- For example, the build system turns the license flag
- "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
- match both the general "commercial" and the specific
- "commercial_1.2_foo" strings found in the whitelist, as
- expected.
- </para>
-
- <para>
- Here are some other scenarios:
- <itemizedlist>
- <listitem><para>You can specify a versioned string in the
- recipe such as "commercial_foo_1.2" in a "foo" recipe.
- The build system expands this string to
- "commercial_foo_1.2_foo".
- Combine this license flag with a whitelist that has
- the string "commercial" and you match the flag along
- with any other flag that starts with the string
- "commercial".</para></listitem>
- <listitem><para>Under the same circumstances, you can
- use "commercial_foo" in the whitelist and the
- build system not only matches "commercial_foo_1.2" but
- also matches any license flag with the string
- "commercial_foo", regardless of the version.
- </para></listitem>
- <listitem><para>You can be very specific and use both the
- package and version parts in the whitelist (e.g.
- "commercial_foo_1.2") to specifically match a
- versioned recipe.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id="other-variables-related-to-commercial-licenses">
- <title>Other Variables Related to Commercial Licenses</title>
-
- <para>
- Other helpful variables related to commercial
- license handling exist and are defined in the
- <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
- <literallayout class='monospaced'>
- COMMERCIAL_AUDIO_PLUGINS ?= ""
- COMMERCIAL_VIDEO_PLUGINS ?= ""
- </literallayout>
- If you want to enable these components, you can do so by making sure you have
- statements similar to the following
- in your <filename>local.conf</filename> configuration file:
- <literallayout class='monospaced'>
- COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
- gst-plugins-ugly-mpegaudioparse"
- COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
- gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
- LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
- </literallayout>
- Of course, you could also create a matching whitelist
- for those components using the more general "commercial"
- in the whitelist, but that would also enable all the
- other packages with
- <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
- containing "commercial", which you may or may not want:
- <literallayout class='monospaced'>
- LICENSE_FLAGS_WHITELIST = "commercial"
- </literallayout>
- </para>
-
- <para>
- Specifying audio and video plug-ins as part of the
- <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
- <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
- (along with the enabling
- <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
- plug-ins or components into built images, thus adding
- support for media formats or components.
- </para>
- </section>
- </section>
-</section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml
deleted file mode 100644
index 13d9ad6..0000000
--- a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml
+++ /dev/null
@@ -1,2091 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='usingpoky'>
-<title>Using the Yocto Project</title>
-
- <para>
- This chapter describes common usage for the Yocto Project.
- The information is introductory in nature as other manuals in the Yocto Project
- documentation set provide more details on how to use the Yocto Project.
- </para>
-
-<section id='usingpoky-build'>
- <title>Running a Build</title>
-
- <para>
- This section provides a summary of the build process and provides information
- for less obvious aspects of the build process.
- For general information on how to build an image using the OpenEmbedded build
- system, see the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section of the Yocto Project Quick Start.
- </para>
-
- <section id='build-overview'>
- <title>Build Overview</title>
-
- <para>
- In the development environment you will need to build an image whenever you change hardware
- support, add or change system libraries, or add or change services that have dependencies.
- </para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
- </imageobject>
- <caption>
- <para>Building an Image</para>
- </caption>
- </mediaobject>
-
- <para>
- The first thing you need to do is set up the OpenEmbedded build
- environment by sourcing the environment setup script
- (i.e.
- <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
- Here is an example:
- <literallayout class='monospaced'>
- $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
- </literallayout>
- </para>
-
- <para>
- The <replaceable>build_dir</replaceable> argument is optional and specifies the directory the
- OpenEmbedded build system uses for the build -
- the
- <link linkend='build-directory'>Build Directory</link>.
- If you do not specify a Build Directory, it defaults to a directory
- named <filename>build</filename> in your current working directory.
- A common practice is to use a different Build Directory for different targets.
- For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
- target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
- </para>
-
- <para>
- Once the build environment is set up, you can build a target using:
- <literallayout class='monospaced'>
- $ bitbake <replaceable>target</replaceable>
- </literallayout>
- <note>
- <para>
- If you experience a build error due to resources
- temporarily being unavailable and it appears you
- should not be having this issue, it might be due
- to the combination of a 4.3+ Linux kernel and
- <filename>systemd</filename> version 228+
- (i.e. see this
- <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
- for information).
- </para>
-
- <para>
- To work around this issue, you can try either
- of the following:
- <itemizedlist>
- <listitem><para>
- Try the build again.
- </para></listitem>
- <listitem><para>
- Modify the "DefaultTasksMax"
- <filename>systemd</filename> parameter
- by uncommenting it and setting it to
- "infinity".
- You can find this parameter in the
- <filename>system.conf</filename> file
- located in
- <filename>/etc/systemd</filename>
- on most systems.
- </para></listitem>
- </itemizedlist>
- </para>
- </note>
- </para>
-
- <para>
- The <replaceable>target</replaceable> is the name of the recipe you want to build.
- Common targets are the images in <filename>meta/recipes-core/images</filename>,
- <filename>meta/recipes-sato/images</filename>, etc. all found in the
- <link linkend='source-directory'>Source Directory</link>.
- Or, the target can be the name of a recipe for a specific piece of software such as
- BusyBox.
- For more details about the images the OpenEmbedded build system supports, see the
- "<link linkend="ref-images">Images</link>" chapter.
- </para>
-
- <note>
- Building an image without GNU General Public License Version
- 3 (GPLv3), or similarly licensed, components is supported for
- only minimal and base images.
- See the "<link linkend='ref-images'>Images</link>" chapter for more information.
- </note>
- </section>
-
- <section id='building-an-image-using-gpl-components'>
- <title>Building an Image Using GPL Components</title>
-
- <para>
- When building an image using GPL components, you need to maintain your original
- settings and not switch back and forth applying different versions of the GNU
- General Public License.
- If you rebuild using different versions of GPL, dependency errors might occur
- due to some components not being rebuilt.
- </para>
- </section>
-</section>
-
-<section id='usingpoky-install'>
- <title>Installing and Using the Result</title>
-
- <para>
- Once an image has been built, it often needs to be installed.
- The images and kernels built by the OpenEmbedded build system are placed in the
- <link linkend='build-directory'>Build Directory</link> in
- <filename class="directory">tmp/deploy/images</filename>.
- For information on how to run pre-built images such as <filename>qemux86</filename>
- and <filename>qemuarm</filename>, see the
- <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
- manual.
- For information about how to install these images, see the documentation for your
- particular board or machine.
- </para>
-</section>
-
-<section id='usingpoky-debugging-tools-and-techniques'>
- <title>Debugging Tools and Techniques</title>
-
- <para>
- The exact method for debugging build failures depends on the nature of
- the problem and on the system's area from which the bug originates.
- Standard debugging practices such as comparison against the last
- known working version with examination of the changes and the
- re-application of steps to identify the one causing the problem are
- valid for the Yocto Project just as they are for any other system.
- Even though it is impossible to detail every possible potential failure,
- this section provides some general tips to aid in debugging.
- </para>
-
- <para>
- A useful feature for debugging is the error reporting tool.
- Configuring the Yocto Project to use this tool causes the
- OpenEmbedded build system to produce error reporting commands as
- part of the console output.
- You can enter the commands after the build completes
- to log error information
- into a common database, that can help you figure out what might be
- going wrong.
- For information on how to enable and use this feature, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>Using the Error Reporting Tool</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
-
- <para>
- For discussions on debugging, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" section
- in the Yocto Project Development Tasks Manual
- and the
- "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
- section in the Yocto Project Application Development and the
- Extensible Software Development Kit (eSDK) manual.
- </para>
-
- <note>
- The remainder of this section presents many examples of the
- <filename>bitbake</filename> command.
- You can learn about BitBake by reading the
- <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
- </note>
-
- <section id='usingpoky-debugging-viewing-logs-from-failed-tasks'>
- <title>Viewing Logs from Failed Tasks</title>
-
- <para>
- You can find the log for a task in the file
- <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
- For example, the log for the
- <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
- task of the QEMU minimal image for the x86 machine
- (<filename>qemux86</filename>) might be in
- <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
- To see the commands
- <link linkend='bitbake-term'>BitBake</link> ran
- to generate a log, look at the corresponding
- <filename>run.do_</filename><replaceable>taskname</replaceable>
- file in the same directory.
- </para>
-
- <para>
- <filename>log.do_</filename><replaceable>taskname</replaceable> and
- <filename>run.do_</filename><replaceable>taskname</replaceable>
- are actually symbolic links to
- <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
- and
- <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
- where <replaceable>pid</replaceable> is the PID the task had when
- it ran.
- The symlinks always point to the files corresponding to the most
- recent run.
- </para>
- </section>
-
- <section id='usingpoky-debugging-viewing-variable-values'>
- <title>Viewing Variable Values</title>
- <para>
- BitBake's <filename>-e</filename> option is used to display
- variable values after parsing.
- The following command displays the variable values after the
- configuration files (i.e. <filename>local.conf</filename>,
- <filename>bblayers.conf</filename>,
- <filename>bitbake.conf</filename> and so forth) have been
- parsed:
- <literallayout class='monospaced'>
- $ bitbake -e
- </literallayout>
- The following command displays variable values after a specific
- recipe has been parsed.
- The variables include those from the configuration as well:
- <literallayout class='monospaced'>
- $ bitbake -e recipename
- </literallayout>
- <note><para>
- Each recipe has its own private set of variables (datastore).
- Internally, after parsing the configuration, a copy of the
- resulting datastore is made prior to parsing each recipe.
- This copying implies that variables set in one recipe will
- not be visible to other recipes.</para>
-
- <para>Likewise, each task within a recipe gets a private
- datastore based on the recipe datastore, which means that
- variables set within one task will not be visible to
- other tasks.</para>
- </note>
- </para>
-
- <para>
- In the output of <filename>bitbake -e</filename>, each variable is
- preceded by a description of how the variable got its value,
- including temporary values that were later overriden.
- This description also includes variable flags (varflags) set on
- the variable.
- The output can be very helpful during debugging.
- </para>
-
- <para>
- Variables that are exported to the environment are preceded by
- <filename>export</filename> in the output of
- <filename>bitbake -e</filename>.
- See the following example:
- <literallayout class='monospaced'>
- export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
- </literallayout>
- </para>
-
- <para>
- In addition to variable values, the output of the
- <filename>bitbake -e</filename> and
- <filename>bitbake -e</filename> <replaceable>recipe</replaceable>
- commands includes the following information:
- <itemizedlist>
- <listitem><para>
- The output starts with a tree listing all configuration
- files and classes included globally, recursively listing
- the files they include or inherit in turn.
- Much of the behavior of the OpenEmbedded build system
- (including the behavior of the
- <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>)
- is implemented in the
- <link linkend='ref-classes-base'><filename>base</filename></link>
- class and the classes it inherits, rather than being built
- into BitBake itself.
- </para></listitem>
- <listitem><para>
- After the variable values, all functions appear in the
- output.
- For shell functions, variables referenced within the
- function body are expanded.
- If a function has been modified using overrides or
- using override-style operators like
- <filename>_append</filename> and
- <filename>_prepend</filename>, then the final assembled
- function body appears in the output.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='viewing-package-information-with-oe-pkgdata-util'>
- <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
-
- <para>
- You can use the <filename>oe-pkgdata-util</filename> command-line
- utility to query
- <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
- and display various package-related information.
- When you use the utility, you must use it to view information
- on packages that have already been built.
- </para>
-
- <para>
- Following are a few of the available
- <filename>oe-pkgdata-util</filename> subcommands.
- <note>
- You can use the standard * and ? globbing wildcards as part of
- package names and paths.
- </note>
- <itemizedlist>
- <listitem><para>
- <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
- Lists all packages that have been built, optionally
- limiting the match to packages that match
- <replaceable>pattern</replaceable>.
- </para></listitem>
- <listitem><para>
- <filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>:
- Lists the files and directories contained in the given
- packages.
- <note>
- <para>
- A different way to view the contents of a package is
- to look at the
- <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/packages-split</filename>
- directory of the recipe that generates the
- package.
- This directory is created by the
- <link linkend='ref-tasks-package'><filename>do_package</filename></link>
- task and has one subdirectory for each package the
- recipe generates, which contains the files stored in
- that package.</para>
- <para>
- If you want to inspect the
- <filename>${WORKDIR}/packages-split</filename>
- directory, make sure that
- <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
- is not enabled when you build the recipe.
- </para>
- </note>
- </para></listitem>
- <listitem><para>
- <filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>:
- Lists the names of the packages that contain the given
- paths.
- For example, the following tells us that
- <filename>/usr/share/man/man1/make.1</filename>
- is contained in the <filename>make-doc</filename>
- package:
- <literallayout class='monospaced'>
- $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
- make-doc: /usr/share/man/man1/make.1
- </literallayout>
- </para></listitem>
- <listitem><para>
- <filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>:
- Lists the name of the recipes that
- produce the given packages.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- For more information on the <filename>oe-pkgdata-util</filename>
- command, use the help facility:
- <literallayout class='monospaced'>
- $ oe-pkgdata-util ‐‐help
- $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
- </literallayout>
- </para>
- </section>
-
- <section id='usingpoky-viewing-dependencies-between-recipes-and-tasks'>
- <title>Viewing Dependencies Between Recipes and Tasks</title>
-
- <para>
- Sometimes it can be hard to see why BitBake wants to build other
- recipes before the one you have specified.
- Dependency information can help you understand why a recipe is
- built.
- </para>
-
- <para>
- To generate dependency information for a recipe, run the following
- command:
- <literallayout class='monospaced'>
- $ bitbake -g <replaceable>recipename</replaceable>
- </literallayout>
- This command writes the following files in the current directory:
- <itemizedlist>
- <listitem><para>
- <filename>pn-buildlist</filename>: A list of
- recipes/targets involved in building
- <replaceable>recipename</replaceable>.
- "Involved" here means that at least one task from the
- recipe needs to run when building
- <replaceable>recipename</replaceable> from scratch.
- Targets that are in
- <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
- are not listed.
- </para></listitem>
- <listitem><para>
- <filename>task-depends.dot</filename>: A graph showing
- dependencies between tasks.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The graphs are in
- <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
- format and can be converted to images (e.g. using the
- <filename>dot</filename> tool from
- <ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- DOT files use a plain text format.
- The graphs generated using the
- <filename>bitbake -g</filename> command are often so
- large as to be difficult to read without special
- pruning (e.g. with Bitbake's
- <filename>-I</filename> option) and processing.
- Despite the form and size of the graphs, the
- corresponding <filename>.dot</filename> files can still
- be possible to read and provide useful information.
- </para>
-
- <para>As an example, the
- <filename>task-depends.dot</filename> file contains
- lines such as the following:
- <literallayout class='monospaced'>
- "libxslt.do_configure" -> "libxml2.do_populate_sysroot"
- </literallayout>
- The above example line reveals that the
- <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
- task in <filename>libxslt</filename> depends on the
- <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
- task in <filename>libxml2</filename>, which is a normal
- <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
- dependency between the two recipes.
- </para></listitem>
- <listitem><para>
- For an example of how <filename>.dot</filename> files
- can be processed, see the
- <filename>scripts/contrib/graph-tool</filename> Python
- script, which finds and displays paths between graph
- nodes.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- You can use a different method to view dependency information
- by using the following command:
- <literallayout class='monospaced'>
- $ bitbake -g -u taskexp <replaceable>recipename</replaceable>
- </literallayout>
- This command displays a GUI window from which you can view
- build-time and runtime dependencies for the recipes involved in
- building <replaceable>recipename</replaceable>.
- </para>
- </section>
-
- <section id='usingpoky-viewing-task-variable-dependencies'>
- <title>Viewing Task Variable Dependencies</title>
-
- <para>
- As mentioned in the
- "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"
- section of the BitBake User Manual, BitBake tries to automatically
- determine what variables a task depends on so that it can rerun
- the task if any values of the variables change.
- This determination is usually reliable.
- However, if you do things like construct variable names at runtime,
- then you might have to manually declare dependencies on those
- variables using <filename>vardeps</filename> as described in the
- "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
- section of the BitBake User Manual.
- </para>
-
- <para>
- If you are unsure whether a variable dependency is being picked up
- automatically for a given task, you can list the variable
- dependencies BitBake has determined by doing the following:
- <orderedlist>
- <listitem><para>
- Build the recipe containing the task:
- <literallayout class='monospaced'>
- $ bitbake <replaceable>recipename</replaceable>
- </literallayout>
- </para></listitem>
- <listitem><para>
- Inside the
- <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>
- directory, find the signature data
- (<filename>sigdata</filename>) file that corresponds to the
- task.
- The <filename>sigdata</filename> files contain a pickled
- Python database of all the metadata that went into creating
- the input checksum for the task.
- As an example, for the
- <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
- task of the <filename>db</filename> recipe, the
- <filename>sigdata</filename> file might be found in the
- following location:
- <literallayout class='monospaced'>
- ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
- </literallayout>
- For tasks that are accelerated through the shared state
- (<link linkend='shared-state-cache'>sstate</link>)
- cache, an additional <filename>siginfo</filename> file is
- written into
- <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
- along with the cached task output.
- The <filename>siginfo</filename> files contain exactly the
- same information as <filename>sigdata</filename> files.
- </para></listitem>
- <listitem><para>
- Run <filename>bitbake-dumpsig</filename> on the
- <filename>sigdata</filename> or
- <filename>siginfo</filename> file.
- Here is an example:
- <literallayout class='monospaced'>
- $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
- </literallayout>
- In the output of the above command, you will find a line
- like the following, which lists all the (inferred) variable
- dependencies for the task.
- This list also includes indirect dependencies from
- variables depending on other variables, recursively.
- <literallayout class='monospaced'>
- Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
- </literallayout>
- <note>
- Functions (e.g. <filename>base_do_fetch</filename>)
- also count as variable dependencies.
- These functions in turn depend on the variables they
- reference.
- </note>
- The output of <filename>bitbake-dumpsig</filename> also includes
- the value each variable had, a list of dependencies for each
- variable, and
- <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>
- information.
- </para></listitem>
- </orderedlist>
- </para>
-
- <para>
- There is also a <filename>bitbake-diffsigs</filename> command for
- comparing two <filename>siginfo</filename> or
- <filename>sigdata</filename> files.
- This command can be helpful when trying to figure out what changed
- between two versions of a task.
- If you call <filename>bitbake-diffsigs</filename> with just one
- file, the command behaves like
- <filename>bitbake-dumpsig</filename>.
- </para>
-
- <para>
- You can also use BitBake to dump out the signature construction
- information without executing tasks by using either of the
- following BitBake command-line options:
- <literallayout class='monospaced'>
- ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
- -S <replaceable>SIGNATURE_HANDLER</replaceable>
- </literallayout>
- <note>
- Two common values for
- <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and
- "printdiff", which dump only the signature or compare the
- dumped signature with the cached one, respectively.
- </note>
- Using BitBake with either of these options causes BitBake to dump
- out <filename>sigdata</filename> files in the
- <filename>stamps</filename> directory for every task it would have
- executed instead of building the specified target package.
- </para>
- </section>
-
- <section id='usingpoky-debugging-taskrunning'>
- <title>Running Specific Tasks</title>
-
- <para>
- Any given recipe consists of a set of tasks.
- The standard BitBake behavior in most cases is:
- <filename>do_fetch</filename>,
- <filename>do_unpack</filename>,
- <filename>do_patch</filename>, <filename>do_configure</filename>,
- <filename>do_compile</filename>, <filename>do_install</filename>,
- <filename>do_package</filename>,
- <filename>do_package_write_*</filename>, and
- <filename>do_build</filename>.
- The default task is <filename>do_build</filename> and any tasks
- on which it depends build first.
- Some tasks, such as <filename>do_devshell</filename>, are not part
- of the default build chain.
- If you wish to run a task that is not part of the default build
- chain, you can use the <filename>-c</filename> option in BitBake.
- Here is an example:
- <literallayout class='monospaced'>
- $ bitbake matchbox-desktop -c devshell
- </literallayout>
- </para>
-
- <para>
- The <filename>-c</filename> option respects task dependencies,
- which means that all other tasks (including tasks from other
- recipes) that the specified task depends on will be run before the
- task.
- Even when you manually specify a task to run with
- <filename>-c</filename>, BitBake will only run the task if it
- considers it "out of date".
- See the
- "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"
- section for how BitBake determines whether a task is "out of date".
- </para>
-
- <para>
- If you want to force an up-to-date task to be rerun (e.g.
- because you made manual modifications to the recipe's
- <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
- that you want to try out), then you can use the
- <filename>-f</filename> option.
- <note>
- The reason <filename>-f</filename> is never required when
- running the
- <link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link>
- task is because the
- <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
- variable flag is already set for the task.
- </note>
- The following example shows one way you can use the
- <filename>-f</filename> option:
- <literallayout class='monospaced'>
- $ bitbake matchbox-desktop
- .
- .
- make some changes to the source code in the work directory
- .
- .
- $ bitbake matchbox-desktop -c compile -f
- $ bitbake matchbox-desktop
- </literallayout>
- </para>
-
- <para>
- This sequence first builds and then recompiles
- <filename>matchbox-desktop</filename>.
- The last command reruns all tasks (basically the packaging tasks)
- after the compile.
- BitBake recognizes that the <filename>do_compile</filename>
- task was rerun and therefore understands that the other tasks
- also need to be run again.
- </para>
-
- <para>
- Another, shorter way to rerun a task and all
- <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>
- that depend on it is to use the <filename>-C</filename>
- option.
- <note>
- This option is upper-cased and is separate from the
- <filename>-c</filename> option, which is lower-cased.
- </note>
- Using this option invalidates the given task and then runs the
- <link linkend='ref-tasks-build'><filename>do_build</filename></link>
- task, which is the default task if no task is given, and the
- tasks on which it depends.
- You could replace the final two commands in the previous example
- with the following single command:
- <literallayout class='monospaced'>
- $ bitbake matchbox-desktop -C compile
- </literallayout>
- Internally, the <filename>-f</filename> and
- <filename>-C</filename> options work by tainting (modifying) the
- input checksum of the specified task.
- This tainting indirectly causes the task and its
- dependent tasks to be rerun through the normal task dependency
- mechanisms.
- <note>
- BitBake explicitly keeps track of which tasks have been
- tainted in this fashion, and will print warnings such as the
- following for builds involving such tasks:
- <literallayout class='monospaced'>
- WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
- </literallayout>
- The purpose of the warning is to let you know that the work
- directory and build output might not be in the clean state they
- would be in for a "normal" build, depending on what actions
- you took.
- To get rid of such warnings, you can remove the work directory
- and rebuild the recipe, as follows:
- <literallayout class='monospaced'>
- $ bitbake matchbox-desktop -c clean
- $ bitbake matchbox-desktop
- </literallayout>
- </note>
- </para>
-
- <para>
- You can view a list of tasks in a given package by running the
- <filename>do_listtasks</filename> task as follows:
- <literallayout class='monospaced'>
- $ bitbake matchbox-desktop -c listtasks
- </literallayout>
- The results appear as output to the console and are also in the
- file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
- </para>
- </section>
-
- <section id='usingpoky-debugging-bitbake'>
- <title>General BitBake Problems</title>
-
- <para>
- You can see debug output from BitBake by using the <filename>-D</filename> option.
- The debug output gives more information about what BitBake
- is doing and the reason behind it.
- Each <filename>-D</filename> option you use increases the logging level.
- The most common usage is <filename>-DDD</filename>.
- </para>
-
- <para>
- The output from <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable> can reveal why
- BitBake chose a certain version of a package or why BitBake
- picked a certain provider.
- This command could also help you in a situation where you think BitBake did something
- unexpected.
- </para>
- </section>
-
- <section id='development-host-system-issues'>
- <title>Development Host System Issues</title>
-
- <para>
- Sometimes issues on the host development system can cause your
- build to fail.
- Following are known, host-specific problems.
- Be sure to always consult the
- <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
- for a look at all release-related issues.
- <itemizedlist>
- <listitem><para><emphasis><filename>glibc-initial</filename> fails to build</emphasis>:
- If your development host system has the unpatched
- <filename>GNU Make 3.82</filename>,
- the
- <link linkend='ref-tasks-install'><filename>do_install</filename></link>
- task fails for <filename>glibc-initial</filename> during
- the build.</para>
- <para>Typically, every distribution that ships
- <filename>GNU Make 3.82</filename> as
- the default already has the patched version.
- However, some distributions, such as Debian, have
- <filename>GNU Make 3.82</filename> as an option, which
- is unpatched.
- You will see this error on these types of distributions.
- Switch to <filename>GNU Make 3.81</filename> or patch
- your <filename>make</filename> to solve the problem.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='usingpoky-debugging-buildfile'>
- <title>Building with No Dependencies</title>
- <para>
- To build a specific recipe (<filename>.bb</filename> file),
- you can use the following command form:
- <literallayout class='monospaced'>
- $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
- </literallayout>
- This command form does not check for dependencies.
- Consequently, you should use it
- only when you know existing dependencies have been met.
- <note>
- You can also specify fragments of the filename.
- In this case, BitBake checks for a unique match.
- </note>
- </para>
- </section>
-
- <section id='recipe-logging-mechanisms'>
- <title>Recipe Logging Mechanisms</title>
- <para>
- The Yocto Project provides several logging functions for producing
- debugging output and reporting errors and warnings.
- For Python functions, the following logging functions exist.
- All of these functions log to
- <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
- and can also log to standard output (stdout) with the right
- settings:
- <itemizedlist>
- <listitem><para>
- <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
- Writes <replaceable>msg</replaceable> as is to the log while
- also logging to stdout.
- </para></listitem>
- <listitem><para>
- <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
- Writes "NOTE: <replaceable>msg</replaceable>" to the log.
- Also logs to stdout if BitBake is called with "-v".
- </para></listitem>
- <listitem><para>
- <filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>:
- Writes "DEBUG: <replaceable>msg</replaceable>" to the log.
- Also logs to stdout if the log level is greater than or
- equal to <replaceable>level</replaceable>.
- See the
- "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
- option in the BitBake User Manual for more information.
- </para></listitem>
- <listitem><para>
- <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
- Writes "WARNING: <replaceable>msg</replaceable>" to the log
- while also logging to stdout.
- </para></listitem>
- <listitem><para>
- <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
- Writes "ERROR: <replaceable>msg</replaceable>" to the log
- while also logging to stdout.
- <note>
- Calling this function does not cause the task to fail.
- </note>
- </para></listitem>
- <listitem><para>
- <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
- This logging function is similar to
- <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
- but also causes the calling task to fail.
- <note>
- <filename>bb.fatal()</filename> raises an exception,
- which means you do not need to put a "return"
- statement after the function.
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- The same logging functions are also available in shell functions,
- under the names
- <filename>bbplain</filename>, <filename>bbnote</filename>,
- <filename>bbdebug</filename>, <filename>bbwarn</filename>,
- <filename>bberror</filename>, and <filename>bbfatal</filename>.
- The
- <link linkend='ref-classes-logging'><filename>logging</filename></link>
- class implements these functions.
- See that class in the
- <filename>meta/classes</filename> folder of the
- <link linkend='source-directory'>Source Directory</link>
- for information.
- </para>
-
- <section id='logging-with-python'>
- <title>Logging With Python</title>
- <para>
- When creating recipes using Python and inserting code that handles build logs,
- keep in mind the goal is to have informative logs while keeping the console as
- "silent" as possible.
- Also, if you want status messages in the log, use the "debug" loglevel.
- </para>
-
- <para>
- Following is an example written in Python.
- The code handles logging for a function that determines the
- number of tasks needed to be run.
- See the
- "<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>"
- section for additional information:
- <literallayout class='monospaced'>
- python do_listtasks() {
- bb.debug(2, "Starting to figure out the task list")
- if noteworthy_condition:
- bb.note("There are 47 tasks to run")
- bb.debug(2, "Got to point xyz")
- if warning_trigger:
- bb.warn("Detected warning_trigger, this might be a problem later.")
- if recoverable_error:
- bb.error("Hit recoverable_error, you really need to fix this!")
- if fatal_error:
- bb.fatal("fatal_error detected, unable to print the task list")
- bb.plain("The tasks present are abc")
- bb.debug(2, "Finished figuring out the tasklist")
- }
- </literallayout>
- </para>
- </section>
-
- <section id='logging-with-bash'>
- <title>Logging With Bash</title>
- <para>
- When creating recipes using Bash and inserting code that handles build
- logs, you have the same goals - informative with minimal console output.
- The syntax you use for recipes written in Bash is similar to that of
- recipes written in Python described in the previous section.
- </para>
-
- <para>
- Following is an example written in Bash.
- The code logs the progress of the <filename>do_my_function</filename> function.
- <literallayout class='monospaced'>
- do_my_function() {
- bbdebug 2 "Running do_my_function"
- if [ exceptional_condition ]; then
- bbnote "Hit exceptional_condition"
- fi
- bbdebug 2 "Got to point xyz"
- if [ warning_trigger ]; then
- bbwarn "Detected warning_trigger, this might cause a problem later."
- fi
- if [ recoverable_error ]; then
- bberror "Hit recoverable_error, correcting"
- fi
- if [ fatal_error ]; then
- bbfatal "fatal_error detected"
- fi
- bbdebug 2 "Completed do_my_function"
- }
- </literallayout>
- </para>
- </section>
- </section>
-
- <section id='usingpoky-debugging-others'>
- <title>Other Tips</title>
-
- <para>
- Here are some other tips that you might find useful:
- <itemizedlist>
- <listitem><para>
- When adding new packages, it is worth watching for
- undesirable items making their way into compiler command
- lines.
- For example, you do not want references to local system
- files like
- <filename>/usr/lib/</filename> or
- <filename>/usr/include/</filename>.
- </para></listitem>
- <listitem><para>
- If you want to remove the <filename>psplash</filename>
- boot splashscreen,
- add <filename>psplash=false</filename> to the kernel
- command line.
- Doing so prevents <filename>psplash</filename> from loading
- and thus allows you to see the console.
- It is also possible to switch out of the splashscreen by
- switching the virtual console (e.g. Fn+Left or Fn+Right
- on a Zaurus).
- </para></listitem>
- <listitem><para>
- Removing
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
- (usually <filename>tmp/</filename>, within the
- <link linkend='build-directory'>Build Directory</link>)
- can often fix temporary build issues.
- Removing <filename>TMPDIR</filename> is usually a
- relatively cheap operation, because task output will be
- cached in
- <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
- (usually <filename>sstate-cache/</filename>, which is
- also in the Build Directory).
- <note>
- Removing <filename>TMPDIR</filename> might be a
- workaround rather than a fix.
- Consequently, trying to determine the underlying cause
- of an issue before removing the directory is a good
- idea.
- </note>
- </para></listitem>
- <listitem><para>
- Understanding how a feature is used in practice within
- existing recipes can be very helpful.
- It is recommended that you configure some method that
- allows you to quickly search through files.</para>
-
- <para>Using GNU Grep, you can use the following shell
- function to recursively search through common
- recipe-related files, skipping binary files,
- <filename>.git</filename> directories, and the
- Build Directory (assuming its name starts with
- "build"):
- <literallayout class='monospaced'>
- g() {
- grep -Ir \
- --exclude-dir=.git \
- --exclude-dir='build*' \
- --include='*.bb*' \
- --include='*.inc*' \
- --include='*.conf*' \
- --include='*.py*' \
- "$@"
- }
- </literallayout>
- Following are some usage examples:
- <literallayout class='monospaced'>
- $ g FOO # Search recursively for "FOO"
- $ g -i foo # Search recursively for "foo", ignoring case
- $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"
- </literallayout>
- If figuring out how some feature works requires a lot of
- searching, it might indicate that the documentation should
- be extended or improved.
- In such cases, consider filing a documentation bug using
- the Yocto Project implementation of
- <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
- For general information on how to submit a bug against
- the Yocto Project, see the Yocto Project Bugzilla
- <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>"
- or the
- <ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
- section, which is in the Yocto Project Development Tasks
- Manual.
- <note>
- The manuals might not be the right place to document
- variables that are purely internal and have a limited
- scope (e.g. internal variables used to implement a
- single <filename>.bbclass</filename> file).
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
-
-<section id='ref-quick-emulator-qemu'>
- <title>Quick EMUlator (QEMU)</title>
-
- <para>
- The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
- Open Source project as part of the Yocto Project development "tool
- set".
- </para>
-
- <para>
- Within the context of the Yocto Project, QEMU is an
- emulator and virtualization machine that allows you to run a complete
- image you have built using the Yocto Project as just another task
- on your build system.
- QEMU is useful for running and testing images and applications on
- supported Yocto Project architectures without having actual hardware.
- Among other things, the Yocto Project uses QEMU to run automated
- Quality Assurance (QA) tests on final images shipped with each
- release.
- <note>
- This implementation is not the same as QEMU in general.
- </note>
- This section provides a brief reference for the Yocto Project
- implementation of QEMU.
- </para>
-
- <para>
- For official information and documentation on QEMU in general, see the
- following references:
- <itemizedlist>
- <listitem><para>
- <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
- The official website for the QEMU Open Source project.
- </para></listitem>
- <listitem><para>
- <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
- The QEMU user manual.
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- For information on how to use the Yocto Project implementation of
- QEMU, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
- chapter in the Yocto Project Development Tasks Manual.
- </para>
-
- <section id='qemu-availability'>
- <title>QEMU Availability</title>
-
- <para>
- QEMU is made available with the Yocto Project a number of ways.
- One method is to install a Software Development Kit (SDK).
- For more information on how to make sure you have
- QEMU available, see
- "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
- section in the Yocto Project Application Development and the
- Extensible Software Development Kit (eSDK) manual.
- </para>
- </section>
-
- <section id='qemu-performance'>
- <title>QEMU Performance</title>
-
- <para>
- Using QEMU to emulate your hardware can result in speed issues
- depending on the target and host architecture mix.
- For example, using the <filename>qemux86</filename> image in the
- emulator on an Intel-based 32-bit (x86) host machine is fast
- because the target and host architectures match.
- On the other hand, using the <filename>qemuarm</filename> image
- on the same Intel-based host can be slower.
- But, you still achieve faithful emulation of ARM-specific issues.
- </para>
-
- <para>
- To speed things up, the QEMU images support using
- <filename>distcc</filename> to call a cross-compiler outside the
- emulated system.
- If you used <filename>runqemu</filename> to start QEMU, and the
- <filename>distccd</filename> application is present on the host
- system, any BitBake cross-compiling toolchain available from the
- build system is automatically used from within QEMU simply by
- calling <filename>distcc</filename>.
- You can accomplish this by defining the cross-compiler variable
- (e.g. <filename>export CC="distcc"</filename>).
- Alternatively, if you are using a suitable SDK image or the
- appropriate stand-alone toolchain is present, the toolchain is
- also automatically used.
- </para>
-
- <note>
- Several mechanisms exist that let you connect to the system
- running on the QEMU emulator:
- <itemizedlist>
- <listitem><para>
- QEMU provides a framebuffer interface that makes standard
- consoles available.
- </para></listitem>
- <listitem><para>
- Generally, headless embedded devices have a serial port.
- If so, you can configure the operating system of the
- running image to use that port to run a console.
- The connection uses standard IP networking.
- </para></listitem>
- <listitem><para>
- SSH servers exist in some QEMU images.
- The <filename>core-image-sato</filename> QEMU image has a
- Dropbear secure shell (SSH) server that runs with the root
- password disabled.
- The <filename>core-image-full-cmdline</filename> and
- <filename>core-image-lsb</filename> QEMU images
- have OpenSSH instead of Dropbear.
- Including these SSH servers allow you to use standard
- <filename>ssh</filename> and <filename>scp</filename>
- commands.
- The <filename>core-image-minimal</filename> QEMU image,
- however, contains no SSH server.
- </para></listitem>
- <listitem><para>
- You can use a provided, user-space NFS server to boot
- the QEMU session using a local copy of the root
- filesystem on the host.
- In order to make this connection, you must extract a
- root filesystem tarball by using the
- <filename>runqemu-extract-sdk</filename> command.
- After running the command, you must then point the
- <filename>runqemu</filename>
- script to the extracted directory instead of a root
- filesystem image file.
- See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</ulink>"
- section in the Yocto Project Development Tasks Manual for
- more information.
- </para></listitem>
- </itemizedlist>
- </note>
- </section>
-
- <section id='qemu-command-line-syntax'>
- <title>QEMU Command-Line Syntax</title>
-
- <para>
- The basic <filename>runqemu</filename> command syntax is as
- follows:
- <literallayout class='monospaced'>
- $ runqemu [<replaceable>option</replaceable> ] [...]
- </literallayout>
- Based on what you provide on the command line,
- <filename>runqemu</filename> does a good job of figuring out what
- you are trying to do.
- For example, by default, QEMU looks for the most recently built
- image according to the timestamp when it needs to look for an
- image.
- Minimally, through the use of options, you must provide either
- a machine name, a virtual machine image
- (<filename>*wic.vmdk</filename>), or a kernel image
- (<filename>*.bin</filename>).
- </para>
-
- <para>
- Following is the command-line help output for the
- <filename>runqemu</filename> command:
- <literallayout class='monospaced'>
- $ runqemu --help
-
- Usage: you can run this script with any valid combination
- of the following environment variables (in any order):
- KERNEL - the kernel image file to use
- ROOTFS - the rootfs image file or nfsroot directory to use
- MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
- Simplified QEMU command-line options can be passed with:
- nographic - disable video console
- serial - enable a serial console on /dev/ttyS0
- slirp - enable user networking, no root privileges is required
- kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
- kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
- publicvnc - enable a VNC server open to all hosts
- audio - enable audio
- [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
- tcpserial=<port> - specify tcp serial port number
- biosdir=<dir> - specify custom bios dir
- biosfilename=<filename> - specify bios filename
- qemuparams=<xyz> - specify custom parameters to QEMU
- bootparams=<xyz> - specify custom kernel parameters during boot
- help, -h, --help: print this text
-
- Examples:
- runqemu
- runqemu qemuarm
- runqemu tmp/deploy/images/qemuarm
- runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
- runqemu qemux86-64 core-image-sato ext4
- runqemu qemux86-64 wic-image-minimal wic
- runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
- runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
- runqemu qemux86 qemuparams="-m 256"
- runqemu qemux86 bootparams="psplash=false"
- runqemu path/to/<image>-<machine>.wic
- runqemu path/to/<image>-<machine>.wic.vmdk
- </literallayout>
- </para>
- </section>
-
- <section id='runqemu-command-line-options'>
- <title><filename>runqemu</filename> Command-Line Options</title>
-
- <para>
- Following is a description of <filename>runqemu</filename>
- options you can provide on the command line:
- <note><title>Tip</title>
- If you do provide some "illegal" option combination or perhaps
- you do not provide enough in the way of options,
- <filename>runqemu</filename> provides appropriate error
- messaging to help you correct the problem.
- </note>
- <itemizedlist>
- <listitem><para>
- <replaceable>QEMUARCH</replaceable>:
- The QEMU machine architecture, which must be "qemuarm",
- "qemuarm64", "qemumips", "qemumips64", "qemuppc",
- "qemux86", or "qemux86-64".
- </para></listitem>
- <listitem><para>
- <filename><replaceable>VM</replaceable></filename>:
- The virtual machine image, which must be a
- <filename>.wic.vmdk</filename> file.
- Use this option when you want to boot a
- <filename>.wic.vmdk</filename> image.
- The image filename you provide must contain one of the
- following strings: "qemux86-64", "qemux86", "qemuarm",
- "qemumips64", "qemumips", "qemuppc", or "qemush4".
- </para></listitem>
- <listitem><para>
- <replaceable>ROOTFS</replaceable>:
- A root filesystem that has one of the following
- filetype extensions: "ext2", "ext3", "ext4", "jffs2",
- "nfs", or "btrfs".
- If the filename you provide for this option uses “nfs”, it
- must provide an explicit root filesystem path.
- </para></listitem>
- <listitem><para>
- <replaceable>KERNEL</replaceable>:
- A kernel image, which is a <filename>.bin</filename> file.
- When you provide a <filename>.bin</filename> file,
- <filename>runqemu</filename> detects it and assumes the
- file is a kernel image.
- </para></listitem>
- <listitem><para>
- <replaceable>MACHINE</replaceable>:
- The architecture of the QEMU machine, which must be one
- of the following: "qemux86", "qemux86-64", "qemuarm",
- "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
- The <replaceable>MACHINE</replaceable> and
- <replaceable>QEMUARCH</replaceable> options are basically
- identical.
- If you do not provide a <replaceable>MACHINE</replaceable>
- option, <filename>runqemu</filename> tries to determine
- it based on other options.
- </para></listitem>
- <listitem><para>
- <filename>ramfs</filename>:
- Indicates you are booting an initial RAM disk (initramfs)
- image, which means the <filename>FSTYPE</filename> is
- <filename>cpio.gz</filename>.
- </para></listitem>
- <listitem><para>
- <filename>iso</filename>:
- Indicates you are booting an ISO image, which means the
- <filename>FSTYPE</filename> is
- <filename>.iso</filename>.
- </para></listitem>
- <listitem><para>
- <filename>nographic</filename>:
- Disables the video console, which sets the console to
- "ttys0".
- </para></listitem>
- <listitem><para>
- <filename>serial</filename>:
- Enables a serial console on
- <filename>/dev/ttyS0</filename>.
- </para></listitem>
- <listitem><para>
- <filename>biosdir</filename>:
- Establishes a custom directory for BIOS, VGA BIOS and
- keymaps.
- </para></listitem>
- <listitem><para>
- <filename>biosfilename</filename>:
- Establishes a custom BIOS name.
- </para></listitem>
- <listitem><para>
- <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
- Specifies custom QEMU parameters.
- Use this option to pass options other than the simple
- "kvm" and "serial" options.
- </para></listitem>
- <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
- Specifies custom boot parameters for the kernel.
- </para></listitem>
- <listitem><para>
- <filename>audio</filename>:
- Enables audio in QEMU.
- The <replaceable>MACHINE</replaceable> option must be
- either "qemux86" or "qemux86-64" in order for audio to be
- enabled.
- Additionally, the <filename>snd_intel8x0</filename>
- or <filename>snd_ens1370</filename> driver must be
- installed in linux guest.
- </para></listitem>
- <listitem><para>
- <filename>slirp</filename>:
- Enables "slirp" networking, which is a different way
- of networking that does not need root access
- but also is not as easy to use or comprehensive
- as the default.
- </para></listitem>
- <listitem><para id='kvm-cond'>
- <filename>kvm</filename>:
- Enables KVM when running "qemux86" or "qemux86-64"
- QEMU architectures.
- For KVM to work, all the following conditions must be met:
- <itemizedlist>
- <listitem><para>
- Your <replaceable>MACHINE</replaceable> must be either
-qemux86" or "qemux86-64".
- </para></listitem>
- <listitem><para>
- Your build host has to have the KVM modules
- installed, which are
- <filename>/dev/kvm</filename>.
- </para></listitem>
- <listitem><para>
- The build host <filename>/dev/kvm</filename>
- directory has to be both writable and readable.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <filename>kvm-vhost</filename>:
- Enables KVM with VHOST support when running "qemux86"
- or "qemux86-64" QEMU architectures.
- For KVM with VHOST to work, the following conditions must
- be met:
- <itemizedlist>
- <listitem><para>
- <link linkend='kvm-cond'>kvm</link> option
- conditions must be met.
- </para></listitem>
- <listitem><para>
- Your build host has to have virtio net device, which
- are <filename>/dev/vhost-net</filename>.
- </para></listitem>
- <listitem><para>
- The build host <filename>/dev/vhost-net</filename>
- directory has to be either readable or writable
- and “slirp-enabled”.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <filename>publicvnc</filename>:
- Enables a VNC server open to all hosts.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
-
-<section id='maintaining-build-output-quality'>
- <title>Maintaining Build Output Quality</title>
-
- <para>
- Many factors can influence the quality of a build.
- For example, if you upgrade a recipe to use a new version of an upstream software
- package or you experiment with some new configuration options, subtle changes
- can occur that you might not detect until later.
- Consider the case where your recipe is using a newer version of an upstream package.
- In this case, a new version of a piece of software might introduce an optional
- dependency on another library, which is auto-detected.
- If that library has already been built when the software is building,
- the software will link to the built library and that library will be pulled
- into your image along with the new software even if you did not want the
- library.
- </para>
-
- <para>
- The
- <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
- class exists to help you maintain
- the quality of your build output.
- You can use the class to highlight unexpected and possibly unwanted
- changes in the build output.
- When you enable build history, it records information about the contents of
- each package and image and then commits that information to a local Git
- repository where you can examine the information.
- </para>
-
- <para>
- The remainder of this section describes the following:
- <itemizedlist>
- <listitem><para>How you can enable and disable
- build history</para></listitem>
- <listitem><para>How to understand what the build history contains
- </para></listitem>
- <listitem><para>How to limit the information used for build history
- </para></listitem>
- <listitem><para>How to examine the build history from both a
- command-line and web interface</para></listitem>
- </itemizedlist>
- </para>
-
- <section id='enabling-and-disabling-build-history'>
- <title>Enabling and Disabling Build History</title>
-
- <para>
- Build history is disabled by default.
- To enable it, add the following <filename>INHERIT</filename>
- statement and set the
- <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
- variable to "1" at the end of your
- <filename>conf/local.conf</filename> file found in the
- <link linkend='build-directory'>Build Directory</link>:
- <literallayout class='monospaced'>
- INHERIT += "buildhistory"
- BUILDHISTORY_COMMIT = "1"
- </literallayout>
- Enabling build history as previously described causes the
- OpenEmbedded build system to collect build output information and
- commit it as a single commit to a local
- <link linkend='git'>Git</link> repository.
- <note>
- Enabling build history increases your build times slightly,
- particularly for images, and increases the amount of disk
- space used during the build.
- </note>
- </para>
-
- <para>
- You can disable build history by removing the previous statements
- from your <filename>conf/local.conf</filename> file.
- </para>
- </section>
-
- <section id='understanding-what-the-build-history-contains'>
- <title>Understanding What the Build History Contains</title>
-
- <para>
- Build history information is kept in
- <filename>${</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>}/buildhistory</filename>
- in the Build Directory as defined by the
- <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
- variable.
- The following is an example abbreviated listing:
- <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
- </para>
-
- <para>
- At the top level, there is a <filename>metadata-revs</filename> file
- that lists the revisions of the repositories for the layers enabled
- when the build was produced.
- The rest of the data splits into separate
- <filename>packages</filename>, <filename>images</filename> and
- <filename>sdk</filename> directories, the contents of which are
- described below.
- </para>
-
- <section id='build-history-package-information'>
- <title>Build History Package Information</title>
-
- <para>
- The history for each package contains a text file that has
- name-value pairs with information about the package.
- For example, <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename>
- contains the following:
- <literallayout class='monospaced'>
- PV = 1.22.1
- PR = r32
- RPROVIDES =
- RDEPENDS = glibc (>= 2.20) update-alternatives-opkg
- RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d
- PKGSIZE = 540168
- FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \
- /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \
- /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \
- /usr/share/pixmaps /usr/share/applications /usr/share/idl \
- /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
- FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \
- /etc/busybox.links.nosuid /etc/busybox.links.suid
- </literallayout>
- Most of these name-value pairs correspond to variables used
- to produce the package.
- The exceptions are <filename>FILELIST</filename>, which is the
- actual list of files in the package, and
- <filename>PKGSIZE</filename>, which is the total size of files
- in the package in bytes.
- </para>
-
- <para>
- There is also a file corresponding to the recipe from which the
- package came (e.g.
- <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>):
- <literallayout class='monospaced'>
- PV = 1.22.1
- PR = r32
- DEPENDS = initscripts kern-tools-native update-rc.d-native \
- virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \
- virtual/libc virtual/update-alternatives
- PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \
- busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \
- busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
- </literallayout>
- </para>
-
- <para>
- Finally, for those recipes fetched from a version control
- system (e.g., Git), a file exists that lists source revisions
- that are specified in the recipe and lists the actual revisions
- used during the build.
- Listed and actual revisions might differ when
- <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
- is set to
- <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
- Here is an example assuming
- <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>):
- <literallayout class='monospaced'>
- # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
- SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
- # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
- SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
- </literallayout>
- You can use the <filename>buildhistory-collect-srcrevs</filename>
- command with the <filename>-a</filename> option to
- collect the stored <filename>SRCREV</filename> values
- from build history and report them in a format suitable for
- use in global configuration (e.g.,
- <filename>local.conf</filename> or a distro include file) to
- override floating <filename>AUTOREV</filename> values to a
- fixed set of revisions.
- Here is some example output from this command:
- <literallayout class='monospaced'>
- $ buildhistory-collect-srcrevs -a
- # i586-poky-linux
- SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"
- SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"
- SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"
- SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
- # x86_64-linux
- SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa"
- SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"
- SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11"
- SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"
- SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"
- SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"
- SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a"
- SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff"
- SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
- # qemux86-poky-linux
- SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
- SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"
- # all-poky-linux
- SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"
- </literallayout>
- <note>
- Here are some notes on using the
- <filename>buildhistory-collect-srcrevs</filename> command:
- <itemizedlist>
- <listitem><para>By default, only values where the
- <filename>SRCREV</filename> was
- not hardcoded (usually when <filename>AUTOREV</filename>
- was used) are reported.
- Use the <filename>-a</filename> option to see all
- <filename>SRCREV</filename> values.
- </para></listitem>
- <listitem><para>The output statements might not have any effect
- if overrides are applied elsewhere in the build system
- configuration.
- Use the <filename>-f</filename> option to add the
- <filename>forcevariable</filename> override to each output line
- if you need to work around this restriction.
- </para></listitem>
- <listitem><para>The script does apply special handling when
- building for multiple machines.
- However, the script does place a
- comment before each set of values that specifies
- which triplet to which they belong as shown above
- (e.g., <filename>i586-poky-linux</filename>).
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
- </section>
-
- <section id='build-history-image-information'>
- <title>Build History Image Information</title>
-
- <para>
- The files produced for each image are as follows:
- <itemizedlist>
- <listitem><para><filename>image-files:</filename>
- A directory containing selected files from the root
- filesystem.
- The files are defined by
- <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>.
- </para></listitem>
- <listitem><para><filename>build-id.txt:</filename>
- Human-readable information about the build configuration
- and metadata source revisions.
- This file contains the full build header as printed
- by BitBake.</para></listitem>
- <listitem><para><filename>*.dot:</filename>
- Dependency graphs for the image that are
- compatible with <filename>graphviz</filename>.
- </para></listitem>
- <listitem><para><filename>files-in-image.txt:</filename>
- A list of files in the image with permissions,
- owner, group, size, and symlink information.
- </para></listitem>
- <listitem><para><filename>image-info.txt:</filename>
- A text file containing name-value pairs with information
- about the image.
- See the following listing example for more information.
- </para></listitem>
- <listitem><para><filename>installed-package-names.txt:</filename>
- A list of installed packages by name only.</para></listitem>
- <listitem><para><filename>installed-package-sizes.txt:</filename>
- A list of installed packages ordered by size.
- </para></listitem>
- <listitem><para><filename>installed-packages.txt:</filename>
- A list of installed packages with full package
- filenames.</para></listitem>
- </itemizedlist>
- <note>
- Installed package information is able to be gathered and
- produced even if package management is disabled for the final
- image.
- </note>
- </para>
-
- <para>
- Here is an example of <filename>image-info.txt</filename>:
- <literallayout class='monospaced'>
- DISTRO = poky
- DISTRO_VERSION = 1.7
- USER_CLASSES = buildstats image-mklibs image-prelink
- IMAGE_CLASSES = image_types
- IMAGE_FEATURES = debug-tweaks
- IMAGE_LINGUAS =
- IMAGE_INSTALL = packagegroup-core-boot run-postinsts
- BAD_RECOMMENDATIONS =
- NO_RECOMMENDATIONS =
- PACKAGE_EXCLUDE =
- ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \
- write_image_manifest ; buildhistory_list_installed_image ; \
- buildhistory_get_image_installed ; ssh_allow_empty_password; \
- postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;
- IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
- IMAGESIZE = 6900
- </literallayout>
- Other than <filename>IMAGESIZE</filename>, which is the
- total size of the files in the image in Kbytes, the
- name-value pairs are variables that may have influenced the
- content of the image.
- This information is often useful when you are trying to determine
- why a change in the package or file listings has occurred.
- </para>
- </section>
-
- <section id='using-build-history-to-gather-image-information-only'>
- <title>Using Build History to Gather Image Information Only</title>
-
- <para>
- As you can see, build history produces image information,
- including dependency graphs, so you can see why something
- was pulled into the image.
- If you are just interested in this information and not
- interested in collecting specific package or SDK information,
- you can enable writing only image information without
- any history by adding the following to your
- <filename>conf/local.conf</filename> file found in the
- <link linkend='build-directory'>Build Directory</link>:
- <literallayout class='monospaced'>
- INHERIT += "buildhistory"
- BUILDHISTORY_COMMIT = "0"
- BUILDHISTORY_FEATURES = "image"
- </literallayout>
- Here, you set the
- <link linkend='var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></link>
- variable to use the image feature only.
- </para>
- </section>
-
- <section id='build-history-sdk-information'>
- <title>Build History SDK Information</title>
-
- <para>
- Build history collects similar information on the contents
- of SDKs
- (e.g. <filename>bitbake -c populate_sdk imagename</filename>)
- as compared to information it collects for images.
- Furthermore, this information differs depending on whether an
- extensible or standard SDK is being produced.
- </para>
-
- <para>
- The following list shows the files produced for SDKs:
- <itemizedlist>
- <listitem><para><filename>files-in-sdk.txt:</filename>
- A list of files in the SDK with permissions,
- owner, group, size, and symlink information.
- This list includes both the host and target parts
- of the SDK.
- </para></listitem>
- <listitem><para><filename>sdk-info.txt:</filename>
- A text file containing name-value pairs with information
- about the SDK.
- See the following listing example for more information.
- </para></listitem>
- <listitem><para><filename>sstate-task-sizes.txt:</filename>
- A text file containing name-value pairs with information
- about task group sizes
- (e.g. <filename>do_populate_sysroot</filename> tasks
- have a total size).
- The <filename>sstate-task-sizes.txt</filename> file
- exists only when an extensible SDK is created.
- </para></listitem>
- <listitem><para><filename>sstate-package-sizes.txt:</filename>
- A text file containing name-value pairs with information
- for the shared-state packages and sizes in the SDK.
- The <filename>sstate-package-sizes.txt</filename> file
- exists only when an extensible SDK is created.
- </para></listitem>
- <listitem><para><filename>sdk-files:</filename>
- A folder that contains copies of the files mentioned in
- <filename>BUILDHISTORY_SDK_FILES</filename> if the
- files are present in the output.
- Additionally, the default value of
- <filename>BUILDHISTORY_SDK_FILES</filename> is specific
- to the extensible SDK although you can set it
- differently if you would like to pull in specific files
- from the standard SDK.</para>
- <para>The default files are
- <filename>conf/local.conf</filename>,
- <filename>conf/bblayers.conf</filename>,
- <filename>conf/auto.conf</filename>,
- <filename>conf/locked-sigs.inc</filename>, and
- <filename>conf/devtool.conf</filename>.
- Thus, for an extensible SDK, these files get copied
- into the <filename>sdk-files</filename> directory.
- </para></listitem>
- <listitem><para>The following information appears under
- each of the <filename>host</filename>
- and <filename>target</filename> directories
- for the portions of the SDK that run on the host and
- on the target, respectively:
- <note>
- The following files for the most part are empty
- when producing an extensible SDK because this
- type of SDK is not constructed from packages as is
- the standard SDK.
- </note>
- <itemizedlist>
- <listitem><para><filename>depends.dot:</filename>
- Dependency graph for the SDK that is
- compatible with <filename>graphviz</filename>.
- </para></listitem>
- <listitem><para><filename>installed-package-names.txt:</filename>
- A list of installed packages by name only.
- </para></listitem>
- <listitem><para><filename>installed-package-sizes.txt:</filename>
- A list of installed packages ordered by size.
- </para></listitem>
- <listitem><para><filename>installed-packages.txt:</filename>
- A list of installed packages with full package
- filenames.</para></listitem>
- </itemizedlist>
- </para></listitem>
- </itemizedlist>
- </para>
-
- <para>
- Here is an example of <filename>sdk-info.txt</filename>:
- <literallayout class='monospaced'>
- DISTRO = poky
- DISTRO_VERSION = 1.3+snapshot-20130327
- SDK_NAME = poky-glibc-i686-arm
- SDK_VERSION = 1.3+snapshot
- SDKMACHINE =
- SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
- BAD_RECOMMENDATIONS =
- SDKSIZE = 352712
- </literallayout>
- Other than <filename>SDKSIZE</filename>, which is the
- total size of the files in the SDK in Kbytes, the
- name-value pairs are variables that might have influenced the
- content of the SDK.
- This information is often useful when you are trying to
- determine why a change in the package or file listings
- has occurred.
- </para>
- </section>
-
- <section id='examining-build-history-information'>
- <title>Examining Build History Information</title>
-
- <para>
- You can examine build history output from the command line or
- from a web interface.
- </para>
-
- <para>
- To see any changes that have occurred (assuming you have
- <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT = "1"</filename></link>),
- you can simply
- use any Git command that allows you to view the history of
- a repository.
- Here is one method:
- <literallayout class='monospaced'>
- $ git log -p
- </literallayout>
- You need to realize, however, that this method does show
- changes that are not significant (e.g. a package's size
- changing by a few bytes).
- </para>
-
- <para>
- A command-line tool called <filename>buildhistory-diff</filename>
- does exist, though, that queries the Git repository and prints just
- the differences that might be significant in human-readable form.
- Here is an example:
- <literallayout class='monospaced'>
- $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
- Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt):
- /etc/anotherpkg.conf was added
- /sbin/anotherpkg was added
- * (installed-package-names.txt):
- * anotherpkg was added
- Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt):
- anotherpkg was added
- packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
- * PR changed from "r0" to "r1"
- * PV changed from "0.1.10" to "0.1.12"
- packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
- * PR changed from "r0" to "r1"
- * PV changed from "0.1.10" to "0.1.12"
- </literallayout>
- <note>
- The <filename>buildhistory-diff</filename> tool requires
- the <filename>GitPython</filename> package.
- Be sure to install it using Pip3 as follows:
- <literallayout class='monospaced'>
- $ pip3 install GitPython --user
- </literallayout>
- Alternatively, you can install
- <filename>python3-git</filename> using the appropriate
- distribution package manager (e.g.
- <filename>apt-get</filename>, <filename>dnf</filename>, or
- <filename>zipper</filename>).
- </note>
- </para>
-
- <para>
- To see changes to the build history using a web interface, follow
- the instruction in the <filename>README</filename> file here.
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
- </para>
-
- <para>
- Here is a sample screenshot of the interface:
- <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
- </para>
- </section>
- </section>
-</section>
-
-<section id='speeding-up-the-build'>
- <title>Speeding Up the Build</title>
-
- <para>
- Build time can be an issue.
- By default, the build system uses simple controls to try and maximize
- build efficiency.
- In general, the default settings for all the following variables
- result in the most efficient build times when dealing with single
- socket systems (i.e. a single CPU).
- If you have multiple CPUs, you might try increasing the default
- values to gain more speed.
- See the descriptions in the glossary for each variable for more
- information:
- <itemizedlist>
- <listitem><para>
- <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</link>
- The maximum number of threads BitBake simultaneously executes.
- </para></listitem>
- <listitem><para>
- <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
- The number of threads BitBake uses during parsing.
- </para></listitem>
- <listitem><para>
- <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</link>
- Extra options passed to the <filename>make</filename> command
- during the
- <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
- task in order to specify parallel compilation on the
- local build host.
- </para></listitem>
- <listitem><para>
- <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</link>
- Extra options passed to the <filename>make</filename> command
- during the
- <link linkend='ref-tasks-install'><filename>do_install</filename></link>
- task in order to specify parallel installation on the
- local build host.
- </para></listitem>
- </itemizedlist>
- As mentioned, these variables all scale to the number of processor
- cores available on the build system.
- For single socket systems, this auto-scaling ensures that the build
- system fundamentally takes advantage of potential parallel operations
- during the build based on the build machine's capabilities.
- </para>
-
- <para>
- Following are additional factors that can affect build speed:
- <itemizedlist>
- <listitem><para>
- File system type:
- The file system type that the build is being performed on can
- also influence performance.
- Using <filename>ext4</filename> is recommended as compared
- to <filename>ext2</filename> and <filename>ext3</filename>
- due to <filename>ext4</filename> improved features
- such as extents.
- </para></listitem>
- <listitem><para>
- Disabling the updating of access time using
- <filename>noatime</filename>:
- The <filename>noatime</filename> mount option prevents the
- build system from updating file and directory access times.
- </para></listitem>
- <listitem><para>
- Setting a longer commit:
- Using the "commit=" mount option increases the interval
- in seconds between disk cache writes.
- Changing this interval from the five second default to
- something longer increases the risk of data loss but decreases
- the need to write to the disk, thus increasing the build
- performance.
- </para></listitem>
- <listitem><para>
- Choosing the packaging backend:
- Of the available packaging backends, IPK is the fastest.
- Additionally, selecting a singular packaging backend also
- helps.
- </para></listitem>
- <listitem><para>
- Using <filename>tmpfs</filename> for
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
- as a temporary file system:
- While this can help speed up the build, the benefits are
- limited due to the compiler using
- <filename>-pipe</filename>.
- The build system goes to some lengths to avoid
- <filename>sync()</filename> calls into the
- file system on the principle that if there was a significant
- failure, the
- <link linkend='build-directory'>Build Directory</link>
- contents could easily be rebuilt.
- </para></listitem>
- <listitem><para>
- Inheriting the
- <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link>
- class:
- Inheriting this class has shown to speed up builds due to
- significantly lower amounts of data stored in the data
- cache as well as on disk.
- Inheriting this class also makes cleanup of
- <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
- faster, at the expense of being easily able to dive into the
- source code.
- File system maintainers have recommended that the fastest way
- to clean up large numbers of files is to reformat partitions
- rather than delete files due to the linear nature of partitions.
- This, of course, assumes you structure the disk partitions and
- file systems in a way that this is practical.
- </para></listitem>
- </itemizedlist>
- Aside from the previous list, you should keep some trade offs in
- mind that can help you speed up the build:
- <itemizedlist>
- <listitem><para>
- Remove items from
- <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
- that you might not need.
- </para></listitem>
- <listitem><para>
- Exclude debug symbols and other debug information:
- If you do not need these symbols and other debug information,
- disabling the <filename>*-dbg</filename> package generation
- can speed up the build.
- You can disable this generation by setting the
- <link linkend='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></link>
- variable to "1".
- </para></listitem>
- <listitem><para>
- Disable static library generation for recipes derived from
- <filename>autoconf</filename> or <filename>libtool</filename>:
- Following is an example showing how to disable static
- libraries and still provide an override to handle exceptions:
- <literallayout class='monospaced'>
- STATICLIBCONF = "--disable-static"
- STATICLIBCONF_sqlite3-native = ""
- EXTRA_OECONF += "${STATICLIBCONF}"
- </literallayout>
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- Some recipes need static libraries in order to work
- correctly (e.g. <filename>pseudo-native</filename>
- needs <filename>sqlite3-native</filename>).
- Overrides, as in the previous example, account for
- these kinds of exceptions.
- </para></listitem>
- <listitem><para>
- Some packages have packaging code that assumes the
- presence of the static libraries.
- If so, you might need to exclude them as well.
- </para></listitem>
- </itemizedlist>
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
-</section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png
new file mode 100644
index 0000000..ec6685f
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-autotools-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
index 985ac33..e7d6173 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png
index fd684ff..18ba8b7 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
index 65474da..7d4f395 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png
new file mode 100644
index 0000000..0ccb418
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-makefile-flow.png
Binary files differ
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml
index 587526f..5b56e73 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -387,8 +387,9 @@
have set <filename>SDK_EXT_TYPE</filename> to
"minimal", which by default, excludes the toolchain.
Also, it is helpful if you are building a small SDK for use with
- an IDE, such as Eclipse, or some other tool where you do not want
- to take extra steps to install a toolchain.
+ an IDE, such as <trademark class='trade'>Eclipse</trademark>, or some
+ other tool where you do not want to take extra steps to install a
+ toolchain.
</para>
</section>
</appendix>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-neon.xml
similarity index 89%
rename from import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml
rename to import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-neon.xml
index 2d80f64..f648047 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-neon.xml
@@ -2,14 +2,14 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-<appendix id='sdk-appendix-latest-yp-eclipse-plug-in'>
- <title>Using Eclipse Mars</title>
+<appendix id='sdk-appendix-neon-yp-eclipse-plug-in'>
+ <title>Using <trademark class='trade'>Eclipse</trademark> Neon</title>
<para>
- This release of the Yocto Project supports both the Neon and Mars
+ This release of the Yocto Project supports both the Oxygen and Neon
versions of the Eclipse IDE.
This appendix presents information that describes how to obtain and
- configure the Mars version of Eclipse.
+ configure the Neon version of Eclipse.
It also provides a basic project example that you can work through
from start to finish.
For general information on using the Eclipse IDE and the Yocto
@@ -18,13 +18,13 @@
Chapter.
</para>
- <section id='mars-setting-up-the-eclipse-ide'>
- <title>Setting Up the Mars Version of the Eclipse IDE</title>
+ <section id='neon-setting-up-the-eclipse-ide'>
+ <title>Setting Up the Neon Version of the Eclipse IDE</title>
<para>
To develop within the Eclipse IDE, you need to do the following:
<orderedlist>
- <listitem><para>Install the Mars version of the Eclipse
+ <listitem><para>Install the Neon version of the Eclipse
IDE.</para></listitem>
<listitem><para>Configure the Eclipse IDE.
</para></listitem>
@@ -41,65 +41,49 @@
</note>
</para>
- <section id='mars-installing-eclipse-ide'>
- <title>Installing the Mars Eclipse IDE</title>
+ <section id='neon-installing-eclipse-ide'>
+ <title>Installing the Neon Eclipse IDE</title>
<para>
Follow these steps to locate, install, and configure
- Mars Eclipse:
+ Neon Eclipse:
<orderedlist>
- <listitem><para><emphasis>Locate the Mars Download:</emphasis>
+ <listitem><para><emphasis>Locate the Neon Download:</emphasis>
Open a browser and go to
- <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/mars/</ulink>.
+ <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>.
</para></listitem>
<listitem><para><emphasis>Download the Tarball:</emphasis>
- Click the "Download" button and then use the "Linux
- for Eclipse IDE for C++ Developers"
- appropriate for your development system
- (e.g.
- <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/2/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz'>64-bit under Linux for Eclipse IDE for C++ Developers</ulink>
- if your development system is a Linux 64-bit machine.
+ Click the "Download" button and then use the "Eclipse
+ IDE for C/C++ Developers"
+ appropriate for your development system.
</para></listitem>
<listitem><para><emphasis>Unpack the Tarball:</emphasis>
Move to a clean directory and unpack the tarball.
Here is an example:
<literallayout class='monospaced'>
$ cd ~
- $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz
+ $ tar -xzvf ~/Downloads/eclipse-cpp-neon-3-linux-gtk-x86_64.tar.gz
</literallayout>
Everything unpacks into a folder named "Eclipse".
</para></listitem>
<listitem><para><emphasis>Launch Eclipse:</emphasis>
- Double click the "Eclipse" file in the folder to
- launch Eclipse.
- <note>
- If you experience a NullPointer Exception after
- launch Eclipse or the debugger from within Eclipse,
- try adding the following
- to your <filename>eclipse.ini</filename> file,
- which is located in the directory in which you
- unpacked the Eclipse tar file:
- <literallayout class='monospaced'>
- --launcher.GTK_version
- 2
- </literallayout>
- Alternatively, you can export the
- <filename>SWT_GTK</filename> variable in your
- shell as follows:
- <literallayout class='monospaced'>
- $ export SWT_GTK3=0
- </literallayout>
- </note>
+ The following commands launch Eclipse assuming you
+ unpacked it in your home directory:
+ <literallayout class='monospaced'>
+ $ cd ~/eclipse
+ $ ./eclipse
+ </literallayout>
+ Accept the default "workspace" once Eclipse launches.
</para></listitem>
</orderedlist>
</para>
</section>
- <section id='mars-configuring-the-mars-eclipse-ide'>
- <title>Configuring the Mars Eclipse IDE</title>
+ <section id='neon-configuring-the-neon-eclipse-ide'>
+ <title>Configuring the Neon Eclipse IDE</title>
<para>
- Follow these steps to configure the Mars Eclipse IDE.
+ Follow these steps to configure the Neon Eclipse IDE.
<note>
Depending on how you installed Eclipse and what you have
already done, some of the options will not appear.
@@ -114,13 +98,15 @@
the "Help" pull-down menu.
</para></listitem>
<listitem><para>Select
- "Mars - http://download.eclipse.org/releases/mars"
+ "Neon - http://download.eclipse.org/releases/neon"
from the "Work with:" pull-down menu.
</para></listitem>
<listitem><para>Expand the box next to
- "Linux Tools" and select "C/C++ Remote
- (Over TCF/TE) Run/Debug Launcher" and
- "TM Terminal".
+ "Linux Tools" and select the following
+ <literallayout class='monospaced'>
+ C/C++ Remote (Over TCF/TE) Run/Debug Launcher
+ TM Terminal
+ </literallayout>
</para></listitem>
<listitem><para>Expand the box next to "Mobile and
Device Development" and select the following
@@ -135,9 +121,8 @@
</para></listitem>
<listitem><para>Expand the box next to
"Programming Languages" and select the
- following boxes:
+ following box:
<literallayout class='monospaced'>
- C/C++ Autotools Support
C/C++ Development Tools SDK
</literallayout>
</para></listitem>
@@ -149,8 +134,8 @@
</para>
</section>
- <section id='mars-installing-the-eclipse-yocto-plug-in'>
- <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title>
+ <section id='neon-installing-the-eclipse-yocto-plug-in'>
+ <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
<para>
You can install the Eclipse Yocto Plug-in into the Eclipse
@@ -159,11 +144,11 @@
install the plug-in from the latest source code.
</para>
- <section id='mars-new-software'>
+ <section id='neon-new-software'>
<title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
<para>
- To install the Mars Eclipse Yocto Plug-in from the update
+ To install the Neon Eclipse Yocto Plug-in from the update
site, follow these steps:
<orderedlist>
<listitem><para>Start up the Eclipse IDE.
@@ -175,7 +160,7 @@
area.
</para></listitem>
<listitem><para>Enter
- <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename>
+ <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
in the URL field and provide a meaningful name
in the "Name" field.
</para></listitem>
@@ -204,15 +189,15 @@
</para>
</section>
- <section id='mars-zip-file-method'>
+ <section id='neon-zip-file-method'>
<title>Installing the Plug-in Using the Latest Source Code</title>
<para>
- To install the Mars Eclipse Yocto Plug-in from the latest
+ To install the Neon Eclipse Yocto Plug-in from the latest
source code, follow these steps:
<orderedlist>
<listitem><para>Be sure your development system
- has JDK 1.7+
+ has JDK 1.8+
</para></listitem>
<listitem><para>install X11-related packages:
<literallayout class='monospaced'>
@@ -223,15 +208,18 @@
repository with:
<literallayout class='monospaced'>
$ cd ~
- $ git clone git://git.yoctoproject.org/eclipse-poky
+ $ git clone git://git.yoctoproject.org/eclipse-yocto
</literallayout>
</para></listitem>
<listitem><para>Use Git to checkout the correct
tag:
<literallayout class='monospaced'>
- $ cd ~/eclipse-poky
- $ git checkout mars/yocto-&DISTRO;
+ $ cd ~/eclipse-yocto
+ $ git checkout neon/yocto-&DISTRO;
</literallayout>
+ This creates a local tag named
+ <filename>neon/yocto-&DISTRO;</filename> based on
+ the branch <filename>origin/neon-master</filename>.
This puts you in a detached HEAD state, which
is fine since you are only going to be building
and not developing.
@@ -262,10 +250,10 @@
<para>
Following is an example:
<literallayout class='monospaced'>
- $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log
+ $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log
</literallayout>
The previous example command adds the tag you
- need for <filename>mars/yocto-&DISTRO;</filename>
+ need for <filename>neon/yocto-&DISTRO;</filename>
to <filename>HEAD</filename>, then tells the
build script to use the local (-l) Git checkout
for the build.
@@ -316,16 +304,16 @@
<para>
At this point you should be able to configure the
Eclipse Yocto Plug-in as described in the
- "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>"
+ "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
section.</para>
</section>
</section>
- <section id='mars-configuring-the-eclipse-yocto-plug-in'>
- <title>Configuring the Mars Eclipse Yocto Plug-in</title>
+ <section id='neon-configuring-the-eclipse-yocto-plug-in'>
+ <title>Configuring the Neon Eclipse Yocto Plug-in</title>
<para>
- Configuring the Mars Eclipse Yocto Plug-in involves setting the
+ Configuring the Neon Eclipse Yocto Plug-in involves setting the
Cross Compiler options and the Target options.
The configurations you choose become the default settings
for all projects.
@@ -355,7 +343,7 @@
</note>
</para>
- <section id='mars-configuring-the-cross-compiler-options'>
+ <section id='neon-configuring-the-cross-compiler-options'>
<title>Configuring the Cross-Compiler Options</title>
<para>
@@ -467,9 +455,9 @@
If the architecture you need is not listed in
the menu, you will need to build the image.
See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section of the Yocto Project Quick Start for
- more information.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
+ section of the Yocto Project Development Tasks
+ Manual for more information.
You can also see the
<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
</para></listitem>
@@ -477,7 +465,7 @@
</para>
</section>
- <section id='mars-configuring-the-target-options'>
+ <section id='neon-configuring-the-target-options'>
<title>Configuring the Target Options</title>
<para>
@@ -547,7 +535,7 @@
</section>
</section>
- <section id='mars-creating-the-project'>
+ <section id='neon-creating-the-project'>
<title>Creating the Project</title>
<para>
@@ -562,7 +550,7 @@
<note>
Do not use special characters in project names
(e.g. spaces, underscores, etc.). Doing so can
- cause configuration to fail.
+ cause the configuration to fail.
</note>
</para>
@@ -591,7 +579,7 @@
<listitem><para>Click "Finish".
</para></listitem>
<listitem><para>If the "open perspective" prompt appears,
- click "Yes" so that you in the C/C++ perspective.
+ click "Yes" so that you are in the C/C++ perspective.
</para></listitem>
<listitem><para>The left-hand navigation pane shows your
project.
@@ -602,12 +590,12 @@
</para>
</section>
- <section id='mars-configuring-the-cross-toolchains'>
+ <section id='neon-configuring-the-cross-toolchains'>
<title>Configuring the Cross-Toolchains</title>
<para>
The earlier section,
- "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>",
+ "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
sets up the default project configurations.
You can override these settings for a given project by following
these steps:
@@ -621,7 +609,7 @@
Options for a project are inherited from settings you
provided using the Preferences Dialog as described
earlier in the
- "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section.
+ "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.
The Yocto Project Settings Dialog allows you to override
those default settings for a given project.
</para></listitem>
@@ -646,7 +634,7 @@
</para>
</section>
- <section id='mars-building-the-project'>
+ <section id='neon-building-the-project'>
<title>Building the Project</title>
<para>
@@ -691,7 +679,7 @@
</para>
</section>
- <section id='mars-starting-qemu-in-user-space-nfs-mode'>
+ <section id='neon-starting-qemu-in-user-space-nfs-mode'>
<title>Starting QEMU in User-Space NFS Mode</title>
<para>
@@ -761,7 +749,7 @@
</para>
</section>
- <section id='mars-deploying-and-debugging-the-application'>
+ <section id='neon-deploying-and-debugging-the-application'>
<title>Deploying and Debugging the Application</title>
<para>
@@ -845,7 +833,8 @@
which is the default for QEMU x86-64 SDK images provided by
the Yocto Project, in the "Remote Absolute File Path for
C/C++ Application" field, browse to
- <filename>/home/root</filename>.
+ <filename>/home/root/</filename><replaceable>ProjectName</replaceable>
+ (e.g. <filename>/home/root/hello</filename>).
You could also browse to any other path you have write
access to on the target such as
<filename>/usr/bin</filename>.
@@ -893,7 +882,7 @@
</para>
</section>
- <section id='mars-using-Linuxtools'>
+ <section id='neon-using-Linuxtools'>
<title>Using Linuxtools</title>
<para>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml
index ab9055e..aa06358 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -105,7 +105,7 @@
<emphasis>Set Up the Build Environment:</emphasis>
Be sure you are set up to use BitBake in a shell.
See the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
section in the Yocto Project Development Tasks Manual for
information on how to get a build host ready that is either a
native Linux machine or a machine that uses CROPS.
@@ -203,7 +203,7 @@
<listitem><para>
For additional information on building the
installer, see the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an <trademark class='trade'>Eclipse</trademark> Debug Capable Image</ulink>
wiki page.
</para></listitem>
</itemizedlist>
@@ -327,7 +327,7 @@
<para>Following is an example command that extracts the root
filesystem from a previously built root filesystem image that
was downloaded from the
- <ulink url='&YOCTO_DOCS_REF_URL;#index-downloads'>Index of Releases</ulink>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#index-downloads'>Index of Releases</ulink>.
This command extracts the root filesystem into the
<filename>core2-64-sato</filename> directory:
<literallayout class='monospaced'>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
index bdb8344..3eb85e8 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
@@ -19,8 +19,8 @@
<para>
The following figure and supporting list summarize the
- application development general workflow that employs both the
- SDK Eclipse.
+ general workflow for application development that uses the
+ SDK within the Eclipse IDE.
</para>
<para>
@@ -31,9 +31,8 @@
<para>
<orderedlist>
<listitem><para>
- <emphasis>Prepare the host system for the Yocto
- Project</emphasis>:
- See
+ <emphasis>Prepare the Host System for the Yocto Project</emphasis>:
+ See the
"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
and
"<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
@@ -43,8 +42,8 @@
<filename>xterm</filename> package installed.
</para></listitem>
<listitem><para>
- <emphasis>Secure the Yocto Project kernel target
- image</emphasis>:
+ <emphasis>Secure the Yocto Project Kernel Target
+ Image</emphasis>:
You must have a target kernel image that has been built
using the OpenEmbedded build system.</para>
<para>Depending on whether the Yocto Project has a
@@ -66,7 +65,8 @@
<filename>machines/qemu</filename></ulink> if
your target architecture is supported and you
are going to develop and test your application
- using the QEMU emulator.
+ using the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU Emulator</ulink>.
</para></listitem>
<listitem><para>
Build your image if you cannot find a pre-built
@@ -91,8 +91,8 @@
section.
</para></listitem>
<listitem><para>
- <emphasis>Secure the target root filesystem
- and the Cross-development toolchain</emphasis>:
+ <emphasis>Secure the Target Root Filesystem
+ and the Cross-Development Toolchain</emphasis>:
You need to find and download the appropriate root
filesystem and the cross-development toolchain.</para>
<para>You can find the tarballs for the root filesystem
@@ -118,22 +118,19 @@
section.
Another helpful resource for building an installer
is the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>"
wiki page.
</note>
</para></listitem>
<listitem><para>
- <emphasis>Create and build your application</emphasis>:
+ <emphasis>Create and Build Your Application</emphasis>:
At this point, you need to have source files for your
application.
Once you have the files, you can use the Eclipse IDE
to import them and build the project.
- If you are not using Eclipse, you need to use the
- cross-development tools you have installed to create
- the image.</para></listitem>
+ </para></listitem>
<listitem><para>
- <emphasis>Deploy the image with the
- application</emphasis>:
+ <emphasis>Deploy the Image With the Application</emphasis>:
Using the Eclipse IDE, you can deploy your image to the
hardware or to QEMU through the project's preferences.
You can also use Eclipse to load and test your image
@@ -144,7 +141,7 @@
for information on using QEMU.
</para></listitem>
<listitem><para>
- <emphasis>Test and debug the application</emphasis>:
+ <emphasis>Test and Debug the Application</emphasis>:
Once your application is deployed, you need to test it.
Within the Eclipse IDE, you can use the debugging
environment along with supported performance enhancing
@@ -179,25 +176,25 @@
collection of power data, collection of latency data, and
collection of performance data.
<note>
- This release of the Yocto Project supports both the Neon
- and Mars versions of the Eclipse IDE.
- This section provides information on how to use the Neon
+ This release of the Yocto Project supports both the Oxygen
+ and Neon versions of the Eclipse IDE.
+ This section provides information on how to use the Oxygen
release with the Yocto Project.
- For information on how to use the Mars version of Eclipse
+ For information on how to use the Neon version of Eclipse
with the Yocto Project, see
- "<link linkend='sdk-appendix-latest-yp-eclipse-plug-in'>Appendix C</link>.
+ "<link linkend='sdk-appendix-neon-yp-eclipse-plug-in'>Appendix D</link>".
</note>
</para>
- <section id='neon-setting-up-the-eclipse-ide'>
- <title>Setting Up the Neon Version of the Eclipse IDE</title>
+ <section id='oxygen-setting-up-the-eclipse-ide'>
+ <title>Setting Up the Oxygen Version of the Eclipse IDE</title>
<para>
To develop within the Eclipse IDE, you need to do the
following:
<orderedlist>
<listitem><para>
- Install the Neon version of the Eclipse IDE.
+ Install the Oxygen version of the Eclipse IDE.
</para></listitem>
<listitem><para>
Configure the Eclipse IDE.
@@ -217,17 +214,17 @@
</note>
</para>
- <section id='neon-installing-eclipse-ide'>
- <title>Installing the Neon Eclipse IDE</title>
+ <section id='oxygen-installing-eclipse-ide'>
+ <title>Installing the Oxygen Eclipse IDE</title>
<para>
Follow these steps to locate, install, and configure
- Neon Eclipse:
+ Oxygen Eclipse:
<orderedlist>
<listitem><para>
- <emphasis>Locate the Neon Download:</emphasis>
+ <emphasis>Locate the Oxygen Download:</emphasis>
Open a browser and go to
- <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>.
+ <ulink url='http://www.eclipse.org/oxygen/'>http://www.eclipse.org/oxygen/</ulink>.
</para></listitem>
<listitem><para>
<emphasis>Download the Tarball:</emphasis>
@@ -262,36 +259,50 @@
</para></listitem>
<listitem><para>
<emphasis>Install the Software:</emphasis>
- Accept the default "cpp-neon" directory and
- click "Install".
- Accept any license agreements and approve any
- certificates.
+ Click "Install" to begin the installation.
+ Accept all the certificates and any license
+ agreements.
+ Click "Install" again to finish the installation.
</para></listitem>
<listitem><para>
- <emphasis>Launch Neon:</emphasis>
- Click the "Launch" button and accept the
- default "workspace".
+ <emphasis>Launch Oxygen:</emphasis>
+ Accept the default "workspace" and click the
+ "Launch" button.
+ You should see the Eclipse welcome page from which
+ can click "workbench" to enter your workspace.
</para></listitem>
</orderedlist>
</para>
</section>
- <section id='neon-configuring-the-mars-eclipse-ide'>
- <title>Configuring the Neon Eclipse IDE</title>
+ <section id='oxygen-configuring-the-eclipse-ide'>
+ <title>Configuring the Oxygen Eclipse IDE</title>
<para>
- Follow these steps to configure the Neon Eclipse IDE.
- <note>
- Depending on how you installed Eclipse and what
- you have already done, some of the options will
- not appear.
- If you cannot find an option as directed by the
- manual, it has already been installed.
+ Follow these steps to configure the Oxygen Eclipse IDE.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Depending on how you installed Eclipse and what
+ you have already done, some of the options will
+ not appear.
+ If you cannot find an option as directed by the
+ manual, it has already been installed.
+ </para></listitem>
+ <listitem><para>
+ If you want to see all items regardless of
+ whether they are installed or not, deselect the
+ "Hide items that are already installed"
+ check box.
+ </para></listitem>
+ </itemizedlist>
</note>
<orderedlist>
<listitem><para>
Be sure Eclipse is running and you are in your
workbench.
+ Just click "workbench" if you are not in your
+ default workspace.
</para></listitem>
<listitem><para>
Select "Install New Software" from the "Help"
@@ -299,7 +310,7 @@
</para></listitem>
<listitem><para>
Select
- "Neon - http://download.eclipse.org/releases/neon"
+ "Oxygen - http://download.eclipse.org/releases/oxygen"
from the "Work with:" pull-down menu.
</para></listitem>
<listitem><para>
@@ -331,28 +342,29 @@
</para></listitem>
<listitem><para>
Complete the installation by clicking through
- appropriate "Next" and "Finish" buttons.
+ appropriate "Next" and "Finish" buttons and then
+ restart the Eclipse IDE.
</para></listitem>
</orderedlist>
</para>
</section>
- <section id='neon-installing-the-eclipse-yocto-plug-in'>
- <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title>
+ <section id='oxygen-installing-the-eclipse-yocto-plug-in'>
+ <title>Installing or Accessing the Oxygen Eclipse Yocto Plug-in</title>
<para>
You can install the Eclipse Yocto Plug-in into the
Eclipse IDE one of two ways: use the Yocto Project's
- Eclipse Update site to install the pre-built plug-in
+ Eclipse Update site to install the pre-built plug-in,
or build and install the plug-in from the latest
source code.
</para>
- <section id='neon-new-software'>
+ <section id='oxygen-new-software'>
<title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
<para>
- To install the Neon Eclipse Yocto Plug-in from the
+ To install the Oxygen Eclipse Yocto Plug-in from the
update site, follow these steps:
<orderedlist>
<listitem><para>
@@ -367,17 +379,15 @@
</para></listitem>
<listitem><para>
Enter
- <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename>
+ <filename>&ECLIPSE_DL_PLUGIN_URL;/oxygen</filename>
in the URL field and provide a meaningful
name in the "Name" field.
</para></listitem>
<listitem><para>
- Click "OK" to have the entry added
- to the "Work with:" drop-down list.
- </para></listitem>
- <listitem><para>
- Select the entry for the plug-in
- from the "Work with:" drop-down list.
+ Click "OK" to have the entry automatically
+ populate the "Work with:" field and to have
+ the items for installation appear in the window
+ below.
</para></listitem>
<listitem><para>
Check the boxes next to the following:
@@ -401,16 +411,21 @@
</para>
</section>
- <section id='neon-zip-file-method'>
+ <section id='oxygen-zip-file-method'>
<title>Installing the Plug-in Using the Latest Source Code</title>
<para>
- To install the Neon Eclipse Yocto Plug-in from the
+ To install the Oxygen Eclipse Yocto Plug-in from the
latest source code, follow these steps:
<orderedlist>
<listitem><para>
- Be sure your development system
- has JDK 1.8+
+ Be sure your build host has JDK version 1.8
+ or greater.
+ On a Linux build host you can determine the
+ version using the following command:
+ <literallayout class='monospaced'>
+ $ java -version
+ </literallayout>
</para></listitem>
<listitem><para>
Install X11-related packages:
@@ -423,19 +438,19 @@
Git repository with:
<literallayout class='monospaced'>
$ cd ~
- $ git clone git://git.yoctoproject.org/eclipse-poky
+ $ git clone git://git.yoctoproject.org/eclipse-yocto
</literallayout>
</para></listitem>
<listitem><para>
Use Git to create the correct tag:
<literallayout class='monospaced'>
- $ cd ~/eclipse-poky
- $ git checkout neon/yocto-&DISTRO;
+ $ cd ~/eclipse-yocto
+ $ git checkout -b oxygen/&DISTRO_NAME_NO_CAP; remotes/origin/oxygen/&DISTRO_NAME_NO_CAP;
</literallayout>
This creates a local tag named
- <filename>neon/yocto-&DISTRO;</filename>
+ <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename>
based on the branch
- <filename>origin/neon-master</filename>.
+ <filename>origin/oxygen/&DISTRO_NAME_NO_CAP;</filename>.
You are put into a detached HEAD state,
which is fine since you are only going to
be building and not developing.
@@ -469,11 +484,11 @@
<para>
Following is an example:
<literallayout class='monospaced'>
- $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log
+ $ ECLIPSE_HOME=/home/scottrif/eclipse-yocto/scripts/eclipse ./build.sh -l oxygen/&DISTRO_NAME_NO_CAP; master yocto-&DISTRO; 2>&1 | tee build.log
</literallayout>
The previous example command adds the tag
you need for
- <filename>mars/yocto-&DISTRO;</filename>
+ <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename>
to <filename>HEAD</filename>, then tells
the build script to use the local (-l) Git
checkout for the build.
@@ -533,17 +548,17 @@
<para>
At this point you should be able to configure the
Eclipse Yocto Plug-in as described in the
- "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
+ "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>"
section.
</para>
</section>
</section>
- <section id='neon-configuring-the-eclipse-yocto-plug-in'>
- <title>Configuring the Neon Eclipse Yocto Plug-in</title>
+ <section id='oxygen-configuring-the-eclipse-yocto-plug-in'>
+ <title>Configuring the Oxygen Eclipse Yocto Plug-in</title>
<para>
- Configuring the Neon Eclipse Yocto Plug-in involves
+ Configuring the Oxygen Eclipse Yocto Plug-in involves
setting the Cross Compiler options and the Target
options.
The configurations you choose become the default
@@ -555,7 +570,7 @@
<para>
To start, you need to do the following from within the
Eclipse IDE:
- <itemizedlist>
+ <orderedlist>
<listitem><para>
Choose "Preferences" from the "Window" menu to
display the Preferences Dialog.
@@ -564,7 +579,7 @@
Click "Yocto Project SDK" to display
the configuration screen.
</para></listitem>
- </itemizedlist>
+ </orderedlist>
The following sub-sections describe how to configure
the plug-in.
<note>
@@ -572,12 +587,12 @@
example for preparing a QEMU image for use with
Eclipse is referenced as the "wiki" and is linked
to the example on the
- <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+ "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>"
wiki page.
</note>
</para>
- <section id='neon-configuring-the-cross-compiler-options'>
+ <section id='oxygen-configuring-the-cross-compiler-options'>
<title>Configuring the Cross-Compiler Options</title>
<para>
@@ -682,8 +697,7 @@
<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
If so, the
<filename>MY_QEMU_ROOTFS</filename>
- directory is found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ directory is found in the Build Directory
and you would browse to and select that
directory (e.g.
<filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>).
@@ -708,9 +722,9 @@
in the menu, you will need to build the
image.
See the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section of the Yocto Project Quick Start
- for more information.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
+ section of the Yocto Project Development Tasks
+ Manual for more information.
You can also see the
<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
</para></listitem>
@@ -718,7 +732,7 @@
</para>
</section>
- <section id='neon-configuring-the-target-options'>
+ <section id='oxygen-configuring-the-target-options'>
<title>Configuring the Target Options</title>
<para>
@@ -787,14 +801,14 @@
</para>
<para>
- Click the "Apply" and "OK" to save your plug-in
+ Click "Apply and Close" to save your plug-in
configurations.
</para>
</section>
</section>
</section>
- <section id='neon-creating-the-project'>
+ <section id='oxygen-creating-the-project'>
<title>Creating the Project</title>
<para>
@@ -818,20 +832,22 @@
display the source code, follow these steps:
<orderedlist>
<listitem><para>
- Select "C Project" from the "File -> New" menu.
+ Select "C/C++ Project" from the "File -> New" menu.
</para></listitem>
<listitem><para>
- Expand
- <filename>Yocto Project SDK Autotools Project</filename>.
+ Select "C Managed Build" from the available options and
+ click "Next".
</para></listitem>
<listitem><para>
- Select <filename>Hello World ANSI C Autotools Projects</filename>.
+ Expand "Yocto Project SDK Autotools Project".
+ </para></listitem>
+ <listitem><para>
+ Select "Hello World ANSI C Autotools Projects".
This is an Autotools-based project based on a Yocto
template.
</para></listitem>
<listitem><para>
- Put a name in the
- <filename>Project name:</filename> field.
+ Put a name in the "Project name:" field.
Do not use hyphens as part of the name
(e.g. <filename>hello</filename>).
</para></listitem>
@@ -857,12 +873,12 @@
</para>
</section>
- <section id='neon-configuring-the-cross-toolchains'>
+ <section id='oxygen-configuring-the-cross-toolchains'>
<title>Configuring the Cross-Toolchains</title>
<para>
The earlier section,
- "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",
+ "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>",
sets up the default project configurations.
You can override these settings for a given project by
following these steps:
@@ -877,7 +893,7 @@
Target Options for a project are inherited from
settings you provided using the Preferences Dialog
as described earlier in the
- "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"
+ "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>"
section.
The Yocto Project Settings Dialog allows you to
override those default settings for a given
@@ -885,21 +901,15 @@
</para></listitem>
<listitem><para>
Make or verify your configurations for the
- project and click "OK".
+ project and click "Apply and Close".
</para></listitem>
<listitem><para>
- Right-click in the navigation pane and
- select "Reconfigure Project" from the pop-up menu.
+ Right-click in the navigation pane and select
+ "Reconfigure Project" from the pop-up menu.
This selection reconfigures the project by running
- <filename>autogen.sh</filename> in the workspace
- for your project.
- The script also runs
- <filename>libtoolize</filename>,
- <filename>aclocal</filename>,
- <filename>autoconf</filename>,
- <filename>autoheader</filename>,
- <filename>automake --a</filename>, and
- <filename>./configure</filename>.
+ <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>Autotools GNU utility programs</ulink>
+ such as Autoconf, Automake, and so forth in the
+ workspace for your project.
Click on the "Console" tab beneath your source code
to see the results of reconfiguring your project.
</para></listitem>
@@ -907,13 +917,14 @@
</para>
</section>
- <section id='neon-building-the-project'>
+ <section id='oxygen-building-the-project'>
<title>Building the Project</title>
<para>
To build the project select "Build All" from the
"Project" menu.
The console should update and you can note the
- cross-compiler you are using.
+ cross-compiler you are using (i.e.
+ <filename>i586-poky-linux-gcc</filename> in this example).
<note>
When building "Yocto Project SDK Autotools" projects,
the Eclipse IDE might display error messages for
@@ -929,12 +940,12 @@
Select the project.
</para></listitem>
<listitem><para>
- Select "Folder" from the
- <filename>File > New</filename> menu.
+ Select "Folder" from the "File -> New" menu.
</para></listitem>
<listitem><para>
- In the "New Folder" Dialog, select "Link to
- alternate location (linked folder)".
+ In the "New Folder" Dialog, click the "Advanced"
+ button and then activate "Link to
+ alternate location (linked folder)" button.
</para></listitem>
<listitem><para>
Click "Browse" to navigate to the include
@@ -943,9 +954,6 @@
configuration preferences.
</para></listitem>
<listitem><para>
- Click "OK".
- </para></listitem>
- <listitem><para>
Click "Finish" to save the linked folder.
</para></listitem>
</orderedlist>
@@ -953,7 +961,7 @@
</para>
</section>
- <section id='neon-starting-qemu-in-user-space-nfs-mode'>
+ <section id='oxygen-starting-qemu-in-user-space-nfs-mode'>
<title>Starting QEMU in User-Space NFS Mode</title>
<para>
@@ -987,8 +995,8 @@
<filename>rpcbind</filename>, follow the
suggestions to get the service running.
As an example, on a new Ubuntu 16.04 LTS
- installation, you must do the following in
- order to get QEMU to launch:
+ installation, you must do the following in a new
+ shell in order to get QEMU to launch:
<literallayout class='monospaced'>
$ sudo apt-get install rpcbind
</literallayout>
@@ -1032,7 +1040,7 @@
</para>
</section>
- <section id='neon-deploying-and-debugging-the-application'>
+ <section id='oxygen-deploying-and-debugging-the-application'>
<title>Deploying and Debugging the Application</title>
<para>
@@ -1186,7 +1194,7 @@
</para>
</section>
- <section id='neon-using-Linuxtools'>
+ <section id='oxygen-using-Linuxtools'>
<title>Using Linuxtools</title>
<para>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml
index 444d816..5215a9d 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml
@@ -28,7 +28,7 @@
In addition to the functionality available through
<filename>devtool</filename>, you can alternatively make use of the
toolchain directly, for example from Makefile, Autotools, and
- Eclipse-based projects.
+ <trademark class='trade'>Eclipse</trademark>-based projects.
See the
"<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
chapter for more information.
@@ -54,29 +54,29 @@
</para>
</section>
- <section id='sdk-setting-up-to-use-the-extensible-sdk'>
- <title>Setting Up to Use the Extensible SDK</title>
+ <section id='sdk-installing-the-extensible-sdk'>
+ <title>Installing the Extensible SDK</title>
<para>
- The first thing you need to do is install the SDK on your host
- development machine by running the <filename>*.sh</filename>
- installation script.
+ The first thing you need to do is install the SDK on your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
+ by running the <filename>*.sh</filename> installation script.
</para>
<para>
You can download a tarball installer, which includes the
pre-built toolchain, the <filename>runqemu</filename>
script, the internal build system, <filename>devtool</filename>,
- and support files from the appropriate directory under
- <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
- Toolchains are available for 32-bit and 64-bit x86 development
- systems from the <filename>i686</filename> and
- <filename>x86_64</filename> directories, respectively.
+ and support files from the appropriate
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
+ directory within the Index of Releases.
+ Toolchains are available for several 32-bit and 64-bit
+ architectures with the <filename>x86_64</filename> directories,
+ respectively.
The toolchains the Yocto Project provides are based off the
- <filename>core-image-sato</filename> image and contain
+ <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images and contain
libraries appropriate for developing against that image.
- Each type of development system supports five or more target
- architectures.
</para>
<para>
@@ -85,6 +85,7 @@
filename and then is immediately followed by a string
representing the target architecture.
An extensible SDK has the string "-ext" as part of the name.
+ Following is the general form:
<literallayout class='monospaced'>
poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh
@@ -93,14 +94,15 @@
i686 or x86_64.
- <replaceable>image_type</replaceable> is the image for which the SDK was built.
+ <replaceable>image_type</replaceable> is the image for which the SDK was built:
+
+ core-image-sato or core-image-minimal
<replaceable>arch</replaceable> is a string representing the tuned target architecture:
- i586, x86_64, powerpc, mips, armv7a or armv5te
+ aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
- <replaceable>release_version</replaceable> is a string representing the release number of the
- Yocto Project:
+ <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
&DISTRO;, &DISTRO;+snapshot
</literallayout>
@@ -131,9 +133,10 @@
home directory.
You can choose to install the extensible SDK in any location when
you run the installer.
- However, the location you choose needs to be writable for whichever
- users need to use the SDK, since files will need to be written
- under that directory during the normal course of operation.
+ However, because files need to be written under that directory
+ during the normal course of operation, the location you choose
+ for installation must be writable for whichever
+ users need to use the SDK.
</para>
<para>
@@ -141,28 +144,34 @@
toolchain tarball for a 64-bit x86 development host system and
a 64-bit x86 target architecture.
The example assumes the SDK installer is located in
- <filename>~/Downloads/</filename>.
+ <filename>~/Downloads/</filename> and has execution rights.
<note>
If you do not have write permissions for the directory
into which you are installing the SDK, the installer
notifies you and exits.
- Be sure you have write permissions in the directory and
- run the installer again.
+ For that case, set up the proper permissions in the directory
+ and run the installer again.
</note>
<literallayout class='monospaced'>
- $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh
- Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
- ===================================================================================
+ $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
+ Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
+ ==========================================================================
Enter target directory for SDK (default: ~/poky_sdk):
You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
- Extracting SDK......................................................................done
+ Extracting SDK..............done
Setting it up...
Extracting buildtools...
Preparing build system...
+ Parsing recipes: 100% |##################################################################| Time: 0:00:52
+ Initialising tasks: 100% |###############################################################| Time: 0:00:00
+ Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
+ Loading cache: 100% |####################################################################| Time: 0:00:00
+ Initialising tasks: 100% |###############################################################| Time: 0:00:00
done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
$ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+
</literallayout>
</para>
</section>
@@ -172,7 +181,7 @@
<para>
Once you have the SDK installed, you must run the SDK environment
- setup script before you can actually use it.
+ setup script before you can actually use the SDK.
This setup script resides in the directory you chose when you
installed the SDK, which is either the default
<filename>poky_sdk</filename> directory or the directory you
@@ -196,32 +205,13 @@
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.
</literallayout>
- When you run the setup script, many environment variables are
- defined:
- <literallayout class='monospaced'>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
- <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
- <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
- <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
- </literallayout>
+ Running the setup script defines many environment variables needed
+ in order to use the SDK (e.g. <filename>PATH</filename>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>,
+ and so forth).
+ If you want to see all the environment variables the script
+ exports, examine the installation file itself.
</para>
</section>
@@ -240,15 +230,15 @@
the extensible SDK.
You can use <filename>devtool</filename> to help you easily
develop any project whose build output must be part of an
- image built using the OpenEmbedded build system.
+ image built using the build system.
</note>
</para>
<para>
The <filename>devtool</filename> command line is organized
similarly to
- <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> in that it has a
- number of sub-commands for each function.
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> in that it
+ has a number of sub-commands for each function.
You can run <filename>devtool --help</filename> to see all the
commands.
<note>
@@ -260,8 +250,8 @@
</para>
<para>
- Three <filename>devtool</filename> subcommands that provide
- entry-points into development are:
+ Three <filename>devtool</filename> subcommands exist that provide
+ entry-points into development:
<itemizedlist>
<listitem><para>
<emphasis><filename>devtool add</filename></emphasis>:
@@ -278,17 +268,17 @@
an updated set of source files.
</para></listitem>
</itemizedlist>
- As with the OpenEmbedded build system, "recipes" represent software
- packages within <filename>devtool</filename>.
+ As with the build system, "recipes" represent software packages
+ within <filename>devtool</filename>.
When you use <filename>devtool add</filename>, a recipe is
automatically created.
When you use <filename>devtool modify</filename>, the specified
- existing recipe is used in order to determine where to get the source
- code and how to patch it.
+ existing recipe is used in order to determine where to get the
+ source code and how to patch it.
In both cases, an environment is set up so that when you build the
recipe a source tree that is under your control is used in order to
allow you to make changes to the source as desired.
- By default, both new recipes and the source go into a "workspace"
+ By default, new recipes and the source go into a "workspace"
directory under the SDK.
</para>
@@ -335,10 +325,10 @@
generate a recipe based on existing source code.</para>
<para>In a shared development environment, it is
- typical where other developers are responsible for
+ typical for other developers to be responsible for
various areas of source code.
As a developer, you are probably interested in using
- that source code as part of your development using
+ that source code as part of your development within
the Yocto Project.
All you need is access to the code, a recipe, and a
controlled area in which to do your work.</para>
@@ -346,138 +336,164 @@
<para>Within the diagram, three possible scenarios
feed into the <filename>devtool add</filename> workflow:
<itemizedlist>
- <listitem><para><emphasis>Left</emphasis>:
- The left scenario represents a common situation
- where the source code does not exist locally
- and needs to be extracted.
- In this situation, you just let it get
- extracted to the default workspace - you do not
- want it in some specific location outside of the
- workspace.
- Thus, everything you need will be located in the
- workspace:
+ <listitem><para>
+ <emphasis>Left</emphasis>:
+ The left scenario in the figure represents a
+ common situation where the source code does not
+ exist locally and needs to be extracted.
+ In this situation, the source code is extracted
+ to the default workspace - you do not
+ want the files in some specific location
+ outside of the workspace.
+ Thus, everything you need will be located in
+ the workspace:
<literallayout class='monospaced'>
$ devtool add <replaceable>recipe fetchuri</replaceable>
</literallayout>
With this command, <filename>devtool</filename>
- creates a recipe and an append file in the
- workspace as well as extracts the upstream
- source files into a local Git repository also
- within the <filename>sources</filename> folder.
+ extracts the upstream source files into a local
+ Git repository within the
+ <filename>sources</filename> folder.
+ The command then creates a recipe named
+ <replaceable>recipe</replaceable> and a
+ corresponding append file in the workspace.
+ If you do not provide
+ <replaceable>recipe</replaceable>, the command
+ makes an attempt to determine the recipe name.
</para></listitem>
- <listitem><para><emphasis>Middle</emphasis>:
- The middle scenario also represents a situation where
- the source code does not exist locally.
+ <listitem><para>
+ <emphasis>Middle</emphasis>:
+ The middle scenario in the figure also
+ represents a situation where the source code
+ does not exist locally.
In this case, the code is again upstream
and needs to be extracted to some
local area - this time outside of the default
workspace.
- If required, <filename>devtool</filename>
- always creates
- a Git repository locally during the extraction.
+ <note>
+ If required, <filename>devtool</filename>
+ always creates
+ a Git repository locally during the
+ extraction.
+ </note>
Furthermore, the first positional argument
- <replaceable>srctree</replaceable> in this case
- identifies where the
+ <replaceable>srctree</replaceable> in this
+ case identifies where the
<filename>devtool add</filename> command
will locate the extracted code outside of the
- workspace:
+ workspace.
+ You need to specify an empty directory:
<literallayout class='monospaced'>
$ devtool add <replaceable>recipe srctree fetchuri</replaceable>
</literallayout>
In summary, the source code is pulled from
- <replaceable>fetchuri</replaceable> and extracted
- into the location defined by
+ <replaceable>fetchuri</replaceable> and
+ extracted into the location defined by
<replaceable>srctree</replaceable> as a local
Git repository.</para>
- <para>Within workspace, <filename>devtool</filename>
- creates both the recipe and an append file
- for the recipe.
+ <para>Within workspace,
+ <filename>devtool</filename> creates a
+ recipe named <replaceable>recipe</replaceable>
+ along with an associated append file.
</para></listitem>
- <listitem><para><emphasis>Right</emphasis>:
- The right scenario represents a situation
- where the source tree (srctree) has been
+ <listitem><para>
+ <emphasis>Right</emphasis>:
+ The right scenario in the figure represents a
+ situation where the
+ <replaceable>srctree</replaceable> has been
previously prepared outside of the
- <filename>devtool</filename> workspace.
- </para>
+ <filename>devtool</filename> workspace.</para>
- <para>The following command names the recipe
- and identifies where the existing source tree
- is located:
+ <para>The following command provides a new
+ recipe name and identifies the existing source
+ tree location:
<literallayout class='monospaced'>
$ devtool add <replaceable>recipe srctree</replaceable>
</literallayout>
- The command examines the source code and creates
- a recipe for it placing the recipe into the
- workspace.</para>
+ The command examines the source code and
+ creates a recipe named
+ <replaceable>recipe</replaceable> for the code
+ and places the recipe into the workspace.
+ </para>
- <para>Because the extracted source code already exists,
- <filename>devtool</filename> does not try to
- relocate it into the workspace - just the new
- the recipe is placed in the workspace.</para>
+ <para>Because the extracted source code already
+ exists, <filename>devtool</filename> does not
+ try to relocate the source code into the
+ workspace - only the new recipe is placed
+ in the workspace.</para>
<para>Aside from a recipe folder, the command
- also creates an append folder and places an initial
- <filename>*.bbappend</filename> within.
+ also creates an associated append folder and
+ places an initial
+ <filename>*.bbappend</filename> file within.
</para></listitem>
</itemizedlist>
</para></listitem>
- <listitem><para><emphasis>Edit the Recipe</emphasis>:
- At this point, you can use <filename>devtool edit-recipe</filename>
+ <listitem><para>
+ <emphasis>Edit the Recipe</emphasis>:
+ You can use <filename>devtool edit-recipe</filename>
to open up the editor as defined by the
<filename>$EDITOR</filename> environment variable
and modify the file:
<literallayout class='monospaced'>
$ devtool edit-recipe <replaceable>recipe</replaceable>
</literallayout>
- From within the editor, you can make modifications to the
- recipe that take affect when you build it later.
+ From within the editor, you can make modifications to
+ the recipe that take affect when you build it later.
</para></listitem>
- <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
- At this point in the flow, the next step you
- take depends on what you are going to do with
- the new code.</para>
- <para>If you need to take the build output and eventually
- move it to the target hardware, you would use
- <filename>devtool build</filename>:
+ <listitem><para>
+ <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+ The next step you take depends on what you are going
+ to do with the new code.</para>
+
+ <para>If you need to eventually move the build output
+ to the target hardware, use the following
+ <filename>devtool</filename> command:
<literallayout class='monospaced'>
$ devtool build <replaceable>recipe</replaceable>
</literallayout></para>
+
<para>On the other hand, if you want an image to
- contain the recipe's packages for immediate deployment
- onto a device (e.g. for testing purposes), you can use
+ contain the recipe's packages from the workspace
+ for immediate deployment onto a device (e.g. for
+ testing purposes), you can use
the <filename>devtool build-image</filename> command:
<literallayout class='monospaced'>
$ devtool build-image <replaceable>image</replaceable>
</literallayout>
</para></listitem>
- <listitem><para><emphasis>Deploy the Build Output</emphasis>:
+ <listitem><para>
+ <emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename>
command to build out your recipe, you probably want to
- see if the resulting build output works as expected on target
- hardware.
+ see if the resulting build output works as expected
+ on the target hardware.
<note>
This step assumes you have a previously built
image that is already either running in QEMU or
- running on actual hardware.
- Also, it is assumed that for deployment of the image
- to the target, SSH is installed in the image and if
- the image is running on real hardware that you have
- network access to and from your development machine.
+ is running on actual hardware.
+ Also, it is assumed that for deployment of the
+ image to the target, SSH is installed in the image
+ and, if the image is running on real hardware,
+ you have network access to and from your
+ development machine.
</note>
- You can deploy your build output to that target hardware by
- using the <filename>devtool deploy-target</filename> command:
+ You can deploy your build output to that target
+ hardware by using the
+ <filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout>
- The <replaceable>target</replaceable> is a live target machine
- running as an SSH server.</para>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
- <para>You can, of course, also deploy the image you build
- using the <filename>devtool build-image</filename> command
- to actual hardware.
- However, <filename>devtool</filename> does not provide a
- specific command that allows you to do this.
+ <para>You can, of course, also deploy the image you
+ build to actual hardware by using the
+ <filename>devtool build-image</filename> command.
+ However, <filename>devtool</filename> does not provide
+ a specific command that allows you to deploy the
+ image to actual hardware.
</para></listitem>
<listitem><para>
<emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -494,8 +510,9 @@
committed to the Git repository in the source tree.
</note></para>
- <para>As mentioned, the <filename>devtool finish</filename>
- command moves the final recipe to its permanent layer.
+ <para>As mentioned, the
+ <filename>devtool finish</filename> command moves the
+ final recipe to its permanent layer.
</para>
<para>As a final process of the
@@ -520,21 +537,20 @@
<para>
The <filename>devtool modify</filename> command prepares the
- way to work on existing code that already has a recipe in
- place.
- The command is flexible enough to allow you to extract code,
- specify the existing recipe, and keep track of and gather any
- patch files from other developers that are
- associated with the code.
+ way to work on existing code that already has a local recipe in
+ place that is used to build the software.
+ The command is flexible enough to allow you to extract code
+ from an upstream source, specify the existing recipe, and
+ keep track of and gather any patch files from other developers
+ that are associated with the code.
</para>
<para>
Depending on your particular scenario, the arguments and options
you use with <filename>devtool modify</filename> form different
combinations.
- The following diagram shows common development flows
- you would use with the <filename>devtool modify</filename>
- command:
+ The following diagram shows common development flows for the
+ <filename>devtool modify</filename> command:
</para>
<para>
@@ -543,140 +559,181 @@
<para>
<orderedlist>
- <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
+ <listitem><para>
+ <emphasis>Preparing to Modify the Code</emphasis>:
The top part of the flow shows three scenarios by which
you could use <filename>devtool modify</filename> to
prepare to work on source files.
Each scenario assumes the following:
<itemizedlist>
- <listitem><para>The recipe exists in some layer external
+ <listitem><para>
+ The recipe exists locally in a layer external
to the <filename>devtool</filename> workspace.
</para></listitem>
- <listitem><para>The source files exist upstream in an
+ <listitem><para>
+ The source files exist either upstream in an
un-extracted state or locally in a previously
extracted state.
</para></listitem>
</itemizedlist>
The typical situation is where another developer has
- created some layer for use with the Yocto Project and
+ created a layer for use with the Yocto Project and
their recipe already resides in that layer.
Furthermore, their source code is readily available
either upstream or locally.
<itemizedlist>
- <listitem><para><emphasis>Left</emphasis>:
- The left scenario represents a common situation
- where the source code does not exist locally
- and needs to be extracted.
+ <listitem><para>
+ <emphasis>Left</emphasis>:
+ The left scenario in the figure represents a
+ common situation where the source code does
+ not exist locally and it needs to be extracted
+ from an upstream source.
In this situation, the source is extracted
- into the default workspace location.
+ into the default <filename>devtool</filename>
+ workspace location.
The recipe, in this scenario, is in its own
layer outside the workspace
(i.e.
<filename>meta-</filename><replaceable>layername</replaceable>).
</para>
- <para>The following command identifies the recipe
- and by default extracts the source files:
+ <para>The following command identifies the
+ recipe and, by default, extracts the source
+ files:
<literallayout class='monospaced'>
$ devtool modify <replaceable>recipe</replaceable>
</literallayout>
- Once <filename>devtool</filename>locates the recipe,
- it uses the
+ Once <filename>devtool</filename>locates the
+ recipe, <filename>devtool</filename> uses the
+ recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- variable to locate the source code and
- any local patch files from other developers are
- located.
- <note>
- You cannot provide an URL for
- <replaceable>srctree</replaceable> when using the
- <filename>devtool modify</filename> command.
- </note>
- With this scenario, however, since no
- <replaceable>srctree</replaceable> argument exists, the
- <filename>devtool modify</filename> command by default
- extracts the source files to a Git structure.
- Furthermore, the location for the extracted source is the
- default area within the workspace.
- The result is that the command sets up both the source
- code and an append file within the workspace with the
- recipe remaining in its original location.
+ statements to locate the source code and any
+ local patch files from other developers.</para>
+
+ <para>With this scenario, no
+ <replaceable>srctree</replaceable> argument
+ exists.
+ Consequently, the default behavior of the
+ <filename>devtool modify</filename> command is
+ to extract the source files pointed to by the
+ <filename>SRC_URI</filename> statements into a
+ local Git structure.
+ Furthermore, the location for the extracted
+ source is the default area within the
+ <filename>devtool</filename> workspace.
+ The result is that the command sets up both
+ the source code and an append file within the
+ workspace while the recipe remains in its
+ original location.
</para></listitem>
- <listitem><para><emphasis>Middle</emphasis>:
- The middle scenario represents a situation where
- the source code also does not exist locally.
+ <listitem><para>
+ <emphasis>Middle</emphasis>:
+ The middle scenario in the figure represents a
+ situation where the source code also does not
+ exist locally.
In this case, the code is again upstream
and needs to be extracted to some
local area as a Git repository.
- The recipe, in this scenario, is again in its own
- layer outside the workspace.</para>
+ The recipe, in this scenario, is again local
+ and in its own layer outside the workspace.
+ </para>
<para>The following command tells
<filename>devtool</filename> what recipe with
- which to work and, in this case, identifies a local
- area for the extracted source files that is outside
- of the default workspace:
+ which to work and, in this case, identifies a
+ local area for the extracted source files that
+ is outside of the default
+ <filename>devtool</filename> workspace:
<literallayout class='monospaced'>
$ devtool modify <replaceable>recipe srctree</replaceable>
</literallayout>
+ <note>
+ You cannot provide a URL for
+ <replaceable>srctree</replaceable> using
+ the <filename>devtool</filename> command.
+ </note>
As with all extractions, the command uses
- the recipe's <filename>SRC_URI</filename> to locate the
- source files.
- Once the files are located, the command by default
- extracts them.
- Providing the <replaceable>srctree</replaceable>
- argument instructs <filename>devtool</filename> where
- to place the extracted source.</para>
+ the recipe's <filename>SRC_URI</filename>
+ statements to locate the source files and any
+ associated patch files.
+ Once the files are located, the command by
+ default extracts them into
+ <replaceable>srctree</replaceable>.</para>
- <para>Within workspace, <filename>devtool</filename>
- creates an append file for the recipe.
+ <para>Within workspace,
+ <filename>devtool</filename> creates an append
+ file for the recipe.
The recipe remains in its original location but
- the source files are extracted to the location you
- provided with <replaceable>srctree</replaceable>.
+ the source files are extracted to the location
+ you provide with
+ <replaceable>srctree</replaceable>.
</para></listitem>
- <listitem><para><emphasis>Right</emphasis>:
- The right scenario represents a situation
- where the source tree
- (<replaceable>srctree</replaceable>) exists as a
- previously extracted Git structure outside of
- the <filename>devtool</filename> workspace.
+ <listitem><para>
+ <emphasis>Right</emphasis>:
+ The right scenario in the figure represents a
+ situation where the source tree
+ (<replaceable>srctree</replaceable>) already
+ exists locally as a previously extracted Git
+ structure outside of the
+ <filename>devtool</filename> workspace.
In this example, the recipe also exists
- elsewhere in its own layer.
+ elsewhere locally in its own layer.
</para>
<para>The following command tells
<filename>devtool</filename> the recipe
- with which to work, uses the "-n" option to indicate
- source does not need to be extracted, and uses
- <replaceable>srctree</replaceable> to point to the
- previously extracted source files:
+ with which to work, uses the "-n" option to
+ indicate source does not need to be extracted,
+ and uses <replaceable>srctree</replaceable> to
+ point to the previously extracted source files:
<literallayout class='monospaced'>
$ devtool modify -n <replaceable>recipe srctree</replaceable>
</literallayout>
</para>
<para>Once the command finishes, it creates only
- an append file for the recipe in the workspace.
+ an append file for the recipe in the
+ <filename>devtool</filename> workspace.
The recipe and the source code remain in their
original locations.
</para></listitem>
</itemizedlist>
</para></listitem>
- <listitem><para><emphasis>Edit the Source</emphasis>:
- Once you have used the <filename>devtool modify</filename>
- command, you are free to make changes to the source
- files.
+ <listitem><para>
+ <emphasis>Edit the Source</emphasis>:
+ Once you have used the
+ <filename>devtool modify</filename> command, you are
+ free to make changes to the source files.
You can use any editor you like to make and save
your source code modifications.
</para></listitem>
- <listitem><para><emphasis>Build the Recipe</emphasis>:
- Once you have updated the source files, you can build
- the recipe.
+ <listitem><para>
+ <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+ The next step you take depends on what you are going
+ to do with the new code.</para>
+
+ <para>If you need to eventually move the build output
+ to the target hardware, use the following
+ <filename>devtool</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build <replaceable>recipe</replaceable>
+ </literallayout></para>
+
+ <para>On the other hand, if you want an image to
+ contain the recipe's packages from the workspace
+ for immediate deployment onto a device (e.g. for
+ testing purposes), you can use
+ the <filename>devtool build-image</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build-image <replaceable>image</replaceable>
+ </literallayout>
</para></listitem>
- <listitem><para><emphasis>Deploy the Build Output</emphasis>:
+ <listitem><para>
+ <emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename>
- command to build out your recipe, you probably want to see
- if the resulting build output works as expected on target
- hardware.
+ command to build out your recipe, you probably want to
+ see if the resulting build output works as expected
+ on target hardware.
<note>
This step assumes you have a previously built
image that is already either running in QEMU or
@@ -686,19 +743,22 @@
the image is running on real hardware that you have
network access to and from your development machine.
</note>
- You can deploy your build output to that target hardware by
- using the <filename>devtool deploy-target</filename> command:
+ You can deploy your build output to that target
+ hardware by using the
+ <filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout>
- The <replaceable>target</replaceable> is a live target machine
- running as an SSH server.</para>
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
- <para>You can, of course, also deploy the image you build
- using the <filename>devtool build-image</filename> command
- to actual hardware.
- However, <filename>devtool</filename> does not provide a
- specific command that allows you to do this.
+ <para>You can, of course, use other methods to deploy
+ the image you built using the
+ <filename>devtool build-image</filename> command to
+ actual hardware.
+ <filename>devtool</filename> does not provide
+ a specific command to deploy the image to actual
+ hardware.
</para></listitem>
<listitem><para>
<emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -707,28 +767,30 @@
Git repository, updates the recipe to point to them
(or creates a <filename>.bbappend</filename> file to do
so, depending on the specified destination layer), and
- then resets the recipe so that the recipe is built normally
- rather than from the workspace.
+ then resets the recipe so that the recipe is built
+ normally rather than from the workspace.
<literallayout class='monospaced'>
$ devtool finish <replaceable>recipe layer</replaceable>
</literallayout>
<note>
Any changes you want to turn into patches must be
- committed to the Git repository in the source tree.
+ staged and committed within the local Git
+ repository before you use the
+ <filename>devtool finish</filename> command.
</note></para>
<para>Because there is no need to move the recipe,
<filename>devtool finish</filename> either updates the
original recipe in the original layer or the command
- creates a <filename>.bbappend</filename> in a different
- layer as provided by <replaceable>layer</replaceable>.
- </para>
+ creates a <filename>.bbappend</filename> file in a
+ different layer as provided by
+ <replaceable>layer</replaceable>.</para>
<para>As a final process of the
<filename>devtool finish</filename> command, the state
of the standard layers and the upstream source is
restored so that you can build the recipe from those
- areas rather than the workspace.
+ areas rather than from the workspace.
<note>
You can use the <filename>devtool reset</filename>
command to put things back should you decide you
@@ -745,22 +807,36 @@
<title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
<para>
- The <filename>devtool upgrade</filename> command updates
- an existing recipe so that you can build it for an updated
- set of source files.
- The command is flexible enough to allow you to specify
- source code revision and versioning schemes, extract code into
- or out of the <filename>devtool</filename> workspace, and
- work with any source file forms that the fetchers support.
+ The <filename>devtool upgrade</filename> command upgrades
+ an existing recipe to that of a more up-to-date version
+ found upstream.
+ Throughout the life of software, recipes continually undergo
+ version upgrades by their upstream publishers.
+ You can use the <filename>devtool upgrade</filename>
+ workflow to make sure your recipes you are using for builds
+ are up-to-date with their upstream counterparts.
+ <note>
+ Several methods exist by which you can upgrade recipes -
+ <filename>devtool upgrade</filename> happens to be one.
+ You can read about all the methods by which you can
+ upgrade recipes in the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
+ section of the Yocto Project Development Tasks Manual.
+ </note>
</para>
<para>
- Depending on your particular scenario, the arguments and options
- you use with <filename>devtool upgrade</filename> form different
- combinations.
- The following diagram shows a common development flow
- you would use with the <filename>devtool modify</filename>
- command:
+ The <filename>devtool upgrade</filename> command is flexible
+ enough to allow you to specify source code revision and
+ versioning schemes, extract code into or out of the
+ <filename>devtool</filename>
+ <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>,
+ and work with any source file forms that the fetchers support.
+ </para>
+
+ <para>
+ The following diagram shows the common development flow
+ used with the <filename>devtool upgrade</filename> command:
</para>
<para>
@@ -769,110 +845,142 @@
<para>
<orderedlist>
- <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
- The top part of the flow shows a typical scenario by which
- you could use <filename>devtool upgrade</filename>.
+ <listitem><para>
+ <emphasis>Initiate the Upgrade</emphasis>:
+ The top part of the flow shows the typical scenario by
+ which you use the <filename>devtool upgrade</filename>
+ command.
The following conditions exist:
<itemizedlist>
- <listitem><para>The recipe exists in some layer external
+ <listitem><para>
+ The recipe exists in a local layer external
to the <filename>devtool</filename> workspace.
</para></listitem>
- <listitem><para>The source files for the new release
- exist adjacent to the same location pointed to by
+ <listitem><para>
+ The source files for the new release
+ exist in the same location pointed to by
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- in the recipe (e.g. a tarball with the new version
- number in the name, or as a different revision in
- the upstream Git repository).
+ in the recipe (e.g. a tarball with the new
+ version number in the name, or as a different
+ revision in the upstream Git repository).
</para></listitem>
</itemizedlist>
A common situation is where third-party software has
undergone a revision so that it has been upgraded.
- The recipe you have access to is likely in your own layer.
+ The recipe you have access to is likely in your own
+ layer.
Thus, you need to upgrade the recipe to use the
newer version of the software:
<literallayout class='monospaced'>
$ devtool upgrade -V <replaceable>version recipe</replaceable>
</literallayout>
- By default, the <filename>devtool upgrade</filename> command
- extracts source code into the <filename>sources</filename>
- directory in the workspace.
- If you want the code extracted to any other location, you
- need to provide the <replaceable>srctree</replaceable>
- positional argument with the command as follows:
+ By default, the <filename>devtool upgrade</filename>
+ command extracts source code into the
+ <filename>sources</filename> directory in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>.
+ If you want the code extracted to any other location,
+ you need to provide the
+ <replaceable>srctree</replaceable> positional argument
+ with the command as follows:
<literallayout class='monospaced'>
$ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
</literallayout>
- Also, in this example, the "-V" option is used to specify
- the new version.
+ <note>
+ In this example, the "-V" option specifies the new
+ version.
+ If you don't use "-V", the command upgrades the
+ recipe to the latest version.
+ </note>
If the source files pointed to by the
- <filename>SRC_URI</filename> statement in the recipe are
- in a Git repository, you must provide the "-S" option and
- specify a revision for the software.</para>
+ <filename>SRC_URI</filename> statement in the recipe
+ are in a Git repository, you must provide the "-S"
+ option and specify a revision for the software.</para>
- <para>Once <filename>devtool</filename> locates the recipe,
- it uses the <filename>SRC_URI</filename> variable to locate
- the source code and any local patch files from other
- developers are located.
+ <para>Once <filename>devtool</filename> locates the
+ recipe, it uses the <filename>SRC_URI</filename>
+ variable to locate the source code and any local patch
+ files from other developers.
The result is that the command sets up the source
code, the new version of the recipe, and an append file
all within the workspace.
</para></listitem>
- <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
- At this point, there could be some conflicts due to the
- software being upgraded to a new version.
- This would occur if your recipe specifies some patch files in
- <filename>SRC_URI</filename> that conflict with changes
- made in the new version of the software.
- If this is the case, you need to resolve the conflicts
+ <listitem><para>
+ <emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
+ Conflicts could exist due to the software being
+ upgraded to a new version.
+ Conflicts occur if your recipe specifies some patch
+ files in <filename>SRC_URI</filename> that conflict
+ with changes made in the new version of the software.
+ For such cases, you need to resolve the conflicts
by editing the source and following the normal
<filename>git rebase</filename> conflict resolution
process.</para>
- <para>Before moving onto the next step, be sure to resolve any
- such conflicts created through use of a newer or different
- version of the software.
+
+ <para>Before moving onto the next step, be sure to
+ resolve any such conflicts created through use of a
+ newer or different version of the software.
</para></listitem>
- <listitem><para><emphasis>Build the Recipe</emphasis>:
- Once you have your recipe in order, you can build it.
- You can either use <filename>devtool build</filename> or
- <filename>bitbake</filename>.
- Either method produces build output that is stored
- in
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
+ <listitem><para>
+ <emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+ The next step you take depends on what you are going
+ to do with the new code.</para>
+
+ <para>If you need to eventually move the build output
+ to the target hardware, use the following
+ <filename>devtool</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build <replaceable>recipe</replaceable>
+ </literallayout></para>
+
+ <para>On the other hand, if you want an image to
+ contain the recipe's packages from the workspace
+ for immediate deployment onto a device (e.g. for
+ testing purposes), you can use
+ the <filename>devtool build-image</filename> command:
+ <literallayout class='monospaced'>
+ $ devtool build-image <replaceable>image</replaceable>
+ </literallayout>
</para></listitem>
- <listitem><para><emphasis>Deploy the Build Output</emphasis>:
+ <listitem><para>
+ <emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename>
- command or <filename>bitbake</filename> to build out your
- recipe, you probably want to see if the resulting build
- output works as expected on target hardware.
+ command or <filename>bitbake</filename> to build
+ your recipe, you probably want to see if the resulting
+ build output works as expected on target hardware.
<note>
This step assumes you have a previously built
image that is already either running in QEMU or
running on actual hardware.
- Also, it is assumed that for deployment of the image
- to the target, SSH is installed in the image and if
- the image is running on real hardware that you have
- network access to and from your development machine.
+ Also, it is assumed that for deployment of the
+ image to the target, SSH is installed in the image
+ and if the image is running on real hardware that
+ you have network access to and from your
+ development machine.
</note>
- You can deploy your build output to that target hardware by
- using the <filename>devtool deploy-target</filename> command:
+ You can deploy your build output to that target
+ hardware by using the
+ <filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout>
- The <replaceable>target</replaceable> is a live target machine
- running as an SSH server.</para>
- <para>You can, of course, also deploy the image you build
- using the <filename>devtool build-image</filename> command
+ The <replaceable>target</replaceable> is a live target
+ machine running as an SSH server.</para>
+
+ <para>You can, of course, also deploy the image you
+ build using the
+ <filename>devtool build-image</filename> command
to actual hardware.
- However, <filename>devtool</filename> does not provide a
- specific command that allows you to do this.
+ However, <filename>devtool</filename> does not provide
+ a specific command that allows you to do this.
</para></listitem>
<listitem><para>
<emphasis>Finish Your Work With the Recipe</emphasis>:
The <filename>devtool finish</filename> command creates
any patches corresponding to commits in the local
- Git repository, moves the new recipe to a more permanent
- layer, and then resets the recipe so that the recipe is
- built normally rather than from the workspace.
+ Git repository, moves the new recipe to a more
+ permanent layer, and then resets the recipe so that
+ the recipe is built normally rather than from the
+ workspace.
If you specify a destination layer that is the same as
the original source, then the old version of the
recipe and associated files will be removed prior to
@@ -884,6 +992,7 @@
Any changes you want to turn into patches must be
committed to the Git repository in the source tree.
</note></para>
+
<para>As a final process of the
<filename>devtool finish</filename> command, the state
of the standard layers and the upstream source is
@@ -906,8 +1015,8 @@
<title>A Closer Look at <filename>devtool add</filename></title>
<para>
- The <filename>devtool add</filename> command automatically creates a
- recipe based on the source tree with which you provide it.
+ The <filename>devtool add</filename> command automatically creates
+ a recipe based on the source tree you provide with the command.
Currently, the command has support for the following:
<itemizedlist>
<listitem><para>
@@ -953,8 +1062,8 @@
In most cases, you need to edit the automatically generated
recipe in order to make it build properly.
Typically, you would go through several edit and build cycles
- until you can build the recipe.
- Once the recipe can be built, you could use possible further
+ until the recipe successfully builds.
+ Once the recipe builds, you could use possible further
iterations to test the recipe on the target device.
</note>
</para>
@@ -969,15 +1078,19 @@
<para>
If you do not specify a name and version on the command
- line, <filename>devtool add</filename> attempts to determine
- the name and version of the software being built from
- various metadata within the source tree.
- Furthermore, the command sets the name of the created recipe
- file accordingly.
- If the name or version cannot be determined, the
- <filename>devtool add</filename> command prints an error and
- you must re-run the command with both the name and version
- or just the name or version specified.
+ line, <filename>devtool add</filename> uses various metadata
+ within the source tree in an attempt to determine
+ the name and version of the software being built.
+ Based on what the tool determines, <filename>devtool</filename>
+ sets the name of the created recipe file accordingly.
+ </para>
+
+ <para>
+ If <filename>devtool</filename> cannot determine the name and
+ version, the command prints an error.
+ For such cases, you must re-run the command and provide
+ the name and version, just the name, or just the version as
+ part of the command line.
</para>
<para>
@@ -1001,26 +1114,27 @@
detect build-time dependencies and map them to other recipes
in the system.
During this mapping, the command fills in the names of those
- recipes in the
+ recipes as part of the
<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
- value within the recipe.
- If a dependency cannot be mapped, then a comment is placed in
- the recipe indicating such.
- The inability to map a dependency might be caused because the
- naming is not recognized or because the dependency simply is
- not available.
+ variable within the recipe.
+ If a dependency cannot be mapped, <filename>devtool</filename>
+ places a comment in the recipe indicating such.
+ The inability to map a dependency can result from naming not
+ being recognized or because the dependency simply is not
+ available.
For cases where the dependency is not available, you must use
the <filename>devtool add</filename> command to add an
- additional recipe to satisfy the dependency and then come
- back to the first recipe and add its name to
- <filename>DEPENDS</filename>.
+ additional recipe that satisfies the dependency.
+ Once you add that recipe, you need to update the
+ <filename>DEPENDS</filename> variable in the original recipe
+ to include the new recipe.
</para>
<para>
If you need to add runtime dependencies, you can do so by
adding the following to your recipe:
<literallayout class='monospaced'>
- RDEPENDS_${PN} += "dependency1 dependency2 ..."
+ RDEPENDS_${PN} += "<replaceable>dependency1 dependency2 ...</replaceable>"
</literallayout>
<note>
The <filename>devtool add</filename> command often cannot
@@ -1031,7 +1145,7 @@
script for the software the recipe is building for further
details.
In some cases, you might find you can substitute the
- dependency for an option to disable the associated
+ dependency with an option that disables the associated
functionality passed to the configure script.
</note>
</para>
@@ -1043,20 +1157,24 @@
<para>
The <filename>devtool add</filename> command attempts to
determine if the software you are adding is able to be
- distributed under a common open-source license and sets the
+ distributed under a common, open-source license.
+ If so, the command sets the
<ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
value accordingly.
- You should double-check this value against the documentation
- or source files for the software you are building and update
- that <filename>LICENSE</filename> value if necessary.
+ You should double-check the value added by the command against
+ the documentation or source files for the software you are
+ building and, if necessary, update that
+ <filename>LICENSE</filename> value.
</para>
<para>
The <filename>devtool add</filename> command also sets the
<ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
value to point to all files that appear to be license-related.
- However, license statements often appear in comments at the top
- of source files or within documentation.
+ Realize that license statements often appear in comments at
+ the top of source files or within the documentation.
+ In such cases, the command does not recognize those license
+ statements.
Consequently, you might need to amend the
<filename>LIC_FILES_CHKSUM</filename> variable to point to one
or more of those comments if present.
@@ -1070,14 +1188,13 @@
<para>
If the <filename>devtool add</filename> command cannot
- determine licensing information, the
- <filename>LICENSE</filename> value is set to "CLOSED" and the
- <filename>LIC_FILES_CHKSUM</filename> value remains unset.
- This behavior allows you to continue with development but is
- unlikely to be correct in all cases.
- Consequently, you should check the documentation or source
- files for the software you are building to determine the actual
- license.
+ determine licensing information, <filename>devtool</filename>
+ sets the <filename>LICENSE</filename> value to "CLOSED" and
+ leaves the <filename>LIC_FILES_CHKSUM</filename> value unset.
+ This behavior allows you to continue with development even
+ though the settings are unlikely to be correct in all cases.
+ You should check the documentation or source files for the
+ software you are building to determine the actual license.
</para>
</section>
@@ -1085,8 +1202,8 @@
<title>Adding Makefile-Only Software</title>
<para>
- The use of <filename>make</filename> by itself is very common
- in both proprietary and open source software.
+ The use of Make by itself is very common in both proprietary
+ and open-source software.
Unfortunately, Makefiles are often not written with
cross-compilation in mind.
Thus, <filename>devtool add</filename> often cannot do very
@@ -1099,7 +1216,7 @@
<filename>gcc</filename> is the compiler for the build host
and the cross-compiler is named something similar to
<filename>arm-poky-linux-gnueabi-gcc</filename> and might
- require some arguments (e.g. to point to the associated sysroot
+ require arguments (e.g. to point to the associated sysroot
for the target machine).
</para>
@@ -1114,18 +1231,17 @@
<filename>g++</filename>.
</para></listitem>
<listitem><para>
- The environment in which <filename>make</filename> runs
- is set up with various standard variables for
- compilation (e.g. <filename>CC</filename>,
- <filename>CXX</filename>, and so forth) in a similar
- manner to the environment set up by the SDK's
- environment setup script.
+ The environment in which Make runs is set up with
+ various standard variables for compilation (e.g.
+ <filename>CC</filename>, <filename>CXX</filename>, and
+ so forth) in a similar manner to the environment set
+ up by the SDK's environment setup script.
One easy way to see these variables is to run the
<filename>devtool build</filename> command on the
recipe and then look in
<filename>oe-logs/run.do_compile</filename>.
- Towards the top of this file you will see a list of
- environment variables that are being set.
+ Towards the top of this file, a list of environment
+ variables exists that are being set.
You can take advantage of these variables within the
Makefile.
</para></listitem>
@@ -1133,7 +1249,7 @@
If the Makefile sets a default for a variable using "=",
that default overrides the value set in the environment,
which is usually not desirable.
- In this situation, you can either patch the Makefile
+ For this case, you can either patch the Makefile
so it sets the default using the "?=" operator, or
you can alternatively force the value on the
<filename>make</filename> command line.
@@ -1158,16 +1274,17 @@
This is particularly true because those hardcoded paths
often point to locations on the build host and thus
will either be read-only or will introduce
- contamination into the cross-compilation by virtue of
- being specific to the build host rather than the target.
+ contamination into the cross-compilation because they
+ are specific to the build host rather than the target.
Patching the Makefile to use prefix variables or other
- path variables is usually the way to handle this.
+ path variables is usually the way to handle this
+ situation.
</para></listitem>
<listitem><para>
Sometimes a Makefile runs target-specific commands such
as <filename>ldconfig</filename>.
- For such cases, you might be able to simply apply
- patches that remove these commands from the Makefile.
+ For such cases, you might be able to apply patches that
+ remove these commands from the Makefile.
</para></listitem>
</itemizedlist>
</para>
@@ -1178,9 +1295,11 @@
<para>
Often, you need to build additional tools that run on the
- build host system as opposed to the target.
- You should indicate this using one of the following methods
- when you run <filename>devtool add</filename>:
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+ as opposed to the target.
+ You should indicate this requirement by using one of the
+ following methods when you run
+ <filename>devtool add</filename>:
<itemizedlist>
<listitem><para>
Specify the name of the recipe such that it ends
@@ -1202,8 +1321,8 @@
typically accomplish this by building the native and target
parts separately rather than within the same compilation
process.
- Realize though that with the "‐‐also-native" option, you
- can add the tool using just one recipe file.
+ Realize though that with the "‐‐also-native"
+ option, you can add the tool using just one recipe file.
</note>
</para>
</section>
@@ -1244,11 +1363,9 @@
found" errors.
</para></listitem>
<listitem><para>
- In order to support adding
- Node.js modules, a
- <filename>nodejs</filename> recipe must be part of your
- SDK in order to provide Node.js
- itself.
+ In order to support adding Node.js modules, a
+ <filename>nodejs</filename> recipe must be part
+ of your SDK.
</para></listitem>
</itemizedlist>
</note>
@@ -1257,14 +1374,15 @@
<para>
As mentioned earlier, you can also add Node.js modules
directly from a repository or local source tree.
- To add modules this way, use <filename>devtool add</filename> in
- the following form:
+ To add modules this way, use <filename>devtool add</filename>
+ in the following form:
<literallayout class='monospaced'>
$ devtool add https://github.com/diversario/node-ssdp
</literallayout>
- In this example, <filename>devtool</filename> fetches the specified
- Git repository, detects that the code is Node.js code, fetches
- dependencies using <filename>npm</filename>, and sets
+ In this example, <filename>devtool</filename> fetches the
+ specified Git repository, detects the code as Node.js
+ code, fetches dependencies using <filename>npm</filename>, and
+ sets
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
accordingly.
</para>
@@ -1275,8 +1393,9 @@
<title>Working With Recipes</title>
<para>
- When building a recipe with <filename>devtool build</filename>, the
- typical build progression is as follows:
+ When building a recipe using the
+ <filename>devtool build</filename> command, the typical build
+ progresses as follows:
<orderedlist>
<listitem><para>
Fetch the source
@@ -1288,7 +1407,7 @@
Configure the source
</para></listitem>
<listitem><para>
- Compiling the source
+ Compile the source
</para></listitem>
<listitem><para>
Install the build output
@@ -1299,10 +1418,13 @@
</orderedlist>
For recipes in the workspace, fetching and unpacking is disabled
as the source tree has already been prepared and is persistent.
- Each of these build steps is defined as a function, usually with a
- "do_" prefix.
- These functions are typically shell scripts but can instead be written
- in Python.
+ Each of these build steps is defined as a function (task), usually
+ with a "do_" prefix (e.g.
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>,
+ and so forth).
+ These functions are typically shell scripts but can instead be
+ written in Python.
</para>
<para>
@@ -1310,12 +1432,13 @@
recipe does not include complete instructions for building the
software.
Instead, common functionality is encapsulated in classes inherited
- with the <filename>inherit</filename> directive, leaving the recipe
- to describe just the things that are specific to the software to be
- built.
- A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
- class exists that is implicitly inherited by all recipes and provides
- the functionality that most typical recipes need.
+ with the <filename>inherit</filename> directive.
+ This technique leaves the recipe to describe just the things that
+ are specific to the software being built.
+ A
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
+ class exists that is implicitly inherited by all recipes and
+ provides the functionality that most recipes typically need.
</para>
<para>
@@ -1327,46 +1450,57 @@
<title>Finding Logs and Work Files</title>
<para>
- When you are debugging a recipe that you previously created using
- <filename>devtool add</filename> or whose source you are modifying
- by using the <filename>devtool modify</filename> command, after
- the first run of <filename>devtool build</filename>, you will
- find some symbolic links created within the source tree:
- <filename>oe-logs</filename>, which points to the directory in
- which log files and run scripts for each build step are created
- and <filename>oe-workdir</filename>, which points to the temporary
- work area for the recipe.
- You can use these links to get more information on what is
- happening at each build step.
- </para>
-
- <para>
- These locations under <filename>oe-workdir</filename> are
- particularly useful:
+ After the first run of the <filename>devtool build</filename>
+ command, recipes that were previously created using the
+ <filename>devtool add</filename> command or whose sources were
+ modified using the <filename>devtool modify</filename>
+ command contain symbolic links created within the source tree:
<itemizedlist>
- <listitem><para><filename>image/</filename>:
- Contains all of the files installed at the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
- stage.
- Within a recipe, this directory is referred to by the
- expression
- <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
+ <listitem><para>
+ <filename>oe-logs</filename>:
+ This link points to the directory in which log files
+ and run scripts for each build step are created.
</para></listitem>
- <listitem><para><filename>sysroot-destdir/</filename>:
- Contains a subset of files installed within
- <filename>do_install</filename> that have been put into the
- shared sysroot.
- For more information, see the
- "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
- section.
- </para></listitem>
- <listitem><para><filename>packages-split/</filename>:
- Contains subdirectories for each package produced by the
+ <listitem><para>
+ <filename>oe-workdir</filename>:
+ This link points to the temporary work area for the
recipe.
- For more information, see the
- "<link linkend='sdk-packaging'>Packaging</link>" section.
+ The following locations under
+ <filename>oe-workdir</filename> are particularly
+ useful:
+ <itemizedlist>
+ <listitem><para>
+ <filename>image/</filename>:
+ Contains all of the files installed during
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ stage.
+ Within a recipe, this directory is referred
+ to by the expression
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>sysroot-destdir/</filename>:
+ Contains a subset of files installed within
+ <filename>do_install</filename> that have
+ been put into the shared sysroot.
+ For more information, see the
+ "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <filename>packages-split/</filename>:
+ Contains subdirectories for each package
+ produced by the recipe.
+ For more information, see the
+ "<link linkend='sdk-packaging'>Packaging</link>"
+ section.
+ </para></listitem>
+ </itemizedlist>
</para></listitem>
</itemizedlist>
+ You can use these links to get more information on what is
+ happening at each build step.
</para>
</section>
@@ -1413,12 +1547,14 @@
<para>
Recipes often need to use files provided by other recipes on
- the build host.
+ the
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
For example, an application linking to a common library needs
access to the library itself and its associated headers.
The way this access is accomplished within the extensible SDK is
through the sysroot.
- One sysroot exists per "machine" for which the SDK is being built.
+ One sysroot exists per "machine" for which the SDK is being
+ built.
In practical terms, this means a sysroot exists for the target
machine, and a sysroot exists for the build host.
</para>
@@ -1431,7 +1567,7 @@
task within the
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
directory.
- A subset of these files automatically go into the sysroot.
+ A subset of these files automatically goes into the sysroot.
The reason for this limitation is that almost all files that go
into the sysroot are cataloged in manifests in order to ensure
they can be removed later when a recipe is modified or removed.
@@ -1456,20 +1592,20 @@
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
task, files installed during the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
- task are split into one main package, which is almost always named
- the same as the recipe, and several other packages.
- This separation is done because not all of those installed files
- are always useful in every image.
+ task are split into one main package, which is almost always
+ named the same as the recipe, and into several other packages.
+ This separation exists because not all of those installed files
+ are useful in every image.
For example, you probably do not need any of the documentation
installed in a production image.
- Consequently, for each recipe the documentation files are separated
- into a <filename>-doc</filename> package.
- Recipes that package software that has optional modules or
- plugins might do additional package splitting as well.
+ Consequently, for each recipe the documentation files are
+ separated into a <filename>-doc</filename> package.
+ Recipes that package software containing optional modules or
+ plugins might undergo additional package splitting as well.
</para>
<para>
- After building a recipe you can see where files have gone by
+ After building a recipe, you can see where files have gone by
looking in the <filename>oe-workdir/packages-split</filename>
directory, which contains a subdirectory for each package.
Apart from some advanced cases, the
@@ -1479,17 +1615,18 @@
variables controls splitting.
The <filename>PACKAGES</filename> variable lists all of the
packages to be produced, while the <filename>FILES</filename>
- variable specifies which files to include in each package,
+ variable specifies which files to include in each package by
using an override to specify the package.
- For example, <filename>FILES_${PN}</filename> specifies the files
- to go into the main package (i.e. the main package is named the
- same as the recipe and
+ For example, <filename>FILES_${PN}</filename> specifies the
+ files to go into the main package (i.e. the main package has
+ the same name as the recipe and
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
evaluates to the recipe name).
- The order of the <filename>PACKAGES</filename> value is significant.
+ The order of the <filename>PACKAGES</filename> value is
+ significant.
For each installed file, the first package whose
- <filename>FILES</filename> value matches the file is the package
- into which the file goes.
+ <filename>FILES</filename> value matches the file is the
+ package into which the file goes.
Defaults exist for both the <filename>PACKAGES</filename> and
<filename>FILES</filename> variables.
Consequently, you might find you do not even need to set these
@@ -1511,29 +1648,29 @@
<filename>devtool deploy-target</filename> command.
Because the <filename>devtool deploy-target</filename> command
backs up any files it overwrites, you can use the
- <filename>devtool undeploy-target</filename> to restore those files
- and remove any other files the recipe deployed.
+ <filename>devtool undeploy-target</filename> command to restore
+ those files and remove any other files the recipe deployed.
Consider the following example:
<literallayout class='monospaced'>
$ devtool undeploy-target lighttpd root@192.168.7.2
</literallayout>
If you have deployed multiple applications, you can remove them
- all at once thus restoring the target device back to its
+ all using the "-a" option thus restoring the target device to its
original state:
<literallayout class='monospaced'>
$ devtool undeploy-target -a root@192.168.7.2
</literallayout>
Information about files deployed to the target as well as any
backed up files are stored on the target itself.
- This storage of course requires some additional space
+ This storage, of course, requires some additional space
on the target machine.
<note>
The <filename>devtool deploy-target</filename> and
- <filename>devtool undeploy-target</filename> command do not
+ <filename>devtool undeploy-target</filename> commands do not
currently interact with any package management system on the
target device (e.g. RPM or OPKG).
- Consequently, you should not intermingle operations
- <filename>devtool deploy-target</filename> and the package
+ Consequently, you should not intermingle
+ <filename>devtool deploy-target</filename> and package
manager operations on the target device.
Doing so could result in a conflicting set of files.
</note>
@@ -1544,16 +1681,14 @@
<title>Installing Additional Items Into the Extensible SDK</title>
<para>
- The extensible SDK typically only comes with a small number of tools
- and libraries out of the box.
- If you have a minimal SDK, then it starts mostly empty and is
- populated on-demand.
- However, sometimes you will need to explicitly install extra items
- into the SDK.
+ Out of the box the extensible SDK typically only comes with a small
+ number of tools and libraries.
+ A minimal SDK starts mostly empty and is populated on-demand.
+ Sometimes you must explicitly install extra items into the SDK.
If you need these extra items, you can first search for the items
using the <filename>devtool search</filename> command.
For example, suppose you need to link to libGL but you are not sure
- which recipe provides it.
+ which recipe provides libGL.
You can use the following command to find out:
<literallayout class='monospaced'>
$ devtool search libGL
@@ -1564,17 +1699,19 @@
<literallayout class='monospaced'>
$ devtool sdk-install mesa
</literallayout>
- By default, the <filename>devtool sdk-install</filename> assumes the
- item is available in pre-built form from your SDK provider.
+ By default, the <filename>devtool sdk-install</filename> command
+ assumes the item is available in pre-built form from your SDK
+ provider.
If the item is not available and it is acceptable to build the item
from source, you can add the "-s" option as follows:
<literallayout class='monospaced'>
$ devtool sdk-install -s mesa
</literallayout>
- It is important to remember that building the item from source takes
- significantly longer than installing the pre-built artifact.
- Also, if no recipe exists for the item you want to add to the SDK, you
- must instead add it using the <filename>devtool add</filename> command.
+ It is important to remember that building the item from source
+ takes significantly longer than installing the pre-built artifact.
+ Also, if no recipe exists for the item you want to add to the SDK,
+ you must instead add the item using the
+ <filename>devtool add</filename> command.
</para>
</section>
@@ -1612,31 +1749,34 @@
<para>
You might need to produce an SDK that contains your own custom
- libraries for sending to a third party (e.g., if you are a vendor with
- customers needing to build their own software for the target platform).
- If that is the case, then you can produce a derivative SDK based on
- the currently installed SDK fairly easily.
- Use these steps:
+ libraries.
+ A good example would be if you were a vendor with customers that
+ use your SDK to build their own platform-specific software and
+ those customers need an SDK that has custom libraries.
+ In such a case, you can produce a derivative SDK based on the
+ currently installed SDK fairly easily by following these steps:
<orderedlist>
- <listitem><para>If necessary, install an extensible SDK that
+ <listitem><para>
+ If necessary, install an extensible SDK that
you want to use as a base for your derivative SDK.
</para></listitem>
- <listitem><para>Source the environment script for the SDK.
+ <listitem><para>
+ Source the environment script for the SDK.
</para></listitem>
- <listitem><para>Add the extra libraries or other components
- you want by using the <filename>devtool add</filename>
- command.
+ <listitem><para>
+ Add the extra libraries or other components you want by
+ using the <filename>devtool add</filename> command.
</para></listitem>
- <listitem><para>Run the <filename>devtool build-sdk</filename>
- command.
+ <listitem><para>
+ Run the <filename>devtool build-sdk</filename> command.
</para></listitem>
</orderedlist>
- The above procedure takes the recipes added to the workspace and
- constructs a new SDK installer containing those recipes and the
+ The previous steps take the recipes added to the workspace and
+ construct a new SDK installer that contains those recipes and the
resulting binary artifacts.
The recipes go into their own separate layer in the constructed
- derivative SDK, leaving the workspace clean and ready for users
- to add their own recipes.
+ derivative SDK, which leaves the workspace clean and ready for
+ users to add their own recipes.
</para>
</section>
</chapter>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml
index b6925fa..8642be6 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml
@@ -31,15 +31,18 @@
<para>
All SDKs consist of the following:
<itemizedlist>
- <listitem><para><emphasis>Cross-Development Toolchain</emphasis>:
+ <listitem><para>
+ <emphasis>Cross-Development Toolchain</emphasis>:
This toolchain contains a compiler, debugger, and various
miscellaneous tools.
</para></listitem>
- <listitem><para><emphasis>Libraries, Headers, and Symbols</emphasis>:
+ <listitem><para>
+ <emphasis>Libraries, Headers, and Symbols</emphasis>:
The libraries, headers, and symbols are specific to the image
(i.e. they match the image).
</para></listitem>
- <listitem><para><emphasis>Environment Setup Script</emphasis>:
+ <listitem><para>
+ <emphasis>Environment Setup Script</emphasis>:
This <filename>*.sh</filename> file, once run, sets up the
cross-development environment by defining variables and
preparing for SDK use.
@@ -48,7 +51,7 @@
</para>
<para>
- Additionally an extensible SDK has tools that allow you to easily add
+ Additionally, an extensible SDK has tools that allow you to easily add
new applications and libraries to an image, modify the source of an
existing component, test changes on the target hardware, and easily
integrate an application into the
@@ -81,14 +84,15 @@
and
<ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
This reduces the space needed for the tools.
- Understand, however, that a sysroot is still needed for every target
- since those binaries are target-specific.
+ Understand, however, that every target still needs a sysroot because
+ those binaries are target-specific.
</para>
<para>
The SDK development environment consists of the following:
<itemizedlist>
- <listitem><para>The self-contained SDK, which is an
+ <listitem><para>
+ The self-contained SDK, which is an
architecture-specific cross-toolchain and
matching sysroots (target and native) all built by the
OpenEmbedded build system (e.g. the SDK).
@@ -100,21 +104,24 @@
Additionally, the extensible SDK contains the
<filename>devtool</filename> functionality.
</para></listitem>
- <listitem><para>The Quick EMUlator (QEMU), which lets you simulate
+ <listitem><para>
+ The Quick EMUlator (QEMU), which lets you simulate
target hardware.
QEMU is not literally part of the SDK.
You must build and include this emulator separately.
However, QEMU plays an important role in the development
process that revolves around use of the SDK.
</para></listitem>
- <listitem><para>The Eclipse IDE Yocto Plug-in.
+ <listitem><para>
+ The Eclipse IDE Yocto Plug-in.
This plug-in is available for you if you are an Eclipse
user.
In the same manner as QEMU, the plug-in is not literally part
of the SDK but is rather available for use as part of the
development process.
</para></listitem>
- <listitem><para>Various performance-related
+ <listitem><para>
+ Various performance-related
<ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink>
that can enhance your development experience.
These tools are also separate from the actual SDK but can be
@@ -192,11 +199,11 @@
</tgroup>
</informaltable>
<literallayout class='monospaced'>
- * Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
+ * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
- ** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
+ ** Sysroot is managed through the use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
- *** Runtime package management can be added to the standard SDK but it is not supported by default.
+ *** You can add runtime package management to the standard SDK but it is not supported by default.
**** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
</literallayout>
@@ -216,7 +223,7 @@
This toolchain is created by running a SDK installer script
or through a
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- that is based on your Metadata configuration or extension for
+ that is based on your metadata configuration or extension for
your targeted device.
The cross-toolchain works with a matching target sysroot.
</para>
@@ -230,7 +237,7 @@
for generating binaries that run on the target architecture.
The target sysroot is based on the target root filesystem image
that is built by the OpenEmbedded build system and uses the same
- Metadata configuration used to build the cross-toolchain.
+ metadata configuration used to build the cross-toolchain.
</para>
</section>
@@ -240,7 +247,8 @@
<para>
The QEMU emulator allows you to simulate your hardware while
running your application or image.
- QEMU is not part of the SDK but is made available a number of ways:
+ QEMU is not part of the SDK but is made available a number of
+ different ways:
<itemizedlist>
<listitem><para>
If you have cloned the <filename>poky</filename> Git
@@ -265,7 +273,7 @@
</section>
<section id='eclipse-overview'>
- <title>Eclipse Yocto Plug-in</title>
+ <title><trademark class='trade'>Eclipse</trademark> Yocto Plug-in</title>
<para>
The Eclipse IDE is a popular development environment and it fully
@@ -285,8 +293,8 @@
Previous releases of the Eclipse Yocto Plug-in supported
"user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap,
and Lttng-ust) that also added to the development experience.
- These tools have been deprecated beginning with this release
- of the plug-in.
+ These tools have been deprecated with the release of the
+ Eclipse Yocto Plug-in.
</note>
</para>
@@ -335,14 +343,18 @@
<para>
You just need to follow these general steps:
<orderedlist>
- <listitem><para><emphasis>Install the SDK for your target hardware:</emphasis>
+ <listitem><para>
+ <emphasis>Install the SDK for your target hardware:</emphasis>
For information on how to install the SDK, see the
"<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
- section.</para></listitem>
- <listitem><para><emphasis>Download or Build the Target Image:</emphasis>
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download or Build the Target Image:</emphasis>
The Yocto Project supports several target architectures
and has many pre-built kernel images and root filesystem
images.</para>
+
<para>If you are going to develop your application on
hardware, go to the
<ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
@@ -356,6 +368,7 @@
so forth.
Be sure to get the files you need for your particular
development process.</para>
+
<para>If you are going to develop your application and
then run and test it using the QEMU emulator, go to the
<ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
@@ -364,35 +377,35 @@
target architecture (e.g. <filename>qemux86_64</filename>
for an <trademark class='registered'>Intel</trademark>-based
64-bit architecture).
- Download kernel, root filesystem, and any other files you
+ Download the kernel, root filesystem, and any other files you
need for your process.
<note>
- To use the root filesystem in QEMU, you
- need to extract it.
+ To use the root filesystem in QEMU, you need to extract it.
See the
"<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
section for information on how to extract the root
filesystem.
</note>
</para></listitem>
- <listitem><para><emphasis>Develop and Test your
- Application:</emphasis> At this point, you have the tools
- to develop your application.
- If you need to separately install and use the QEMU
- emulator, you can go to
+ <listitem><para>
+ <emphasis>Develop and Test your Application:</emphasis>
+ At this point, you have the tools to develop your application.
+ If you need to separately install and use the QEMU emulator,
+ you can go to
<ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
to download and learn about the emulator.
See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
chapter in the Yocto Project Development Tasks Manual
for information on using QEMU within the Yocto
- Project.</para></listitem>
+ Project.
+ </para></listitem>
</orderedlist>
</para>
<para>
- The remainder of this manual describes how to use both the standard
- SDK and the extensible SDK.
+ The remainder of this manual describes how to use the extensible
+ and standard SDKs.
Information also exists in appendix form that describes how you can
build, install, and modify an SDK.
</para>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml
index 7fc0472..e858b9b 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml
@@ -52,14 +52,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -81,27 +76,38 @@
manual is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
-
</legalnotice>
</bookinfo>
@@ -122,7 +128,7 @@
<xi:include href="sdk-appendix-customizing-standard.xml"/>
- <xi:include href="sdk-appendix-mars.xml"/>
+ <xi:include href="sdk-appendix-neon.xml"/>
<!-- <index id='index'>
<title>Index</title>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml
index 7281e83..dd220c3 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml
@@ -19,9 +19,9 @@
<para>
You can use a standard SDK to work on Makefile, Autotools, and
- Eclipse-based projects.
+ <trademark class='trade'>Eclipse</trademark>-based projects.
See the
- "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>"
+ "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>"
chapter for more information.
</para>
@@ -53,24 +53,24 @@
<title>Installing the SDK</title>
<para>
- The first thing you need to do is install the SDK on your host
- development machine by running the <filename>*.sh</filename>
- installation script.
+ The first thing you need to do is install the SDK on your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink>
+ by running the <filename>*.sh</filename> installation script.
</para>
<para>
You can download a tarball installer, which includes the
pre-built toolchain, the <filename>runqemu</filename>
- script, and support files from the appropriate directory under
- <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
- Toolchains are available for 32-bit and 64-bit x86 development
- systems from the <filename>i686</filename> and
- <filename>x86_64</filename> directories, respectively.
+ script, and support files from the appropriate
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchain</ulink>
+ directory within the Index of Releases.
+ Toolchains are available for several 32-bit and 64-bit
+ architectures with the <filename>x86_64</filename> directories,
+ respectively.
The toolchains the Yocto Project provides are based off the
- <filename>core-image-sato</filename> image and contain
+ <filename>core-image-sato</filename> and
+ <filename>core-image-minimal</filename> images and contain
libraries appropriate for developing against that image.
- Each type of development system supports five or more target
- architectures.
</para>
<para>
@@ -86,14 +86,15 @@
i686 or x86_64.
- <replaceable>image_type</replaceable> is the image for which the SDK was built.
+ <replaceable>image_type</replaceable> is the image for which the SDK was built:
+
+ core-image-minimal or core-image-sato.
<replaceable>arch</replaceable> is a string representing the tuned target architecture:
- i586, x86_64, powerpc, mips, armv7a or armv5te
+ aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
- <replaceable>release_version</replaceable> is a string representing the release number of the
- Yocto Project:
+ <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project:
&DISTRO;, &DISTRO;+snapshot
</literallayout>
@@ -120,38 +121,36 @@
<para>
The SDK and toolchains are self-contained and by default are
- installed into <filename>/opt/poky</filename>.
- However, when you run the SDK installer, you can choose an
- installation directory.
- <note>
- You must change the permissions on the SDK
- installer script so that it is executable:
- <literallayout class='monospaced'>
- $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
- </literallayout>
- </note>
+ installed into the <filename>poky_sdk</filename> folder in your
+ home directory.
+ You can choose to install the extensible SDK in any location when
+ you run the installer.
+ However, because files need to be written under that directory
+ during the normal course of operation, the location you choose
+ for installation must be writable for whichever
+ users need to use the SDK.
</para>
<para>
The following command shows how to run the installer given a
toolchain tarball for a 64-bit x86 development host system and
- a 32-bit x86 target architecture.
+ a 64-bit x86 target architecture.
The example assumes the SDK installer is located in
- <filename>~/Downloads/</filename>.
+ <filename>~/Downloads/</filename> and has execution rights.
<note>
If you do not have write permissions for the directory
into which you are installing the SDK, the installer
notifies you and exits.
- Be sure you have write permissions in the directory and
- run the installer again.
+ For that case, set up the proper permissions in the directory
+ and run the installer again.
</note>
<literallayout class='monospaced'>
- $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+ $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
Poky (Yocto Project Reference Distro) SDK installer version &DISTRO;
===============================================================
Enter target directory for SDK (default: /opt/poky/&DISTRO;):
You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y
- Extracting SDK.......................................................................done
+ Extracting SDK........................................ ..............................done
Setting it up...done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
@@ -172,12 +171,11 @@
<para>
Once you have the SDK installed, you must run the SDK environment
- setup script before you can actually use it.
+ setup script before you can actually use the SDK.
This setup script resides in the directory you chose when you
- installed the SDK.
- For information on where this setup script can reside, see the
- "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
- Appendix.
+ installed the SDK, which is either the default
+ <filename>/opt/poky/&DISTRO;</filename> directory or the directory
+ you chose during installation.
</para>
<para>
@@ -186,9 +184,11 @@
Environment setup scripts begin with the string
"<filename>environment-setup</filename>" and include as part of
their name the tuned target architecture.
- For example, the command to source a setup script for an IA-based
- target machine using i586 tuning and located in the default SDK
- installation directory is as follows:
+ As an example, the following commands set the working directory
+ to where the SDK was installed and then source the environment
+ setup script.
+ In this example, the setup script is for an IA-based
+ target machine using i586 tuning:
<literallayout class='monospaced'>
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
</literallayout>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml
index 6965e3f..d8cc422 100644
--- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml
@@ -8,7 +8,7 @@
<para>
You can use the SDK toolchain directly with Makefile,
- Autotools, and <trademark class='trade'>Eclipse</trademark> based
+ Autotools, and <trademark class='trade'>Eclipse</trademark>-based
projects.
This chapter covers the first two, while the
"<link linkend='sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
@@ -19,263 +19,494 @@
<title>Autotools-Based Projects</title>
<para>
- Once you have a suitable cross-toolchain installed, it is very easy
- to develop a project outside of the OpenEmbedded build system.
- This section presents a simple "Helloworld" example that shows how
- to set up, compile, and run the project.
+ Once you have a suitable
+ <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>cross-development toolchain</ulink>
+ installed, it is very easy to develop a project using the
+ <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>GNU Autotools-based</ulink>
+ workflow, which is outside of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
</para>
- <section id='creating-and-running-a-project-based-on-gnu-autotools'>
- <title>Creating and Running a Project Based on GNU Autotools</title>
+ <para>
+ The following figure presents a simple Autotools workflow.
+ <imagedata fileref="figures/sdk-autotools-flow.png" width="7in" height="8in" align="center" />
+ </para>
- <para>
- Follow these steps to create a simple Autotools-based project:
- <orderedlist>
- <listitem><para>
- <emphasis>Create your directory:</emphasis>
- Create a clean directory for your project and then make
- that directory your working location:
- <literallayout class='monospaced'>
+ <para>
+ Follow these steps to create a simple Autotools-based
+ "Hello World" project:
+ <note>
+ For more information on the GNU Autotools workflow,
+ see the same example on the
+ <ulink url='https://developer.gnome.org/anjuta-build-tutorial/stable/create-autotools.html.en'>GNOME Developer</ulink>
+ site.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create a Working Directory and Populate It:</emphasis>
+ Create a clean directory for your project and then make
+ that directory your working location.
+ <literallayout class='monospaced'>
$ mkdir $HOME/helloworld
$ cd $HOME/helloworld
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Populate the directory:</emphasis>
- Create <filename>hello.c</filename>,
- <filename>Makefile.am</filename>,
- and <filename>configure.ac</filename> files as follows:
- <itemizedlist>
- <listitem><para>
- For <filename>hello.c</filename>, include
- these lines:
- <literallayout class='monospaced'>
+ </literallayout>
+ After setting up the directory, populate it with files
+ needed for the flow.
+ You need a project source file, a file to help with
+ configuration, and a file to help create the Makefile,
+ and a README file:
+ <filename>hello.c</filename>,
+ <filename>configure.ac</filename>,
+ <filename>Makefile.am</filename>, and
+ <filename>README</filename>, respectively.</para>
+
+ <para> Use the following command to create an empty README
+ file, which is required by GNU Coding Standards:
+ <literallayout class='monospaced'>
+ $ touch README
+ </literallayout>
+ Create the remaining three files as follows:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>hello.c</filename>:</emphasis>
+ <literallayout class='monospaced'>
#include <stdio.h>
main()
{
printf("Hello World!\n");
}
- </literallayout>
- </para></listitem>
- <listitem><para>
- For <filename>Makefile.am</filename>,
- include these lines:
- <literallayout class='monospaced'>
- bin_PROGRAMS = hello
- hello_SOURCES = hello.c
- </literallayout>
- </para></listitem>
- <listitem><para>
- For <filename>configure.in</filename>,
- include these lines:
- <literallayout class='monospaced'>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>configure.ac</filename>:</emphasis>
+ <literallayout class='monospaced'>
AC_INIT(hello,0.1)
AM_INIT_AUTOMAKE([foreign])
AC_PROG_CC
- AC_PROG_INSTALL
- AC_OUTPUT(Makefile)
- </literallayout>
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Source the cross-toolchain
- environment setup file:</emphasis>
- As described earlier in the manual, installing the
- cross-toolchain creates a cross-toolchain
- environment setup script in the directory that the SDK
- was installed.
- Before you can use the tools to develop your project,
- you must source this setup script.
- The script begins with the string "environment-setup"
- and contains the machine architecture, which is
- followed by the string "poky-linux".
- Here is an example that sources a script from the
- default SDK installation directory that uses the
- 32-bit Intel x86 Architecture and the
- &DISTRO_NAME; Yocto Project release:
- <literallayout class='monospaced'>
+ AC_CONFIG_FILES(Makefile)
+ AC_OUTPUT
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>Makefile.am</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ bin_PROGRAMS = hello
+ hello_SOURCES = hello.c
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Source the Cross-Toolchain
+ Environment Setup File:</emphasis>
+ As described earlier in the manual, installing the
+ cross-toolchain creates a cross-toolchain
+ environment setup script in the directory that the SDK
+ was installed.
+ Before you can use the tools to develop your project,
+ you must source this setup script.
+ The script begins with the string "environment-setup"
+ and contains the machine architecture, which is
+ followed by the string "poky-linux".
+ For this example, the command sources a script from the
+ default SDK installation directory that uses the
+ 32-bit Intel x86 Architecture and the
+ &DISTRO_NAME; Yocto Project release:
+ <literallayout class='monospaced'>
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Generate the local aclocal.m4
- files and create the configure script:</emphasis>
- The following GNU Autotools generate the local
- <filename>aclocal.m4</filename> files and create the
- configure script:
- <literallayout class='monospaced'>
- $ aclocal
- $ autoconf
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Generate files needed by GNU coding
- standards:</emphasis>
- GNU coding standards require certain files in order
- for the project to be compliant.
- This command creates those files:
- <literallayout class='monospaced'>
- $ touch NEWS README AUTHORS ChangeLog
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Generate the configure file:</emphasis>
- This command generates the
- <filename>configure</filename>:
- <literallayout class='monospaced'>
- $ automake -a
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Cross-compile the project:</emphasis>
- This command compiles the project using the
- cross-compiler.
- The
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
- environment variable provides the minimal arguments for
- GNU configure:
- <literallayout class='monospaced'>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create the <filename>configure</filename> Script:</emphasis>
+ Use the <filename>autoreconf</filename> command to
+ generate the <filename>configure</filename> script.
+ <literallayout class='monospaced'>
+ $ autoreconf
+ </literallayout>
+ The <filename>autoreconf</filename> tool takes care
+ of running the other Autotools such as
+ <filename>aclocal</filename>,
+ <filename>autoconf</filename>, and
+ <filename>automake</filename>.
+ <note>
+ If you get errors from
+ <filename>configure.ac</filename>, which
+ <filename>autoreconf</filename> runs, that indicate
+ missing files, you can use the "-i" option, which
+ ensures missing auxiliary files are copied to the build
+ host.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Cross-Compile the Project:</emphasis>
+ This command compiles the project using the
+ cross-compiler.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
+ environment variable provides the minimal arguments for
+ GNU configure:
+ <literallayout class='monospaced'>
$ ./configure ${CONFIGURE_FLAGS}
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Make and install the project:</emphasis>
- These two commands generate and install the project
- into the destination directory:
- <literallayout class='monospaced'>
+ </literallayout>
+ For an Autotools-based project, you can use the
+ cross-toolchain by just passing the appropriate host
+ option to <filename>configure.sh</filename>.
+ The host option you use is derived from the name of the
+ environment setup script found in the directory in which
+ you installed the cross-toolchain.
+ For example, the host option for an ARM-based target that
+ uses the GNU EABI is
+ <filename>armv5te-poky-linux-gnueabi</filename>.
+ You will notice that the name of the script is
+ <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+ Thus, the following command works to update your project
+ and rebuild it using the appropriate cross-toolchain tools:
+ <literallayout class='monospaced'>
+ $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make and Install the Project:</emphasis>
+ These two commands generate and install the project
+ into the destination directory:
+ <literallayout class='monospaced'>
$ make
$ make install DESTDIR=./tmp
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Verify the installation:</emphasis>
- This command is a simple way to verify the installation
- of your project.
- Running the command prints the architecture on which
- the binary file can run.
- This architecture should be the same architecture that
- the installed cross-toolchain supports.
- <literallayout class='monospaced'>
- $ file ./tmp/usr/local/bin/hello
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Execute your project:</emphasis>
- To execute the project in the shell, simply enter
- the name.
- You could also copy the binary to the actual target
- hardware and run the project there as well:
- <literallayout class='monospaced'>
- $ ./hello
- </literallayout>
- As expected, the project displays the "Hello World!"
- message.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='passing-host-options'>
- <title>Passing Host Options</title>
-
- <para>
- For an Autotools-based project, you can use the cross-toolchain
- by just passing the appropriate host option to
- <filename>configure.sh</filename>.
- The host option you use is derived from the name of the
- environment setup script found in the directory in which you
- installed the cross-toolchain.
- For example, the host option for an ARM-based target that uses
- the GNU EABI is <filename>armv5te-poky-linux-gnueabi</filename>.
- You will notice that the name of the script is
- <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
- Thus, the following command works to update your project and
- rebuild it using the appropriate cross-toolchain tools:
- <literallayout class='monospaced'>
- $ ./configure --host=armv5te-poky-linux-gnueabi \
- --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
- </literallayout>
- <note>
- If the <filename>configure</filename> script results in
- problems recognizing the
- <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable>
- option, regenerate the script to enable the support by
- doing the following and then run the script again:
- <literallayout class='monospaced'>
- $ libtoolize --automake
- $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
- $ autoconf
- $ autoheader
- $ automake -a
</literallayout>
- </note>
- </para>
- </section>
+ <note>
+ To learn about environment variables established
+ when you run the cross-toolchain environment setup
+ script and how they are used or overridden when
+ the Makefile, see the
+ "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
+ section.
+ </note>
+ This next command is a simple way to verify the
+ installation of your project.
+ Running the command prints the architecture on which
+ the binary file can run.
+ This architecture should be the same architecture that
+ the installed cross-toolchain supports.
+ <literallayout class='monospaced'>
+ $ file ./tmp/usr/local/bin/hello
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Execute Your Project:</emphasis>
+ To execute the project, you would need to run it on your
+ target hardware.
+ If your target hardware happens to be your build host,
+ you could run the project as follows:
+ <literallayout class='monospaced'>
+ $ ./tmp/usr/local/bin/hello
+ </literallayout>
+ As expected, the project displays the "Hello World!"
+ message.
+ </para></listitem>
+ </orderedlist>
+ </para>
</section>
<section id='makefile-based-projects'>
<title>Makefile-Based Projects</title>
<para>
- For Makefile-based projects, the cross-toolchain environment
- variables established by running the cross-toolchain environment
- setup script are subject to general <filename>make</filename>
- rules.
+ Simple Makefile-based projects use and interact with the
+ cross-toolchain environment variables established when you run
+ the cross-toolchain environment setup script.
+ The environment variables are subject to general
+ <filename>make</filename> rules.
</para>
<para>
- To illustrate this, consider the following four cross-toolchain
- environment variables:
- <literallayout class='monospaced'>
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
- </literallayout>
- Now, consider the following three cases:
+ This section presents a simple Makefile development flow and
+ provides an example that lets you see how you can use
+ cross-toolchain environment variables and Makefile variables
+ during development.
+ <imagedata fileref="figures/sdk-makefile-flow.png" width="6in" height="7in" align="center" />
+ </para>
+
+ <para>
+ The main point of this section is to explain the following three
+ cases regarding variable behavior:
<itemizedlist>
<listitem><para>
<emphasis>Case 1 - No Variables Set in the
- <filename>Makefile</filename>:</emphasis>
- Because these variables are not specifically set in the
+ <filename>Makefile</filename> Map to Equivalent
+ Environment Variables Set in the SDK Setup Script:</emphasis>
+ Because matching variables are not specifically set in the
<filename>Makefile</filename>, the variables retain their
- values based on the environment.
+ values based on the environment setup script.
</para></listitem>
<listitem><para>
- <emphasis>Case 2 - Variables Set in the
- <filename>Makefile</filename>:</emphasis>
- Specifically setting variables in the
+ <emphasis>Case 2 - Variables Are Set in the Makefile that
+ Map to Equivalent Environment Variables from the SDK
+ Setup Script:</emphasis>
+ Specifically setting matching variables in the
<filename>Makefile</filename> during the build results in
the environment settings of the variables being
overwritten.
+ In this case, the variables you set in the
+ <filename>Makefile</filename> are used.
</para></listitem>
<listitem><para>
- <emphasis>Case 3 - Variables Set when the
- <filename>Makefile</filename> is Executed from the
- Command Line:</emphasis>
+ <emphasis>Case 3 - Variables Are Set Using the Command Line
+ that Map to Equivalent Environment Variables from the
+ SDK Setup Script:</emphasis>
Executing the <filename>Makefile</filename> from the
- command-line results in the variables being overwritten
- with command-line content regardless of what is being set
- in the <filename>Makefile</filename>.
- In this case, environment variables are not considered
- unless you use the "-e" flag during the build:
- <literallayout class='monospaced'>
- $ make -e <replaceable>file</replaceable>
- </literallayout>
- If you use this flag, then the environment values of the
- variables override any variables specifically set in the
- <filename>Makefile</filename>.
+ command line results in the environment variables being
+ overwritten.
+ In this case, the command-line content is used.
</para></listitem>
</itemizedlist>
<note>
- For the list of variables set up by the cross-toolchain
- environment setup script, see the
- "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
- section.
+ Regardless of how you set your variables, if you use
+ the "-e" option with <filename>make</filename>, the
+ variables from the SDK setup script take precedence:
+ <literallayout class='monospaced'>
+ $ make -e <replaceable>target</replaceable>
+ </literallayout>
</note>
</para>
+
+ <para>
+ The remainder of this section presents a simple Makefile example
+ that demonstrates these variable behaviors.
+ </para>
+
+ <para>
+ In a new shell environment variables are not established for the
+ SDK until you run the setup script.
+ For example, the following commands show a null value for the
+ compiler variable (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>).
+ <literallayout class='monospaced'>
+ $ echo ${CC}
+
+ $
+ </literallayout>
+ Running the SDK setup script for a 64-bit build host and an
+ i586-tuned target architecture for a
+ <filename>core-image-sato</filename> image using the current
+ &DISTRO; Yocto Project release and then echoing that variable
+ shows the value established through the script:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ $ echo ${CC}
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
+ </literallayout>
+ </para>
+
+ <para>
+ To illustrate variable use, work through this simple "Hello World!"
+ example:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create a Working Directory and Populate It:</emphasis>
+ Create a clean directory for your project and then make
+ that directory your working location.
+ <literallayout class='monospaced'>
+ $ mkdir $HOME/helloworld
+ $ cd $HOME/helloworld
+ </literallayout>
+ After setting up the directory, populate it with files
+ needed for the flow.
+ You need a <filename>main.c</filename> file from which you
+ call your function, a <filename>module.h</filename> file
+ to contain headers, and a <filename>module.c</filename>
+ that defines your function.
+ </para>
+
+ <para>Create the three files as follows:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>main.c</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include "module.h"
+ void sample_func();
+ int main()
+ {
+ sample_func();
+ return 0;
+ }
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>module.h</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include <stdio.h>
+ void sample_func();
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>module.c</filename>:</emphasis>
+ <literallayout class='monospaced'>
+ #include "module.h"
+ void sample_func()
+ {
+ printf("Hello World!");
+ printf("\n");
+ }
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Source the Cross-Toolchain Environment Setup File:</emphasis>
+ As described earlier in the manual, installing the
+ cross-toolchain creates a cross-toolchain environment setup
+ script in the directory that the SDK was installed.
+ Before you can use the tools to develop your project,
+ you must source this setup script.
+ The script begins with the string "environment-setup"
+ and contains the machine architecture, which is
+ followed by the string "poky-linux".
+ For this example, the command sources a script from the
+ default SDK installation directory that uses the
+ 32-bit Intel x86 Architecture and the
+ &DISTRO_NAME; Yocto Project release:
+ <literallayout class='monospaced'>
+ $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create the <filename>Makefile</filename>:</emphasis>
+ For this example, the Makefile contains two lines that
+ can be used to set the <filename>CC</filename> variable.
+ One line is identical to the value that is set when you
+ run the SDK environment setup script, and the other line
+ sets <filename>CC</filename> to "gcc", the default GNU
+ compiler on the build host:
+ <literallayout class='monospaced'>
+ # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
+ # CC="gcc"
+ all: main.o module.o
+ ${CC} main.o module.o -o target_bin
+ main.o: main.c module.h
+ ${CC} -I . -c main.c
+ module.o: module.c module.h
+ ${CC} -I . -c module.c
+ clean:
+ rm -rf *.o
+ rm target_bin
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make the Project:</emphasis>
+ Use the <filename>make</filename> command to create the
+ binary output file.
+ Because variables are commented out in the Makefile,
+ the value used for <filename>CC</filename> is the value
+ set when the SDK environment setup file was run:
+ <literallayout class='monospaced'>
+ $ make
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+ </literallayout>
+ From the results of the previous command, you can see that
+ the compiler used was the compiler established through
+ the <filename>CC</filename> variable defined in the
+ setup script.</para>
+
+ <para>You can override the <filename>CC</filename>
+ environment variable with the same variable as set from
+ the Makefile by uncommenting the line in the Makefile
+ and running <filename>make</filename> again.
+ <literallayout class='monospaced'>
+ $ make clean
+ rm -rf *.o
+ rm target_bin
+ #
+ # Edit the Makefile by uncommenting the line that sets CC to "gcc"
+ #
+ $ make
+ gcc -I . -c main.c
+ gcc -I . -c module.c
+ gcc main.o module.o -o target_bin
+ </literallayout>
+ As shown in the previous example, the cross-toolchain
+ compiler is not used.
+ Rather, the default compiler is used.</para>
+
+ <para>This next case shows how to override a variable
+ by providing the variable as part of the command line.
+ Go into the Makefile and re-insert the comment character
+ so that running <filename>make</filename> uses
+ the established SDK compiler.
+ However, when you run <filename>make</filename>, use a
+ command-line argument to set <filename>CC</filename>
+ to "gcc":
+ <literallayout class='monospaced'>
+ $ make clean
+ rm -rf *.o
+ rm target_bin
+ #
+ # Edit the Makefile to comment out the line setting CC to "gcc"
+ #
+ $ make
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+ $ make clean
+ rm -rf *.o
+ rm target_bin
+ $ make CC="gcc"
+ gcc -I . -c main.c
+ gcc -I . -c module.c
+ gcc main.o module.o -o target_bin
+ </literallayout>
+ In the previous case, the command-line argument overrides
+ the SDK environment variable.</para>
+
+ <para>In this last case, edit Makefile again to use the
+ "gcc" compiler but then use the "-e" option on the
+ <filename>make</filename> command line:
+ <literallayout class='monospaced'>
+ $ make clean
+ rm -rf *.o
+ rm target_bin
+ #
+ # Edit the Makefile to use "gcc"
+ #
+ $ make
+ gcc -I . -c main.c
+ gcc -I . -c module.c
+ gcc main.o module.o -o target_bin
+ $ make clean
+ rm -rf *.o
+ rm target_bin
+ $ make -e
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+ </literallayout>
+ In the previous case, the "-e" option forces
+ <filename>make</filename> to use the SDK environment
+ variables regardless of the values in the Makefile.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Execute Your Project:</emphasis>
+ To execute the project (i.e.
+ <filename>target_bin</filename>), use the following
+ command:
+ <literallayout class='monospaced'>
+ $ ./target_bin
+ Hello World!
+ </literallayout>
+ <note>
+ If you used the cross-toolchain compiler to build
+ <filename>target_bin</filename> and your build host
+ differs in architecture from that of the target
+ machine, you need to run your project on the target
+ device.
+ </note>
+ As expected, the project displays the "Hello World!"
+ message.
+ </para></listitem>
+ </orderedlist>
+ </para>
</section>
</chapter>
<!--
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml
index 4e59e00..e84964c 100644
--- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml
+++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml
@@ -38,7 +38,7 @@
Browse layers listed in the various
<link linkend='layer-source'>layer sources</link>
that are available in your project (e.g. the
- OpenEmbedded Metadata Index at
+ OpenEmbedded Layer Index at
<ulink url='http://layers.openembedded.org/layerindex/'></ulink>).
</para></listitem>
<listitem><para>
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml
index e984391..7440580 100644
--- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml
+++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml
@@ -34,7 +34,7 @@
A layer index is a web application that contains information
about a set of custom layers.
A good example of an existing layer index is the
- OpenEmbedded Metadata Index.
+ OpenEmbedded Layer Index.
A public instance of this layer index exists at
<ulink url='http://layers.openembedded.org'></ulink>.
You can find the code for this layer index's web application at
@@ -92,11 +92,11 @@
<para>
For general information on layers, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
- sections in the Yocto Project Board Support Package (BSP)
- Developer's Guide.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ For information on how to create layers, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+ section in the Yocto Project Development Tasks Manual.
</para>
</section>
@@ -681,26 +681,27 @@
(e.g. <filename>poky</filename>) at
<filename>bitbake/lib/manage.py</filename>.
This section documents those commands.
- <note>
- <para>
- When using <filename>manage.py</filename> commands given
- a default configuration, you must be sure that your
- working directory is set to the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
- Using <filename>manage.py</filename> commands from the
- Build Directory allows Toaster to find the
- <filename>toaster.sqlite</filename> file, which is located
- in the Build Directory.
- </para>
-
- <para>
- For non-default database configurations, it is possible
- that you can use <filename>manage.py</filename> commands
- from a directory other than the Build directory.
- To do so, the
- <filename>toastermain/settings.py</filename> file must be
- configured to point to the correct database backend.
- </para>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ When using <filename>manage.py</filename> commands given
+ a default configuration, you must be sure that your
+ working directory is set to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ Using <filename>manage.py</filename> commands from the
+ Build Directory allows Toaster to find the
+ <filename>toaster.sqlite</filename> file, which is located
+ in the Build Directory.
+ </para></listitem>
+ <listitem><para>
+ For non-default database configurations, it is possible
+ that you can use <filename>manage.py</filename> commands
+ from a directory other than the Build Directory.
+ To do so, the
+ <filename>toastermain/settings.py</filename> file must be
+ configured to point to the correct database backend.
+ </para></listitem>
+ </itemizedlist>
</note>
</para>
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml
index c26a32a..b4caebb 100644
--- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml
+++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml
@@ -11,9 +11,9 @@
<para>
Once you have set up the Yocto Project and installed the
- Toaster system dependencies as described in
- "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>",
- you are ready to start Toaster.
+ Toaster system dependencies as described in the
+ "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
+ chapter, you are ready to start Toaster.
</para>
<para>
@@ -61,6 +61,71 @@
</para>
</section>
+ <section id='setting-up-toaster-without-a-web-server'>
+ <title>Setting Up Toaster Without a Web Server</title>
+
+ <para>
+ You can start a Toaster environment without starting its
+ web server. This is useful for the following:
+ <itemizedlist>
+ <listitem><para>
+ Capturing a command-line build’s statistics into
+ the Toaster database for examination later.
+ </para></listitem>
+ <listitem><para>
+ Capturing a command-line build’s statistics when
+ the Toaster server is already running.
+ </para></listitem>
+ <listitem><para>
+ Having one instance of the Toaster web server
+ track and capture multiple command-line builds,
+ where each build is started in its own “noweb”
+ Toaster environment.
+ </para></listitem>
+ </itemizedlist>
+ The following commands show how to start a Toaster environment
+ without starting its web server, perform BitBake operations,
+ and then shut down the Toaster environment.
+ Once the build is complete, you can close the Toaster environment.
+ Before closing the environment, however, you should allow a few
+ minutes to ensure the complete transfer of its BitBake build
+ statistics to the Toaster database.
+ If you have a separate Toaster web server instance running, you
+ can watch this command-line build’s progress and examine the
+ results as soon as they are posted:
+ <literallayout class='monospaced'>
+ $ source toaster start noweb
+ $ bitbake <replaceable>target</replaceable>
+ $ source toaster stop
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='setting-up-toaster-without-a-build-server'>
+ <title>Setting Up Toaster Without a Build Server</title>
+
+ <para>
+ You can start a Toaster environment with the
+ “New Projects” feature disabled.
+ Doing so is useful for the following:
+ <itemizedlist>
+ <listitem><para>
+ Sharing your build results over the web server while
+ blocking others from starting builds on your host.
+ </para></listitem>
+ <listitem><para>
+ Allowing only local command-line builds to be captured
+ into the Toaster database.
+ </para></listitem>
+ </itemizedlist>
+ Use the following command to set up Toaster without a
+ build server:
+ <literallayout class='monospaced'>
+ $ source toaster start nobuild webport=<replaceable>port</replaceable>
+ </literallayout>
+ </para>
+ </section>
+
<section id='setting-up-external-access'>
<title>Setting up External Access</title>
@@ -227,8 +292,8 @@
</note>
<itemizedlist>
<listitem><para>
- Have all the build requirements as described in
- "<link linkend='toaster-setting-up-the-basic-system-requirements'>Setting Up the Basic System Requirements</link>"
+ Have all the build requirements as described in the
+ "<link linkend='toaster-manual-start'>Preparing to Use Toaster</link>"
chapter.
</para></listitem>
<listitem><para>
@@ -312,7 +377,7 @@
<itemizedlist>
<listitem><para>
Edit the
- <ulink url='http://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-SECRET_KEY'>DATABASE</ulink>
+ <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#databases'>DATABASES</ulink>
settings:
<literallayout class='monospaced'>
DATABASES = {
@@ -329,14 +394,14 @@
</para></listitem>
<listitem><para>
Edit the
- <ulink url='http://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>:
+ <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>:
<literallayout class='monospaced'>
SECRET_KEY = '<replaceable>your_secret_key</replaceable>'
</literallayout>
</para></listitem>
<listitem><para>
Edit the
- <ulink url='http://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-SECRET_KEY'>STATIC_ROOT</ulink>:
+ <ulink url='https://docs.djangoproject.com/en/1.11/ref/settings/#std:setting-STATIC_ROOT'>STATIC_ROOT</ulink>:
<literallayout class='monospaced'>
STATIC_ROOT = '/var/www/toaster/static_files/'
</literallayout>
@@ -360,58 +425,68 @@
<literallayout class='monospaced'>
$ cd /var/www/toaster/poky/
$ ./bitbake/lib/toaster/manage.py migrate
- $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-poky/conf/toasterconf.json \
+ $ TOASTER_DIR=`pwd` TEMPLATECONF='poky' \
./bitbake/lib/toaster/manage.py checksettings
$ ./bitbake/lib/toaster/manage.py collectstatic
</literallayout>
- </para>
+ In the previous example, from the <filename>poky</filename>
+ directory, the <filename>migrate</filename> command
+ ensures the database schema changes have propagated
+ correctly (i.e. migrations).
+ The next line sets the Toaster root directory
+ <filename>TOASTER_DIR</filename> and the location
+ of the Toaster configuration file
+ <filename>TOASTER_CONF</filename>, which is relative to
+ <filename>TOASTER_DIR</filename>.
+ The <filename>TEMPLATECONF</filename> value reflects the
+ contents of <filename>poky/.templateconf</filename>, and
+ by default, should include the string "poky".
+ For more information on the Toaster configuration
+ file, see the
+ "<link linkend='configuring-toaster'>Configuring Toaster</link>"
+ section.</para>
- <para>
- For the above set of commands, after moving to the
- <filename>poky</filename> directory,
- the <filename>migrate</filename>
- command ensures the database
- schema has had changes propagated correctly (i.e.
- migrations).
- </para>
-
- <para>
- The next line sets the Toaster root directory
- <filename>TOASTER_DIR</filename> and the location of
- the Toaster configuration file
- <filename>TOASTER_CONF</filename>, which is
- relative to the Toaster root directory
- <filename>TOASTER_DIR</filename>.
- For more information on the Toaster configuration file,
- see the
- <link linkend='configuring-toaster'>Configuring Toaster</link>
- chapter.
- </para>
-
- <para>
- This line also runs the <filename>checksettings</filename>
- command, which configures the location of the Toaster
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build directory</ulink>.
- The Toaster root directory <filename>TOASTER_DIR</filename>
- determines where the Toaster build directory
- is created on the file system.
- In the example above,
- <filename>TOASTER_DIR</filename> is set as follows:
- <literallayout class="monospaced">
+ <para>This line also runs the <filename>checksettings</filename>
+ command, which configures the location of the Toaster
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ The Toaster root directory <filename>TOASTER_DIR</filename>
+ determines where the Toaster build directory
+ is created on the file system.
+ In the example above,
+ <filename>TOASTER_DIR</filename> is set as follows:
+ <literallayout class="monospaced">
/var/www/toaster/poky
- </literallayout>
- This setting causes the Toaster build directory to be:
- <literallayout class="monospaced">
+ </literallayout>
+ This setting causes the Toaster build directory to be:
+ <literallayout class="monospaced">
/var/www/toaster/poky/build
- </literallayout>
- </para>
+ </literallayout></para>
- <para>
- Finally, the <filename>collectstatic</filename> command
- is a Django framework command that collects all the
- statically served files into a designated directory to
- be served up by the Apache web server as defined by
- <filename>STATIC_ROOT</filename>.
+ <para>Finally, the <filename>collectstatic</filename> command
+ is a Django framework command that collects all the
+ statically served files into a designated directory to
+ be served up by the Apache web server as defined by
+ <filename>STATIC_ROOT</filename>.
+ </para></listitem>
+ <listitem><para>
+ Test and/or use the Mysql integration with Toaster’s
+ Django web server.
+ At this point, you can start up the normal Toaster
+ Django web server with the Toaster database in Mysql.
+ You can use this web server to confirm that the database
+ migration and data population from the Layer Index is
+ complete.</para>
+
+ <para>To start the default Toaster Django web server with
+ the Toaster database now in Mysql, use the standard
+ start commands:
+ <literallayout class='monospaced'>
+ $ source oe-init-build-env
+ $ source toaster start
+ </literallayout>
+ Additionally, if Django is sufficient for your requirements,
+ you can use it for your release system and migrate later
+ to Apache as your requirements change.
</para></listitem>
<listitem><para>
Add an Apache configuration file for Toaster to your Apache web
@@ -535,7 +610,7 @@
<itemizedlist>
<listitem><para>
Browse published layers in the
- <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink>
+ <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink>
that are available for your selected version of the build
system.
</para></listitem>
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml
index 65e057a..45f6046 100644
--- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml
+++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml
@@ -18,10 +18,9 @@
Before you can use Toaster, you need to first set up your
build system to run the Yocto Project.
To do this, follow the instructions in the
- "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_QS_URL;#releases'>Yocto Project Release</ulink>"
- sections in the Yocto Project Quick Start.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
+ section of the Yocto Project Development Tasks
+ Manual.
For Ubuntu/Debian, you might also need to do an additional install
of pip3.
<literallayout class='monospaced'>
diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml
index 5a1b60e..1888744 100644
--- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml
+++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml
@@ -62,14 +62,9 @@
<revremark>Released with the Yocto Project 2.4 Release.</revremark>
</revision>
<revision>
- <revnumber>2.4.1</revnumber>
- <date>January 2018</date>
- <revremark>Released with the Yocto Project 2.4.1 Release.</revremark>
- </revision>
- <revision>
- <revnumber>2.4.2</revnumber>
- <date>March 2018</date>
- <revremark>Released with the Yocto Project 2.4.2 Release.</revremark>
+ <revnumber>2.5</revnumber>
+ <date>May 2018</date>
+ <revremark>Released with the Yocto Project 2.5 Release.</revremark>
</revision>
</revhistory>
@@ -91,24 +86,36 @@
is for the &YOCTO_DOC_VERSION; release of the
Yocto Project.
To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
+ for this release, go to the
<ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
+ and select the manual from that site.
+ Manuals from the site are more up-to-date than manuals
+ derived from the Yocto Project released TAR files.
</para></listitem>
<listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
+ If you located this manual through a web search, the
+ version of the manual might not be the one you want
+ (e.g. the search might have returned a manual much
+ older than the Yocto Project version with which you
+ are working).
+ You can see all Yocto Project major releases by
+ visiting the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+ page.
+ If you need a version of this manual for a different
+ Yocto Project release, visit the
+ <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+ and select the manual set by using the
+ "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+ pull-down menus.
+ </para></listitem>
+ <listitem><para>
+ To report any inaccuracies or problems with this
+ manual, send an email to the Yocto Project
+ discussion group at
+ <filename>yocto@yoctoproject.com</filename> or log into
+ the freenode <filename>#yocto</filename> channel.
+ </para></listitem>
</itemizedlist>
</note>
diff --git a/import-layers/yocto-poky/documentation/tools/eclipse-help.sed b/import-layers/yocto-poky/documentation/tools/eclipse-help.sed
index 38690bc..ab5c9af 100644
--- a/import-layers/yocto-poky/documentation/tools/eclipse-help.sed
+++ b/import-layers/yocto-poky/documentation/tools/eclipse-help.sed
@@ -1,18 +1,18 @@
-# Processes poky-ref-manual and yocto-project-qs manual (<word>-<word>-<word> style)
+# Process poky-ref-manual and yocto-project-qs manual (<word>-<word>-<word> style)
# For example:
# "ulink" href="http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#faq"
# -> "link" href="../poky-ref-manual/faq.html"
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*-[a-z]*\)\/[a-z]*-[a-z]*-[a-z]*.html#\([^\"]*\)\"/\"link\" href=\"\.\.\/\1\/\2.html\"/g
+s@"ulink" href="http://www.yoctoproject.org/docs/[^/]*/([a-z]*-[a-z]*-[a-z]*)/[a-z]*-[a-z]*-[a-z]*.html#([^"]*)"/@"link" href="../1/2.html"@g
# Processes all other manuals (<word>-<word> style)
# For example:
# "ulink" href="http://www.yoctoproject.org/docs/1.3/kernel-manual/kernel-manual.html#faq"
# -> "link" href="../kernel-manual/faq.html"
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*\)\/[a-z]*-[a-z]*.html#\([^\"]*\)\"/\"link\" href=\"\.\.\/\1\/\2.html\"/g
+s@"ulink" href="http://www.yoctoproject.org/docs/[^/]*/([a-z]*-[a-z]*)/[a-z]*-[a-z]*.html#([^"]*)"@"link" href="../1/2.html"@g
# Process cases where just an external manual is referenced without an id anchor
# For example:
# "ulink" href="http://www.yoctoproject.org/docs/1.3/kernel-manual/kernel-manual.html
# -> "link" href="../kernel-manual/index.html"
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*-[a-z]*\)\/[a-z]*-[a-z]*-[a-z]*.html\"/\"link\" href=\"\.\.\/\1\/index.html\"/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*\)\/[a-z]*-[a-z]*.html\"/\"link\" href=\"\.\.\/\1\/index.html\"/g
+s@"ulink" href="http://www.yoctoproject.org/docs/[^/]*/([a-z]*-[a-z]*-[a-z]*)/[a-z]*-[a-z]*-[a-z]*.html"@"link" href="../1/index.html"@g
+s@"ulink" href="http://www.yoctoproject.org/docs/[^/]*/([a-z]*-[a-z]*)/[a-z]*-[a-z]*.html"@"link" href="../1/index.html"@g
diff --git a/import-layers/yocto-poky/documentation/tools/mega-manual.sed b/import-layers/yocto-poky/documentation/tools/mega-manual.sed
index ae2800c..64fa4d2 100644
--- a/import-layers/yocto-poky/documentation/tools/mega-manual.sed
+++ b/import-layers/yocto-poky/documentation/tools/mega-manual.sed
@@ -2,32 +2,39 @@
# This style is for manual folders like "yocto-project-qs" and "poky-ref-manual".
# This is the old way that did it. Can't do that now that we have "bitbake-user-manual" strings
# in the mega-manual.
-# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g
+# s@"ulink" href="http://www.yoctoproject.org/docs/2.5/[a-z]*-[a-z]*-[a-z]*/[a-z]*-[a-z]*-[a-z]*.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/yocto-project-qs/yocto-project-qs.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/poky-ref-manual/poky-ref-manual.html#@"link" href="#@g
# Processes all other manuals (<word>-<word> style) except for the BitBake User Manual because
# it is not included in the mega-manual.
# This style is for manual folders that use two word, which is the standard now (e.g. "ref-manual").
# This was the one-liner that worked before we introduced the BitBake User Manual, which is
# not in the mega-manual.
-# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g
+# s@"ulink" href="http://www.yoctoproject.org/docs/2.5/[a-z]*-[a-z]*/[a-z]*-[a-z]*.html#@"link" href="#@g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/sdk-manual\/sdk-manual.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/toaster-manual\/toaster-manual.html#/\"link\" href=\"#/g
-s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/bsp-guide/bsp-guide.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/overview-manual/overview-manual.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/brief-yoctoprojectqs/brief-yoctoprojectqs.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/kernel-dev/kernel-dev.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/profile-manual/profile-manual.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html#@"link" href="#@g
+s@"ulink" href="http://www.yoctoproject.org/docs/2.5/toaster-manual/toaster-manual.html#@"link" href="#@g
# Process cases where just an external manual is referenced without an id anchor
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Tasks Manual<\/a>/Yocto Project Development Tasks Manual/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/sdk-manual\/sdk-manual.html\" target=\"_top\">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)<\/a>/Yocto Project Application Development and the Extensible Software Development Kit (eSDK)/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/profile-manual\/profile-manual.html\" target=\"_top\">Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g
-s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.4.2\/toaster-manual\/toaster-manual.html\" target=\"_top\">Toaster User Manual<\/a>/Toaster User Manual/g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/brief-yoctoprojectqs/brief-yoctoprojectqs.html" target="_top">Yocto Project Quick Build</a>@Yocto Project Quick Build@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/yocto-project-qs/yocto-project-qs.html" target="_top">Yocto Project Quick Start</a>@Yocto Project Quick Start@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/dev-manual/dev-manual.html" target="_top">Yocto Project Development Tasks Manual</a>@Yocto Project Development Tasks Manual@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/overview-manual/overview-manual.html" target="_top">Yocto Project Overview and Concepts Manual</a>@Yocto project Overview and Concepts Manual@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html" target="_top">Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</a>@Yocto Project Application Development and the Extensible Software Development Kit (eSDK)@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>@Yocto Project Board Support Package (BSP) Developer's Guide@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/profile-manual/profile-manual.html" target="_top">Yocto Project Profiling and Tracing Manual</a>@Yocto Project Profiling and Tracing Manual@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/kernel-dev/kernel-dev.html" target="_top">Yocto Project Linux Kernel Development Manual</a>@Yocto Project Linux Kernel Development Manual@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/ref-manual/ref-manual.html" target="_top">Yocto Project Reference Manual</a>@Yocto Project Reference Manual@g
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/toaster-manual/toaster-manual.html" target="_top">Toaster User Manual</a>@Toaster User Manual@g
+
+# Process a single, rouge occurrence of a linked reference to the Mega-Manual.
+s@<a class="ulink" href="http://www.yoctoproject.org/docs/2.5/mega-manual/mega-manual.html" target="_top">Yocto Project Mega-Manual</a>@Yocto Project Mega-Manual@g
+
diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml b/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml
deleted file mode 100644
index e6dae7f..0000000
--- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml
+++ /dev/null
@@ -1,1056 +0,0 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<article id='yocto-project-qs-intro'>
- <articleinfo>
- <title>Yocto Project Quick Start</title>
-
- <copyright>
- <year>©RIGHT_YEAR;</year>
- <holder>Linux Foundation</holder>
- </copyright>
-
- <legalnotice>
- <para>
- Permission is granted to copy, distribute and/or modify this document under
- the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.
- </para>
- <note><title>Manual Notes</title>
- <itemizedlist>
- <listitem><para>
- This version of the
- <emphasis>Yocto Project Quick Start</emphasis>
- is for the &YOCTO_DOC_VERSION; release of the
- Yocto Project.
- To be sure you have the latest version of the manual
- for this release, use the manual from the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
- </para></listitem>
- <listitem><para>
- For manuals associated with other releases of the Yocto
- Project, go to the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
- and use the drop-down "Active Releases" button
- and choose the manual associated with the desired
- Yocto Project.
- </para></listitem>
- <listitem><para>
- To report any inaccuracies or problems with this
- manual, send an email to the Yocto Project
- discussion group at
- <filename>yocto@yoctoproject.com</filename> or log into
- the freenode <filename>#yocto</filename> channel.
- </para></listitem>
- </itemizedlist>
- </note>
- </legalnotice>
-
- <abstract>
- <imagedata fileref="figures/yocto-project-transp.png"
- width="6in" depth="1in"
- align="right" scale="25" />
- </abstract>
- </articleinfo>
-
- <section id='welcome'>
- <title>Welcome!</title>
- <para>
- Welcome to the Yocto Project!
- The Yocto Project is an open-source collaboration project whose
- focus is developers of embedded Linux systems.
- Among other things, the Yocto Project uses a build host based
- on the OpenEmbedded (OE) project, which uses the
- <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
- tool, to construct complete Linux images.
- The BitBake and OE components combine together to form
- a reference build host, historically known as
- <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
- (<emphasis>Pah</emphasis>-kee).
- </para>
-
- <para>
- This quick start is written so that you can quickly get a
- build host set up to use the Yocto Project and then build some
- Linux images.
- Rather than go into great detail about the Yocto Project and its
- many capabilities, this quick start provides the minimal
- information you need to try out the Yocto Project using either a
- supported Linux build host or a build host set up to use
- <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
- which leverages
- <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
- </para>
-
- <para>
- Reading and using the quick start should result in you having a
- basic understanding of what the Yocto Project is and how to use
- some of its core components.
- You will also have worked through steps to produce two images:
- one that runs on the emulator (QEMU) and one that boots on actual
- hardware (i.e. MinnowBoard Turbot).
- The examples highlight the ease with which you can use the
- Yocto Project to create images for multiple types of hardware.
- </para>
-
- <para>
- The following list directs you to key sections of this
- quick start:
- <itemizedlist>
- <listitem><para>
- <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#yp-resources'>Setting Up to Use the Yocto Project</ulink>
- </para></listitem>
- <listitem><para>
- <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#building-an-image-for-emulation'>Building an Image for Emulation</ulink>
- </para></listitem>
- <listitem><para>
- <ulink url='http://www.yoctoproject.org/docs/2.4/yocto-project-qs/yocto-project-qs.html#building-an-image-for-hardware'>Building an Image for Hardware</ulink>
- </para></listitem>
- </itemizedlist>
-<!--
- <note>
- If you do not have a system that runs Linux and you want to give
- the Yocto Project a test run, you might consider using the Yocto
- Project Build Appliance.
- The Build Appliance allows you to build and boot a custom
- embedded Linux image with the Yocto Project using a non-Linux
- development system.
- See the
- <ulink url='https://www.yoctoproject.org/tools-resources/projects/build-appliance'>Yocto Project Build Appliance</ulink>
- for more information.
- </note>
--->
- </para>
-
- <para>
- For more detailed information on the Yocto Project, you can
- reference these resources:
- <itemizedlist>
- <listitem><para>
- <emphasis>Website:</emphasis>
- The
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
- provides background information, the latest builds, breaking
- news, full development documentation, and access to a rich
- Yocto Project Development Community into which you can tap.
- </para></listitem>
- <listitem><para>
- <emphasis>Yocto Project Development Environment Overview:</emphasis>
- The
- "<ulink url='&YOCTO_DOCS_REF_URL;#yp-intro'>Introducing the Yocto Project Development Environment</ulink>"
- section presents an overview of the Yocto Project
- development environment.
- </para></listitem>
- <listitem><para>
- <emphasis>FAQs:</emphasis>
- Lists commonly asked Yocto Project questions and answers.
- You can find two FAQs:
- <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink>
- on a wiki, and the
- "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>"
- chapter in the Yocto Project Reference Manual.
- </para></listitem>
- <listitem><para>
- <emphasis>Developer Screencast:</emphasis>
- The
- <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
- provides a 30-minute video created for users unfamiliar
- with the Yocto Project but familiar with Linux build
- hosts.
- While this screencast is somewhat dated, the introductory
- and fundamental concepts are useful for the beginner.
- </para></listitem>
- <listitem><para>
- <emphasis>Comprehensive List of Links and Other Documentation:</emphasis>
- The
- "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
- section in the Yocto Project Reference Manual provides a
- comprehensive list of related links and documentation.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='yp-resources'>
- <title>Setting Up to Use the Yocto Project</title>
-
- <para>
- Setting up to use the Yocto Project involves getting your build
- host ready.
- If you have a native Linux machine that runs a Yocto Project
- supported distribution as described by the
- "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
- section in the Yocto Project Reference Manual, you can prepare
- that machine as your build host.
- See the
- "<link linkend='qs-native-linux-build-host'>Using a Native Linux Machine</link>"
- section for more information.
- </para>
-
- <para>
- If you do not want to use the Yocto Project on a native Linux
- machine, you can prepare your build host to use
- <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
- which leverages
- <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
- You can set up a build host for Windows, Mac, and Linux
- machines.
- See the
- "<link linkend='qs-crops-build-host'>Using CROPS and Containers</link>"
- section for more information.
- </para>
-
- <section id='qs-crops-build-host'>
- <title>Using CROPS and Containers</title>
-
- <para>
- Follow these steps to get your build host set up with a
- Poky container that you can use to complete the build
- examples further down in the Quick Start:
- <orderedlist>
- <listitem><para>
- <emphasis>Set Up to use CROss PlatformS (CROPS):</emphasis>
- Work through the first six steps of the procedure
- in the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
- section of the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>
- <emphasis>Set Up the Poky Container to Use the Yocto Project:</emphasis>
- Go to
- <ulink url='https://github.com/crops/poky-container/blob/master/README.md'></ulink>
- and follow the directions to set up the Poky container
- on your build host.</para>
-
- <para>Once you complete the setup instructions for your
- machine, you need to get a copy of the
- <filename>poky</filename> repository on your build
- host.
- See the
- "<link linkend='releases'>Yocto Project Release</link>"
- section to continue.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='qs-native-linux-build-host'>
- <title>Using a Native Linux Machine</title>
-
- <para>
- The following list shows what you need in order to use a
- Linux-based build host to use the Yocto Project to build images:
- </para>
-
- <itemizedlist>
- <listitem><para><emphasis>Build Host</emphasis>
- A build host with a minimum of 50 Gbytes of free disk
- space that is running a supported Linux distribution (i.e.
- recent releases of Fedora, openSUSE, CentOS, Debian, or
- Ubuntu).
- </para></listitem>
- <listitem><para><emphasis>Build Host Packages</emphasis>
- Appropriate packages installed on the build host.
- </para></listitem>
- </itemizedlist>
-
- <section id='the-linux-distro'>
- <title>The Linux Distribution</title>
-
- <para>
- The Yocto Project team verifies each release against recent
- versions of the most popular Linux distributions that
- provide stable releases.
- In general, if you have the current release minus one of the
- following distributions, you should have no problems.
- <itemizedlist>
- <listitem><para>
- Ubuntu
- </para></listitem>
- <listitem><para>
- Fedora
- </para></listitem>
- <listitem><para>
- openSUSE
- </para></listitem>
- <listitem><para>
- CentOS
- </para></listitem>
- <listitem><para>
- Debian
- </para></listitem>
- </itemizedlist>
- For a more detailed list of distributions that support the
- Yocto Project, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
- section in the Yocto Project Reference Manual.
- </para>
-
- <para>
- The OpenEmbedded build system should be able to run on any
- modern distribution that has the following versions for
- Git, tar, and Python.
- <itemizedlist>
- <listitem><para>
- Git 1.8.3.1 or greater
- </para></listitem>
- <listitem><para>
- tar 1.27 or greater
- </para></listitem>
- <listitem><para>
- Python 3.4.0 or greater.
- </para></listitem>
- </itemizedlist>
- If your build host does not meet any of these three listed
- version requirements, you can take steps to prepare the
- system so that you can still use the Yocto Project.
- See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
- section in the Yocto Project Reference Manual for information.
- </para>
- </section>
-
- <section id='packages'>
- <title>The Build Host Packages</title>
-
- <para>
- Required build host packages vary depending on your
- build machine and what you want to do with the Yocto Project.
- For example, if you want to build an image that can run
- on QEMU in graphical mode (a minimal, basic build
- requirement), then the build host package requirements
- are different than if you want to build an image on a headless
- system or build out the Yocto Project documentation set.
- </para>
-
- <para>
- Collectively, the number of required packages is large
- if you want to be able to cover all cases.
- <note>
- In general, you need to have root access and then install
- the required packages.
- Thus, the commands in the following section may or may
- not work depending on whether or not your Linux
- distribution has <filename>sudo</filename> installed.
- </note>
- </para>
-
- <para>
- The following list shows the required packages needed to build
- an image that runs on QEMU in graphical mode (e.g. essential
- plus graphics support).
- For lists of required packages for other scenarios, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
- section in the Yocto Project Reference Manual.
- <itemizedlist>
- <listitem><para><emphasis>Ubuntu and Debian</emphasis>
- <literallayout class='monospaced'>
- $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Fedora</emphasis>
- <literallayout class='monospaced'>
- $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>OpenSUSE</emphasis>
- <literallayout class='monospaced'>
- $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>CentOS</emphasis>
- <literallayout class='monospaced'>
- $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
- </literallayout>
- <note><title>Notes</title>
- <itemizedlist>
- <listitem><para>
- Extra Packages for Enterprise Linux
- (i.e. <filename>epel-release</filename>)
- is a collection of packages from Fedora
- built on RHEL/CentOS for easy installation
- of packages not included in enterprise
- Linux by default.
- You need to install these packages
- separately.
- </para></listitem>
- <listitem><para>
- The <filename>makecache</filename> command
- consumes additional Metadata from
- <filename>epel-release</filename>.
- </para></listitem>
- </itemizedlist>
- </note>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <para>
- Once you complete the setup instructions for your
- machine, you need to get a copy of the
- <filename>poky</filename> repository on your build
- host.
- Continue with the
- "<link linkend='releases'>Yocto Project Release</link>"
- section.
- </para>
- </section>
-
- <section id='releases'>
- <title>Yocto Project Release</title>
-
- <para>
- Now that your build host has the right packages (native
- Linux machine) or you have the Poky container set up
- (CROPS), you need to get a copy of the Yocto Project.
- It is recommended that you get the latest Yocto Project release
- by setting up (cloning in
- <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> terms) a
- local copy of the <filename>poky</filename> Git repository on
- your build host and then checking out the latest release.
- Doing so allows you to easily update to newer Yocto Project
- releases as well as contribute back to the Yocto Project.
- </para>
-
- <para>
- Here is an example from a native Linux machine that is
- running Ubuntu.
- <note>
- If your build host is using a Poky container, you can
- use the same Git commands.
- </note>
- The following example clones the <filename>poky</filename>
- repository and then checks out the latest Yocto Project Release
- by tag (i.e. <filename>&DISTRO_REL_TAG;</filename>):
- <literallayout class='monospaced'>
- $ git clone git://git.yoctoproject.org/poky
- Cloning into 'poky'...
- remote: Counting objects: 361782, done.
- remote: Compressing objects: 100% (87100/87100), done.
- remote: Total 361782 (delta 268619), reused 361439 (delta 268277)
- Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.
- Resolving deltas: 100% (268619/268619), done.
- Checking connectivity... done.
- $ git checkout tags/&DISTRO_REL_TAG; -b poky_&DISTRO;
- </literallayout>
- </para>
-
- <para>
- The previous Git <filename>checkout</filename> command
- creates a local branch named
- <filename>poky_&DISTRO;</filename>.
- The files available to you in that branch exactly match the
- repository's files in the
- <filename>&DISTRO_NAME_NO_CAP;</filename>
- development branch at the time of the Yocto Project &DISTRO;
- release.
- <note>
- Rather than checking out the entire development branch
- of a release (i.e. the tip), which could be continuously
- changing while you are doing your development, you would
- check out a branch based on a release tag as shown in
- the previous example.
- Doing so provides you with an unchanging, stable set of
- files.
- </note>
- </para>
-
- <para>
- For more options and information about accessing Yocto
- Project related repositories, see the
- "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
- section in the Yocto Project Development Tasks Manual.
- </para>
- </section>
- </section>
-
- <section id='qs-building-images'>
- <title>Building Images</title>
-
- <para>
- You are now ready to give the Yocto Project a try.
- For this example, you will be using the command line to build
- your images.
- <note>
- A graphical user interface to the Yocto Project is available
- through
- <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>.
- See the
- <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
- for more information.
- </note>
- </para>
-
- <para>
- The remainder of this quick start steps you through the
- following:
- <itemizedlist>
- <listitem><para>
- Build a <filename>qemux86</filename> reference image
- and run it in the QEMU emulator.
- </para></listitem>
- <listitem><para>
- Easily change configurations so that you can quickly
- create a second image that you can load onto bootable
- media and actually boot target hardware.
- This example uses the MinnowBoard
- Turbot-compatible boards.
- </para></listitem>
- </itemizedlist>
- <note>
- The steps in the following two sections do not provide detail,
- but rather provide minimal, working commands and examples
- designed to just get you started.
- For more details, see the appropriate manuals in the
- <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project manual set</ulink>.
- </note>
- </para>
-
- <section id='building-an-image-for-emulation'>
- <title>Building an Image for Emulation</title>
-
- <para>
- Use the following commands to build your image.
- The OpenEmbedded build system creates an entire Linux
- distribution, including the toolchain, from source.
- <note><title>Notes about Network Proxies</title>
- <itemizedlist>
- <listitem><para>
- By default, the build process searches for source
- code using a pre-determined order through a set of
- locations.
- If you are working behind a firewall and your build
- host is not set up for proxies, you could encounter
- problems with the build process when fetching source
- code (e.g. fetcher failures or Git failures).
- </para></listitem>
- <listitem><para>
- If you do not know your proxy settings, consult your
- local network infrastructure resources and get that
- information.
- A good starting point could also be to check your
- web browser settings.
- Finally, you can find more information on using the
- Yocto Project behind a firewall in the Yocto Project
- Reference Manual
- <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink>
- and on the
- "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
- wiki page.
- </para></listitem>
- </itemizedlist>
- </note>
- </para>
-
- <para>
- <orderedlist>
- <listitem><para>
- <emphasis>Be Sure Your Build Host is Set Up:</emphasis>
- The steps to build an image in this section depend on
- your build host being properly set up.
- Be sure you have worked through the requirements
- described in the
- "<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Check Out Your Branch:</emphasis>
- Be sure you are in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- (e.g. <filename>poky</filename>) and then check out
- the branch associated with the latest Yocto Project
- Release:
- <literallayout class='monospaced'>
- $ cd ~/poky
- $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
- </literallayout>
- Git's <filename>checkout</filename> command checks out
- the current Yocto Project release into a local branch
- whose name matches the release (i.e.
- <filename>&DISTRO_NAME_NO_CAP;</filename>).
- The local branch tracks the upstream branch of the
- same name.
- Creating your own branch based on the released
- branch ensures you are using the latest files for
- that release.
- </para></listitem>
- <listitem><para>
- <emphasis>Initialize the Build Environment:</emphasis>
- Run the
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
- environment setup script to define the OpenEmbedded
- build environment on your build host.
- <literallayout class='monospaced'>
- $ source &OE_INIT_FILE;
- </literallayout>
- Among other things, the script creates the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
- which is <filename>build</filename> in this case
- and is located in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
- After the script runs, your current working directory
- is set to the Build Directory.
- Later, when the build completes, the Build Directory
- contains all the files created during the build.
- </para></listitem>
- <listitem><para>
- <emphasis>Examine Your Local Configuration File:</emphasis>
- When you set up the build environment, a local
- configuration file named
- <filename>local.conf</filename> becomes available in
- a <filename>conf</filename> subdirectory of the
- Build Directory.
- Before using BitBake to start the build, you can
- look at this file and be sure your general
- configurations are how you want them:
- <itemizedlist>
- <listitem><para>
- To help conserve disk space during builds,
- you can add the following statement to your
- project's configuration file, which for this
- example is
- <filename>poky/build/conf/local.conf</filename>.
- Adding this statement deletes the work
- directory used for building a recipe once the
- recipe is built.
- <literallayout class='monospaced'>
- INHERIT += "rm_work"
- </literallayout>
- </para></listitem>
- <listitem><para>
- By default, the target machine for the build is
- <filename>qemux86</filename>,
- which produces an image that can be used in
- the QEMU emulator and is targeted at an
- <trademark class='registered'>Intel</trademark>
- 32-bit based architecture.
- Further on in this example, this default is
- easily changed through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable so that you can quickly
- build an image for a different machine.
- </para></listitem>
- <listitem><para>
- Another consideration before you build is the
- package manager used when creating the image.
- The default <filename>local.conf</filename>
- file selects the RPM package manager.
- You can control this configuration by using the
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename>
- variable.</para>
- <para>Selection of the package manager is separate
- from whether package management is used at runtime
- in the target image.</para>
- <para>For additional package manager selection
- information, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>"
- section in the Yocto Project Reference Manual.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- <listitem><para>
- <emphasis>Start the Build:</emphasis>
- Continue with the following command to build an OS image
- for the target, which is
- <filename>core-image-sato</filename> in this example:
- <note>
- Depending on the number of processors and cores, the
- amount of RAM, the speed of your Internet connection
- and other factors, the build process could take
- several hours the first time you run it.
- Subsequent builds run much faster since parts of the
- build are cached.
- </note>
- <literallayout class='monospaced'>
- $ bitbake core-image-sato
- </literallayout>
- <note>
- <para>
- If you experience a build error due to resources
- temporarily being unavailable and it appears you
- should not be having this issue, it might be due
- to the combination of a 4.3+ Linux kernel and
- <filename>systemd</filename> version 228+
- (i.e. see this
- <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
- for information).
- </para>
-
- <para>
- To work around this issue, you can try either
- of the following:
- <itemizedlist>
- <listitem><para>
- Try the build again.
- </para></listitem>
- <listitem><para>
- Modify the "DefaultTasksMax"
- <filename>systemd</filename> parameter
- by uncommenting it and setting it to
- "infinity".
- You can find this parameter in the
- <filename>system.conf</filename> file
- located in
- <filename>/etc/systemd</filename>
- on most systems.
- </para></listitem>
- </itemizedlist>
- </para>
- </note>
- For information on using the
- <filename>bitbake</filename> command, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
- section in the Yocto Project Reference Manual, or see the
- "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
- section in the BitBake User Manual.
- For information on other targets, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
- chapter in the Yocto Project Reference Manual.
- </para></listitem>
- <listitem><para>
- <emphasis>Simulate Your Image Using QEMU:</emphasis>
- Once this particular image is built, you can start QEMU
- and run the image:
- <literallayout class='monospaced'>
- $ runqemu qemux86
- </literallayout>
- If you want to learn more about running QEMU, see the
- "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
- chapter in the Yocto Project Development Tasks Manual.
- </para></listitem>
- <listitem><para>
- <emphasis>Exit QEMU:</emphasis>
- Exit QEMU by either clicking on the shutdown icon or by
- typing <filename>Ctrl-C</filename> in the QEMU
- transcript window from which you evoked QEMU.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='building-an-image-for-hardware'>
- <title>Building an Image for Hardware</title>
-
- <para id='qs-minnowboard-example'>
- The following steps show how easy it is to set up to build an
- image for a new machine.
- These steps build an image for the MinnowBoard Turbot, which is
- supported by the Yocto Project and the
- <filename>meta-intel</filename> <filename>intel-corei7-64</filename>
- and <filename>intel-core2-32</filename> Board Support Packages
- (BSPs).
- <note>
- The MinnowBoard Turbot ships with 64-bit firmware.
- If you want to use the board in 32-bit mode, you must
- download the
- <ulink url='http://firmware.intel.com/projects/minnowboard-max'>32-bit firmware</ulink>.
- </note>
- </para>
-
- <para>
- <orderedlist>
- <listitem><para>
- <emphasis>Create a Local Copy of the
- <filename>meta-intel</filename> Repository:</emphasis>
- Building an image for the MinnowBoard Turbot requires
- the
- <filename>meta-intel</filename> layer.
- Use the <filename>git clone</filename> command to create
- a local copy of the repository inside your
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>,
- which is <filename>poky</filename> in this example:
- <literallayout class='monospaced'>
- $ cd $HOME/poky
- $ git clone git://git.yoctoproject.org/meta-intel
- Cloning into 'meta-intel'...
- remote: Counting objects: 14039, done.
- remote: Compressing objects: 100% (4471/4471), done.
- remote: Total 14039 (delta 8130), reused 13837 (delta 7947)
- Receiving objects: 100% (14039/14039), 4.27 MiB | 3.98 MiB/s, done.
- Resolving deltas: 100% (8130/8130), done.
- Checking connectivity... done.
- </literallayout>
- By default when you clone a Git repository, the
- "master" branch is checked out.
- Before you build your image that uses the
- <filename>meta-intel</filename> layer, you must be
- sure that both repositories
- (<filename>meta-intel</filename> and
- <filename>poky</filename>) are using the same releases.
- Because you used the <filename>&DISTRO_REL_TAG;</filename>
- tag when you checked out the <filename>poky</filename>
- repository by tag, you should use a
- <filename>meta-intel</filename>
- tag that corresponds with the release you used for
- <filename>poky</filename>.
- Consequently, you need to checkout out the
- "<filename>&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;</filename>"
- branch after cloning <filename>meta-intel</filename>:
- <literallayout class='monospaced'>
- $ cd $HOME/poky/meta-intel
- $ git checkout tags/&METAINTELVERSION;-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION; -b meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;
- Switched to a new branch 'meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;'
- </literallayout>
- The previous Git <filename>checkout</filename> command
- creates a local branch named
- <filename>meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;</filename>.
- You have the option to name your local branch whatever
- you want by providing any name you like for
- "meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;"
- in the above example.
- </para></listitem>
- <listitem><para>
- <emphasis>Configure the Build:</emphasis>
- To configure the build, you edit the
- <filename>bblayers.conf</filename> and
- <filename>local.conf</filename> files, both of which are
- located in the <filename>build/conf</filename> directory.
- </para>
-
- <para>Here is a quick way to make the edits.
- The first command uses the
- <filename>bitbake-layers add-layer</filename> command
- to add the <filename>meta-intel</filename>
- layer, which contains the <filename>intel-core*</filename>
- BSPs to the build.
- The second command selects the BSP by setting the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- variable.
- <literallayout class='monospaced'>
- $ cd $HOME/poky/build
- $ bitbake-layers add-layer "$HOME/poky/meta-intel"
- $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf
- </literallayout>
- <note><title>Notes</title>
- <para>
- If you want a 64-bit build, use the following:
- <literallayout class='monospaced'>
- $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf
- </literallayout>
- </para>
-
- <para>
- If you want 32-bit images, use the following:
- <literallayout class='monospaced'>
- $ echo 'MACHINE = "intel-core2-32"' >> conf/local.conf
- </literallayout>
- </para>
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Build an Image for MinnowBoard
- Turbot:</emphasis>
- The type of image you build depends on your goals.
- For example, the previous build created a
- <filename>core-image-sato</filename> image, which is an
- image with Sato support.
- It is possible to build many image types for the
- MinnowBoard Turbot.
- Some possibilities are <filename>core-image-base</filename>,
- which is a console-only image.
- Another choice could be a
- <filename>core-image-full-cmdline</filename>, which is
- another console-only image but has more full-features
- Linux system functionality installed.
- For types of images you can build using the Yocto
- Project, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
- chapter in the Yocto Project Reference Manual.</para>
- <para>Because configuration changes are minimal to set up
- for this second build, the OpenEmbedded build system can
- re-use files from previous builds as much as possible.
- Re-using files means this second build will be much faster
- than an initial build.
- For this example, the <filename>core-image-base</filename>
- image is built:
- <literallayout class='monospaced'>
- $ bitbake core-image-base
- </literallayout>
- <note>
- <para>
- If you experience a build error due to resources
- temporarily being unavailable and it appears you
- should not be having this issue, it might be due
- to the combination of a 4.3+ Linux kernel and
- <filename>systemd</filename> version 228+
- (i.e. see this
- <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink>
- for information).
- </para>
-
- <para>
- To work around this issue, you can try either
- of the following:
- <itemizedlist>
- <listitem><para>
- Try the build again.
- </para></listitem>
- <listitem><para>
- Modify the "DefaultTasksMax"
- <filename>systemd</filename> parameter
- by uncommenting it and setting it to
- "infinity".
- You can find this parameter in the
- <filename>system.conf</filename> file
- located in
- <filename>/etc/systemd</filename>
- on most systems.
- </para></listitem>
- </itemizedlist>
- </para>
- </note>
- Once the build completes, the resulting console-only image
- is located in the Build Directory here:
- <literallayout class='monospaced'>
- tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Write the Image:</emphasis>
- You can write the image just built to a bootable media
- (e.g. a USB key, SATA drive, SD card, etc.) using the
- <filename>dd</filename> utility:
- <literallayout class='monospaced'>
- $ sudo dd if=tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic of=TARGET_DEVICE
- </literallayout>
- In the previous command, the
- <filename>TARGET_DEVICE</filename> is the device node in
- the host machine (e.g. <filename>/dev/sdc</filename>, which
- is most likely a USB stick, or
- <filename>/dev/mmcblk0</filename>, which is most likely an
- SD card).
- </para></listitem>
- <listitem><para>
- <emphasis>Boot the Hardware:</emphasis>
- With the boot device provisioned, you can insert the
- media into the MinnowBoard Turbot and boot the hardware.
- The board should automatically detect the media and boot to
- the bootloader and subsequently the operating system.
- </para>
-
- <para>If the board does not boot automatically, you can
- boot it manually from the EFI shell as follows:
- <literallayout class='monospaced'>
- Shell> connect -r
- Shell> map -r
- Shell> fs0:
- Shell> bootx64
- </literallayout>
- <note>
- For a 32-bit image use the following:
- <literallayout class='monospaced'>
- Shell> bootia32
- </literallayout>
- </note>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
- </section>
-
- <section id='qs-next-steps'>
- <title>Next Steps</title>
-
- <para>
- If you completed all the steps in the previous section then
- congratulations!
- What now?
- </para>
-
- <para>
- Depending on what you primary interests are with the Yocto Project,
- you could consider any of the following:
- <itemizedlist>
- <listitem><para>
- <emphasis>Visit the Yocto Project Web Site:</emphasis>
- The official
- <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink>
- web site contains information on the entire project.
- Visiting this site is a good way to familiarize yourself
- with the overall project.
- </para></listitem>
- <listitem><para>
- <emphasis>Look Through the
- <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-intro'>Yocto Project Development Tasks Manual</ulink>:</emphasis>
- This manual contains procedural information grouped to
- help you get set up, work with layers, customize images,
- write new recipes, work with libraries, and use QEMU.
- The information is task-based and spans the breadth of the
- Yocto Project.
- </para></listitem>
- <listitem><para>
- <emphasis>Look Through the
- <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
- manual:</emphasis>
- This manual describes how to use both the
- <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink>
- and the
- <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>,
- which are used primarily for application development.
- This manual also provides example workflows
- that use the popular <trademark class='trade'>Eclipse</trademark>
- development environment and that use <filename>devtool</filename>.
- See the
- "<ulink url='&YOCTO_DOCS_SDK_URL;#workflow-using-eclipse'>Workflow using Eclipse™</ulink>"
- and
- "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in your SDK Workflow</ulink>"
- sections for more information.
- </para></listitem>
- <listitem><para>
- <emphasis>Learn About Kernel Development:</emphasis>
- If you want to see how to work with the kernel and
- understand Yocto Linux kernels, see the
- <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-dev-intro'>Yocto Project Linux Kernel Development Manual</ulink>.
- This manual provides information on how to patch the
- kernel, modify kernel recipes, and configure the kernel.
- </para></listitem>
- <listitem><para>
- <emphasis>Learn About Board Support Packages (BSPs):</emphasis>
- If you want to learn about BSPs, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>.
- This manual also provides an example BSP creation workflow.
- See the
- <ulink url='&YOCTO_DOCS_BSP_URL;#developing-a-board-support-package-bsp'>"Developing a Board Support Package (BSP)</ulink>"
- section.
- </para></listitem>
- <listitem><para>
- <emphasis>Learn About Toaster:</emphasis>
- Toaster is a web interface to the Yocto Project's
- OpenEmbedded build system.
- If you are interested in using this type of interface to
- create images, see the
- <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink>.
- </para></listitem>
- <listitem><para>
- <emphasis>Have Available the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-manual-intro'>Yocto Project Reference Manual:</ulink></emphasis>
- Unlike the rest of the Yocto Project manual set, this manual
- is comprised of material suited for reference rather than
- procedures.
- You can get
- <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky'>build details</ulink>,
- a
- <ulink url='&YOCTO_DOCS_REF_URL;#development-concepts'>closer look</ulink>
- at how the pieces of the Yocto Project development
- environment work together, information on various
- <ulink url='&YOCTO_DOCS_REF_URL;#technical-details'>technical details</ulink>,
- guidance on
- <ulink url='&YOCTO_DOCS_REF_URL;#migration'>migrating to a newer Yocto Project release</ulink>,
- reference material on the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-structure'>directory structure</ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>classes</ulink>,
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks'>tasks</ulink>.
- The Yocto Project Reference Manual also contains a fairly
- comprehensive
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glossary'>glossary of variables</ulink>
- used within the Yocto Project.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-</article>
-<!--
-vim: expandtab tw=80 ts=4
--->
