diff options
| author |   Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-12-11 12:07:58 -0600 |
|---|---|---|
| committer |   Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-07 14:43:25 +0000 |
| commit | ed0a240e1632682ec4c33341f3e24ad71773cdfc (patch) | |
| tree | 201557f498b77b9f51fad7e12a6009f74aca4c65 | |
| parent | af19d889ef320f9625aae42eed6688b5cc739793 (diff) | |
| download | openembedded-core-contrib-ed0a240e1632682ec4c33341f3e24ad71773cdfc.tar.gz | |
documentation: Rename of poky-ref-manual folder to ref-manual.
Changing the folder that holds the YP Reference Manual to be
"ref-manual". This will help with confustion over the manual's
intended purpose.
(From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
214 files changed, 26016 insertions, 0 deletions
diff --git a/documentation/ref-manual/TODO b/documentation/ref-manual/TODO new file mode 100644 index 0000000000..ee0db977cc --- /dev/null +++ b/documentation/ref-manual/TODO @@ -0,0 +1,11 @@ +Handbook Todo List: + + * Document adding a new IMAGE_FEATURE to the customising images section + * Add instructions about using zaurus/openmoko emulation + * Add component overview/block diagrams + * Software Deevelopment intro should mention its software development for + intended target and could be a different arch etc and thus special case. + * Expand insane.bbclass documentation to cover tests + * Document remaining classes (see list in ref-classes) + * Document formfactor + diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-local-configuration.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-local-configuration.html new file mode 100644 index 0000000000..d4a9f0875d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-local-configuration.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.1. Local Configuration</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release"> +<link rel="prev" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release"> +<link rel="next" href="migration-1.3-sstate-mirrors.html" title="4.1.1.1. SSTATE_MIRRORS"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.1. Local Configuration"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="1.3-local-configuration"></a>4.1.1. Local Configuration</h3></div></div></div> +<p> + Differences include changes for + <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a> + and <code class="filename">bblayers.conf</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-recipes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-recipes.html new file mode 100644 index 0000000000..69966945f2 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-recipes.html @@ -0,0 +1,29 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2. Recipes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release"> +<link rel="prev" href="migration-1.3-bblayers-conf.html" title="4.1.1.2. bblayers.conf"> +<link rel="next" href="migration-1.3-python-function-whitespace.html" title="4.1.2.1. Python Function Whitespace"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2. Recipes"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="1.3-recipes"></a>4.1.2. Recipes</h3></div></div></div> +<p> + Differences include changes for the following: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>Python function whitespace</p></li> +<li class="listitem"><p><code class="filename">proto=</code> in <code class="filename">SRC_URI</code></p></li> +<li class="listitem"><p><code class="filename">nativesdk</code></p></li> +<li class="listitem"><p>Task recipes</p></li> +<li class="listitem"><p><code class="filename">IMAGE_FEATURES</code></p></li> +<li class="listitem"><p>Removed recipes</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-image-information.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-image-information.html new file mode 100644 index 0000000000..f1b0f9e2ad --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-image-information.html @@ -0,0 +1,80 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4.2.2. Build History Image Information</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains"> +<link rel="prev" href="build-history-package-information.html" title="2.4.2.1. Build History Package Information"> +<link rel="next" href="using-build-history-to-gather-image-information-only.html" title="2.4.2.3. Using Build History to Gather Image Information Only"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.2. Build History Image Information"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="build-history-image-information"></a>2.4.2.2. Build History Image Information</h4></div></div></div> +<p> + The files produced for each image are as follows: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>build-id:</em></span> + Human-readable information about the build configuration + and metadata source revisions.</p></li> +<li class="listitem"><p><span class="emphasis"><em>*.dot:</em></span> + Dependency graphs for the image that are + compatible with <code class="filename">graphviz</code>. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>files-in-image.txt:</em></span> + A list of files in the image with permissions, + owner, group, size, and symlink information. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>image-info.txt:</em></span> + A text file containing name-value pairs with information + about the image. + See the following listing example for more information. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>installed-package-names.txt:</em></span> + A list of installed packages by name only.</p></li> +<li class="listitem"><p><span class="emphasis"><em>installed-package-sizes.txt:</em></span> + A list of installed packages ordered by size. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>installed-packages.txt:</em></span> + A list of installed packages with fuill package + filenames.</p></li> +</ul></div> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + Installed package information is able to be gathered and + produced even if package management is disabled for the final + image. + </div> +<p> + </p> +<p> + Here is an example of <code class="filename">image-info.txt</code>: + </p> +<pre class="literallayout"> + DISTRO = poky + DISTRO_VERSION = 1.1+snapshot-20120207 + USER_CLASSES = image-mklibs image-prelink + IMAGE_CLASSES = image_types + IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ + package-management ssh-server-dropbear package-management + IMAGE_LINGUAS = en-us en-gb + IMAGE_INSTALL = task-core-boot task-base-extended + BAD_RECOMMENDATIONS = + ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + IMAGESIZE = 171816 + </pre> +<p> + Other than <code class="filename">IMAGESIZE</code>, 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-package-information.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-package-information.html new file mode 100644 index 0000000000..370481da75 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-package-information.html @@ -0,0 +1,58 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4.2.1. Build History Package Information</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains"> +<link rel="prev" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains"> +<link rel="next" href="build-history-image-information.html" title="2.4.2.2. Build History Image Information"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.1. Build History Package Information"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="build-history-package-information"></a>2.4.2.1. Build History Package Information</h4></div></div></div> +<p> + The history for each package contains a text file that has + name-value pairs with information about the package. + For example, <code class="filename">buildhistory/packages/core2-poky-linux/busybox/busybox/latest</code> + contains the following: + </p> +<pre class="literallayout"> + PV = 1.19.3 + PR = r3 + RDEPENDS = update-rc.d eglibc (>= 2.13) + RRECOMMENDS = busybox-syslog busybox-udhcpc + PKGSIZE = 564701 + FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ + /etc /com /var /bin/* /sbin/* /lib/*.so.* /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 = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh + </pre> +<p> + Most of these name-value pairs corresponds to variables used + to produce the package. + The exceptions are <code class="filename">FILELIST</code>, which is the + actual list of files in the package, and + <code class="filename">PKGSIZE</code>, which is the total size of files + in the package in bytes. + </p> +<p> + There is also a file corresponding to the recipe from which the + package came (e.g. + <code class="filename">buildhistory/packages/core2-poky-linux/busybox/latest</code>): + </p> +<pre class="literallayout"> + PV = 1.19.3 + PR = r3 + DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ + virtual/libc update-rc.d-native + PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ + busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ + busybox-staticdev busybox-locale + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/build-overview.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/build-overview.html new file mode 100644 index 0000000000..4ee4185ba9 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/build-overview.html @@ -0,0 +1,61 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.1.1. Build Overview</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-build.html" title="2.1. Running a Build"> +<link rel="prev" href="usingpoky-build.html" title="2.1. Running a Build"> +<link rel="next" href="building-an-image-using-gpl-components.html" title="2.1.2. Building an Image Using GPL Components"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1.1. Build Overview"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="build-overview"></a>2.1.1. Build Overview</h3></div></div></div> +<p> + The first thing you need to do is set up the OpenEmbedded build environment by sourcing + the <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">environment setup script</a> as follows: + </p> +<pre class="literallayout"> + $ source oe-init-build-env [build_dir] + </pre> +<p> + </p> +<p> + The <code class="filename">build_dir</code> is optional and specifies the directory the + OpenEmbedded build system uses for the build - + the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + If you do not specify a Build Directory it defaults to <code class="filename">build</code> + in your current working directory. + A common practice is to use a different Build Directory for different targets. + For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code> + target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target. + See <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">oe-init-build-env</a> + for more information on this script. + </p> +<p> + Once the build environment is set up, you can build a target using: + </p> +<pre class="literallayout"> + $ bitbake <target> + </pre> +<p> + </p> +<p> + The <code class="filename">target</code> is the name of the recipe you want to build. + Common targets are the images in <code class="filename">meta/recipes-core/images</code>, + <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + Or, the target can be the name of a recipe for a specific piece of software such as + <span class="application">busybox</span>. + For more details about the images the OpenEmbedded build system supports, see the + "<a class="link" href="ref-images.html" title="Chapter 8. Images">Images</a>" chapter. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + Building an image without GNU General Public License Version 3 (GPLv3) components + is only supported for minimal and base images. + See the "<a class="link" href="ref-images.html" title="Chapter 8. Images">Images</a>" chapter for more information. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/building-an-image-using-gpl-components.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/building-an-image-using-gpl-components.html new file mode 100644 index 0000000000..12073d58d8 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/building-an-image-using-gpl-components.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.1.2. Building an Image Using GPL Components</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-build.html" title="2.1. Running a Build"> +<link rel="prev" href="build-overview.html" title="2.1.1. Build Overview"> +<link rel="next" href="usingpoky-install.html" title="2.2. Installing and Using the Result"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1.2. Building an Image Using GPL Components"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div> +<p> + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/centos-packages.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/centos-packages.html new file mode 100644 index 0000000000..05463bc93a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/centos-packages.html @@ -0,0 +1,69 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3.2.4. CentOS Packages</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System"> +<link rel="prev" href="opensuse-packages.html" title="1.3.2.3. OpenSUSE Packages"> +<link rel="next" href="intro-getit.html" title="1.4. Obtaining the Yocto Project"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.4. CentOS Packages"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="centos-packages"></a>1.3.2.4. CentOS Packages</h4></div></div></div> +<p> + The following list shows the required packages by function + given a supported CentOS Linux distribution: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> +<p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image for a headless + system: + </p> +<pre class="literallayout"> + $ sudo yum -y install gawk make wget tar bzip2 gzip python unzip perl patch \ + diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p> +<pre class="literallayout"> + $ sudo yum -y install SDL-devel xterm + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p> +<pre class="literallayout"> + $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>: + </p> +<pre class="literallayout"> + $ sudo yum -y install autoconf automake libtool glib2-devel + </pre> +</li> +</ul></div> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>Depending on the CentOS version you are using, other requirements + and dependencies might exist. + For details, you should look at the CentOS sections on the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_self">Poky/GettingStarted/Dependencies</a> + wiki page.</div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/checksums.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/checksums.html new file mode 100644 index 0000000000..5dccce93b9 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/checksums.html @@ -0,0 +1,164 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2.2. Checksums (Signatures)</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache"> +<link rel="prev" href="overall-architecture.html" title="3.2.1. Overall Architecture"> +<link rel="next" href="shared-state.html" title="3.2.3. Shared State"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.2. Checksums (Signatures)"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div> +<p> + 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. + </p> +<p> + 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 <code class="filename">WORKDIR</code>. + It does not matter if the working directory changes because it should not + affect the output for target packages. + Also, the build process has the objective of making native/cross packages relocatable. + The checksum therefore needs to exclude <code class="filename">WORKDIR</code>. + The simplistic approach for excluding the working directory is to set + <code class="filename">WORKDIR</code> to some fixed value and create the checksum + for the "run" script. + </p> +<p> + 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. + </p> +<p> + 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. + </p> +<p> + Like the <code class="filename">WORKDIR</code> 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: + </p> +<pre class="literallayout"> + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + </pre> +<p> + This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not + depend on the value of <code class="filename">MACHINE</code>, even if it does reference it. + </p> +<p> + 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: + </p> +<pre class="literallayout"> + PACKAGE_ARCHS[vardeps] = "MACHINE" + </pre> +<p> + This example explicitly adds the <code class="filename">MACHINE</code> variable as a + dependency for <code class="filename">PACKAGE_ARCHS</code>. + </p> +<p> + Consider a case with inline python, for example, where BitBake is not + able to figure out dependencies. + When running in debug mode (i.e. using <code class="filename">-DDD</code>), 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. + </p> +<p> + 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 Build Directory. + 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. + </p> +<p> + 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 statements effectively result in a list of global variable + dependency excludes - variables never included in any checksum: + </p> +<pre class="literallayout"> + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" + BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" + BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" + BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" + </pre> +<p> + The previous example actually excludes + <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a> + since it is actually constructed as a path within + <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on + the whitelist. + </p> +<p> + 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 <code class="filename">meta/lib/oe/sstatesig.py</code> 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 <code class="filename">OE-Core</code> + 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. + <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default + through this setting in the <code class="filename">bitbake.conf</code> file: + </p> +<pre class="literallayout"> + BB_SIGNATURE_HANDLER ?= "OEBasic" + </pre> +<p> + The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the + "OEBasic" version but adds the task hash to the stamp files. + 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 <a class="link" href="ref-variables-glos.html#var-PR" title="PR"><code class="filename">PR</code></a> + values and changes to metadata automatically ripple across the build. + Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code> + but is the default in <code class="filename">poky</code>. + </p> +<p> + 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: + </p> +<pre class="literallayout"> + BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe + BB_BASEHASH_<filename:taskname> - the base hashes for each dependent task + BBHASHDEPS_<filename:taskname> - The task dependencies for each task + BB_TASKHASH - the hash of the currently running task + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/debugging.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/debugging.html new file mode 100644 index 0000000000..80a19f98a4 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/debugging.html @@ -0,0 +1,43 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2.4.1. Debugging</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks"> +<link rel="prev" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks"> +<link rel="next" href="invalidating-shared-state.html" title="3.2.4.2. Invalidating Shared State"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.4.1. Debugging"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="debugging"></a>3.2.4.1. Debugging</h4></div></div></div> +<p> + When things go wrong, debugging needs to be straightforward. + Because of this, the Yocto Project team included strong debugging + tools: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>Whenever a shared state package is written out, so is a + corresponding <code class="filename">.siginfo</code> file. + This practice results in a pickled python database of all + the metadata that went into creating the hash for a given shared state + package.</p></li> +<li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code> + (or <code class="filename">-S</code>) option, BitBake dumps out + <code class="filename">.siginfo</code> files in + the stamp directory for every task it would have executed instead of + building the specified target package.</p></li> +<li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that + can process these <code class="filename">.siginfo</code> files. + If one file is specified, it will dump out the dependency + information in the file. + If two files are specified, it will compare the two files and dump out + the differences between the two. + This allows the question of "What changed between X and Y?" to be + answered easily.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/detailed-supported-distros.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/detailed-supported-distros.html new file mode 100644 index 0000000000..6222ae54cf --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/detailed-supported-distros.html @@ -0,0 +1,45 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3.1. Supported Linux Distributions</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro-requirements.html" title="1.3. System Requirements"> +<link rel="prev" href="intro-requirements.html" title="1.3. System Requirements"> +<link rel="next" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.1. Supported Linux Distributions"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="detailed-supported-distros"></a>1.3.1. Supported Linux Distributions</h3></div></div></div> +<p> + Currently, the Yocto Project is supported on the following distributions: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>Ubuntu 10.04.4 LTS</p></li> +<li class="listitem"><p>Ubuntu 11.10</p></li> +<li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li> +<li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li> +<li class="listitem"><p>Ubuntu 12.10</p></li> +<li class="listitem"><p>Fedora release 16 (Verne)</p></li> +<li class="listitem"><p>Fedora release 17 (Beefy Miracle)</p></li> +<li class="listitem"><p>Fedora release 18 (Spherical Cow)</p></li> +<li class="listitem"><p>CentOS release 5.6 (Final)</p></li> +<li class="listitem"><p>CentOS release 5.7 (Final)</p></li> +<li class="listitem"><p>CentOS release 5.8 (Final)</p></li> +<li class="listitem"><p>CentOS release 6.3 (Final)</p></li> +<li class="listitem"><p>Debian GNU/Linux 6.0.6 (squeeze)</p></li> +<li class="listitem"><p>openSUSE 11.4</p></li> +<li class="listitem"><p>openSUSE 12.1</p></li> +<li class="listitem"><p>openSUSE 12.2</p></li> +</ul></div> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + For additional information on distributions that support the + Yocto Project, see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_self">Distribution Support</a> wiki page. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-and-disabling-build-history.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-and-disabling-build-history.html new file mode 100644 index 0000000000..06be8f5332 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-and-disabling-build-history.html @@ -0,0 +1,62 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4.1. Enabling and Disabling Build History</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality"> +<link rel="prev" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality"> +<link rel="next" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.1. Enabling and Disabling Build History"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="enabling-and-disabling-build-history"></a>2.4.1. Enabling and Disabling Build History</h3></div></div></div> +<p> + Build history is disabled by default. + To enable it, add the following statements to the end of your + <code class="filename">conf/local.conf</code> file found in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>: + </p> +<pre class="literallayout"> + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + </pre> +<p> + Enabling build history as previously described + causes the build process to collect build + output information and commit it to a local + <a class="link" href="../dev-manual/git.html" target="_self">Git</a> repository. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + Enabling build history increases your build times slightly, + particularly for images, and increases the amount of disk + space used during the build. + </div> +<p> + </p> +<p> + You can disable build history by removing the previous statements + from your <code class="filename">conf/local.conf</code> file. + However, you should realize that enabling and disabling + build history in this manner can change the + <code class="filename">do_package</code> task checksums, which if you + are using the OEBasicHash signature generator (the default + for many current distro configurations including + <code class="filename">DISTRO = "poky"</code> and + <code class="filename">DISTRO = ""</code>) will result in the packaging + tasks being re-run during the subsequent build. + </p> +<p> + To disable the build history functionality without causing the + packaging tasks to be re-run, add just this statement to your + <code class="filename">conf/local.conf</code> file: + </p> +<pre class="literallayout"> + BUILDHISTORY_FEATURES = "" + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-commercially-licensed-recipes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-commercially-licensed-recipes.html new file mode 100644 index 0000000000..9ecf3cc128 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-commercially-licensed-recipes.html @@ -0,0 +1,85 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4.2. Enabling Commercially Licensed Recipes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="licenses.html" title="3.4. Licenses"> +<link rel="prev" href="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html" title="3.4.1.2. Explanation of Syntax"> +<link rel="next" href="license-flag-matching.html" title="3.4.2.1. License Flag Matching"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div> +<p> + 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 <code class="filename">LICENSE_FLAGS</code> variable + definition in the affected recipe. + For instance, the + <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> + recipe contains the following statement: + </p> +<pre class="literallayout"> + LICENSE_FLAGS = "commercial" + </pre> +<p> + Here is a slightly more complicated example that contains both an + explicit recipe name and version (after variable expansion): + </p> +<pre class="literallayout"> + LICENSE_FLAGS = "license_${PN}_${PV}" + </pre> +<p> + In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code> + definition to be enabled and included in an image, it + needs to have a matching entry in the global + <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable + typically defined in your <code class="filename">local.conf</code> file. + For example, to enable + the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>. + See the + "<a class="link" href="license-flag-matching.html" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section + for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works. + Here is the example: + </p> +<pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + </pre> +<p> + Likewise, to additionally enable the package built from the recipe containing + <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming + that the actual recipe name was <code class="filename">emgd_1.10.bb</code>, + the following string would enable that package as well as + the original <code class="filename">gst-plugins-ugly</code> package: + </p> +<pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + </pre> +<p> + 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". + </p> +<pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial license" + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/examining-build-history-information.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/examining-build-history-information.html new file mode 100644 index 0000000000..0fa3f74545 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/examining-build-history-information.html @@ -0,0 +1,70 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4.2.4. Examining Build History Information</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains"> +<link rel="prev" href="using-build-history-to-gather-image-information-only.html" title="2.4.2.3. Using Build History to Gather Image Information Only"> +<link rel="next" href="technical-details.html" title="Chapter 3. Technical Details"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.4. Examining Build History Information"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="examining-build-history-information"></a>2.4.2.4. Examining Build History Information</h4></div></div></div> +<p> + You can examine build history output from the command line or + from a web interface. + </p> +<p> + To see any changes that have occurred (assuming you have + <code class="filename">BUILDHISTORY_COMMIT = "1"</code>), you can simply + use any Git command that allows you to view the history of + a repository. + Here is one method: + </p> +<pre class="literallayout"> + $ git log -p + </pre> +<p> + 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). + </p> +<p> + A command-line tool called <code class="filename">buildhistory-diff</code> + 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: + </p> +<pre class="literallayout"> + $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ + Changes to images/qemux86_64/eglibc/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/eglibc/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" + </pre> +<p> + </p> +<p> + To see changes to the build history using a web interface, follow + the instruction in the <code class="filename">README</code> file here. + <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/" target="_self">http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/</a>. + </p> +<p> + Here is a sample screenshot of the interface: + </p> +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="130%"><tr><td align="center"><img src="figures/buildhistory-web.png" align="middle" height="468"></td></tr></table> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/faq.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/faq.html new file mode 100644 index 0000000000..8b8cafbc3a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/faq.html @@ -0,0 +1,791 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 12. FAQ</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="ref-varlocality-recipe-build.html" title="11.2.4. Extra Build Information"> +<link rel="next" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 12. FAQ"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="faq"></a>Chapter 12. FAQ</h2></div></div></div> +<div class="qandaset" title="Frequently Asked Questions"> +<a name="idm1966160"></a><dl> +<dt>12.1. <a href="faq.html#idm1965696"> + How does Poky differ from OpenEmbedded? + </a> +</dt> +<dt>12.2. <a href="faq.html#idm1961792"> + I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. + Can I still use the Yocto Project? + </a> +</dt> +<dt>12.3. <a href="faq.html#idm2605168"> + How can you claim Poky / OpenEmbedded-Core is stable? + </a> +</dt> +<dt>12.4. <a href="faq.html#idm3232752"> + How do I get support for my board added to the Yocto Project? + </a> +</dt> +<dt>12.5. <a href="faq.html#idm3230416"> + Are there any products built using the OpenEmbedded build system? + </a> +</dt> +<dt>12.6. <a href="faq.html#idm3227696"> + What does the OpenEmbedded build system produce as output? + </a> +</dt> +<dt>12.7. <a href="faq.html#idm5359408"> + How do I add my package to the Yocto Project? + </a> +</dt> +<dt>12.8. <a href="faq.html#idm5357680"> + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + </a> +</dt> +<dt>12.9. <a href="faq.html#idm5354224"> + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + </a> +</dt> +<dt>12.10. <a href="faq.html#idm2088960"> + I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'. + What is wrong? + </a> +</dt> +<dt>12.11. <a href="faq.html#idm2085168"> + How do I make the Yocto Project work in RHEL/CentOS? + </a> +</dt> +<dt>12.12. <a href="faq.html#idm3829808"> + I see lots of 404 responses for files on + http://www.yoctoproject.org/sources/*. Is something wrong? + </a> +</dt> +<dt>12.13. <a href="faq.html#idm3827408"> + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + </a> +</dt> +<dt>12.14. <a href="faq.html#idm5331776"> + I'm behind a firewall and need to use a proxy server. How do I do that? + </a> +</dt> +<dt>12.15. <a href="faq.html#idm1524432"> + What’s the difference between foo and foo-native? + </a> +</dt> +<dt>12.16. <a href="faq.html#idm1520336"> + I'm seeing random build failures. Help?! + </a> +</dt> +<dt>12.17. <a href="faq.html#idm4636672"> + What do we need to ship for license compliance? + </a> +</dt> +<dt>12.18. <a href="faq.html#idm4635216"> + How do I disable the cursor on my touchscreen device? + </a> +</dt> +<dt>12.19. <a href="faq.html#idm4631744"> + How do I make sure connected network interfaces are brought up by default? + </a> +</dt> +<dt>12.20. <a href="faq.html#idm3888832"> + How do I create images with more free space? + </a> +</dt> +<dt>12.21. <a href="faq.html#idm619504"> + Why don't you support directories with spaces in the pathnames? + </a> +</dt> +<dt>12.22. <a href="faq.html#idm617456"> + How do I use an external toolchain? + </a> +</dt> +<dt>12.23. <a href="faq.html#idm4577168"> + How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server? + </a> +</dt> +<dt>12.24. <a href="faq.html#idm3953616"> + Can I get rid of build output so I can start over? + </a> +</dt> +</dl> +<table border="0" width="100%" summary="Q and A Set"> +<col align="left" width="1%"> +<col> +<tbody> +<tr class="question" title="12.1."> +<td align="left" valign="top"> +<a name="idm1965696"></a><a name="idm1965568"></a><p><b>12.1.</b></p> +</td> +<td align="left" valign="top"><p> + How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_self">OpenEmbedded</a>? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + The term "Poky" refers to the specific reference build system that + the Yocto Project provides. + Poky is based on <a class="link" href="../dev-manual/oe-core.html" target="_self">OE-Core</a> + and BitBake. + Thus, the generic term used here for the build system is + the "OpenEmbedded build system." + Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with + changes always being merged to OE-Core or BitBake first before being pulled back + into Poky. + This practice benefits both projects immediately. + For a fuller description of the term "Poky", see the + <a class="link" href="../dev-manual/poky.html" target="_self">poky</a> term in the Yocto Project + Development Manual. + </p></td> +</tr> +<tr class="question" title="12.2."> +<td align="left" valign="top"> +<a name="idm1961792"></a><a name="idm1961664"></a><p><b>12.2.</b></p> +</td> +<td align="left" valign="top"><p> + I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. + Can I still use the Yocto Project? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + You can use a stand-alone tarball to provide Python 2.6. + You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2" target="_self">32-bit tarball</a></p></li> +<li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2" target="_self">64-bit tarball</a></p></li> +</ul></div> +<p> + </p> +<p> + These tarballs are self-contained with all required libraries and should work + on most Linux systems. + To use the tarballs extract them into the root + directory and run the appropriate command: + </p> +<pre class="literallayout"> + $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH + $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH + </pre> +<p> + </p> +<p> + Once you run the command, BitBake uses Python 2.6. + </p> +</td> +</tr> +<tr class="question" title="12.3."> +<td align="left" valign="top"> +<a name="idm2605168"></a><a name="idm2605040"></a><p><b>12.3.</b></p> +</td> +<td align="left" valign="top"><p> + How can you claim Poky / OpenEmbedded-Core is stable? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + There are three areas that help with stability; + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>The Yocto Project team keeps + <a class="link" href="../dev-manual/oe-core.html" target="_self">OE-Core</a> small + and focused, containing around 830 recipes as opposed to the thousands + available in other OpenEmbedded community layers. + Keeping it small makes it easy to test and maintain.</p></li> +<li class="listitem"><p>The Yocto Project team runs manual and automated tests + using a small, fixed set of reference hardware as well as emulated + targets.</p></li> +<li class="listitem"><p>The Yocto Project uses an an autobuilder, + which provides continuous build and integration tests.</p></li> +</ul></div> +<p> + </p> +</td> +</tr> +<tr class="question" title="12.4."> +<td align="left" valign="top"> +<a name="idm3232752"></a><a name="idm3232624"></a><p><b>12.4.</b></p> +</td> +<td align="left" valign="top"><p> + How do I get support for my board added to the Yocto Project? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + Support for an additional board is added by creating a BSP layer for it. + For more information on how to create a BSP layer, see the + <a class="link" href="../bsp-guide/index.html" target="_self">Yocto Project Board Support Package (BSP) Developer's Guide</a>. + </p> +<p> + Usually, if the board is not completely exotic, adding support in + the Yocto Project is fairly straightforward. + </p> +</td> +</tr> +<tr class="question" title="12.5."> +<td align="left" valign="top"> +<a name="idm3230416"></a><a name="idm3230288"></a><p><b>12.5.</b></p> +</td> +<td align="left" valign="top"><p> + Are there any products built using the OpenEmbedded build system? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + The software running on the <a class="ulink" href="http://vernier.com/labquest/" target="_self">Vernier LabQuest</a> + is built using the OpenEmbedded build system. + See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_self">Vernier LabQuest</a> + website for more information. + There are a number of pre-production devices using the OpenEmbedded build system + and the Yocto Project team + announces them as soon as they are released. + </p></td> +</tr> +<tr class="question" title="12.6."> +<td align="left" valign="top"> +<a name="idm3227696"></a><a name="idm3227568"></a><p><b>12.6.</b></p> +</td> +<td align="left" valign="top"><p> + What does the OpenEmbedded build system produce as output? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + Because the same set of recipes can be used to create output of various formats, the + output of an OpenEmbedded build depends on how it was started. + Usually, the output is a flashable image ready for the target device. + </p></td> +</tr> +<tr class="question" title="12.7."> +<td align="left" valign="top"> +<a name="idm5359408"></a><a name="idm5359280"></a><p><b>12.7.</b></p> +</td> +<td align="left" valign="top"><p> + How do I add my package to the Yocto Project? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + To add a package, you need to create a BitBake recipe. + For information on how to add a package, see the section + "<a class="link" href="../dev-manual/usingpoky-extend-addpkg.html" target="_self">Adding a Package</a>" + in the Yocto Project Development Manual. + </p></td> +</tr> +<tr class="question" title="12.8."> +<td align="left" valign="top"> +<a name="idm5357680"></a><a name="idm5357552"></a><p><b>12.8.</b></p> +</td> +<td align="left" valign="top"><p> + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + The OpenEmbedded build system can build packages in various formats such as + <code class="filename">ipk</code> for <code class="filename">opkg</code>, + Debian package (<code class="filename">.deb</code>), or RPM. + The packages can then be upgraded using the package tools on the device, much like + on a desktop distribution such as Ubuntu or Fedora. + </p></td> +</tr> +<tr class="question" title="12.9."> +<td align="left" valign="top"> +<a name="idm5354224"></a><a name="idm5354096"></a><p><b>12.9.</b></p> +</td> +<td align="left" valign="top"><p> + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_self">GNOME</a> + platform targeted at mobile and embedded devices. + The the main difference between GNOME Mobile and standard GNOME is that + desktop-orientated libraries have been removed, along with deprecated libraries, + creating a much smaller footprint. + </p></td> +</tr> +<tr class="question" title="12.10."> +<td align="left" valign="top"> +<a name="idm2088960"></a><a name="idm2088832"></a><p><b>12.10.</b></p> +</td> +<td align="left" valign="top"><p> + I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'. + What is wrong? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + You are probably running the build on an NTFS filesystem. + Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead. + </p></td> +</tr> +<tr class="question" title="12.11."> +<td align="left" valign="top"> +<a name="idm2085168"></a><a name="idm2085040"></a><p><b>12.11.</b></p> +</td> +<td align="left" valign="top"><p> + How do I make the Yocto Project work in RHEL/CentOS? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + To get the Yocto Project working under RHEL/CentOS 5.1 you need to first + install some required packages. + The standard CentOS packages needed are: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>"Development tools" (selected during installation)</p></li> +<li class="listitem"><p><code class="filename">texi2html</code></p></li> +<li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li> +</ul></div> +<p> + On top of these, you need the following external packages: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename">python-sqlite2</code> from + <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_self">DAG repository</a> + </p></li> +<li class="listitem"><p><code class="filename">help2man</code> from + <a class="ulink" href="http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html" target="_self">Karan repository</a></p></li> +</ul></div> +<p> + </p> +<p> + Once these packages are installed, the OpenEmbedded build system will be able + to build standard images. + However, there might be a problem with the QEMU emulator segfaulting. + You can either disable the generation of binary locales by setting + <code class="filename"><a class="link" href="ref-variables-glos.html#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a> + </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code> + from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. + </p> +</td> +</tr> +<tr class="question" title="12.12."> +<td align="left" valign="top"> +<a name="idm3829808"></a><a name="idm3829680"></a><p><b>12.12.</b></p> +</td> +<td align="left" valign="top"><p> + I see lots of 404 responses for files on + <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + Nothing is wrong. + The OpenEmbedded build system checks any configured source mirrors before downloading + from the upstream sources. + The build system does this searching for both source archives and + pre-checked out versions of SCM managed software. + These checks help in large installations because it can reduce load on the SCM servers + themselves. + The address above is one of the default mirrors configured into the + build system. + Consequently, if an upstream source disappears, the team + can place sources there so builds continue to work. + </p></td> +</tr> +<tr class="question" title="12.13."> +<td align="left" valign="top"> +<a name="idm3827408"></a><a name="idm3827280"></a><p><b>12.13.</b></p> +</td> +<td align="left" valign="top"><p> + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + Set <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a> + </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is + manually marked as + machine-specific in the case that needs it. + The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>. + </p></td> +</tr> +<tr class="question" title="12.14."> +<td align="left" valign="top"> +<a name="idm5331776"></a><a name="idm5331648"></a><p><b>12.14.</b></p> +</td> +<td align="left" valign="top"><p> + I'm behind a firewall and need to use a proxy server. How do I do that? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code> + and you therefore need to specify the proxy settings in a + <code class="filename">.wgetrc</code> file in your home directory. + Example settings in that file would be + </p> +<pre class="literallayout"> + http_proxy = http://proxy.yoyodyne.com:18023/ + ftp_proxy = http://proxy.yoyodyne.com:18023/ + </pre> +<p> + The Yocto Project also includes a <code class="filename">site.conf.sample</code> + file that shows how to configure CVS and Git proxy servers + if needed. + </p> +</td> +</tr> +<tr class="question" title="12.15."> +<td align="left" valign="top"> +<a name="idm1524432"></a><a name="idm1524304"></a><p><b>12.15.</b></p> +</td> +<td align="left" valign="top"><p> + What’s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + The <code class="filename">*-native</code> targets are designed to run on the system + being used for the build. + These are usually tools that are needed to assist the build in some way such as + <code class="filename">quilt-native</code>, which is used to apply patches. + The non-native version is the one that runs on the target device. + </p></td> +</tr> +<tr class="question" title="12.16."> +<td align="left" valign="top"> +<a name="idm1520336"></a><a name="idm1520208"></a><p><b>12.16.</b></p> +</td> +<td align="left" valign="top"><p> + I'm seeing random build failures. Help?! + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + If the same build is failing in totally different and random ways, + the most likely explanation is that either the hardware you're running the + build on has some problem, or, if you are running the build under virtualisation, + the virtualisation probably has bugs. + The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and + CPU activity and is sensitive to even single bit failures in any of these areas. + True random failures have always been traced back to hardware or virtualisation issues. + </p></td> +</tr> +<tr class="question" title="12.17."> +<td align="left" valign="top"> +<a name="idm4636672"></a><a name="idm4636544"></a><p><b>12.17.</b></p> +</td> +<td align="left" valign="top"><p> + What do we need to ship for license compliance? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + This is a difficult question and you need to consult your lawyer for the answer + for your specific case. + It is worth bearing in mind that for GPL compliance there needs to be enough + information shipped to allow someone else to rebuild the same end result + you are shipping. + This means sharing the source code, any patches applied to it, and also any + configuration information about how that package was configured and built. + </p></td> +</tr> +<tr class="question" title="12.18."> +<td align="left" valign="top"> +<a name="idm4635216"></a><a name="idm4635088"></a><p><b>12.18.</b></p> +</td> +<td align="left" valign="top"><p> + How do I disable the cursor on my touchscreen device? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + You need to create a form factor file as described in the + "<a class="link" href="../bsp-guide/bsp-filelayout-misc-recipes.html" target="_self">Miscellaneous Recipe Files</a>" + section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows: + </p> +<pre class="literallayout"> + HAVE_TOUCHSCREEN=1 + </pre> +<p> + </p> +</td> +</tr> +<tr class="question" title="12.19."> +<td align="left" valign="top"> +<a name="idm4631744"></a><a name="idm4631616"></a><p><b>12.19.</b></p> +</td> +<td align="left" valign="top"><p> + How do I make sure connected network interfaces are brought up by default? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + The default interfaces file provided by the netbase recipe does not + automatically bring up network interfaces. + Therefore, you will need to add a BSP-specific netbase that includes an interfaces + file. + See the "<a class="link" href="../bsp-guide/bsp-filelayout-misc-recipes.html" target="_self">Miscellaneous Recipe Files</a>" + section for information on creating these types of miscellaneous recipe files. + </p> +<p> + For example, add the following files to your layer: + </p> +<pre class="literallayout"> + meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces + meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend + </pre> +<p> + </p> +</td> +</tr> +<tr class="question" title="12.20."> +<td align="left" valign="top"> +<a name="idm3888832"></a><a name="idm3888704"></a><p><b>12.20.</b></p> +</td> +<td align="left" valign="top"><p> + How do I create images with more free space? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + Images are created to be 1.2 times the size of the populated root filesystem. + To modify this ratio so that there is more free space available, you need to + set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>. + For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets + the image size ratio to one and a half times the size of the populated + root filesystem. + </p> +<pre class="literallayout"> + IMAGE_OVERHEAD_FACTOR = "1.5" + </pre> +<p> + </p> +</td> +</tr> +<tr class="question" title="12.21."> +<td align="left" valign="top"> +<a name="idm619504"></a><a name="idm619376"></a><p><b>12.21.</b></p> +</td> +<td align="left" valign="top"><p> + Why don't you support directories with spaces in the pathnames? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"><p> + The Yocto Project team has tried to do this before but too many of the tools + the OpenEmbedded build system depends on such as <code class="filename">autoconf</code> + break when they find spaces in pathnames. + Until that situation changes, the team will not support spaces in pathnames. + </p></td> +</tr> +<tr class="question" title="12.22."> +<td align="left" valign="top"> +<a name="idm617456"></a><a name="idm617328"></a><p><b>12.22.</b></p> +</td> +<td align="left" valign="top"><p> + How do I use an external toolchain? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + The toolchain configuration is very flexible and customizable. + It is primarily controlled with the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-TCMODE" title="TCMODE">TCMODE</a></code> variable. + This variable controls which <code class="filename">tcmode-*.inc</code> file to include + from the <code class="filename">meta/conf/distro/include</code> directory within the + <a class="link" href="../dev-manual/source-directory.html" target="_self">source directory</a>. + </p> +<p> + The default value of <code class="filename">TCMODE</code> is "default" + (i.e. <code class="filename">tcmode-default.inc</code>). + However, other patterns are accepted. + In particular, "external-*" refers to external toolchains of which there are some + basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>). + You can use your own custom toolchain definition in your own layer + (or as defined in the <code class="filename">local.conf</code> file) at the location + <code class="filename">conf/distro/include/tcmode-*.inc</code>. + </p> +<p> + In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. + This recipe file needs to package up any pre-built objects in the toolchain such as + <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>, + any locales, and <code class="filename">libc</code>. + An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located + in <code class="filename">meta/recipes-core/meta/</code> within the source directory. + </p> +</td> +</tr> +<tr class="question" title="12.23."> +<td align="left" valign="top"> +<a name="idm4577168"></a><a name="idm5139136"></a><p><b>12.23.</b></p> +</td> +<td align="left" valign="top"><p><a name="how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server"></a> + How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + The way the build system obtains source code is highly configurable. + You can setup the build system to get source code in most environments if + HTTP transport is available. + </p> +<p> + When the build system searches for source code, it first tries the local download directory. + If that location fails, Poky tries PREMIRRORS, the upstream source, + and then MIRRORS in that order. + </p> +<p> + By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS + for SCM-based sources, + upstreams for normal tarballs, and then falls back to a number of other mirrors + including the Yocto Project source mirror if those fail. + </p> +<p> + As an example, you could add a specific server for Poky to attempt before any + others by adding something like the following to the <code class="filename">local.conf</code> + configuration file: + </p> +<pre class="literallayout"> + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + </pre> +<p> + </p> +<p> + These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS + requests and direct them to the <code class="filename">http://</code> sources mirror. + You can use <code class="filename">file://</code> URLs to point to local directories + or network shares as well. + </p> +<p> + Aside from the previous technique, these options also exist: + </p> +<pre class="literallayout"> + BB_NO_NETWORK = "1" + </pre> +<p> + This statement tells BitBake to throw an error instead of trying to access the + Internet. + This technique is useful if you want to ensure code builds only from local sources. + </p> +<p> + Here is another technique: + </p> +<pre class="literallayout"> + BB_FETCH_PREMIRRORONLY = "1" + </pre> +<p> + This statement limits Poky to pulling source from the PREMIRRORS only. + Again, this technique is useful for reproducing builds. + </p> +<p> + Here is another technique: + </p> +<pre class="literallayout"> + BB_GENERATE_MIRROR_TARBALLS = "1" + </pre> +<p> + This statement tells Poky to generate mirror tarballs. + This technique is useful if you want to create a mirror server. + If not, however, the technique can simply waste time during the build. + </p> +<p> + Finally, consider an example where you are behind an HTTP-only firewall. + You could make the following changes to the <code class="filename">local.conf</code> + configuration file as long as the PREMIRROR server is up to date: + </p> +<pre class="literallayout"> + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + BB_FETCH_PREMIRRORONLY = "1" + </pre> +<p> + These changes would cause Poky to successfully fetch source over HTTP and + any network accesses to anything other than the PREMIRROR would fail. + </p> +<p> + The build system also honors the standard shell environment variables + <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>, + <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code> + to redirect requests through proxy servers. + </p> +</td> +</tr> +<tr class="question" title="12.24."> +<td align="left" valign="top"> +<a name="idm3953616"></a><a name="idm3685632"></a><p><b>12.24.</b></p> +</td> +<td align="left" valign="top"><p> + Can I get rid of build output so I can start over? + </p></td> +</tr> +<tr class="answer"> +<td align="left" valign="top"></td> +<td align="left" valign="top"> +<p> + Yes - you can easily do this. + When you use BitBake to build an image, all the build output goes into the + directory created when you source the <code class="filename">oe-init-build-env</code> + setup file. + By default, this <a class="link" href="../dev-manual/build-directory.html" target="_self">build directory</a> + is named <code class="filename">build</code> but can be named + anything you want. + </p> +<p> + Within the build directory is the <code class="filename">tmp</code> directory. + To remove all the build output yet preserve any source code or downloaded files + from previous builds, simply remove the <code class="filename">tmp</code> directory. + </p> +</td> +</tr> +</tbody> +</table> +</div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/fedora-packages.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/fedora-packages.html new file mode 100644 index 0000000000..d1dc7d1f33 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/fedora-packages.html @@ -0,0 +1,62 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3.2.2. Fedora Packages</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System"> +<link rel="prev" href="ubuntu-packages.html" title="1.3.2.1. Ubuntu"> +<link rel="next" href="opensuse-packages.html" title="1.3.2.3. OpenSUSE Packages"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.2. Fedora Packages"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="fedora-packages"></a>1.3.2.2. Fedora Packages</h4></div></div></div> +<p> + The following list shows the required packages by function + given a supported Fedora Linux distribution: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> +<p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image for a headless + system: + </p> +<pre class="literallayout"> + $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ + diffutils diffstat git cpp gcc gcc-c++ eglibc-devel texinfo chrpath \ + ccache + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p> +<pre class="literallayout"> + $ sudo yum install SDL-devel xterm + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p> +<pre class="literallayout"> + $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>: + </p> +<pre class="literallayout"> + $ sudo yum install autoconf automake libtool glib2-devel + </pre> +</li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory-web.png Binary files differnew file mode 100644 index 0000000000..f6db86c977 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory-web.png diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory.png b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory.png Binary files differnew file mode 100644 index 0000000000..614b8ee2e4 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory.png diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/poky-title.png b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/poky-title.png Binary files differnew file mode 100644 index 0000000000..2893d84620 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/poky-title.png diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/future-development-and-limitations.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/future-development-and-limitations.html new file mode 100644 index 0000000000..cd09ff8193 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/future-development-and-limitations.html @@ -0,0 +1,33 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.3.2. Future Development and Limitations</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="x32.html" title="3.3. x32"> +<link rel="prev" href="support.html" title="3.3.1. Support"> +<link rel="next" href="using-x32-right-now.html" title="3.3.3. Using x32 Right Now"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.2. Future Development and Limitations"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div> +<p> + As of this Yocto Project release, the x32 psABI kernel and library interfaces + specifications are not finalized. + </p> +<p> + Future Plans for the x32 psABI in the Yocto Project include the following: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>Enhance and fix the few remaining recipes so they + work with and support x32 toolchains.</p></li> +<li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li> +<li class="listitem"><p>Support larger images.</p></li> +<li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from + <code class="filename">experimental/meta-x32</code> into OE-core.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/handbook.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/handbook.html new file mode 100644 index 0000000000..9588191dbe --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/handbook.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.3. documentation</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-build.html" title="5.1.2. build/"> +<link rel="next" href="structure-core-meta.html" title="5.1.4. meta/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.3. documentation"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="handbook"></a>5.1.3. <code class="filename">documentation</code> +</h3></div></div></div> +<p> + This directory holds the source for the Yocto Project documentation + as well as templates and tools that allow you to generate PDF and HTML + versions of the manuals. + Each manual is contained in a sub-folder. + For example, the files for this manual reside in + <code class="filename">poky-ref-manual</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/index.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/index.html new file mode 100644 index 0000000000..70ef00544c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/index.html @@ -0,0 +1,327 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>The Yocto Project Reference Manual</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="next" href="intro.html" title="Chapter 1. Introduction"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="The Yocto Project Reference Manual"> +<div class="titlepage"> +<div> +<div><h1 class="title"> +<a name="poky-ref-manual"></a> + The Yocto Project Reference Manual + </h1></div> +<div><div class="authorgroup"> + <div class="author"> +<h3 class="author"> +<span class="firstname">Richard</span> <span class="surname">Purdie</span> +</h3> +<div class="affiliation"> + <span class="orgname">Linux Foundation<br></span> + </div> +<code class="email"><<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>></code> +</div> + + </div></div> +<div><p class="copyright">Copyright © 2010-2013 Linux Foundation</p></div> +<div><div class="legalnotice" title="Legal Notice"> +<a name="idm3374608"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_self">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. + </p> + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + <a class="link" href="../poky-ref-manual/index.html" target="_self">Yocto Project Reference Manual</a> on + the <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + </div></div> +<div><div class="revhistory"><table border="1" width="100%" summary="Revision history"> +<tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr> + <tr> +<td align="left">Revision 4.0+git</td> +<td align="left">24 November 2010</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr> + <tr> +<td align="left">Revision 1.0</td> +<td align="left">6 April 2011</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> + <tr> +<td align="left">Revision 1.0.1</td> +<td align="left">23 May 2011</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> + <tr> +<td align="left">Revision 1.1</td> +<td align="left">6 October 2011</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> + <tr> +<td align="left">Revision 1.2</td> +<td align="left">April 2012</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr> +<td align="left">Revision 1.3</td> +<td align="left">October 2012</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + <tr> +<td align="left">Revision 1.4</td> +<td align="left">Sometime in 2013</td> +</tr> +<tr><td align="left" colspan="2">Released with the Yocto Project 1.4 Release.</td></tr> + </table></div></div> +</div> +<hr> +</div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="chapter"><a href="intro.html">1. Introduction</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="intro-welcome.html">1.1. Introduction</a></span></dt> +<dt><span class="section"><a href="intro-manualoverview.html">1.2. Documentation Overview</a></span></dt> +<dt><span class="section"><a href="intro-requirements.html">1.3. System Requirements</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="detailed-supported-distros.html">1.3.1. Supported Linux Distributions</a></span></dt> +<dt><span class="section"><a href="required-packages-for-the-host-development-system.html">1.3.2. Required Packages for the Host Development System</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="intro-getit.html">1.4. Obtaining the Yocto Project</a></span></dt> +<dt><span class="section"><a href="intro-getit-dev.html">1.5. Development Checkouts</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="usingpoky.html">2. Using the Yocto Project</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-build.html">2.1. Running a Build</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="build-overview.html">2.1.1. Build Overview</a></span></dt> +<dt><span class="section"><a href="building-an-image-using-gpl-components.html">2.1.2. Building an Image Using GPL Components</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="usingpoky-install.html">2.2. Installing and Using the Result</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging.html">2.3. Debugging Build Failures</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-debugging-taskfailures.html">2.3.1. Task Failures</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-taskrunning.html">2.3.2. Running Specific Tasks</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-dependencies.html">2.3.3. Dependency Graphs</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-bitbake.html">2.3.4. General BitBake Problems</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-buildfile.html">2.3.5. Building with No Dependencies</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-variables.html">2.3.6. Variables</a></span></dt> +<dt><span class="section"><a href="recipe-logging-mechanisms.html">2.3.7. Recipe Logging Mechanisms</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-others.html">2.3.8. Other Tips</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="maintaining-build-output-quality.html">2.4. Maintaining Build Output Quality</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="enabling-and-disabling-build-history.html">2.4.1. Enabling and Disabling Build History</a></span></dt> +<dt><span class="section"><a href="understanding-what-the-build-history-contains.html">2.4.2. Understanding What the Build History Contains</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="technical-details.html">3. Technical Details</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-components.html">3.1. Yocto Project Components</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-components-bitbake.html">3.1.1. BitBake</a></span></dt> +<dt><span class="section"><a href="usingpoky-components-metadata.html">3.1.2. Metadata (Recipes)</a></span></dt> +<dt><span class="section"><a href="usingpoky-components-classes.html">3.1.3. Classes</a></span></dt> +<dt><span class="section"><a href="usingpoky-components-configuration.html">3.1.4. Configuration</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="shared-state-cache.html">3.2. Shared State Cache</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="overall-architecture.html">3.2.1. Overall Architecture</a></span></dt> +<dt><span class="section"><a href="checksums.html">3.2.2. Checksums (Signatures)</a></span></dt> +<dt><span class="section"><a href="shared-state.html">3.2.3. Shared State</a></span></dt> +<dt><span class="section"><a href="tips-and-tricks.html">3.2.4. Tips and Tricks</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="x32.html">3.3. x32</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="support.html">3.3.1. Support</a></span></dt> +<dt><span class="section"><a href="future-development-and-limitations.html">3.3.2. Future Development and Limitations</a></span></dt> +<dt><span class="section"><a href="using-x32-right-now.html">3.3.3. Using x32 Right Now</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="licenses.html">3.4. Licenses</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-configuring-LIC_FILES_CHKSUM.html">3.4.1. Tracking License Changes</a></span></dt> +<dt><span class="section"><a href="enabling-commercially-licensed-recipes.html">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="migration.html">4. Migrating to a Newer Yocto Project Release</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="moving-to-the-yocto-project-1.3-release.html">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="1.3-local-configuration.html">4.1.1. Local Configuration</a></span></dt> +<dt><span class="section"><a href="1.3-recipes.html">4.1.2. Recipes</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="ref-structure.html">5. Source Directory Structure</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-core.html">5.1. Top level core components</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-core-bitbake.html">5.1.1. <code class="filename">bitbake/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-build.html">5.1.2. <code class="filename">build/</code></a></span></dt> +<dt><span class="section"><a href="handbook.html">5.1.3. <code class="filename">documentation</code></a></span></dt> +<dt><span class="section"><a href="structure-core-meta.html">5.1.4. <code class="filename">meta/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-meta-yocto.html">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-meta-yocto-bsp.html">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-hob.html">5.1.7. <code class="filename">meta-hob/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-skeleton.html">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-scripts.html">5.1.9. <code class="filename">scripts/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-script.html">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt> +<dt><span class="section"><a href="structure-basic-top-level.html">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="structure-build.html">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-build-pseudodone.html">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt> +<dt><span class="section"><a href="structure-build-conf-local.conf.html">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt> +<dt><span class="section"><a href="structure-build-conf-bblayers.conf.html">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt> +<dt><span class="section"><a href="structure-build-conf-sanity_info.html">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt> +<dt><span class="section"><a href="structure-build-downloads.html">5.2.5. <code class="filename">build/downloads/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-sstate-cache.html">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp.html">5.2.7. <code class="filename">build/tmp/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-buildstats.html">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-cache.html">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy.html">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-deb.html">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-rpm.html">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-licenses.html">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-images.html">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-ipk.html">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-sysroots.html">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-stamps.html">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-log.html">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-pkgdata.html">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-work.html">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="structure-meta.html">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-meta-classes.html">5.3.1. <code class="filename">meta/classes/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-conf.html">5.3.2. <code class="filename">meta/conf/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-conf-machine.html">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-conf-distro.html">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-bsp.html">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-connectivity.html">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-core.html">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-devtools.html">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-extended.html">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-gnome.html">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-graphics.html">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-kernel.html">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-multimedia.html">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-qt.html">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-rt.html">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-sato.html">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-support.html">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-site.html">5.3.18. <code class="filename">meta/site/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-txt.html">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="ref-bitbake.html">6. BitBake</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-bitbake-parsing.html">6.1. Parsing</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-providers.html">6.2. Preferences and Providers</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-dependencies.html">6.3. Dependencies</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-tasklist.html">6.4. The Task List</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-runtask.html">6.5. Running a Task</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-commandline.html">6.6. BitBake Command Line</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-fetchers.html">6.7. Fetchers</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="ref-classes.html">7. Classes</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-classes-base.html">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-autotools.html">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-update-alternatives.html">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-update-rc.d.html">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-binconfig.html">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-debian.html">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-pkgconfig.html">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-src-distribute.html">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-perl.html">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-distutils.html">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-devshell.html">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-packagegroup.html">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-package.html">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-kernel.html">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-image.html">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-sanity.html">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-insane.html">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-siteinfo.html">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-useradd.html">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-externalsrc.html">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-others.html">7.21. Other Classes</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="ref-images.html">8. Images</a></span></dt> +<dt><span class="chapter"><a href="ref-features.html">9. Reference: Features</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-features-distro.html">9.1. Distro</a></span></dt> +<dt><span class="section"><a href="ref-features-machine.html">9.2. Machine</a></span></dt> +<dt><span class="section"><a href="ref-features-image.html">9.3. Images</a></span></dt> +<dt><span class="section"><a href="ref-features-backfill.html">9.4. Feature Backfilling</a></span></dt> +</dl></dd> +<dt><span class="chapter"><a href="ref-variables-glos.html">10. Variables Glossary</a></span></dt> +<dd><dl><dt><span class="glossary"><a href="ref-variables-glos.html#ref-variables-glossary">Glossary</a></span></dt></dl></dd> +<dt><span class="chapter"><a href="ref-varlocality.html">11. Variable Context</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-varlocality-configuration.html">11.1. Configuration</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-varlocality-config-distro.html">11.1.1. Distribution (Distro)</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-config-machine.html">11.1.2. Machine</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-config-local.html">11.1.3. Local</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="ref-varlocality-recipes.html">11.2. Recipes</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-varlocality-recipe-required.html">11.2.1. Required</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-recipe-dependencies.html">11.2.2. Dependencies</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-recipe-paths.html">11.2.3. Paths</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-recipe-build.html">11.2.4. Extra Build Information</a></span></dt> +</dl></dd> +</dl></dd> +<dt><span class="chapter"><a href="faq.html">12. FAQ</a></span></dt> +<dt><span class="chapter"><a href="resources.html">13. Contributing to the Yocto Project</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="resources-intro.html">13.1. Introduction</a></span></dt> +<dt><span class="section"><a href="resources-bugtracker.html">13.2. Tracking Bugs</a></span></dt> +<dt><span class="section"><a href="resources-mailinglist.html">13.3. Mailing lists</a></span></dt> +<dt><span class="section"><a href="resources-irc.html">13.4. Internet Relay Chat (IRC)</a></span></dt> +<dt><span class="section"><a href="resources-links.html">13.5. Links</a></span></dt> +<dt><span class="section"><a href="resources-contributions.html">13.6. Contributions</a></span></dt> +</dl></dd> +</dl> +</div> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/index.xml b/documentation/ref-manual/eclipse/html/poky-ref-manual/index.xml new file mode 100644 index 0000000000..9edb4b92ac --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/index.xml @@ -0,0 +1,2 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<index/> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit-dev.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit-dev.html new file mode 100644 index 0000000000..0a2590314f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit-dev.html @@ -0,0 +1,26 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.5. Development Checkouts</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro.html" title="Chapter 1. Introduction"> +<link rel="prev" href="intro-getit.html" title="1.4. Obtaining the Yocto Project"> +<link rel="next" href="usingpoky.html" title="Chapter 2. Using the Yocto Project"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.5. Development Checkouts"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div> +<p> + Development using the Yocto Project requires a local + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, + or by cloning a copy of the upstream + <a class="link" href="../dev-manual/poky.html" target="_self">Poky</a> Git repository. + For information on both these methods, see the + "<a class="link" href="../dev-manual/getting-setup.html" target="_self">Getting Setup</a>" + section in the Yocto Project Development Manual. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit.html new file mode 100644 index 0000000000..56fa85f771 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit.html @@ -0,0 +1,35 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.4. Obtaining the Yocto Project</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro.html" title="Chapter 1. Introduction"> +<link rel="prev" href="centos-packages.html" title="1.3.2.4. CentOS Packages"> +<link rel="next" href="intro-getit-dev.html" title="1.5. Development Checkouts"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.4. Obtaining the Yocto Project"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div> +<p> + The Yocto Project development team makes the Yocto Project available through a number + of methods: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_self">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li> +<li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at + <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_self">http://autobuilder.yoctoproject.org/nightly</a>. + These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and + experimental builds.</p></li> +<li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases + of the Yocto Project and supported BSPs at the + <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project website</a>. + Along with these downloads, you can find lots of other information at this site. + </p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-manualoverview.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-manualoverview.html new file mode 100644 index 0000000000..7f8e368e6d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-manualoverview.html @@ -0,0 +1,73 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.2. Documentation Overview</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro.html" title="Chapter 1. Introduction"> +<link rel="prev" href="intro-welcome.html" title="1.1. Introduction"> +<link rel="next" href="intro-requirements.html" title="1.3. System Requirements"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.2. Documentation Overview"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div> +<p> + This reference manual consists of the following: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter + provides an overview of the components that make up the Yocto Project + followed by information about debugging images created in the Yocto Project. + </p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="technical-details.html" title="Chapter 3. Technical Details">Technical Details</a>:</em></span> + This chapter describes fundamental Yocto Project components as well as an explanation + behind how the Yocto Project uses shared state (sstate) cache to speed build time. + </p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-structure.html" title="Chapter 5. Source Directory Structure">Directory Structure</a>:</em></span> + This chapter describes the + <a class="link" href="../dev-manual/source-directory.html" target="_self">source directory</a> created + either by unpacking a released Yocto Project tarball on your host development system, + or by cloning the upstream + <a class="link" href="../dev-manual/poky.html" target="_self">Poky</a> Git repository. + </p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-bitbake.html" title="Chapter 6. BitBake">BitBake</a>:</em></span> + This chapter provides an overview of the BitBake tool and its role within + the Yocto Project.</p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-classes.html" title="Chapter 7. Classes">Classes</a>:</em></span> + This chapter describes the classes used in the Yocto Project.</p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-images.html" title="Chapter 8. Images">Images</a>:</em></span> + This chapter describes the standard images that the Yocto Project supports. + </p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-features.html" title="Chapter 9. Reference: Features">Features</a>:</em></span> + This chapter describes mechanisms for creating distribution, machine, and image + features during the build process using the OpenEmbedded build system.</p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-variables-glos.html" title="Chapter 10. Variables Glossary">Variables Glossary</a>:</em></span> + This chapter presents most variables used by the OpenEmbedded build system, which + using BitBake. + Entries describe the function of the variable and how to apply them. + </p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="ref-varlocality.html" title="Chapter 11. Variable Context">Variable Context</a>:</em></span> + This chapter provides variable locality or context.</p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="faq.html" title="Chapter 12. FAQ">FAQ</a>:</em></span> + This chapter provides answers for commonly asked questions in the Yocto Project + development environment.</p></li> +<li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span> + This chapter provides guidance on how you can contribute back to the Yocto + Project.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-requirements.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-requirements.html new file mode 100644 index 0000000000..3cab8ac66c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-requirements.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3. System Requirements</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro.html" title="Chapter 1. Introduction"> +<link rel="prev" href="intro-manualoverview.html" title="1.2. Documentation Overview"> +<link rel="next" href="detailed-supported-distros.html" title="1.3.1. Supported Linux Distributions"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3. System Requirements"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="intro-requirements"></a>1.3. System Requirements</h2></div></div></div> +<p> + For general Yocto Project system requirements, see the + "<a class="link" href="../yocto-project-qs/yp-resources.html" target="_self">What You Need and How You Get It</a>" 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-welcome.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-welcome.html new file mode 100644 index 0000000000..378b87f2ed --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro-welcome.html @@ -0,0 +1,30 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.1. Introduction</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro.html" title="Chapter 1. Introduction"> +<link rel="prev" href="intro.html" title="Chapter 1. Introduction"> +<link rel="next" href="intro-manualoverview.html" title="1.2. Documentation Overview"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.1. Introduction"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="intro-welcome"></a>1.1. Introduction</h2></div></div></div> +<p> + This manual provides reference information for the current release of the Yocto Project. + The Yocto Project is an open-source collaboration project focused on embedded Linux + developers. + Amongst other things, the Yocto Project uses the OpenEmbedded build system, which + is based on the Poky project, to construct complete Linux images. + You can find complete introductory and getting started information on the Yocto Project + by reading the + <a class="link" href="../yocto-project-qs/index.html" target="_self">Yocto Project Quick Start</a>. + For task-based information using the Yocto Project, see the + <a class="link" href="../dev-manual/index.html" target="_self">Yocto Project Development Manual</a>. + You can also find lots of information on the Yocto Project on the + <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project website</a>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/intro.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro.html new file mode 100644 index 0000000000..1ff7cdcd05 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/intro.html @@ -0,0 +1,30 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 1. Introduction</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="next" href="intro-welcome.html" title="1.1. Introduction"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 1. Introduction"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="intro"></a>Chapter 1. Introduction</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="intro-welcome.html">1.1. Introduction</a></span></dt> +<dt><span class="section"><a href="intro-manualoverview.html">1.2. Documentation Overview</a></span></dt> +<dt><span class="section"><a href="intro-requirements.html">1.3. System Requirements</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="detailed-supported-distros.html">1.3.1. Supported Linux Distributions</a></span></dt> +<dt><span class="section"><a href="required-packages-for-the-host-development-system.html">1.3.2. Required Packages for the Host Development System</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="intro-getit.html">1.4. Obtaining the Yocto Project</a></span></dt> +<dt><span class="section"><a href="intro-getit-dev.html">1.5. Development Checkouts</a></span></dt> +</dl> +</div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/invalidating-shared-state.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/invalidating-shared-state.html new file mode 100644 index 0000000000..425f17953d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/invalidating-shared-state.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2.4.2. Invalidating Shared State</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks"> +<link rel="prev" href="debugging.html" title="3.2.4.1. Debugging"> +<link rel="next" href="x32.html" title="3.3. x32"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.4.2. Invalidating Shared State"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div> +<p> + The shared state code uses checksums and shared state + cache to avoid unnecessarily rebuilding tasks. + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes that are not factored + into the checksum calculation, but do affect a task's output. + A good example is perhaps when a tool changes its output. + Let's say that the output of <code class="filename">rpmdeps</code> needed to change. + The result of the change should be that all the "package", "package_write_rpm", + and "package_deploy-rpm" shared state cache items would become invalid. + But, because this is a change that is external to the code and therefore implicit, + the associated shared state cache items do not become invalidated. + In this case, the build process would use the cached items rather than running the + task again. + Obviously, these types of implicit changes can cause problems. + </p> +<p> + To avoid these problems during the build, you need to understand the effects of any + change you make. + Note that any changes you make directly to a function automatically are factored into + the checksum calculation and thus, will invalidate the associated area of sstate cache. + 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. + Once you are aware of such a change, you can take steps to invalidate the cache + and force the task to run. + The step to take is 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 <code class="filename">do_package</code> or the comments of one of the functions it calls. + The change is purely cosmetic, but it causes the checksum to be recalculated and + forces the task to be run again. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + For an example of a commit that makes a cosmetic change to invalidate + a shared state, see this + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_self">commit</a>. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/license-flag-matching.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/license-flag-matching.html new file mode 100644 index 0000000000..8909689399 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/license-flag-matching.html @@ -0,0 +1,91 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4.2.1. License Flag Matching</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes"> +<link rel="prev" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes"> +<link rel="next" href="other-variables-related-to-commercial-licenses.html" title="3.4.2.2. Other Variables Related to Commercial Licenses"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.2.1. License Flag Matching"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div> +<p> + The definition of 'matching' in reference to a + recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple. + However, some things exist that you should know about in order to + correctly and effectively use it. + </p> +<p> + Before a flag + defined by a particular recipe is tested against the + contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the + string <code class="filename">_${PN}</code> (with + <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is + appended to the flag, thus automatically making each + <code class="filename">LICENSE_FLAGS</code> value recipe-specific. + That string is + then matched against the whitelist. + So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe + "foo" for example, the string <code class="filename">"commercial_foo"</code> + would normally be what is specified in the whitelist in order for it to + match. + </p> +<p> + You can broaden the match by + putting any "_"-separated beginning subset of a + <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also + match. + For example, simply specifying "commercial" in + the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code> + definition starting with "commercial" such as + "commercial_foo" and "commercial_bar", which are the + strings that would be automatically generated for + hypothetical "foo" and "bar" recipes assuming those + recipes had simply specified the following: + </p> +<pre class="literallayout"> + LICENSE_FLAGS = "commercial" + </pre> +<p> + </p> +<p> + Broadening the match allows for a range of specificity for the items + in the whitelist, from more general to perfectly + specific. + So you have the choice of exhaustively + enumerating each license flag in the whitelist to + allow only those specific recipes into the image, or + of using a more general string to pick up anything + matching just the first component or components of the specified + string. + </p> +<p> + This scheme works even if the flag already + has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is + redundant, but does not affect the outcome. + For example, a license flag of "commercial_1.2_foo" would + turn into "commercial_1.2_foo_foo" and would match + both the general "commercial" and the specific + "commercial_1.2_foo", as expected. + The flag would also match + "commercial_1.2_foo_foo" and "commercial_1.2", which + does not make much sense regarding use in the whitelist. + </p> +<p> + For a versioned string, you could instead specify + "commercial_foo_1.2", which would turn into + "commercial_foo_1.2_foo". + And, as expected, this flag allows + you to pick up this package along with + anything else "commercial" when you specify "commercial" + in the whitelist. + Or, the flag allows you to pick up this package along with anything "commercial_foo" + regardless of version when you use "commercial_foo" in the whitelist. + Finally, you can be completely specific about the package and version and specify + "commercial_foo_1.2" package and version. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/licenses.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/licenses.html new file mode 100644 index 0000000000..3af03e999f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/licenses.html @@ -0,0 +1,28 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4. Licenses</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details"> +<link rel="prev" href="using-x32-right-now.html" title="3.3.3. Using x32 Right Now"> +<link rel="next" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4. Licenses"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="licenses"></a>3.4. Licenses</h2></div></div></div> +<p> + 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. + </p> +<p> + For information that can help you maintain compliance with various open + source licensing during the lifecycle of the product, see the + "<a class="link" href="../dev-manual/maintaining-open-source-license-compliance-during-your-products-lifecycle.html" target="_self">Maintaining Open Source License Compliance During Your Project's Lifecycle</a>" section + in the Yocto Project Development Manual. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-bash.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-bash.html new file mode 100644 index 0000000000..3cea310b1f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-bash.html @@ -0,0 +1,47 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.7.2. Logging With Bash</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms"> +<link rel="prev" href="logging-with-python.html" title="2.3.7.1. Logging With Python"> +<link rel="next" href="usingpoky-debugging-others.html" title="2.3.8. Other Tips"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.7.2. Logging With Bash"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div> +<p> + 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. + </p> +<p> + Following is an example written in Bash. + The code logs the progress of the <code class="filename">do_my_function</code> function. + </p> +<pre class="literallayout"> + 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" + } + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-python.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-python.html new file mode 100644 index 0000000000..e57b647148 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-python.html @@ -0,0 +1,45 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.7.1. Logging With Python</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms"> +<link rel="prev" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms"> +<link rel="next" href="logging-with-bash.html" title="2.3.7.2. Logging With Bash"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.7.1. Logging With Python"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div> +<p> + 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. + </p> +<p> + Following is an example written in Python. + The code handles logging for a function that determines the number of tasks + needed to be run: + </p> +<pre class="literallayout"> + 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") + } + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/maintaining-build-output-quality.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/maintaining-build-output-quality.html new file mode 100644 index 0000000000..f0896e6c89 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/maintaining-build-output-quality.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4. Maintaining Build Output Quality</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project"> +<link rel="prev" href="usingpoky-debugging-others.html" title="2.3.8. Other Tips"> +<link rel="next" href="enabling-and-disabling-build-history.html" title="2.4.1. Enabling and Disabling Build History"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4. Maintaining Build Output Quality"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="maintaining-build-output-quality"></a>2.4. Maintaining Build Output Quality</h2></div></div></div> +<p> + A build's quality can be influenced by many things. + 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, + then 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. + </p> +<p> + The <code class="filename">buildhistory</code> 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. + </p> +<p> + The remainder of this section describes the following: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>How you can enable and disable + build history</p></li> +<li class="listitem"><p>How to understand what the build history contains + </p></li> +<li class="listitem"><p>How to limit the information used for build history + </p></li> +<li class="listitem"><p>How to examine the build history from both a + command-line and web interface</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-bblayers-conf.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-bblayers-conf.html new file mode 100644 index 0000000000..50cd0caa4b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-bblayers-conf.html @@ -0,0 +1,27 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.1.2. bblayers.conf</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-local-configuration.html" title="4.1.1. Local Configuration"> +<link rel="prev" href="migration-1.3-sstate-mirrors.html" title="4.1.1.1. SSTATE_MIRRORS"> +<link rel="next" href="1.3-recipes.html" title="4.1.2. Recipes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.1.2. bblayers.conf"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-bblayers-conf"></a>4.1.1.2. bblayers.conf</h4></div></div></div> +<p> + The <code class="filename">meta-yocto</code> layer has been split into + two parts: <code class="filename">meta-yocto</code> and + <code class="filename">meta-yocto-bsp</code>, corresponding to the + Poky reference distro configuration and the reference + hardware Board Support Packages (BSPs), respectively. + When running BitBake or Hob for the first time after upgrading, + your <code class="filename">conf/bblayers.conf</code> file will be + updated to handle this change and you will be asked to + re-run/restart for the changes to take effect. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-image-features.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-image-features.html new file mode 100644 index 0000000000..48ef697506 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-image-features.html @@ -0,0 +1,26 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2.5. IMAGE_FEATURES</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="prev" href="migration-1.3-task-recipes.html" title="4.1.2.4. Task Recipes"> +<link rel="next" href="migration-1.3-removed-recipes.html" title="4.1.2.6. Removed Recipes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.5. IMAGE_FEATURES"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-image-features"></a>4.1.2.5. IMAGE_FEATURES</h4></div></div></div> +<p> + Image recipes that previously included "apps-console-core" + in <a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES"><code class="filename">IMAGE_FEATURES</code></a> + should now include "splash" instead to enable the boot-up + splash screen. + Retaining "apps-console-core" will still include the splash + screen generates a warning. + The "apps-x11-core" and "apps-x11-games" + <code class="filename">IMAGE_FEATURES</code> features have been removed. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-nativesdk.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-nativesdk.html new file mode 100644 index 0000000000..b20f6101e4 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-nativesdk.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2.3. nativesdk</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="prev" href="migration-1.3-proto=-in-src-uri.html" title="4.1.2.2. proto= in SRC_URI"> +<link rel="next" href="migration-1.3-task-recipes.html" title="4.1.2.4. Task Recipes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.3. nativesdk"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-nativesdk"></a>4.1.2.3. nativesdk</h4></div></div></div> +<p> + The suffix <code class="filename">nativesdk</code> is now implemented + as a prefix, which simplifies a lot of the packaging code for + <code class="filename">nativesdk</code> recipes. + All custom <code class="filename">nativesdk</code> recipes and any + references need to be updated to use + <code class="filename">nativesdk-*</code> instead of + <code class="filename">*-nativesdk</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-proto=-in-src-uri.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-proto=-in-src-uri.html new file mode 100644 index 0000000000..85702b8479 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-proto=-in-src-uri.html @@ -0,0 +1,32 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2.2. proto= in SRC_URI</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="prev" href="migration-1.3-python-function-whitespace.html" title="4.1.2.1. Python Function Whitespace"> +<link rel="next" href="migration-1.3-nativesdk.html" title="4.1.2.3. nativesdk"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.2. proto= in SRC_URI"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-proto=-in-src-uri"></a>4.1.2.2. proto= in SRC_URI</h4></div></div></div> +<p> + Any use of <code class="filename">proto=</code> in + <a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI"><code class="filename">SRC_URI</code></a> + needs to be changed to <code class="filename">protocol=</code>. + In particular, this applies to the following URIs: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename">svn://</code></p></li> +<li class="listitem"><p><code class="filename">bzr://</code></p></li> +<li class="listitem"><p><code class="filename">hg://</code></p></li> +<li class="listitem"><p><code class="filename">osc://</code></p></li> +</ul></div> +<p> + Other URIs were already using <code class="filename">protocol=</code>. + This change improves consistency. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-python-function-whitespace.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-python-function-whitespace.html new file mode 100644 index 0000000000..7b7405984c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-python-function-whitespace.html @@ -0,0 +1,29 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2.1. Python Function Whitespace</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="prev" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="next" href="migration-1.3-proto=-in-src-uri.html" title="4.1.2.2. proto= in SRC_URI"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.1. Python Function Whitespace"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-python-function-whitespace"></a>4.1.2.1. Python Function Whitespace</h4></div></div></div> +<p> + All Python functions must now use four spaces for indentation. + Previously, an inconsistent mix of spaces and tabs existed, + which made extending these functions using + <code class="filename">_append</code> or <code class="filename">_prepend</code> + complicated given that Python treats whitespace as + syntactically significant. + If you are defining or extending any Python functions (e.g. + <code class="filename">populate_packages</code>, <code class="filename">do_unpack</code>, + <code class="filename">do_patch</code> and so forth) in custom recipes + or classes, you need to ensure you are using consistent + four-space indentation. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-removed-recipes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-removed-recipes.html new file mode 100644 index 0000000000..ff8a213ccf --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-removed-recipes.html @@ -0,0 +1,64 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2.6. Removed Recipes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="prev" href="migration-1.3-image-features.html" title="4.1.2.5. IMAGE_FEATURES"> +<link rel="next" href="ref-structure.html" title="Chapter 5. Source Directory Structure"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.6. Removed Recipes"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-removed-recipes"></a>4.1.2.6. Removed Recipes</h4></div></div></div> +<p> + The following recipes have been removed. + For most of them, it is unlikely that you would have any + references to them in your own metadata. + However, you should check your metadata against this list to be sure: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">libx11-trim</code></em></span>: + Replaced by <code class="filename">libx11</code>, which has a negligible + size difference with modern Xorg.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-xorg-lite</code></em></span>: + Use <code class="filename">xserver-xorg</code>, which has a negligible + size difference when DRI and GLX modules are not installed.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-kdrive</code></em></span>: + Effectively unmaintained for many years.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">mesa-xlib</code></em></span>: + No longer serves any purpose.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">galago</code></em></span>: + Replaced by telepathy.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">gail</code></em></span>: + Functionality was integrated into GTK+ 2.13.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">eggdbus</code></em></span>: + No longer needed.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">gcc-*-intermediate</code></em></span>: + The build has been restructured to avoid the need for + this step.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">libgsmd</code></em></span>: + Unmaintained for many years. + Functionality now provided by + <code class="filename">ofono</code> instead.</p></li> +<li class="listitem"><p><span class="emphasis"><em>contacts, dates, tasks, eds-tools</em></span>: + Largely unmaintained PIM application suite. + It has been moved to <code class="filename">meta-gnome</code> + in <code class="filename">meta-openembedded</code>.</p></li> +</ul></div> +<p> + In addition to the previously listed changes, the + <code class="filename">meta-demoapps</code> directory has also been removed + because the recipes in it were not being maintained and many + had become obsolete or broken. + Additionally, these recipes were not parsed in the default configuration. + Many of these recipes are already provided in an updated and + maintained form within OpenEmbedded community layers such as + <code class="filename">meta-oe</code> and <code class="filename">meta-gnome</code>. + For the remainder, you can now find them in the + <code class="filename">meta-extras</code> repository, which is in the + Yocto Project source repositories. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-sstate-mirrors.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-sstate-mirrors.html new file mode 100644 index 0000000000..b2f790649b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-sstate-mirrors.html @@ -0,0 +1,36 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.1.1. SSTATE_MIRRORS</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-local-configuration.html" title="4.1.1. Local Configuration"> +<link rel="prev" href="1.3-local-configuration.html" title="4.1.1. Local Configuration"> +<link rel="next" href="migration-1.3-bblayers-conf.html" title="4.1.1.2. bblayers.conf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.1.1. SSTATE_MIRRORS"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-sstate-mirrors"></a>4.1.1.1. SSTATE_MIRRORS</h4></div></div></div> +<p> + The shared state cache (sstate-cache) as pointed to by + <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> by default + now has two-character subdirectories to prevent there being an issue with too + many files in the same directory. + Also, native sstate-cache packages will go into a subdirectory named using + the distro ID string. + If you copy the newly structured sstate-cache to a mirror location + (either local or remote) and then point to it in + <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>, + you need to append "PATH" to the end of the mirror URL so that + the path used by BitBake before the mirror substitution is + appended to the path used to access the mirror. + Here is an example: + </p> +<pre class="literallayout"> + SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-task-recipes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-task-recipes.html new file mode 100644 index 0000000000..1d93d893b1 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-task-recipes.html @@ -0,0 +1,39 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1.2.4. Task Recipes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes"> +<link rel="prev" href="migration-1.3-nativesdk.html" title="4.1.2.3. nativesdk"> +<link rel="next" href="migration-1.3-image-features.html" title="4.1.2.5. IMAGE_FEATURES"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.4. Task Recipes"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="migration-1.3-task-recipes"></a>4.1.2.4. Task Recipes</h4></div></div></div> +<p> + "Task" recipes are now known as "Package groups" and have + been renamed from <code class="filename">task-*.bb</code> to + <code class="filename">packagegroup-*.bb</code>. + Existing references to the previous <code class="filename">task-*</code> + names should work in most cases as there is an automatic + upgrade path for most packages. + However, you should update references in your own recipes and + configurations as they could be removed in future releases. + You should also rename any custom <code class="filename">task-*</code> + recipes to <code class="filename">packagegroup-*</code>, and change + them to inherit <code class="filename">packagegroup</code> instead of + <code class="filename">task</code>, as well as taking the opportunity + to remove anything now handled by + <code class="filename">packagegroup.bbclass</code>, such as providing + <code class="filename">-dev</code> and <code class="filename">-dbg</code> + packages, setting + <a class="link" href="ref-variables-glos.html#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM"><code class="filename">LIC_FILES_CHKSUM</code></a>, + and so forth. + See the + "<a class="link" href="ref-classes-packagegroup.html" title="7.12. Package Groups - packagegroup.bbclass">Package Groups - packagegroup.bbclass</a>" + section for further details. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/migration.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration.html new file mode 100644 index 0000000000..f7bb138de9 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/migration.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 4. Migrating to a Newer Yocto Project Release</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="other-variables-related-to-commercial-licenses.html" title="3.4.2.2. Other Variables Related to Commercial Licenses"> +<link rel="next" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 4. Migrating to a Newer Yocto Project Release"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="migration"></a>Chapter 4. Migrating to a Newer Yocto Project Release</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="moving-to-the-yocto-project-1.3-release.html">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="1.3-local-configuration.html">4.1.1. Local Configuration</a></span></dt> +<dt><span class="section"><a href="1.3-recipes.html">4.1.2. Recipes</a></span></dt> +</dl></dd> +</dl> +</div> +<p> + This chapter provides information you can use to migrate work to a + newer Yocto Project release. You can find the same information in the + release notes for a given release. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/moving-to-the-yocto-project-1.3-release.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/moving-to-the-yocto-project-1.3-release.html new file mode 100644 index 0000000000..8afa731200 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/moving-to-the-yocto-project-1.3-release.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>4.1. Moving to the Yocto Project 1.3 Release</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="migration.html" title="Chapter 4. Migrating to a Newer Yocto Project Release"> +<link rel="prev" href="migration.html" title="Chapter 4. Migrating to a Newer Yocto Project Release"> +<link rel="next" href="1.3-local-configuration.html" title="4.1.1. Local Configuration"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1. Moving to the Yocto Project 1.3 Release"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="moving-to-the-yocto-project-1.3-release"></a>4.1. Moving to the Yocto Project 1.3 Release</h2></div></div></div> +<p> + This section provides migration information for moving to the + Yocto Project 1.3 Release. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/opensuse-packages.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/opensuse-packages.html new file mode 100644 index 0000000000..16a1860596 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/opensuse-packages.html @@ -0,0 +1,60 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3.2.3. OpenSUSE Packages</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System"> +<link rel="prev" href="fedora-packages.html" title="1.3.2.2. Fedora Packages"> +<link rel="next" href="centos-packages.html" title="1.3.2.4. CentOS Packages"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.3. OpenSUSE Packages"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="opensuse-packages"></a>1.3.2.3. OpenSUSE Packages</h4></div></div></div> +<p> + The following list shows the required packages by function + given a supported OpenSUSE Linux distribution: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> +<p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image for a headless + system: + </p> +<pre class="literallayout"> + $ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \ + diffstat texinfo python-curses + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p> +<pre class="literallayout"> + $ sudo zypper install libSDL-devel xterm + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p> +<pre class="literallayout"> + $ sudo zypper install make fop xsltproc + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>: + </p> +<pre class="literallayout"> + $ sudo zypper install autoconf automake libtool glib2-devel + </pre> +</li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/other-variables-related-to-commercial-licenses.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/other-variables-related-to-commercial-licenses.html new file mode 100644 index 0000000000..31b096ec73 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/other-variables-related-to-commercial-licenses.html @@ -0,0 +1,60 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4.2.2. Other Variables Related to Commercial Licenses</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes"> +<link rel="prev" href="license-flag-matching.html" title="3.4.2.1. License Flag Matching"> +<link rel="next" href="migration.html" title="Chapter 4. Migrating to a Newer Yocto Project Release"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.2.2. Other Variables Related to Commercial Licenses"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div> +<p> + Other helpful variables related to commercial + license handling exist and are defined in the + <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file: + </p> +<pre class="literallayout"> + COMMERCIAL_AUDIO_PLUGINS ?= "" + COMMERCIAL_VIDEO_PLUGINS ?= "" + COMMERCIAL_QT = "" + </pre> +<p> + If you want to enable these components, you can do so by making sure you have + the following statements in your <code class="filename">local.conf</code> configuration file: + </p> +<pre class="literallayout"> + 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" + COMMERCIAL_QT ?= "qmmp" + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" + </pre> +<p> + 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 <code class="filename">LICENSE_FLAGS</code> containing + "commercial", which you may or may not want: + </p> +<pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial" + </pre> +<p> + </p> +<p> + Specifying audio and video plug-ins as part of the + <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and + <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements + or commercial qt components as part of + the <code class="filename">COMMERCIAL_QT</code> statement (along + with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the + plug-ins or components into built images, thus adding + support for media formats or components. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/overall-architecture.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/overall-architecture.html new file mode 100644 index 0000000000..89a6979603 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/overall-architecture.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2.1. Overall Architecture</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache"> +<link rel="prev" href="shared-state-cache.html" title="3.2. Shared State Cache"> +<link rel="next" href="checksums.html" title="3.2.2. Checksums (Signatures)"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.1. Overall Architecture"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div> +<p> + When determining what parts of the system need to be built, BitBake + uses a per-task basis and does not use 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, <code class="filename">do_install</code> and <code class="filename">do_package</code> + output are still valid. + However, with a per-recipe approach, the build would not include the + <code class="filename">.deb</code> files. + Consequently, you would have to invalidate the whole build and rerun it. + Rerunning everything is not the best situation. + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/recipe-logging-mechanisms.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/recipe-logging-mechanisms.html new file mode 100644 index 0000000000..add1017473 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/recipe-logging-mechanisms.html @@ -0,0 +1,41 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.7. Recipe Logging Mechanisms</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging-variables.html" title="2.3.6. Variables"> +<link rel="next" href="logging-with-python.html" title="2.3.7.1. Logging With Python"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.7. Recipe Logging Mechanisms"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div> +<p> + Best practices exist while writing recipes that both log build progress and + act on build conditions such as warnings and errors. + Both Python and Bash language bindings exist for the logging mechanism: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake + supports several loglevels: <code class="filename">bb.fatal</code>, + <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>, + <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>, + and <code class="filename">bb.debug</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set + of loglevels exist and are accessed with a similar syntax: + <code class="filename">bbfatal</code>, <code class="filename">bberror</code>, + <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>, + <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li> +</ul></div> +<p> + </p> +<p> + For guidance on how logging is handled in both Python and Bash recipes, see the + <code class="filename">logging.bbclass</code> file in the + <code class="filename">meta/classes</code> folder of the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-commandline.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-commandline.html new file mode 100644 index 0000000000..34c8394c3f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-commandline.html @@ -0,0 +1,79 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.6. BitBake Command Line</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake-runtask.html" title="6.5. Running a Task"> +<link rel="next" href="ref-bitbake-fetchers.html" title="6.7. Fetchers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.6. BitBake Command Line"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-commandline"></a>6.6. BitBake Command Line</h2></div></div></div> +<p> + Following is the BitBake help output: + </p> +<pre class="screen"> +$ bitbake --help +Usage: bitbake [options] [package ...] + +Executes the specified task (default is 'build') for a given set of BitBake files. +It expects that BBFILES is defined, which is a space separated list of files to +be executed. BBFILES does support wildcards. +Default BBFILES are the .bb files in the current directory. + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + -b BUILDFILE, --buildfile=BUILDFILE + execute the task against this .bb file, rather than a + package from BBFILES. Does not handle any + dependencies. + -k, --continue continue as much as possible after an error. While the + target that failed, and those that depend on it, + cannot be remade, the other dependencies of these + targets can be processed all the same. + -a, --tryaltconfigs continue with builds by trying to use alternative + providers where possible. + -f, --force force run of specified cmd, regardless of stamp status + -c CMD, --cmd=CMD Specify task to execute. Note that this only executes + the specified task for the providee and the packages + it depends on, i.e. 'compile' does not implicitly call + stage for the dependencies (IOW: use only if you know + what you are doing). Depending on the base.bbclass a + listtasks tasks is defined and will show available + tasks + -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 chit-chat 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 files (developers only) + -s, --show-versions show current and preferred versions of all packages + -e, --environment show the global or per-package environment (this is + what used to be bbread) + -g, --graphviz emit the dependency trees of the specified packages 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 print a report + -u UI, --ui=UI userinterface to use + -t SERVERTYPE, --servertype=SERVERTYPE + Choose which server to use, none, process or xmlrpc + --revisions-changed Set the exit code depending on whether upstream + floating revisions have changed or not + </pre> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-dependencies.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-dependencies.html new file mode 100644 index 0000000000..e7106ca6d2 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-dependencies.html @@ -0,0 +1,34 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.3. Dependencies</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake-providers.html" title="6.2. Preferences and Providers"> +<link rel="next" href="ref-bitbake-tasklist.html" title="6.4. The Task List"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.3. Dependencies"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-dependencies"></a>6.3. Dependencies</h2></div></div></div> +<p> + Each target BitBake builds consists of multiple tasks such as + <code class="filename">fetch</code>, <code class="filename">unpack</code>, + <code class="filename">patch</code>, <code class="filename">configure</code>, + and <code class="filename">compile</code>. + For best performance on multi-core systems, BitBake considers each task as an independent + entity with its own set of dependencies. + </p> +<p> + Dependencies are defined through several variables. + You can find information about variables BitBake uses in the BitBake documentation, + which is found in the <code class="filename">bitbake/doc/manual</code> directory within the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + At a basic level, it is sufficient to know that BitBake uses the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and + <code class="filename"><a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when + calculating dependencies. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-fetchers.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-fetchers.html new file mode 100644 index 0000000000..e1bda8b995 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-fetchers.html @@ -0,0 +1,43 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.7. Fetchers</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake-commandline.html" title="6.6. BitBake Command Line"> +<link rel="next" href="ref-classes.html" title="Chapter 7. Classes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.7. Fetchers"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-fetchers"></a>6.7. Fetchers</h2></div></div></div> +<p> + 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 <code class="filename">cvs/subversion/git</code>. + </p> +<p> + Fetchers are usually triggered by entries in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>. + You can find information about the options and formats of entries for specific + fetchers in the BitBake manual located in the + <code class="filename">bitbake/doc/manual</code> directory of the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </p> +<p> + 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 <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV">SRCREV</a></code> + variable. + See the + "<a class="link" href="../dev-manual/platdev-appdev-srcrev.html" target="_self">Using an External SCM</a>" section + in the Yocto Project Development Manual for more information. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-parsing.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-parsing.html new file mode 100644 index 0000000000..c86621eb38 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-parsing.html @@ -0,0 +1,93 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.1. Parsing</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="next" href="ref-bitbake-providers.html" title="6.2. Preferences and Providers"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.1. Parsing"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-parsing"></a>6.1. Parsing</h2></div></div></div> +<p> + BitBake parses configuration files, classes, and <code class="filename">.bb</code> files. + </p> +<p> + The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file. + This file resides in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> + within the <code class="filename">meta/conf/</code> directory. + BitBake finds it by examining its + <a class="link" href="ref-variables-glos.html#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment + variable and looking for the <code class="filename">meta/conf/</code> + directory. + </p> +<p> + The <code class="filename">bitbake.conf</code> file lists other configuration + files to include from a <code class="filename">conf/</code> + directory below the directories listed in <code class="filename">BBPATH</code>. + In general, the most important configuration file from a user's perspective + is <code class="filename">local.conf</code>, which contains a user's customized + settings for the OpenEmbedded build environment. + Other notable configuration files are the distribution + configuration file (set by the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO" title="DISTRO">DISTRO</a></code> variable) + and the machine configuration file + (set by the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a></code> variable). + The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment + variables are both usually set in + the <code class="filename">local.conf</code> file. + Valid distribution + configuration files are available in the <code class="filename">meta/conf/distro/</code> directory + and valid machine configuration + files in the <code class="filename">meta/conf/machine/</code> directory. + Within the <code class="filename">meta/conf/machine/include/</code> + directory are various <code class="filename">tune-*.inc</code> configuration files that provide common + "tuning" settings specific to and shared between particular architectures and machines. + </p> +<p> + After the parsing of the configuration files, some standard classes are included. + The <code class="filename">base.bbclass</code> file is always included. + Other classes that are specified in the configuration using the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-INHERIT" title="INHERIT">INHERIT</a></code> + variable are also included. + Class files are searched for in a <code class="filename">classes</code> subdirectory + under the paths in <code class="filename">BBPATH</code> in the same way as + configuration files. + </p> +<p> + After classes are included, the variable + <code class="filename"><a class="link" href="ref-variables-glos.html#var-BBFILES" title="BBFILES">BBFILES</a></code> + is set, usually in + <code class="filename">local.conf</code>, and defines the list of places to search for + <code class="filename">.bb</code> files. + By default, the <code class="filename">BBFILES</code> variable specifies the + <code class="filename">meta/recipes-*/</code> directory within Poky. + Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of + BitBake layers as described in the + "<a class="link" href="../dev-manual/understanding-and-creating-layers.html" target="_self">Understanding and + Creating Layers</a>" section of the Yocto Project Development Manual. + </p> +<p> + BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and + stores the values of various variables. + In summary, for each <code class="filename">.bb</code> + file the configuration plus the base class of variables are set, followed + by the data in the <code class="filename">.bb</code> file + itself, followed by any inherit commands that + <code class="filename">.bb</code> file might contain. + </p> +<p> + Because parsing <code class="filename">.bb</code> files is a time + consuming process, a cache is kept to speed up subsequent parsing. + This cache is invalid if the timestamp of the <code class="filename">.bb</code> + file itself changes, or if the timestamps of any of the include, + configuration or class files the <code class="filename">.bb</code> + file depends on changes. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-providers.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-providers.html new file mode 100644 index 0000000000..37d34a0e70 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-providers.html @@ -0,0 +1,63 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.2. Preferences and Providers</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake-parsing.html" title="6.1. Parsing"> +<link rel="next" href="ref-bitbake-dependencies.html" title="6.3. Dependencies"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.2. Preferences and Providers"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-providers"></a>6.2. Preferences and Providers</h2></div></div></div> +<p> + Once all the <code class="filename">.bb</code> files have been + parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code> + 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 <code class="filename">core-image-sato</code>, it would lead to + <code class="filename">packagegroup-core-x11-sato</code>, + which in turn leads to recipes like <code class="filename">matchbox-terminal</code>, + <code class="filename">pcmanfm</code> and <code class="filename">gthumb</code>. + These recipes in turn depend on <code class="filename">eglibc</code> and the toolchain. + </p> +<p> + 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: + </p> +<pre class="literallayout"> + PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" + </pre> +<p> + The default <code class="filename"><a class="link" href="ref-variables-glos.html#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code> + is the provider with the same name as the target. + </p> +<p> + 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 + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code> + variable to specify a particular version (usually in the distro configuration). + You can influence the order by using the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code> + variable. + By default, files have a preference of "0". + Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the + package unlikely to be used unless it is explicitly referenced. + Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used. + <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting. + <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package + versions until they have undergone sufficient testing to be considered stable. + </p> +<p> + In summary, BitBake has created a list of providers, which is prioritized, for each target. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-runtask.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-runtask.html new file mode 100644 index 0000000000..f653e30561 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-runtask.html @@ -0,0 +1,86 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.5. Running a Task</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake-tasklist.html" title="6.4. The Task List"> +<link rel="next" href="ref-bitbake-commandline.html" title="6.6. BitBake Command Line"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.5. Running a Task"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-runtask"></a>6.5. Running a Task</h2></div></div></div> +<p> + Tasks can either be a shell task or a Python task. + For shell tasks, BitBake writes a shell script to + <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> 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 <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. + Looking at the expanded shell functions in the run file and the output in the log files + is a useful debugging technique. + </p> +<p> + 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 way similar to shell tasks as well. + </p> +<p> + Once all the tasks have been completed BitBake exits. + </p> +<p> + 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: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<p>Tell BitBake to load what you want from the environment + into the data store. + You can do so through the <code class="filename">BB_ENV_EXTRAWHITE</code> + variable. + For example, assume you want to prevent the build system from + accessing your <code class="filename">$HOME/.ccache</code> directory. + The following command tells BitBake to load + <code class="filename">CCACHE_DIR</code> from the environment into the data + store: + </p> +<pre class="literallayout"> + export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" + </pre> +</li> +<li class="listitem"> +<p>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 + <code class="filename">local.conf</code> or distro configuration file: + </p> +<pre class="literallayout"> + export CCACHE_DIR + </pre> +</li> +</ol></div> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + 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 <code class="filename">BB_HASHBASE_WHITELIST</code> + example in the "<a class="link" href="checksums.html" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-tasklist.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-tasklist.html new file mode 100644 index 0000000000..fedbcca285 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-tasklist.html @@ -0,0 +1,54 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>6.4. The Task List</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake"> +<link rel="prev" href="ref-bitbake-dependencies.html" title="6.3. Dependencies"> +<link rel="next" href="ref-bitbake-runtask.html" title="6.5. Running a Task"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.4. The Task List"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-bitbake-tasklist"></a>6.4. The Task List</h2></div></div></div> +<p> + 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 + <code class="filename"><a class="link" href="ref-variables-glos.html#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></code> 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. + </p> +<p> + It is worth noting that you can greatly speed up the build time by properly setting + the <code class="filename">BB_NUMBER_THREADS</code> variable. + See the + "<a class="link" href="../yocto-project-qs/building-image.html" target="_self">Building an Image</a>" + section in the Yocto Project Quick Start for more information. + </p> +<p> + As each task completes, a timestamp is written to the directory specified by the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-STAMP" title="STAMP">STAMP</a></code> variable (usually + <code class="filename">build/tmp/stamps/*/</code>). + On subsequent runs, BitBake looks at the <code class="filename">/build/tmp/stamps</code> + 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 + <code class="filename">.bb</code> 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. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + Some tasks are marked as "nostamp" tasks. + No timestamp file is created when these tasks are run. + Consequently, "nostamp" tasks are always rerun. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake.html new file mode 100644 index 0000000000..c724158b6e --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake.html @@ -0,0 +1,48 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 6. BitBake</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="structure-meta-recipes-txt.html" title="5.3.19. meta/recipes.txt"> +<link rel="next" href="ref-bitbake-parsing.html" title="6.1. Parsing"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 6. BitBake"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-bitbake"></a>Chapter 6. BitBake</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="ref-bitbake-parsing.html">6.1. Parsing</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-providers.html">6.2. Preferences and Providers</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-dependencies.html">6.3. Dependencies</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-tasklist.html">6.4. The Task List</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-runtask.html">6.5. Running a Task</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-commandline.html">6.6. BitBake Command Line</a></span></dt> +<dt><span class="section"><a href="ref-bitbake-fetchers.html">6.7. Fetchers</a></span></dt> +</dl> +</div> +<p> + BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded + build system. + At some point, developers wonder what actually happens when you enter: + </p> +<pre class="literallayout"> + $ bitbake core-image-sato + </pre> +<p> + </p> +<p> + This chapter provides an overview of what happens behind the scenes from BitBake's perspective. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + 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 metadata + that consists of variables in a certain format that get passed to the tasks. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-autotools.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-autotools.html new file mode 100644 index 0000000000..36ae47a158 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-autotools.html @@ -0,0 +1,52 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.2. Autotooled Packages - autotools.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-base.html" title="7.1. The base class - base.bbclass"> +<link rel="next" href="ref-classes-update-alternatives.html" title="7.3. Alternatives - update-alternatives.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.2. Autotooled Packages - autotools.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-autotools"></a>7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code> +</h2></div></div></div> +<p> + Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>, + and <code class="filename">libtool</code>) bring standardization. + This class defines a set of tasks (configure, compile etc.) that + work for all Autotooled packages. + It should usually be enough to define a few standard variables + and then simply <code class="filename">inherit autotools</code>. + This class can also work with software that emulates Autotools. + For more information, see the + "<a class="link" href="../dev-manual/usingpoky-extend-addpkg-autotools.html" target="_self">Autotooled Package</a>" + section in the Yocto Project Development Manual. + </p> +<p> + It's useful to have some idea of how the tasks defined by this class work + and what they do behind the scenes. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename">do_configure</code> ‐ regenerates the + configure script (using <code class="filename">autoreconf</code>) and then launches it + with a standard set of arguments used during cross-compilation. + You can pass additional parameters to <code class="filename">configure</code> through the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable. + </p></li> +<li class="listitem"><p><code class="filename">do_compile</code> ‐ runs <code class="filename">make</code> with + arguments that specify the compiler and linker. + You can pass additional arguments through + the <code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable. + </p></li> +<li class="listitem"><p><code class="filename">do_install</code> ‐ runs <code class="filename">make install</code> + and passes a DESTDIR option, which takes its value from the standard + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable. + </p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-base.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-base.html new file mode 100644 index 0000000000..a10285bf40 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-base.html @@ -0,0 +1,28 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.1. The base class - base.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="next" href="ref-classes-autotools.html" title="7.2. Autotooled Packages - autotools.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.1. The base class - base.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-base"></a>7.1. The base class - <code class="filename">base.bbclass</code> +</h2></div></div></div> +<p> + The base class is special in that every <code class="filename">.bb</code> + file inherits it automatically. + This class contains definitions for standard basic + tasks such as fetching, unpacking, configuring (empty by default), compiling + (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging + (empty by default). + These classes are often overridden or extended by other classes + such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>. + The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-binconfig.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-binconfig.html new file mode 100644 index 0000000000..bbf035e950 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-binconfig.html @@ -0,0 +1,30 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.5. Binary config scripts - binconfig.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-update-rc.d.html" title="7.4. Initscripts - update-rc.d.bbclass"> +<link rel="next" href="ref-classes-debian.html" title="7.6. Debian renaming - debian.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.5. Binary config scripts - binconfig.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-binconfig"></a>7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code> +</h2></div></div></div> +<p> + Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell + scripts to give information about the libraries and include paths needed + to build software (usually named <code class="filename">LIBNAME-config</code>). + This class assists any recipe using such scripts. + </p> +<p> + During staging, BitBake installs such scripts into the + <code class="filename">sysroots/</code> directory. + BitBake also changes all paths to point into the <code class="filename">sysroots/</code> + directory so all builds that use the script will use the correct + directories for the cross compiling layout. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-debian.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-debian.html new file mode 100644 index 0000000000..9d37cbb716 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-debian.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.6. Debian renaming - debian.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-binconfig.html" title="7.5. Binary config scripts - binconfig.bbclass"> +<link rel="next" href="ref-classes-pkgconfig.html" title="7.7. Pkg-config - pkgconfig.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.6. Debian renaming - debian.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-debian"></a>7.6. Debian renaming - <code class="filename">debian.bbclass</code> +</h2></div></div></div> +<p> + This class renames packages so that they follow the Debian naming + policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code> + and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-devshell.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-devshell.html new file mode 100644 index 0000000000..cbbcc4c4c6 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-devshell.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.11. Developer Shell - devshell.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-distutils.html" title="7.10. Python extensions - distutils.bbclass"> +<link rel="next" href="ref-classes-packagegroup.html" title="7.12. Package Groups - packagegroup.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.11. Developer Shell - devshell.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-devshell"></a>7.11. Developer Shell - <code class="filename">devshell.bbclass</code> +</h2></div></div></div> +<p> + This class adds the <code class="filename">devshell</code> task. + Distribution policy dictates whether to include this class. + See the + "<a class="link" href="../dev-manual/platdev-appdev-devshell.html" target="_self">Using a Development Shell</a>" section + in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-distutils.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-distutils.html new file mode 100644 index 0000000000..d176cb8dc1 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-distutils.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.10. Python extensions - distutils.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-perl.html" title="7.9. Perl modules - cpan.bbclass"> +<link rel="next" href="ref-classes-devshell.html" title="7.11. Developer Shell - devshell.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.10. Python extensions - distutils.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-distutils"></a>7.10. Python extensions - <code class="filename">distutils.bbclass</code> +</h2></div></div></div> +<p> + Recipes for Python extensions are simple. + These recipes usually only need to point to the source's archive and then inherit + the proper <code class="filename">.bbclass</code> file. + Building is split into two methods dependling on which method the module authors used. + </p> +<p> + Extensions that use an Autotools-based build system require Autotools and + <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes. + </p> +<p> + Extensions that use <code class="filename">distutils</code>-based build systems require + <code class="filename">distutils.bbclass</code> in their recipes. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-externalsrc.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-externalsrc.html new file mode 100644 index 0000000000..ead3708607 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-externalsrc.html @@ -0,0 +1,72 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.20. Using External Source - externalsrc.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-useradd.html" title="7.19. Adding Users - useradd.bbclass"> +<link rel="next" href="ref-classes-others.html" title="7.21. Other Classes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.20. Using External Source - externalsrc.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-externalsrc"></a>7.20. Using External Source - <code class="filename">externalsrc.bbclass</code> +</h2></div></div></div> +<p> + You can use this class to build software from source code that is external to the + OpenEmbedded build system. + In other words, your source code resides in an external tree outside of the Yocto Project. + Building software from an external source tree means that the normal fetch, unpack, and + patch process is not used. + </p> +<p> + To use the class, you need to define the + <a class="link" href="ref-variables-glos.html#var-S" title="S"><code class="filename">S</code></a> variable to point to the directory that contains the source files. + You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class. + </p> +<p> + This class expects the source code to support recipe builds that use the + <a class="link" href="ref-variables-glos.html#var-B" title="B"><code class="filename">B</code></a> variable to point to the directory in + which the OpenEmbedded build system places the generated objects built from the recipes. + By default, the <code class="filename">B</code> directory is set to the following, which is separate from the + Source Directory (<code class="filename">S</code>): + </p> +<pre class="literallayout"> + ${WORKDIR}/${BPN}-{PV}/ + </pre> +<p> + See the glossary entries for the + <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>, + <a class="link" href="ref-variables-glos.html#var-BPN" title="BPN"><code class="filename">BPN</code></a>, + <a class="link" href="ref-variables-glos.html#var-PV" title="PV"><code class="filename">PV</code></a>, + <a class="link" href="ref-variables-glos.html#var-S" title="S"><code class="filename">S</code></a>, and + <a class="link" href="ref-variables-glos.html#var-B" title="B"><code class="filename">B</code></a> for more information. + </p> +<p> + You can build object files in the external tree by setting the + <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>. + However, this practice does not work well if you use the source for more than one variant + (i.e., "natives" such as <code class="filename">quilt-native</code>, + or "crosses" such as <code class="filename">gcc-cross</code>). + So, be sure there are no "native", "cross", or "multilib" variants of the recipe. + </p> +<p> + If you do want to build different variants of a recipe, you can use the + <a class="link" href="ref-variables-glos.html#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable. + When you do, the <a class="link" href="ref-variables-glos.html#var-B" title="B"><code class="filename">B</code></a> variable must support the + recipe's ability to build variants in different working directories. + Most autotools-based recipes support separating these directories. + The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code> + and some kernel recipes. + Alternatively, you can make sure that separate recipes exist that each + use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant. + The separate recipes can inherit a single target recipe. + </p> +<p> + For information on how to use this class, see the + "<a class="link" href="../dev-manual/building-software-from-an-external-source.html" target="_self">Building + Software from an External Source</a>" section in the Yocto Project Development Manual. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-image.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-image.html new file mode 100644 index 0000000000..a8453e97b9 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-image.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.15. Creating images - image.bbclass and rootfs*.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-kernel.html" title="7.14. Building kernels - kernel.bbclass"> +<link rel="next" href="ref-classes-sanity.html" title="7.16. Host System sanity checks - sanity.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.15. Creating images - image.bbclass and rootfs*.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-image"></a>7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code> +</h2></div></div></div> +<p> + These classes add support for creating images in several formats. + First, the root filesystem is created from packages using + one of the <code class="filename">rootfs_*.bbclass</code> + files (depending on the package format used) and then the image is created. + </p> +<p> + The <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code> + variable controls the types of images to generate. + </p> +<p> + The <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code> + variable controls the list of packages to install into the image. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-insane.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-insane.html new file mode 100644 index 0000000000..1cdf589cff --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-insane.html @@ -0,0 +1,105 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.17. Generated output quality assurance checks - insane.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-sanity.html" title="7.16. Host System sanity checks - sanity.bbclass"> +<link rel="next" href="ref-classes-siteinfo.html" title="7.18. Autotools configuration data cache - siteinfo.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.17. Generated output quality assurance checks - insane.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-insane"></a>7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code> +</h2></div></div></div> +<p> + This class adds a step to the package generation process that sanity checks the + packages generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + </p> +<p> + You can configure the sanity checks so that specific test failures either raise a warning or + an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error message + once the metadata is in a known and good condition. + You use the <code class="filename">WARN_QA</code> variable to specify tests for which you + want to generate a warning message on failure. + You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you + want to generate an error message on failure. + </p> +<p> + The following list shows the tests you can list with the <code class="filename">WARN_QA</code> + and <code class="filename">ERROR_QA</code> variables: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span> + Ensures that the binaries were linked with the + <code class="filename">LDFLAGS</code> options provided by the build system. + If this test fails, check that the <code class="filename">LDFLAGS</code> variable + is being passed to the linker command.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span> + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>). + While these paths will not cause any breakage, they do waste space and + are unnecessary.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span> + Checks for rpaths in the binaries that contain build system paths such + as <code class="filename">TMPDIR</code>. + If this test fails, bad <code class="filename">-rpath</code> options are being + passed to the linker commands and your binaries have potential security + issues.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span> + Checks that the <code class="filename">.so</code> symbolic links are in the + <code class="filename">-dev</code> package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the <code class="filename">-dev</code> package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span> + Checks for <code class="filename">.debug</code> directories in anything but the + <code class="filename">-dbg</code> package. + The debug files should all be in the <code class="filename">-dbg</code> package. + Thus, anything packaged elsewhere is incorrect packaging.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span> + Checks the Executable and Linkable Format (ELF) type, bit size and endianness + of any binaries to ensure it matches the target architecture. + This test fails if any binaries don't match the type since there would be an + incompatibility. + Sometimes software, like bootloaders, might need to bypass this check. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span> + Checks that <code class="filename">-dbg</code> packages only depend on other + <code class="filename">-dbg</code> packages and not on any other types of packages, + which would cause a packaging bug.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span> + Checks that <code class="filename">-dev</code> packages only depend on other + <code class="filename">-dev</code> packages and not on any other types of packages, + which would be a packaging bug.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span> + Checks <code class="filename">.pc</code> files for any + <code class="filename">TMPDIR/WORKDIR</code> paths. + Any <code class="filename">.pc</code> file containing these paths is incorrect + since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix + when the files are accessed.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span> + Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code> + paths. + Any <code class="filename">.la</code> file continaing these paths is incorrect since + <code class="filename">libtool</code> adds the correct sysroot prefix when using the + files automatically itself.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span> + Runs the <code class="filename">desktop-file-validate</code> program against any + <code class="filename">.desktop</code> files to validate their contents against + the specification for <code class="filename">.desktop</code> files.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-kernel.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-kernel.html new file mode 100644 index 0000000000..72afff8226 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-kernel.html @@ -0,0 +1,36 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.14. Building kernels - kernel.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass"> +<link rel="next" href="ref-classes-image.html" title="7.15. Creating images - image.bbclass and rootfs*.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.14. Building kernels - kernel.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-kernel"></a>7.14. Building kernels - <code class="filename">kernel.bbclass</code> +</h2></div></div></div> +<p> + This class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code> + directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>. + </p> +<p> + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the <code class="filename">modinfo</code> output. + If all modules are required, then installing the <code class="filename">kernel-modules</code> + package installs all packages with modules and various other kernel packages + such as <code class="filename">kernel-vmlinux</code>. + </p> +<p> + Various other classes are used by the kernel and module classes internally including + <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>, + <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-others.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-others.html new file mode 100644 index 0000000000..cafdb13b11 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-others.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.21. Other Classes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-externalsrc.html" title="7.20. Using External Source - externalsrc.bbclass"> +<link rel="next" href="ref-images.html" title="Chapter 8. Images"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.21. Other Classes"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-others"></a>7.21. Other Classes</h2></div></div></div> +<p> + Thus far, this chapter has discussed only the most useful and important + classes. + However, other classes exist within the <code class="filename">meta/classes</code> directory + in the <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + You can examine the <code class="filename">.bbclass</code> files directly for more + information. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-package.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-package.html new file mode 100644 index 0000000000..eb43660f9e --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-package.html @@ -0,0 +1,73 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.13. Packaging - package*.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-packagegroup.html" title="7.12. Package Groups - packagegroup.bbclass"> +<link rel="next" href="ref-classes-kernel.html" title="7.14. Building kernels - kernel.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.13. Packaging - package*.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-package"></a>7.13. Packaging - <code class="filename">package*.bbclass</code> +</h2></div></div></div> +<p> + The packaging classes add support for generating packages from a build's + output. + The core generic functionality is in <code class="filename">package.bbclass</code>. + The code specific to particular package types is contained in various sub-classes such as + <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>, + and <code class="filename">package_rpm.bbclass</code>. + Most users will want one or more of these classes. + </p> +<p> + You can control the list of resulting package formats by using the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code> + variable defined in the <code class="filename">local.conf</code> configuration file, + which is located in the <code class="filename">conf</code> folder of the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + </p> +<p> + The package class you choose can affect build-time performance and has space + ramifications. + In general, building a package with RPM takes about thirty percent more time as + compared to using IPK to build the same or similar package. + This comparison takes into account a complete build of the package with all + dependencies previously built. + The reason for this discrepancy is because the RPM package manager creates and + processes more metadata than the IPK package manager. + Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code> + to "package_ipk" if you are building smaller systems. + </p> +<p> + Keep in mind, however, that RPM starts to provide more abilities than IPK due to + the fact that it processes more metadata. + For example, this information includes individual file types, file checksum generation + and evaluation on install, sparse file support, conflict detection and resolution + for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks. + </p> +<p> + Another consideration for packages built using the RPM package manager is space. + For smaller systems, the extra space used for the Berkley Database and the amount + of metadata can affect your ability to do on-device upgrades. + </p> +<p> + You can find additional information on the effects of the package class at these + two Yocto Project mailing list links: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_self"> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li> +<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_self"> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-packagegroup.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-packagegroup.html new file mode 100644 index 0000000000..96944339aa --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-packagegroup.html @@ -0,0 +1,33 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.12. Package Groups - packagegroup.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-devshell.html" title="7.11. Developer Shell - devshell.bbclass"> +<link rel="next" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.12. Package Groups - packagegroup.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-packagegroup"></a>7.12. Package Groups - <code class="filename">packagegroup.bbclass</code> +</h2></div></div></div> +<p> + This class sets default values appropriate for package group recipes (such as + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>, + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>, + <code class="filename"><a class="link" href="ref-variables-glos.html#var-ALLOW_EMPTY" title="ALLOW_EMPTY">ALLOW_EMPTY</a></code>, + and so forth. + It is highly recommended that all package group recipes inherit this class. + </p> +<p> + For information on how to use this class, see the + "<a class="link" href="../dev-manual/usingpoky-extend-customimage-customtasks.html" target="_self">Customizing Images Using Custom Package Tasks</a>" + section in the Yocto Project Development Manual. + </p> +<p> + Previously, this class was named <code class="filename">task.bbclass</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-perl.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-perl.html new file mode 100644 index 0000000000..b4be9b4da0 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-perl.html @@ -0,0 +1,31 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.9. Perl modules - cpan.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-src-distribute.html" title="7.8. Distribution of sources - src_distribute_local.bbclass"> +<link rel="next" href="ref-classes-distutils.html" title="7.10. Python extensions - distutils.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.9. Perl modules - cpan.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-perl"></a>7.9. Perl modules - <code class="filename">cpan.bbclass</code> +</h2></div></div></div> +<p> + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and then inherit the + proper <code class="filename">.bbclass</code> file. + Building is split into two methods depending on which method the module authors used. + </p> +<p> + Modules that use old <code class="filename">Makefile.PL</code>-based build system require + <code class="filename">cpan.bbclass</code> in their recipes. + </p> +<p> + Modules that use <code class="filename">Build.PL</code>-based build system require + using <code class="filename">cpan_build.bbclass</code> in their recipes. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-pkgconfig.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-pkgconfig.html new file mode 100644 index 0000000000..09566fd328 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-pkgconfig.html @@ -0,0 +1,27 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.7. Pkg-config - pkgconfig.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-debian.html" title="7.6. Debian renaming - debian.bbclass"> +<link rel="next" href="ref-classes-src-distribute.html" title="7.8. Distribution of sources - src_distribute_local.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.7. Pkg-config - pkgconfig.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-pkgconfig"></a>7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code> +</h2></div></div></div> +<p> + <code class="filename">pkg-config</code> brought standardization and this class aims to make its + integration smooth for all libraries that make use of it. + </p> +<p> + During staging, BitBake installs <code class="filename">pkg-config</code> data into the + <code class="filename">sysroots/</code> directory. + By making use of sysroot functionality within <code class="filename">pkg-config</code>, + this class no longer has to manipulate the files. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-sanity.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-sanity.html new file mode 100644 index 0000000000..0e3a19a76a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-sanity.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.16. Host System sanity checks - sanity.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-image.html" title="7.15. Creating images - image.bbclass and rootfs*.bbclass"> +<link rel="next" href="ref-classes-insane.html" title="7.17. Generated output quality assurance checks - insane.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.16. Host System sanity checks - sanity.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-sanity"></a>7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code> +</h2></div></div></div> +<p> + This class checks to see if prerequisite software is present so that + users can be notified of potential problems that might affect their build. + The class also performs basic user configuration checks from + the <code class="filename">local.conf</code> configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually determines whether to include this class. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-siteinfo.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-siteinfo.html new file mode 100644 index 0000000000..878794d201 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-siteinfo.html @@ -0,0 +1,39 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.18. Autotools configuration data cache - siteinfo.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-insane.html" title="7.17. Generated output quality assurance checks - insane.bbclass"> +<link rel="next" href="ref-classes-useradd.html" title="7.19. Adding Users - useradd.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.18. Autotools configuration data cache - siteinfo.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-siteinfo"></a>7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code> +</h2></div></div></div> +<p> + Autotools can require tests that must execute on the target hardware. + Since this is not possible in general when cross compiling, site information is + used to provide cached test results so these tests can be skipped over but + still make the correct values available. + The <code class="filename"><a class="link" href="structure-meta-site.html" title="5.3.18. meta/site/">meta/site directory</a></code> + contains test results sorted into different categories such as architecture, endianness, and + the <code class="filename">libc</code> used. + Site information provides a list of files containing data relevant to + the current build in the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable + that Autotools automatically picks up. + </p> +<p> + The class also provides variables like + <code class="filename"><a class="link" href="ref-variables-glos.html#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code> + and <code class="filename"><a class="link" href="ref-variables-glos.html#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code> + that can be used elsewhere in the metadata. + </p> +<p> + Because this class is included from <code class="filename">base.bbclass</code>, it is always active. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-src-distribute.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-src-distribute.html new file mode 100644 index 0000000000..a1bbb8b415 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-src-distribute.html @@ -0,0 +1,43 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.8. Distribution of sources - src_distribute_local.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-pkgconfig.html" title="7.7. Pkg-config - pkgconfig.bbclass"> +<link rel="next" href="ref-classes-perl.html" title="7.9. Perl modules - cpan.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.8. Distribution of sources - src_distribute_local.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-src-distribute"></a>7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code> +</h2></div></div></div> +<p> + Many software licenses require that source files be provided along with the binaries. + To simplify this process, two classes were created: + <code class="filename">src_distribute.bbclass</code> and + <code class="filename">src_distribute_local.bbclass</code>. + </p> +<p> + The results of these classes are <code class="filename">tmp/deploy/source/</code> + subdirs with sources sorted by + <code class="filename"><a class="link" href="ref-variables-glos.html#var-LICENSE" title="LICENSE">LICENSE</a></code> field. + If recipes list few licenses (or have entries like "Bitstream Vera"), + the source archive is placed in each license directory. + </p> +<p> + This class operates using three modes: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the + distribute directory.</p></li> +<li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the + distribute directory.</p></li> +<li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into + the distribute directory and then symlinks them back.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-alternatives.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-alternatives.html new file mode 100644 index 0000000000..cb6dfac6c4 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-alternatives.html @@ -0,0 +1,48 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.3. Alternatives - update-alternatives.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-autotools.html" title="7.2. Autotooled Packages - autotools.bbclass"> +<link rel="next" href="ref-classes-update-rc.d.html" title="7.4. Initscripts - update-rc.d.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.3. Alternatives - update-alternatives.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-update-alternatives"></a>7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code> +</h2></div></div></div> +<p> + Several programs can fulfill the same or similar function and be installed with the same name. + For example, the <code class="filename">ar</code> command is available from the + <code class="filename">busybox</code>, <code class="filename">binutils</code> and + <code class="filename">elfutils</code> packages. + The <code class="filename">update-alternatives.bbclass</code> class handles renaming the + binaries so that multiple packages can be installed without conflicts. + The <code class="filename">ar</code> command still works regardless of which packages are installed + or subsequently removed. + The class renames the conflicting binary in each package and symlinks the highest + priority binary during installation or removal of packages. + </p> +<p> + Four variables control this class: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> ‐ The name of the + binary that is replaced (<code class="filename">ar</code> in this example).</p></li> +<li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> ‐ The path to + the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li> +<li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> ‐ The path to the + real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li> +<li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> ‐ The priority of + the binary. + The version with the most features should have the highest priority.</p></li> +</ul></div> +<p> + </p> +<p> + Currently, the OpenEmbedded build system supports only one binary per package. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-rc.d.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-rc.d.html new file mode 100644 index 0000000000..7ab1688c3b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-rc.d.html @@ -0,0 +1,28 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.4. Initscripts - update-rc.d.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-update-alternatives.html" title="7.3. Alternatives - update-alternatives.bbclass"> +<link rel="next" href="ref-classes-binconfig.html" title="7.5. Binary config scripts - binconfig.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.4. Initscripts - update-rc.d.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-update-rc.d"></a>7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code> +</h2></div></div></div> +<p> + This class uses <code class="filename">update-rc.d</code> to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system takes care of details such as making sure the script is stopped before + a package is removed and started when the package is installed. + Three variables control this class: + <code class="filename"><a class="link" href="ref-variables-glos.html#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>, + <code class="filename"><a class="link" href="ref-variables-glos.html#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and + <code class="filename"><a class="link" href="ref-variables-glos.html#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>. + See the variable links for details. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-useradd.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-useradd.html new file mode 100644 index 0000000000..cc78211aab --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-useradd.html @@ -0,0 +1,28 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>7.19. Adding Users - useradd.bbclass</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-classes.html" title="Chapter 7. Classes"> +<link rel="prev" href="ref-classes-siteinfo.html" title="7.18. Autotools configuration data cache - siteinfo.bbclass"> +<link rel="next" href="ref-classes-externalsrc.html" title="7.20. Using External Source - externalsrc.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.19. Adding Users - useradd.bbclass"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-classes-useradd"></a>7.19. Adding Users - <code class="filename">useradd.bbclass</code> +</h2></div></div></div> +<p> + If you have packages that install files that are owned by custom users or groups, + you can use this class to specify those packages and associate the users and groups + with those packages. + The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code> + recipe in the <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> + provides a simple exmample that shows how to add three + users and groups to two packages. + See the <code class="filename">useradd-example.bb</code> for more information on how to + use this class. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes.html new file mode 100644 index 0000000000..35cc535e70 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes.html @@ -0,0 +1,61 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 7. Classes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="ref-bitbake-fetchers.html" title="6.7. Fetchers"> +<link rel="next" href="ref-classes-base.html" title="7.1. The base class - base.bbclass"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 7. Classes"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-classes"></a>Chapter 7. Classes</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="ref-classes-base.html">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-autotools.html">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-update-alternatives.html">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-update-rc.d.html">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-binconfig.html">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-debian.html">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-pkgconfig.html">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-src-distribute.html">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-perl.html">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-distutils.html">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-devshell.html">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-packagegroup.html">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-package.html">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-kernel.html">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-image.html">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-sanity.html">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-insane.html">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-siteinfo.html">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-useradd.html">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-externalsrc.html">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt> +<dt><span class="section"><a href="ref-classes-others.html">7.21. Other Classes</a></span></dt> +</dl> +</div> +<p> + Class files are used to abstract common functionality and share it amongst multiple + <code class="filename">.bb</code> files. + Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class + file. + Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed + in a <code class="filename">classes/</code> directory beneath the + <code class="filename">meta*/</code> directory found in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as + <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. + Class files are searched for in <a class="link" href="ref-variables-glos.html#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> + using the same method by which <code class="filename">.conf</code> files are searched. +</p> +<p> + In most cases inheriting the class is enough to enable its features, although + for some classes you might need to set variables or override some of the + default behaviour. +</p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-backfill.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-backfill.html new file mode 100644 index 0000000000..0ad90dfd70 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-backfill.html @@ -0,0 +1,88 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>9.4. Feature Backfilling</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features"> +<link rel="prev" href="ref-features-image.html" title="9.3. Images"> +<link rel="next" href="ref-variables-glos.html" title="Chapter 10. Variables Glossary"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.4. Feature Backfilling"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-features-backfill"></a>9.4. Feature Backfilling</h2></div></div></div> +<p> + Sometimes it is necessary in the OpenEmbedded build system to extend + <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a> + or <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a> + to control functionality that was previously enabled and not able + to be disabled. + For these cases, we need to add an + additional feature item to appear in one of these variables, + but we do not want to force developers who have existing values + of the variables in their configuration to add the new feature + in order to retain the same overall level of functionality. + Thus, the OpenEmbedded build system has a mechanism to + automatically "backfill" these added features into existing + distro or machine configurations. + You can see the list of features for which this is done by + finding the + <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL"><code class="filename">DISTRO_FEATURES_BACKFILL</code></a> + and <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL"><code class="filename">MACHINE_FEATURES_BACKFILL</code></a> + variables in the <code class="filename">meta/conf/bitbake.conf</code> file. + </p> +<p> + Because such features are backfilled by default into all + configurations as described in the previous paragraph, developers + who wish to disable the new features need to be able to selectively + prevent the backfilling from occurring. + They can do this by adding the undesired feature or features to the + <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED"><code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code></a> + or <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED"><code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code></a> + variables for distro features and machine features respectively. + </p> +<p> + Here are two examples to help illustrate feature backfilling: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>The "pulseaudio" distro feature option</em></span>: + Previously, PulseAudio support was enabled within the Qt and + GStreamer frameworks. + Because of this, the feature is backfilled and thus + enabled for all distros through the + <code class="filename">DISTRO_FEATURES_BACKFILL</code> + variable in the <code class="filename">meta/conf/bitbake.conf</code> file. + However, your distro needs to disable the feature. + You can disable the feature without affecting + other existing distro configurations that need PulseAudio support + by adding "pulseaudio" to + <code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code> + in your distro's <code class="filename">.conf</code> file. + Adding the feature to this variable when it also + exists in the <code class="filename">DISTRO_FEATURES_BACKFILL</code> + variable prevents the build system from adding the feature to + your configuration's <code class="filename">DISTRO_FEATURES</code>, effectively disabling + the feature for that particular distro.</p></li> +<li class="listitem"><p><span class="emphasis"><em>The "rtc" machine feature option</em></span>: + Previously, real time clock (RTC) support was enabled for all + target devices. + Because of this, the feature is backfilled and thus enabled + for all machines through the <code class="filename">MACHINE_FEATURES_BACKFILL</code> + variable in the <code class="filename">meta/conf/bitbake.conf</code> file. + However, your target device does not have this capability. + You can disable RTC support for your device without + affecting other machines that need RTC support + by adding the feature to your machine's + <code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code> + list in the machine's <code class="filename">.conf</code> file. + Adding the feature to this variable when it also + exists in the <code class="filename">MACHINE_FEATURES_BACKFILL</code> + variable prevents the build system from adding the feature to + your configuration's <code class="filename">MACHINE_FEATURES</code>, effectively + disabling RTC support for that particular machine.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-distro.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-distro.html new file mode 100644 index 0000000000..d261858123 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-distro.html @@ -0,0 +1,68 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>9.1. Distro</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features"> +<link rel="prev" href="ref-features.html" title="Chapter 9. Reference: Features"> +<link rel="next" href="ref-features-machine.html" title="9.2. Machine"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.1. Distro"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-features-distro"></a>9.1. Distro</h2></div></div></div> +<p> + The items below are features you can use with + <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within <code class="filename">do_configure</code> for a particular + recipe. + </p> +<p> + This list only represents features as shipped with the Yocto Project metadata: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility + kernel modules will be installed if available).</p></li> +<li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal + HDD/Microdrive for storing files (instead of Flash only devices) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be + loaded during boot). + </p></li> +<li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB + networking/serial/storage) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external + keyboard, mouse, storage, network etc) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on + device)</p></li> +<li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li> +<li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting + Samba/Microsoft Windows shares on device)</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-image.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-image.html new file mode 100644 index 0000000000..e705a2922f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-image.html @@ -0,0 +1,73 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>9.3. Images</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features"> +<link rel="prev" href="ref-features-machine.html" title="9.2. Machine"> +<link rel="next" href="ref-features-backfill.html" title="9.4. Feature Backfilling"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.3. Images"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-features-image"></a>9.3. Images</h2></div></div></div> +<p> + The contents of images generated by the OpenEmbedded build system can be controlled by the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> + and <code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> + variables that you typically configure in your image recipes. + Through these variables you can add several different + predefined packages such as development utilities or packages with debug + information needed to investigate application problems or profile applications. + </p> +<p> + Current list of + <code class="filename">IMAGE_FEATURES</code> contains the following: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>splash:</em></span> Enables showing a splash screen during boot. + By default, this screen is provided by <code class="filename">psplash</code>, which does + allow customization. + If you prefer to use an alternative splash screen package, you can do so by + setting the <code class="filename">SPLASH</code> variable + to a different package name (or names) within the image recipe or at the distro + configuration level.</p></li> +<li class="listitem"><p><span class="emphasis"><em>ssh-server-dropbear:</em></span> Installs the Dropbear minimal + SSH server. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>ssh-server-openssh:</em></span> Installs the OpenSSH SSH server, + which is more full-featured than Dropbear. + Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server + are present in <code class="filename">IMAGE_FEATURES</code>, then OpenSSH will take + precedence and Dropbear will not be installed.</p></li> +<li class="listitem"><p><span class="emphasis"><em>x11:</em></span> Installs the X server</p></li> +<li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> Installs the X server with a + minimal environment.</p></li> +<li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> Installs the OpenedHand Sato environment. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> Installs a full SDK that runs on the device. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Installs debugging tools such as + <code class="filename">strace</code> and <code class="filename">gdb</code>. + </p></li> +<li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Installs profiling tools such as + <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and + <code class="filename">LTTng</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Installs device testing tools (e.g. + touchscreen debugging).</p></li> +<li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> Installs an NFS server.</p></li> +<li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Installs development packages (headers and + extra library links) for all packages installed in a given image.</p></li> +<li class="listitem"><p><span class="emphasis"><em>staticdev-pkgs:</em></span> Installs static development + packages (i.e. static libraries containing <code class="filename">*.a</code> files) for all + packages installed in a given image.</p></li> +<li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Installs debug symbol packages for all packages + installed in a given image.</p></li> +<li class="listitem"><p><span class="emphasis"><em>doc-pkgs:</em></span> Installs documentation packages for all packages + installed in a given image.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-machine.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-machine.html new file mode 100644 index 0000000000..428aca3973 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-machine.html @@ -0,0 +1,63 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>9.2. Machine</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features"> +<link rel="prev" href="ref-features-distro.html" title="9.1. Distro"> +<link rel="next" href="ref-features-image.html" title="9.3. Images"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.2. Machine"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-features-machine"></a>9.2. Machine</h2></div></div></div> +<p> + The items below are features you can use with + <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within <code class="filename">do_configure</code> for a particular + recipe. + </p> +<p> + This feature list only represents features as shipped with the Yocto Project metadata: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers + </p></li> +<li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT + </p></li> +<li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive + </p></li> +<li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support + </p></li> +<li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard + </p></li> +<li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus + </p></li> +<li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets + </p></li> +<li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen + </p></li> +<li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232) + </p></li> +<li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen + </p></li> +<li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable + </p></li> +<li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable + </p></li> +<li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi + </p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features.html new file mode 100644 index 0000000000..c10c49cb19 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features.html @@ -0,0 +1,60 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 9. Reference: Features</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="ref-images.html" title="Chapter 8. Images"> +<link rel="next" href="ref-features-distro.html" title="9.1. Distro"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 9. Reference: Features"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-features"></a>Chapter 9. Reference: Features</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="ref-features-distro.html">9.1. Distro</a></span></dt> +<dt><span class="section"><a href="ref-features-machine.html">9.2. Machine</a></span></dt> +<dt><span class="section"><a href="ref-features-image.html">9.3. Images</a></span></dt> +<dt><span class="section"><a href="ref-features-backfill.html">9.4. Feature Backfilling</a></span></dt> +</dl> +</div> +<p> + Features provide a mechanism for working out which packages + should be included in the generated images. + Distributions can select which features they want to support through the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code> + variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file. + Machine features are set in the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code> + variable, which is set in the machine configuration file and + specifies the hardware features for a given machine. + </p> +<p> + These two variables combine to work out which kernel modules, + utilities, and other packages to include. + A given distribution can support a selected subset of features so some machine features might not + be included if the distribution itself does not support them. + </p> +<p> + One method you can use to determine which recipes are checking to see if a + particular feature is contained or not is to <code class="filename">grep</code> through + the metadata for the feature. + Here is an example that discovers the recipes whose build is potentially + changed based on a given feature: + </p> +<pre class="literallayout"> + $ cd $HOME/poky + $ git grep 'contains.*MACHINE_FEATURES.*<feature>' + </pre> +<p> + </p> +<p> + This chapter provides a reference of shipped machine and distro features + you can include as part of the image, a reference on image types you can + build, and a reference on feature backfilling. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-images.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-images.html new file mode 100644 index 0000000000..81ed4ba8f2 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-images.html @@ -0,0 +1,137 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 8. Images</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="ref-classes-others.html" title="7.21. Other Classes"> +<link rel="next" href="ref-features.html" title="Chapter 9. Reference: Features"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 8. Images"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-images"></a>Chapter 8. Images</h2></div></div></div> +<p> + The OpenEmbedded build process supports several types of images to satisfy different needs. + When you issue the <code class="filename">bitbake</code> command you provide a “top-level” recipe + that essentially begins the build for the type of image you want. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + Building an image without GNU General Public License Version 3 (GPLv3) components + is only supported for minimal and base images. + Furthermore, if you are going to build an image using non-GPLv3 components, + you must make the following changes in the <code class="filename">local.conf</code> file + before using the BitBake command to build the minimal or base image: + <pre class="literallayout"> + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPLv3" + </pre> +</div> +<p> + From within the <code class="filename">poky</code> Git repository, use the following command to list + the supported images: + </p> +<pre class="literallayout"> + $ ls meta*/recipes*/images/*.bb + </pre> +<p> + These recipes reside in the <code class="filename">meta/recipes-core/images</code>, + <code class="filename">meta/recipes-extended/images</code>, + <code class="filename">meta/recipes-graphics/images</code>, and + <code class="filename">meta/recipes-sato/images</code> directories + within the <a class="link" href="../dev-manual/source-directory.html" target="_self">source directory</a>. + Although the recipe names are somewhat explanatory, here is a list that describes them: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span> + A console-only image that fully supports the target device hardware.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span> + A small image just capable of allowing a device to boot.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span> + A <code class="filename">core-image-minimal</code> image suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span> + A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based + Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel, + which allows the system to find the first “init” program more efficiently. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span> + A <code class="filename">core-image-minimal</code> image that has support + for the Minimal MTD Utilities, which let the user interact with the + MTD subsystem in the kernel to perform operations on flash devices. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-x11</code>:</em></span> + A very basic X11 image with a terminal. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span> + A console-only image with more full-featured Linux system + functionality installed.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span> + An image that conforms to the Linux Standard Base (LSB) specification.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span> + A <code class="filename">core-image-lsb</code> image that is suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span> + A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain + but also includes development headers and libraries to form a complete standalone SDK. + This image is suitable for development using the target.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span> + An image with support for the Open GL-based toolkit Clutter, which enables development of + rich and animated graphical user interfaces.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span> + An image with Sato support, a mobile environment and visual style that works well + with mobile devices. + The image supports X11 with a Sato theme and applications such as + a terminal, editor, file manager, media player, and so forth.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span> + A <code class="filename">core-image-sato</code> image suitable for development + using the host. + The image includes libraries needed to build applications on the device itself, + testing and profiling tools, and debug symbols. + This image was formerly <code class="filename">core-image-sdk</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span> + A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain. + The image also includes development headers and libraries to form a complete standalone SDK + and is suitable for development using the target.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span> + A <code class="filename">core-image-minimal</code> image plus a real-time test suite and + tools appropriate for real-time use.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span> + A <code class="filename">core-image-rt</code> image that includes everything in + <code class="filename">meta-toolchain</code>. + The image also includes development headers and libraries to form a complete + stand-alone SDK and is suitable for development using the target.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span> + An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code> + instead of X11. + In order to build, this image requires specific distro configuration that enables + <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span> + An image you can boot and run using either the + <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_self">VMware Player</a> + or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_self">VMware Workstation</a>. + For more information on this image, see the + <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_self">Build Appliance</a> page on + the Yocto Project website.</p></li> +</ul></div> +<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Tip</h3> + From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and + <code class="filename">-directdisk</code> images have been replaced by a "live" + option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an + image file that can be + copied directly to a CD or USB device and run as is. + To build a live image, simply add + "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code> + file or wherever appropriate and then build the desired image as normal. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-structure.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-structure.html new file mode 100644 index 0000000000..afc8334ebd --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-structure.html @@ -0,0 +1,98 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 5. Source Directory Structure</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="migration-1.3-removed-recipes.html" title="4.1.2.6. Removed Recipes"> +<link rel="next" href="structure-core.html" title="5.1. Top level core components"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 5. Source Directory Structure"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-structure"></a>Chapter 5. Source Directory Structure</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="structure-core.html">5.1. Top level core components</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-core-bitbake.html">5.1.1. <code class="filename">bitbake/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-build.html">5.1.2. <code class="filename">build/</code></a></span></dt> +<dt><span class="section"><a href="handbook.html">5.1.3. <code class="filename">documentation</code></a></span></dt> +<dt><span class="section"><a href="structure-core-meta.html">5.1.4. <code class="filename">meta/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-meta-yocto.html">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-meta-yocto-bsp.html">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-hob.html">5.1.7. <code class="filename">meta-hob/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-skeleton.html">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-scripts.html">5.1.9. <code class="filename">scripts/</code></a></span></dt> +<dt><span class="section"><a href="structure-core-script.html">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt> +<dt><span class="section"><a href="structure-basic-top-level.html">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="structure-build.html">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-build-pseudodone.html">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt> +<dt><span class="section"><a href="structure-build-conf-local.conf.html">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt> +<dt><span class="section"><a href="structure-build-conf-bblayers.conf.html">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt> +<dt><span class="section"><a href="structure-build-conf-sanity_info.html">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt> +<dt><span class="section"><a href="structure-build-downloads.html">5.2.5. <code class="filename">build/downloads/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-sstate-cache.html">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp.html">5.2.7. <code class="filename">build/tmp/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-buildstats.html">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-cache.html">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy.html">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-deb.html">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-rpm.html">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-licenses.html">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-images.html">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-deploy-ipk.html">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-sysroots.html">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-stamps.html">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-log.html">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-pkgdata.html">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt> +<dt><span class="section"><a href="structure-build-tmp-work.html">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt> +</dl></dd> +<dt><span class="section"><a href="structure-meta.html">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt> +<dd><dl> +<dt><span class="section"><a href="structure-meta-classes.html">5.3.1. <code class="filename">meta/classes/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-conf.html">5.3.2. <code class="filename">meta/conf/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-conf-machine.html">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-conf-distro.html">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-bsp.html">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-connectivity.html">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-core.html">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-devtools.html">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-extended.html">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-gnome.html">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-graphics.html">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-kernel.html">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-multimedia.html">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-qt.html">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-rt.html">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-sato.html">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-support.html">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-site.html">5.3.18. <code class="filename">meta/site/</code></a></span></dt> +<dt><span class="section"><a href="structure-meta-recipes-txt.html">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt> +</dl></dd> +</dl> +</div> +<p> + The <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> consists of several components. + Understanding them and knowing where they are located is key to using the Yocto Project well. + This chapter describes the Source Directory and gives information about the various + files and directories. +</p> +<p> + For information on how to establish a local Source Directory on your development system, see the + "<a class="link" href="../dev-manual/getting-setup.html" target="_self">Getting Set Up</a>" + section in the Yocto Project Development Manual. +</p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + 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. +</div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-variables-glos.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-variables-glos.html new file mode 100644 index 0000000000..bb6374fab7 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-variables-glos.html @@ -0,0 +1,2800 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 10. Variables Glossary</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="ref-features-backfill.html" title="9.4. Feature Backfilling"> +<link rel="next" href="ref-varlocality.html" title="Chapter 11. Variable Context"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 10. Variables Glossary"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-variables-glos"></a>Chapter 10. Variables Glossary</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl><dt><span class="glossary"><a href="ref-variables-glos.html#ref-variables-glossary">Glossary</a></span></dt></dl> +</div> +<p> + This chapter lists common variables used in the OpenEmbedded build system and gives an overview + of their function and contents. +</p> +<div class="glossary" title="Glossary"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-variables-glossary"></a>Glossary</h2></div></div></div> +<p> + <a class="link" href="ref-variables-glos.html#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a> + <a class="link" href="ref-variables-glos.html#var-B" title="B">B</a> + <a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">C</a> + <a class="link" href="ref-variables-glos.html#var-D" title="D">D</a> + <a class="link" href="ref-variables-glos.html#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a> + <a class="link" href="ref-variables-glos.html#var-FILES" title="FILES">F</a> + + <a class="link" href="ref-variables-glos.html#var-HOMEPAGE" title="HOMEPAGE">H</a> + <a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a> + + <a class="link" href="ref-variables-glos.html#var-KBRANCH" title="KBRANCH">K</a> + <a class="link" href="ref-variables-glos.html#var-LAYERDIR" title="LAYERDIR">L</a> + <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">M</a> + + <a class="link" href="ref-variables-glos.html#var-OE_TERMINAL" title="OE_TERMINAL">O</a> + <a class="link" href="ref-variables-glos.html#var-P" title="P">P</a> + + <a class="link" href="ref-variables-glos.html#var-RCONFLICTS" title="RCONFLICTS">R</a> + <a class="link" href="ref-variables-glos.html#var-S" title="S">S</a> + <a class="link" href="ref-variables-glos.html#var-T" title="T">T</a> + + + <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">W</a> + + + + </p> +<div class="glossdiv" title="A"> +<h3 class="title">A</h3> +<dl> +<dt> +<a name="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt> +<dd> +<p> + Specifies if an output package should still be produced if it is empty. + By default, BitBake does not produce empty packages. + This default behavior can cause issues when there is an + <a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or + some other runtime hard-requirement on the existence of the package. + </p> +<p> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + </p> +<pre class="literallayout"> + ALLOW_EMPTY_${PN} = "1" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-AUTHOR"></a>AUTHOR</dt> +<dd><p>The email address used to contact the original author or authors in + order to send patches, forward bugs, etc.</p></dd> +<dt> +<a name="var-AUTOREV"></a>AUTOREV</dt> +<dd> +<p>When <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV">SRCREV</a></code> + is set to the value of this variable, it specifies that the latest + source revision in the repository should be used. Here is an example: + </p> +<pre class="literallayout"> + SRCREV = "${AUTOREV}" + </pre> +<p> + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="B"> +<h3 class="title">B</h3> +<dl> +<dt> +<a name="var-B"></a>B</dt> +<dd> +<p> + The <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + The OpenEmbedded build system places generated objects into the Build Directory + during a recipe's build process. + By default, this directory is the same as the <a class="link" href="ref-variables-glos.html#var-S" title="S"><code class="filename">S</code></a> + directory: + </p> +<pre class="literallayout"> + B = ${WORKDIR}/${BPN}-{PV}/ + </pre> +<p> + You can separate the (<code class="filename">S</code>) directory and the directory pointed to + by the <code class="filename">B</code> variable. + Most autotools-based recipes support separating these directories. + The build system defaults to using separate directories for <code class="filename">gcc</code> + and some kernel recipes. + </p> +</dd> +<dt> +<a name="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt> +<dd><p> + A list of packages not to install despite being recommended by a recipe. + Support for this variable exists only when using the + <code class="filename">ipk</code> packaging backend. + </p></dd> +<dt> +<a name="var-BB_DISKMON_DIRS"></a>BB_DISKMON_DIRS</dt> +<dd> +<p> + Monitors disk space and available inodes during the build + and allows you to control the build based on these + parameters. + </p> +<p> + Disk space monitoring is disabled by default. + To enable monitoring, add the <code class="filename">BB_DISKMON_DIRS</code> + variable to your <code class="filename">conf/local.conf</code> file found in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + Use the following form: + </p> +<pre class="literallayout"> + BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" + + where: + + <action> is: + ABORT: Immediately abort the build when + a threshold is broken. + STOPTASKS: Stop the build after the currently + executing tasks have finished when + a threshold is broken. + WARN: Issue a warning but continue the + build when a threshold is broken. + Subsequent warnings are issued as + defined by the + <a class="link" href="ref-variables-glos.html#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL">BB_DISKMON_WARNINTERVAL</a> variable, + which must be defined in the + conf/local.conf file. + + <dir> is: + Any directory you choose. You can specify one or + more directories to monitor by separating the + groupings with a space. If two directories are + on the same device, only the first directory + is monitored. + + <threshold> is: + Either the minimum available disk space, + the minimum number of free inodes, or + both. You must specify at least one. To + omit one or the other, simply omit the value. + Specify the threshold using G, M, K for Gbytes, + Mbytes, and Kbytes, respectively. If you do + not specify G, M, or K, Kbytes is assumed by + default. Do not use GB, MB, or KB. + </pre> +<p> + </p> +<p> + Here are some examples: + </p> +<pre class="literallayout"> + BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" + BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + </pre> +<p> + The first example works only if you also provide + the <a class="link" href="ref-variables-glos.html#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL"><code class="filename">BB_DISKMON_WARNINTERVAL</code></a> variable + in the <code class="filename">conf/local.conf</code>. + This example causes the build system to immediately + abort when either the disk space in <code class="filename">${TMPDIR}</code> drops + below 1 Gbyte or the available free inodes drops below + 100 Kbytes. + Because two directories are provided with the variable, the + build system also issue a + warning when the disk space in the + <code class="filename">${SSTATE_DIR}</code> directory drops + below 1 Gbyte or the number of free inodes drops + below 100 Kbytes. + Subsequent warnings are issued during intervals as + defined by the <code class="filename">BB_DISKMON_WARNINTERVAL</code> + variable. + </p> +<p> + The second example stops the build after all currently + executing tasks complete when the minimum disk space + in the <code class="filename">${TMPDIR}</code> directory drops + below 1 Gbyte. + No disk monitoring occurs for the free inodes in this case. + </p> +<p> + The final example immediately aborts the build when the + number of free inodes in the <code class="filename">${TMPDIR}</code> directory + drops below 100 Kbytes. + No disk space monitoring for the directory itself occurs + in this case. + </p> +</dd> +<dt> +<a name="var-BB_DISKMON_WARNINTERVAL"></a>BB_DISKMON_WARNINTERVAL</dt> +<dd> +<p> + Defines the disk space and free inode warning intervals. + To set these intervals, define the variable in your + <code class="filename">conf/local.conf</code> file in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + </p> +<p> + If you are going to use the + <code class="filename">BB_DISKMON_WARNINTERVAL</code> variable, you must + also use the + <a class="link" href="ref-variables-glos.html#var-BB_DISKMON_DIRS" title="BB_DISKMON_DIRS"><code class="filename">BB_DISKMON_DIRS</code></a> variable + and define its action as "WARN". + During the build, subsequent warnings are issued each time + disk space or number of free inodes further reduces by + the respective interval. + </p> +<p> + If you do not provide a <code class="filename">BB_DISKMON_WARNINTERVAL</code> + variable and you do use <code class="filename">BB_DISKMON_DIRS</code> with + the "WARN" action, the disk monitoring interval defaults to + the following: + </p> +<pre class="literallayout"> + BB_DISKMON_WARNINTERVAL = "50M,5K" + </pre> +<p> + </p> +<p> + When specifying the variable in your configuration file, + use the following form: + </p> +<pre class="literallayout"> + BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" + + where: + + <disk_space_interval> is: + An interval of memory expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + <disk_inode_interval> is: + An interval of free inodes expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + </pre> +<p> + </p> +<p> + Here is an example: + </p> +<pre class="literallayout"> + BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_WARNINTERVAL = "50M,5K" + </pre> +<p> + These variables cause the OpenEmbedded build system to + issue subsequent warnings each time the available + disk space further reduces by 50 Mbytes or the number + of free inodes further reduces by 5 Kbytes in the + <code class="filename">${SSTATE_DIR}</code> directory. + Subsequent warnings based on the interval occur each time + a respective interval is reached beyond the intial warning + (i.e. 1 Gbytes and 100 Kbytes). + </p> +</dd> +<dt> +<a name="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt> +<dd> +<p> + Allows you to extend a recipe so that it builds variants of the software. + Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>, + which is a copy of quilt built to run on the build system; + "crosses" such as <code class="filename">gcc-cross</code>, + which is a compiler built to run on the build machine but produces binaries + that run on the target <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>; + "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>; + and "mulitlibs" in the form "<code class="filename">multilib:<multilib_name></code>". + </p> +<p> + To build a different variant of the recipe with a minimal amount of code, it usually + is as simple as adding the following to your recipe: + </p> +<pre class="literallayout"> + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:<multilib_name>" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-BBMASK"></a>BBMASK</dt> +<dd> +<p>Prevents BitBake from processing recipes and recipe append files. + You can use the <code class="filename">BBMASK</code> variable to "hide" + these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files. + BitBake ignores any recipe or recipe append files that match the expression. + It is as if BitBake does not see them at all. + Consequently, matching files are not parsed or otherwise used by + BitBake.</p> +<p>The value you provide is passed to python's regular expression compiler. + For complete syntax information, see python's documentation at + <a class="ulink" href="http://docs.python.org/release/2.3/lib/re-syntax.html" target="_self">http://docs.python.org/release/2.3/lib/re-syntax.html</a>. + The expression is compared against the full paths to the files. + For example, the following uses a complete regular expression to tell + BitBake to ignore all recipe and recipe append files in the + <code class="filename">.*/meta-ti/recipes-misc/</code> directory: + </p> +<pre class="literallayout"> + BBMASK = ".*/meta-ti/recipes-misc/" + </pre> +<p>Use the <code class="filename">BBMASK</code> variable from within the + <code class="filename">conf/local.conf</code> file found + in the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.</p> +</dd> +<dt> +<a name="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt> +<dd><p>The maximum number of tasks BitBake should run in parallel at any one time. + If your host development system supports multiple cores a good rule of thumb + is to set this variable to twice the number of cores.</p></dd> +<dt> +<a name="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt> +<dd><p>Lists the names of configured layers. + These names are used to find the other <code class="filename">BBFILE_*</code> + variables. + Typically, each layer will append its name to this variable in its + <code class="filename">conf/layer.conf</code> file. + </p></dd> +<dt> +<a name="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt> +<dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer. + This variable is used in the <code class="filename">conf/layer.conf</code> file and must + be suffixed with the name of the specific layer (e.g. + <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd> +<dt> +<a name="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt> +<dd> +<p>Assigns the priority for recipe files in each layer.</p> +<p>This variable is useful in situations where the same recipe appears in + more than one layer. + Setting this variable allows you to prioritize a + layer against other layers that contain the same recipe - effectively + letting you control the precedence for the multiple layers. + The precedence established through this variable stands regardless of a + recipe's version (<code class="filename">PV</code> variable). + For example, a layer that has a recipe with a higher <code class="filename">PV</code> value but for + which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a + lower precedence.</p> +<p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher + precedence. + For example, the value 6 has a higher precedence than the value 5. + If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer + dependencies (see the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for + more information. + The default priority, if unspecified + for a layer with no dependencies, is the lowest defined priority + 1 + (or 1 if no priorities are defined).</p> +<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Tip</h3> + You can use the command <code class="filename">bitbake-layers show_layers</code> to list + all configured layers along with their priorities. + </div> +</dd> +<dt> +<a name="var-BBFILES"></a>BBFILES</dt> +<dd><p>List of recipe files used by BitBake to build software</p></dd> +<dt> +<a name="var-BBPATH"></a>BBPATH</dt> +<dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files. + This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd> +<dt> +<a name="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt> +<dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd> +<dt> +<a name="var-BBLAYERS"></a>BBLAYERS</dt> +<dd> +<p>Lists the layers to enable during the build. + This variable is defined in the <code class="filename">bblayers.conf</code> configuration + file in the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + Here is an example: + </p> +<pre class="literallayout"> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + </pre> +<p> + This example enables four layers, one of which is a custom, user-defined layer + named <code class="filename">meta-mykernel</code>. + </p> +</dd> +<dt> +<a name="var-BP"></a>BP</dt> +<dd> +<p>The base recipe name and version but without any special + recipe name suffix (i.e. <code class="filename">-native</code>, <code class="filename">lib64-</code>, + and so forth). + <code class="filename">BP</code> is comprised of the following: + </p> +<pre class="literallayout"> + ${BPN}-${PV} + </pre> +</dd> +<dt> +<a name="var-BPN"></a>BPN</dt> +<dd><p>The bare name of the recipe. + This variable is a version of the <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> variable + but removes common suffixes such as "-native" and "-cross" as well + as removes common prefixes such as multilib's "lib64-" and "lib32-". + The exact list of suffixes removed is specified by the + <a class="link" href="ref-variables-glos.html#var-SPECIAL_PKGSUFFIX" title="SPECIAL_PKGSUFFIX"><code class="filename">SPECIAL_PKGSUFFIX</code></a> variable. + The exact list of prefixes removed is specified by the + <a class="link" href="ref-variables-glos.html#var-MLPREFIX" title="MLPREFIX"><code class="filename">MLPREFIX</code></a> variable. + Prefixes are removed for multilib and nativesdk cases.</p></dd> +</dl> +</div> +<div class="glossdiv" title="C"> +<h3 class="title">C</h3> +<dl> +<dt> +<a name="var-CFLAGS"></a>CFLAGS</dt> +<dd><p> + Flags passed to C compiler for the target system. + This variable evaluates to the same as + <code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>. + </p></dd> +<dt> +<a name="var-COMBINED_FEATURES"></a>COMBINED_FEATURES</dt> +<dd><p>A set of features common between + <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a> + and <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>. + See the glossary descriptions for these variables for more information.</p></dd> +<dt> +<a name="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt> +<dd><p>A regular expression which evaluates to match the machines the recipe + works with. + It stops recipes being run on machines for which they are not compatible. + This is particularly useful with kernels. + It also helps to increase parsing speed as further parsing of the recipe is skipped + if it is found the current machine is not compatible.</p></dd> +<dt> +<a name="var-CONFFILES"></a>CONFFILES</dt> +<dd> +<p> + Identifies editable or configurable files that are part of a package. + If the Package Management System (PMS) is being used to update + packages on the target system, it is possible that + configuration files you have changed after the original installation + and that you now want to remain unchanged are overwritten. + In other words, editable files might exist in the package that you do not + want reset as part of the package update process. + You can use the <code class="filename">CONFFILES</code> variable to list the files in the + package that you wish to prevent the PMS from overwriting during this update process. + </p> +<p> + To use the <code class="filename">CONFFILES</code> variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files. + Here is an example: + </p> +<pre class="literallayout"> + CONFFILES_${PN} += "${sysconfdir}/file1 \ + ${sysconfdir}/file2 ${sysconfdir}/file3" + </pre> +<p> + </p> +<p> + A relationship exists between the <code class="filename">CONFFILES</code> and + <code class="filename"><a class="link" href="ref-variables-glos.html#var-FILES" title="FILES">FILES</a></code> variables. + The files listed within <code class="filename">CONFFILES</code> must be a subset of + the files listed within <code class="filename">FILES</code>. + Because the configuration files you provide with <code class="filename">CONFFILES</code> + are simply being identified so that the PMS will not overwrite them, + it makes sense that + the files must already be included as part of the package through the + <code class="filename">FILES</code> variable. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + When specifying paths as part of the <code class="filename">CONFFILES</code> variable, + it is good practice to use appropriate path variables. + For example, <code class="filename">${sysconfdir}</code> rather than + <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather + than <code class="filename">/usr/bin</code>. + You can find a list of these variables at the top of the + <code class="filename">/meta/conf/bitbake.conf</code> file in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </div> +</dd> +<dt> +<a name="var-CONFIG_SITE"></a>CONFIG_SITE</dt> +<dd><p> + A list of files that contains <code class="filename">autoconf</code> test results relevant + to the current build. + This variable is used by the Autotools utilities when running + <code class="filename">configure</code>. + </p></dd> +<dt> +<a name="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt> +<dd> +<p> + Specifies the list of packages to be added to the image. + This variable should only be set in the <code class="filename">local.conf</code> + configuration file found in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + </p> +<p> + This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported. + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="D"> +<h3 class="title">D</h3> +<dl> +<dt> +<a name="var-D"></a>D</dt> +<dd><p>The destination directory.</p></dd> +<dt> +<a name="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt> +<dd><p> + Specifies to build packages with debugging information. + This influences the value of the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code> + variable. + </p></dd> +<dt> +<a name="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt> +<dd><p> + The options to pass in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> + and <code class="filename"><a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling + a system for debugging. + This variable defaults to "-O -fno-omit-frame-pointer -g". + </p></dd> +<dt> +<a name="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt> +<dd><p>Specifies the priority of recipes.</p></dd> +<dt> +<a name="var-DEPENDS"></a>DEPENDS</dt> +<dd><p> + Lists a recipe's build-time dependencies + (i.e. other recipe files). + The system ensures that all the dependencies listed + have been built and have their contents in the appropriate + sysroots before the recipe's configure task is executed. + </p></dd> +<dt> +<a name="var-DESCRIPTION"></a>DESCRIPTION</dt> +<dd><p>The package description used by package managers. + If not set, <code class="filename">DESCRIPTION</code> takes + the value of the + <a class="link" href="ref-variables-glos.html#var-SUMMARY" title="SUMMARY"><code class="filename">SUMMARY</code></a> + variable. + </p></dd> +<dt> +<a name="var-DESTDIR"></a>DESTDIR</dt> +<dd><p>the destination directory.</p></dd> +<dt> +<a name="var-DISTRO"></a>DISTRO</dt> +<dd> +<p> + The short name of the distribution. + This variable corresponds to a file with the + extension <code class="filename">.conf</code> + located in a <code class="filename">conf/distro</code> directory + within the metadata that contains the distribution configuration. + The + value must not contain spaces, and is typically all lower-case. + </p> +<p> + If the variable is blank, a set of default configuration + will be used, which is specified + within <code class="filename">meta/conf/distro/defaultsetup.conf</code>. + </p> +</dd> +<dt> +<a name="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt> +<dd><p> + Specifies a list of distro-specific packages to add to all images. + This variable takes affect through + <code class="filename">packagegroup-base</code> so the + variable only really applies to the more full-featured + images that include <code class="filename">packagegroup-base</code>. + You can use this variable to keep distro policy out of + generic images. + As with all other distro variables, you set this variable + in the distro <code class="filename">.conf</code> file. + </p></dd> +<dt> +<a name="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt> +<dd><p> + Specifies a list of distro-specific packages to add to all images + if the packages exist. + The packages might not exist or be empty (e.g. kernel modules). + The list of packages are automatically installed but can be + removed by the user. + </p></dd> +<dt> +<a name="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt> +<dd><p>The features enabled for the distribution. + For a list of features supported by the Yocto Project as shipped, + see the "<a class="link" href="ref-features-distro.html" title="9.1. Distro">Distro</a>" + section. + </p></dd> +<dt> +<a name="var-DISTRO_FEATURES_BACKFILL"></a>DISTRO_FEATURES_BACKFILL</dt> +<dd> +<p>Features to be added to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code> + if not also present in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED">DISTRO_FEATURES_BACKFILL_CONSIDERED</a></code>. + </p> +<p> + This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file. + 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 <a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature backfilling</a> section for + more information. + </p> +</dd> +<dt> +<a name="var-DISTRO_FEATURES_BACKFILL_CONSIDERED"></a>DISTRO_FEATURES_BACKFILL_CONSIDERED</dt> +<dd><p>Features from + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL">DISTRO_FEATURES_BACKFILL</a></code> + that should not backfilled (i.e. added to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>) + during the build. + See the "<a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature Backfilling</a>" section for + more information. + </p></dd> +<dt> +<a name="var-DISTRO_NAME"></a>DISTRO_NAME</dt> +<dd><p>The long name of the distribution.</p></dd> +<dt> +<a name="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt> +<dd> +<p>Alias names used for the recipe in various Linux distributions.</p> +<p>See the + "<a class="link" href="../dev-manual/usingpoky-configuring-DISTRO_PN_ALIAS.html" target="_self">Handling + a Package Name Alias</a>" section in the Yocto Project Development + Manual for more information.</p> +</dd> +<dt> +<a name="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt> +<dd><p>the version of the distribution.</p></dd> +<dt> +<a name="var-DL_DIR"></a>DL_DIR</dt> +<dd> +<p> + The central download directory used by the build process to store downloads. + You can set this directory by defining the <code class="filename">DL_DIR</code> + variable in the <code class="filename">/conf/local.conf</code> file. + This directory is self-maintaining and you should not have + to touch it. + By default, the directory is <code class="filename">downloads</code> in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + </p> +<pre class="literallayout"> + #DL_DIR ?= "${TOPDIR}/downloads" + </pre> +<p> + To specify a different download directory, simply uncomment the line + and provide your directory. + </p> +<p> + During a first build, the system downloads many different source code + tarballs from various upstream projects. + Downloading can take a while, particularly if your network + connection is slow. + Tarballs are all stored in the directory defined by + <code class="filename">DL_DIR</code> and the build system looks there first + to find source tarballs. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + When wiping and rebuilding, you can preserve this directory to speed + up this part of subsequent builds. + </div> +<p> + </p> +<p> + You can safely share this directory between multiple builds on the + same development machine. + For additional information on how the build process gets source files + when working behind a firewall or proxy server, see the + "<a class="link" href="faq.html#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server">FAQ</a>" + chapter. + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="E"> +<h3 class="title">E</h3> +<dl> +<dt> +<a name="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt> +<dd> +<p></p> +<p>Variable that controls which locales for <code class="filename">eglibc</code> are + to be generated during the build (useful if the target device has 64Mbytes + of RAM or less).</p> +</dd> +<dt> +<a name="var-EXTENDPE"></a>EXTENDPE</dt> +<dd> +<p> + Used with file and pathnames to create a prefix for a recipe's + version based on the recipe's + <a class="link" href="ref-variables-glos.html#var-PE" title="PE"><code class="filename">PE</code></a> value. + If <code class="filename">PE</code> is set and greater than zero for a recipe, + <code class="filename">EXTENDPE</code> becomes that value (e.g if + <code class="filename">PE</code> is equal to "1" then <code class="filename">EXTENDPE</code> + becomes "1_"). + If a recipe's <code class="filename">PE</code> is not set (the default) or is equal to + zero, <code class="filename">EXTENDPE</code> becomes "".</p> +<p>See the <a class="link" href="ref-variables-glos.html#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> + variable for an example. + </p> +</dd> +<dt> +<a name="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt> +<dd> +<p>Allows extra packages to be added to the generated images. + You set this variable in the <code class="filename">local.conf</code> + configuration file. + Note that some image features are also added using the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> + variable generally configured in image recipes. + You can use this variable to add more features in addition to those. + Here are some examples of features you can add:</p> +<pre class="literallayout"> +"dbg-pkgs" - Adds -dbg packages for all installed packages + including symbol information for debugging and + profiling. + +"dev-pkgs" - Adds -dev packages for all installed packages. + This is useful if you want to develop against + the libraries in the image. + +"tools-sdk" - Adds development tools such as gcc, make, + pkgconfig and so forth. + +"tools-debug" - Adds debugging tools such as gdb and + strace. + +"tools-profile" - Adds profiling tools such as oprofile, + exmap, lttng and valgrind (x86 only). + +"tools-testapps" - Adds useful testing tools such as + ts_print, aplay, arecord and so + forth. + +"debug-tweaks" - Makes an image suitable for development. + For example, ssh root access has a blank + password. You should remove this feature + before you produce a production image. + </pre> +<p>There are other valid features too, see the + <a class="link" href="ref-features-image.html" title="9.3. Images">Images</a> + section for more details.</p> +</dd> +<dt> +<a name="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt> +<dd> +<p>A list of recipes to be built that do not provide packages to be installed in + the root filesystem. + </p> +<p>Sometimes a recipe is required to build the final image but is not + needed in the root filesystem. + You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to + list these recipes and thus, specify the dependencies. + A typical example is a required bootloader in a machine configuration. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + To add packages to the root filesystem, see the various + <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code> + variables. + </div> +</dd> +<dt> +<a name="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt> +<dd><p>Additional <code class="filename">cmake</code> options.</p></dd> +<dt> +<a name="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt> +<dd><p>Additional <code class="filename">configure</code> script options.</p></dd> +<dt> +<a name="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt> +<dd><p>Additional GNU <code class="filename">make</code> options.</p></dd> +</dl> +</div> +<div class="glossdiv" title="F"> +<h3 class="title">F</h3> +<dl> +<dt> +<a name="var-FILES"></a>FILES</dt> +<dd> +<p> + The list of directories or files that are placed in packages. + </p> +<p> + To use the <code class="filename">FILES</code> variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files or paths that identifies the + files you want included as part of the resulting package. + Here is an example: + </p> +<pre class="literallayout"> + FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + </pre> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + When specifying paths as part of the <code class="filename">FILES</code> variable, + it is good practice to use appropriate path variables. + For example, <code class="filename">${sysconfdir}</code> rather than + <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather + than <code class="filename">/usr/bin</code>. + You can find a list of these variables at the top of the + <code class="filename">/meta/conf/bitbake.conf</code> file in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </div> +<p> + If some of the files you provide with the <code class="filename">FILES</code> variable + are editable and you know they should not be + overwritten during the package update process by the Package Management + System (PMS), you can identify these files so that the PMS will not + overwrite them. + See the <code class="filename"><a class="link" href="ref-variables-glos.html#var-CONFFILES" title="CONFFILES">CONFFILES</a></code> + variable for information on how to identify these files to the PMS. + </p> +</dd> +<dt> +<a name="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt> +<dd> +<p> + Extends the search path the OpenEmbedded build system uses when + looking for files and patches as it processes recipes. + The directories BitBake uses when it processes recipes is defined by the + <a class="link" href="ref-variables-glos.html#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable. + You can add directories to the search path by defining the + <code class="filename">FILESEXTRAPATHS</code> variable. + </p> +<p> + To add paths to the search order, provide a list of directories and separate + each path using a colon character as follows: + </p> +<pre class="literallayout"> + FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" + </pre> +<p> + Typically, you want your directories search first. + To make sure that happens, use <code class="filename">_prepend</code> and + the immediate expansion (<code class="filename">:=</code>) operator as shown in the + previous example. + Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable, + you must include the appropriate beginning or ending (as needed) colon character. + </p> +<p> + The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in + <code class="filename">.bbappend</code> files to include any additional files provided in that layer. + You typically accomplish this with the following: + </p> +<pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-FILESPATH"></a>FILESPATH</dt> +<dd> +<p> + The default set of directories the OpenEmbedded build system uses + when searching for patches and files. + During the build process, BitBake searches each directory in + <code class="filename">FILESPATH</code> in the specified order when looking for + files and patches specified by each <code class="filename">file://</code> URI in a recipe. + </p> +<p> + The default value for the <code class="filename">FILESPATH</code> variable is defined + in the <code class="filename">base.bbclass</code> class found in + <code class="filename">meta/classes</code> in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>: + </p> +<pre class="literallayout"> +FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ + "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \ + "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ + "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" + </pre> +<p> + Do not hand-edit the <code class="filename">FILESPATH</code> variable. + If you want to extend the set of pathnames that BitBake uses when searching for + files and patches, use the + <a class="link" href="ref-variables-glos.html#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable. + </p> +</dd> +<dt> +<a name="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt> +<dd> +<p>Allows you to define your own file permissions settings table as part of + your configuration for the packaging process. + For example, suppose you need a consistent set of custom permissions for + a set of groups and users across an entire work project. + It is best to do this in the packages themselves but this is not always + possible. + </p> +<p> + By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which + is located in the <code class="filename">meta/files</code> folder in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + If you create your own file permissions setting table, you should place it in your + layer or the distros layer. + </p> +<p> + You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the + <code class="filename">conf/local.conf</code> file, which is found in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>, to + point to your custom <code class="filename">fs-perms.txt</code>. + You can specify more than a single file permissions setting table. + The paths you specify to these files must be defined within the + <code class="filename">BBPATH</code> variable. + </p> +<p> + For guidance on how to create your own file permissions settings table file, + examine the existing <code class="filename">fs-perms.txt</code>. + </p> +</dd> +<dt> +<a name="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt> +<dd><p> + The options to pass in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> + and <code class="filename"><a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> + when compiling an optimized system. + This variable defaults to + "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". + </p></dd> +</dl> +</div> +<div class="glossdiv" title="H"> +<h3 class="title">H</h3> +<dl> +<dt> +<a name="var-HOMEPAGE"></a>HOMEPAGE</dt> +<dd><p>Website where more information about the software the recipe is building + can be found.</p></dd> +</dl> +</div> +<div class="glossdiv" title="I"> +<h3 class="title">I</h3> +<dl> +<dt> +<a name="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt> +<dd><p>The list of features to include in an image. + Typically, you configure this variable in an image recipe. + Note that you can also add extra features to the image by using the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> variable. + See the "<a class="link" href="ref-features-image.html" title="9.3. Images">Images</a>" section for the + full list of features that can be included in images built by the + OpenEmbedded build system.</p></dd> +<dt> +<a name="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt> +<dd><p>Formats of root filesystem images that you want to have created.</p></dd> +<dt> +<a name="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt> +<dd> +<p> + Specifies the packages to install into an image. + The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image + recipe and you should use it with care to avoid ordering issues. + </p> +<p> + Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the + packages to install into an image through <code class="filename">image.bbclass</code>. + Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>, + that can take + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists + and turn these into auto-generated entries in + <code class="filename">IMAGE_INSTALL</code> in addition to its default contents. + </p> +<p> + Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code> + operator from the <code class="filename">/conf/local.conf</code> file or from within + an image recipe is not recommended as it can cause ordering issues. + Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code> + to a default value using the <code class="filename">?=</code> operator, using a + <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code> + will result in unexpected behavior when used in + <code class="filename">/conf/local.conf</code>. + Furthermore, the same operation from with 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 <code class="filename">+=</code> operator to work. + </p> +<p> + When you use this variable, it is best to use it as follows: + </p> +<pre class="literallayout"> + IMAGE_INSTALL_append = " package-name" + </pre> +<p> + Be sure to include the space between the quotation character and the start of the + package name. + </p> +</dd> +<dt> +<a name="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt> +<dd> +<p> + Defines a multiplier that the build system applies to the initial image + size for cases when the multiplier times the returned disk usage value + for the image is greater than the sum of + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> + and + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>. + The result of the multiplier applied to the initial image size creates + free disk space in the image as overhead. + By default, the build process uses a multiplier of 1.3 for this variable. + This default value results in 30% free disk space added to the image when this + method is used to determine the final generated image size. + You should be aware that post install scripts and the package management + system uses disk space inside this overhead area. + Consequently, the multiplier does not produce an image with + all the theoretical free disk space. + See <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> + for information on how the build system determines the overall image size. + </p> +<p> + The default 30% free disk space typically gives the image enough room to boot + and allows for basic post installs while still leaving a small amount of + free disk space. + If 30% free space is inadequate, you can increase the default value. + For example, the following setting gives you 50% free space added to the image: + </p> +<pre class="literallayout"> + IMAGE_OVERHEAD_FACTOR = "1.5" + </pre> +<p> + </p> +<p> + Alternatively, you can ensure a specific amount of free disk space is added + to the image by using + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code> + the variable. + </p> +</dd> +<dt> +<a name="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt> +<dd> +<p> + Defines additional free disk space created in the image in Kbytes. + By default, this variable is set to "0". + This free disk space is added to the image after the build system determines + the image size as described in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>. + </p> +<p> + This variable is particularly useful when you want to ensure that a + specific amount of free disk space is available on a device after an image + is installed and running. + For example, to be sure 5 Gbytes of free disk space is available, set the + variable as follows: + </p> +<pre class="literallayout"> + IMAGE_ROOTFS_EXTRA_SPACE = "5242880" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt> +<dd> +<p> + Defines the size in Kbytes for the generated image. + The OpenEmbedded build system determines the final size for the generated + image using an algorithm that takes into account the initial disk space used + for the generated image, a requested size for the image, and requested + additional free disk space to be added to the image. + Programatically, the build system determines the final size of the + generated image as follows: + </p> +<pre class="literallayout"> + if (image-du * overhead) < rootfs-size: + internal-rootfs-size = rootfs-size + xspace + else: + internal-rootfs-size = (image-du * overhead) + xspace + + where: + + image-du = Returned value of the du command on + the image. + + overhead = IMAGE_OVERHEAD_FACTOR + + rootfs-size = IMAGE_ROOTFS_SIZE + + internal-rootfs-size = Initial root filesystem + size before any modifications. + + xspace = IMAGE_ROOTFS_EXTRA_SPACE + </pre> +<p> + + </p> +</dd> +<dt> +<a name="var-INC_PR"></a>INC_PR</dt> +<dd> +<p>Helps define the recipe revision for recipes that share + a common <code class="filename">include</code> file. + You can think of this variable as part of the recipe revision + as set from within an include file.</p> +<p>Suppose, for example, you have a set of recipes that + are used across several projects. + And, within each of those recipes the revision + (its <code class="filename">PR</code> value) is set accordingly. + In this case, when the revision of those recipes changes + the burden is on you to find all those recipes and + be sure that they get changed to reflect the updated + version of the recipe. + In this scenario, it can get complicated when recipes + used in many places and that provide common functionality + are upgraded to a new revision.</p> +<p>A more efficient way of dealing with this situation is + to set the <code class="filename">INC_PR</code> variable inside + the <code class="filename">include</code> files that the recipes + share and then expand the <code class="filename">INC_PR</code> + variable within the recipes to help + define the recipe revision. + </p> +<p> + The following provides an example that shows how to use + the <code class="filename">INC_PR</code> variable + given a common <code class="filename">include</code> file that + defines the variable. + Once the variable is defined in the + <code class="filename">include</code> file, you can use the + variable to set the <code class="filename">PR</code> values in + each recipe. + You will notice that when you set a recipe's + <code class="filename">PR</code> you can provide more granular + revisioning by appending values to the + <code class="filename">INC_PR</code> variable: + </p> +<pre class="literallayout"> +recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" +recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" +recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" +recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + </pre> +<p> + The first line of the example establishes the baseline + revision to be used for all recipes that use the + <code class="filename">include</code> file. + The remaining lines in the example are from individual + recipes and show how the <code class="filename">PR</code> value + is set.</p> +</dd> +<dt> +<a name="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt> +<dd><p> + Causes the build to not strip binaries in resulting packages. + </p></dd> +<dt> +<a name="var-INHERIT"></a>INHERIT</dt> +<dd><p> + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + </p></dd> +<dt> +<a name="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt> +<dd> +<p> + A list of the packages that contain initscripts. + If multiple packages are specified, you need to append the package name + to the other <code class="filename">INITSCRIPT_*</code> as an override.</p> +<p> + This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. + The variable is optional and defaults to the <code class="filename">PN</code> variable. + </p> +</dd> +<dt> +<a name="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt> +<dd> +<p> + The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>. + </p> +<p> + This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. + The variable is Mandatory. + </p> +</dd> +<dt> +<a name="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt> +<dd> +<p> + Specifies the options to pass to <code class="filename">update-rc.d</code>. + An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a + runlevel of 99, starts the script in initlevels 2 and 5, and + stops the script in levels 0, 1 and 6. + </p> +<p> + The variable is mandatory and is used in recipes when using + <code class="filename">update-rc.d.bbclass</code>. + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="K"> +<h3 class="title">K</h3> +<dl> +<dt> +<a name="var-KBRANCH"></a>KBRANCH</dt> +<dd> +<p> + A regular expression used by the build process to explicitly identify the kernel + branch that is validated, patched and configured during a build. + The <code class="filename">KBRANCH</code> variable is optional. + You can use it to trigger checks to ensure the exact kernel branch you want is + being used by the build process. + </p> +<p> + Values for this variable are set in the kernel's recipe file and the kernel's + append file. + For example, if you are using the Yocto Project kernel that is based on the + Linux 3.4 kernel, the kernel recipe file is the + <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.4.bb</code> file. + Following is the default value for <code class="filename">KBRANCH</code> and the default + override for the architectures the Yocto Project supports: + </p> +<pre class="literallayout"> + KBRANCH_DEFAULT = "standard/base" + KBRANCH = "${KBRANCH_DEFAULT}" + </pre> +<p> + This branch exists in the <code class="filename">linux-yocto-3.4</code> kernel Git + repository <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads" target="_self">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads</a>. + </p> +<p> + This variable is also used from the kernel's append file to identify the kernel + branch specific to a particular machine or target hardware. + The kernel's append file is located in the BSP layer for a given machine. + For example, the kernel append file for the Crown Bay BSP is in the + <code class="filename">meta-intel</code> Git repository and is named + <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</code>. + Here are the related statements from the append file: + </p> +<pre class="literallayout"> + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/crownbay" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/crownbay" + </pre> +<p> + The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to + use when building for the Crown Bay BSP. + In this case there are two identical statements: one for each type of + Crown Bay machine. + </p> +</dd> +<dt> +<a name="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt> +<dd> +<p>Includes additional metadata from the Yocto Project kernel Git repository. + In the OpenEmbedded build system, the default Board Support Packages (BSPs) + metadata is provided through + the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables. + You can use the <code class="filename">KERNEL_FEATURES</code> variable to further + add metadata for all BSPs.</p> +<p>The metadata you add through this variable includes config fragments and + features descriptions, + which usually includes patches as well as config fragments. + You typically override the <code class="filename">KERNEL_FEATURES</code> variable + for a specific machine. + In this way, you can provide validated, but optional, sets of kernel + configurations and features.</p> +<p>For example, the following adds <code class="filename">netfilter</code> to all + the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code> + machine: + </p> +<pre class="literallayout"> + # Add netfilter to all linux-yocto kernels + KERNEL_FEATURES="features/netfilter" + + # Add sound support to the qemux86 machine + KERNEL_FEATURES_append_qemux86=" cfg/sound" + </pre> +</dd> +<dt> +<a name="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt> +<dd><p>The type of kernel to build for a device, usually set by the + machine configuration files and defaults to "zImage". + This variable is used + when building the kernel and is passed to <code class="filename">make</code> as the target to + build.</p></dd> +<dt> +<a name="var-KMACHINE"></a>KMACHINE</dt> +<dd> +<p> + The machine as known by the kernel. + Sometimes the machine name used by the kernel does not match the machine name + used by the OpenEmbedded build system. + For example, the machine name that the OpenEmbedded build system understands as + <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel. + The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>. + For cases like these, the <code class="filename">KMACHINE</code> variable maps the + kernel machine name to the OpenEmbedded build system machine name. + </p> +<p> + Kernel machine names are initially defined in the + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_self">Yocto Linux Kernel</a> in + the <code class="filename">meta</code> branch. + From the <code class="filename">meta</code> branch, look in + the <code class="filename">meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</code> file. + For example, from the <code class="filename">meta</code> branch in the + <code class="filename">linux-yocto-3.0</code> kernel, the + <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file + has the following: + </p> +<pre class="literallayout"> + define KMACHINE cedartrail + define KTYPE standard + define KARCH i386 + + include ktypes/standard + branch cedartrail + + include cedartrail.scc + </pre> +<p> + You can see that the kernel understands the machine name for the Cedar Trail BSP as + <code class="filename">cedartrail</code>. + </p> +<p> + If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source + repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>, + you will find the following statements among others: + </p> +<pre class="literallayout"> + COMPATIBLE_MACHINE_cedartrail = "cedartrail" + KMACHINE_cedartrail = "cedartrail" + KBRANCH_cedartrail = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" + KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" + + COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" + KMACHINE_cedartrail-nopvr = "cedartrail" + KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" + </pre> +<p> + The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that + the OpenEmbedded build system and the Yocto Linux kernel understand the same machine + names. + </p> +<p> + This append file uses two <code class="filename">KMACHINE</code> statements. + The first is not really necessary but does ensure that the machine known to the + OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine + in the kernel also known as <code class="filename">cedartrail</code>: + </p> +<pre class="literallayout"> + KMACHINE_cedartrail = "cedartrail" + </pre> +<p> + </p> +<p> + The second statement is a good example of why the <code class="filename">KMACHINE</code> variable + is needed. + In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code> + machine name to refer to the Cedar Trail BSP that does not support the propriatory + PowerVR driver. + The kernel, however, uses the machine name <code class="filename">cedartrail</code>. + Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to + the kernel's <code class="filename">cedartrail</code> name: + </p> +<pre class="literallayout"> + KMACHINE_cedartrail-nopvr = "cedartrail" + </pre> +<p> + </p> +<p> + BSPs that ship with the Yocto Project release provide all mappings between the Yocto + Project kernel machine names and the OpenEmbedded machine names. + Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine + name you use is different than that used in the kernel. + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="L"> +<h3 class="title">L</h3> +<dl> +<dt> +<a name="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt> +<dd><p>Lists the layers that this recipe depends upon, separated by spaces. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" + to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case). + An error will be produced if any dependency is missing or + the version numbers do not match exactly (if specified). + This variable is used in the <code class="filename">conf/layer.conf</code> file + and must be suffixed with the name of the specific layer (e.g. + <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd> +<dt> +<a name="var-LAYERDIR"></a>LAYERDIR</dt> +<dd><p>When used inside the <code class="filename">layer.conf</code> configuration + file, this variable provides the path of the current layer. + This variable requires immediate expansion + (see the BitBake manual) as lazy expansion can result in + the expansion happening in the wrong directory and therefore + giving the wrong value.</p></dd> +<dt> +<a name="var-LAYERVERSION"></a>LAYERVERSION</dt> +<dd><p>Optionally specifies the version of a layer as a single number. + You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to + depend on a specific version of the layer. + This variable is used in the <code class="filename">conf/layer.conf</code> file + and must be suffixed with the name of the specific layer (e.g. + <code class="filename">LAYERVERSION_mylayer</code>).</p></dd> +<dt> +<a name="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt> +<dd> +<p>Checksums of the license text in the recipe source code.</p> +<p>This variable tracks changes in license text of the source + code files. + If the license text is changed, it will trigger a build + failure, which gives the developer an opportunity to review any + license change.</p> +<p> + This variable must be defined for all recipes (unless <code class="filename">LICENSE</code> + is set to "CLOSED")</p> +<p>For more information, see the + <a class="link" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes"> + Tracking License Changes</a> section</p> +</dd> +<dt> +<a name="var-LICENSE"></a>LICENSE</dt> +<dd> +<p> + The list of source licenses for the recipe. + Follow these rules: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>Do not use spaces within individual + license names.</p></li> +<li class="listitem"><p>Separate license names using + | (pipe) when there is a choice between licenses. + </p></li> +<li class="listitem"><p>Separate license names using + & (ampersand) when multiple licenses exist + that cover different parts of the source. + </p></li> +<li class="listitem"><p>You can use spaces between license + names.</p></li> +</ul></div> +<p> + </p> +<p> + Here are some examples: + </p> +<pre class="literallayout"> + LICENSE = "LGPLv2.1 | GPLv3" + LICENSE = "MPL-1 & LGPLv2.1" + LICENSE = "GPLv2+" + </pre> +<p> + The first example is from the recipes for Qt, which the user + may choose to distribute under either the LGPL version + 2.1 or GPL version 3. + The second example is from Cairo where two licenses cover + different parts of the source code. + The final example is from <code class="filename">sysstat</code>, + which presents a single license. + </p> +</dd> +<dt> +<a name="var-LICENSE_PATH"></a>LICENSE_PATH</dt> +<dd> +<p>Path to additional licenses used during the build. + By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code> + to define the directory that holds common license text used during the build. + The <code class="filename">LICENSE_PATH</code> variable allows you to extend that + location to other areas that have additional licenses: + </p> +<pre class="literallayout"> + LICENSE_PATH += "/path/to/additional/common/licenses" + </pre> +</dd> +</dl> +</div> +<div class="glossdiv" title="M"> +<h3 class="title">M</h3> +<dl> +<dt> +<a name="var-MACHINE"></a>MACHINE</dt> +<dd> +<p> + Specifies the target device for which the image is built. + You define <code class="filename">MACHINE</code> in the + <code class="filename">local.conf</code> file found in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + By default, <code class="filename">MACHINE</code> is set to + "qemux86", which is an x86-based architecture machine to + be emulated using QEMU: + </p> +<pre class="literallayout"> + MACHINE ?= "qemux86" + </pre> +<p> + The variable corresponds to a machine configuration file of the + same name, through which machine-specific configurations are set. + Thus, when <code class="filename">MACHINE</code> is set to "qemux86" there + exists the corresponding <code class="filename">qemux86.conf</code> machine + configuration file, which can be found in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> + in <code class="filename">meta/conf/machine</code>. + </p> +<p> + The list of machines supported by the Yocto Project as + shipped include the following: + </p> +<pre class="literallayout"> + MACHINE ?= "qemuarm" + MACHINE ?= "qemumips" + MACHINE ?= "qemuppc" + MACHINE ?= "qemux86" + MACHINE ?= "qemux86-64" + MACHINE ?= "atom-pc" + MACHINE ?= "beagleboard" + MACHINE ?= "mpc8315e-rdb" + MACHINE ?= "routerstationpro" + </pre> +<p> + The last four are Yocto Project reference hardware boards, which + are provided in the <code class="filename">meta-yocto-bsp</code> layer. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>Adding additional Board Support Package (BSP) layers + to your configuration adds new possible settings for + <code class="filename">MACHINE</code>. + </div> +<p> + </p> +</dd> +<dt> +<a name="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt> +<dd> +<p></p> +<p> + 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 + packages are essential for the machine to boot. + The impact of this variable affects images based on + <code class="filename">packagegroup-core-boot</code>, + including the <code class="filename">core-image-minimal</code> image. + </p> +<p> + This variable is similar to the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code> + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </p> +<p> + As an example, suppose the machine for which you are building requires + <code class="filename">example-init</code> to be run during boot to initialize the hardware. + In this case, you would use the following in the machine's + <code class="filename">.conf</code> configuration file: + </p> +<pre class="literallayout"> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt> +<dd> +<p></p> +<p> + 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 + packages are essential for the machine to boot. + The impact of this variable affects images based on + <code class="filename">packagegroup-core-boot</code>, + including the <code class="filename">core-image-minimal</code> image. + </p> +<p> + This variable is similar to the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS</a></code> + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will still build if a package in this list is not found. + Typically, this variable is used to handle essential kernel modules, whose + functionality may be selected to be built into the kernel rather than as a module, + in which case a package will not be produced. + </p> +<p> + Consider an example where you have a custom kernel where a specific touchscreen + driver is required for the machine to be usable. + However, the driver can be built as a module or + into the kernel depending on the kernel configuration. + If the driver is built as a module, you want it to be installed. + But, when the driver is built into the kernel, you still want the + build to succeed. + This variable sets up a "recommends" relationship so that in the latter case, + the build will not fail due to the missing package. + To accomplish this, assuming the package for the module was called + <code class="filename">kernel-module-ab123</code>, you would use the + following in the machine's <code class="filename">.conf</code> configuration + file: + </p> +<pre class="literallayout"> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" + </pre> +<p> + </p> +<p> + Some examples of these machine essentials are flash, screen, keyboard, mouse, + or touchscreen drivers (depending on the machine). + </p> +</dd> +<dt> +<a name="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt> +<dd> +<p> + A list of machine-specific packages to install as part of the + image being built that are not essential for the machine to boot. + However, the build process for more fully-featured images + depends on the packages being present. + </p> +<p> + This variable affects all images based on + <code class="filename">packagegroup-base</code>, which does not include the + <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> + images. + </p> +<p> + The variable is similar to the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code> + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </p> +<p> + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + the WiFi. + The package containing the firmware for the WiFi hardware is always + expected to exist, so it is acceptable for the build process to depend upon + finding the package. + In this case, assuming the package for the firmware was called + <code class="filename">wifidriver-firmware</code>, you would use the following in the + <code class="filename">.conf</code> file for the machine: + </p> +<pre class="literallayout"> + MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt> +<dd> +<p></p> +<p> + A list of machine-specific packages to install as part of the + image being built that are not essential for booting the machine. + The image being built has no build dependency on this list of packages. + </p> +<p> + This variable affects only images based on + <code class="filename">packagegroup-base</code>, which does not include the + <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> + images. + </p> +<p> + This variable is similar to the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code> + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will build if a file in this list is not found. + </p> +<p> + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + WiFi. + In this case, the package containing the WiFi kernel module will not be produced + if the WiFi driver is built into the kernel, in which case you still want the + build to succeed instead of failing as a result of the package not being found. + To accomplish this, assuming the package for the module was called + <code class="filename">kernel-module-examplewifi</code>, you would use the + following in the <code class="filename">.conf</code> file for the machine: + </p> +<pre class="literallayout"> + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt> +<dd> +<p>Specifies the list of hardware features the + <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a> supports. + For example, including the "bluetooth" feature causes the + <code class="filename">bluez</code> bluetooth daemon to be built and + added to the image. + It also causes the <code class="filename">connman</code> recipe + to look at <code class="filename">MACHINE_FEATURES</code> and when it + finds "bluetooth" there it enables the bluetooth + support in ConnMan. + </p> +<p> + For a list of features supported by the Yocto Project as shipped, + see the "<a class="link" href="ref-features-machine.html" title="9.2. Machine">Machine</a>" section. + </p> +</dd> +<dt> +<a name="var-MACHINE_FEATURES_BACKFILL"></a>MACHINE_FEATURES_BACKFILL</dt> +<dd> +<p>Features to be added to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code> + if not also present in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED">MACHINE_FEATURES_BACKFILL_CONSIDERED</a></code>. + </p> +<p> + This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file. + 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 <a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature backfilling</a> section for + more information. + </p> +</dd> +<dt> +<a name="var-MACHINE_FEATURES_BACKFILL_CONSIDERED"></a>MACHINE_FEATURES_BACKFILL_CONSIDERED</dt> +<dd><p>Features from + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL">MACHINE_FEATURES_BACKFILL</a></code> + that should not be backfilled (i.e. added to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>) + during the build. + See the <a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature backfilling</a> section for + more information. + </p></dd> +<dt> +<a name="var-MAINTAINER"></a>MAINTAINER</dt> +<dd><p>The email address of the distribution maintainer.</p></dd> +<dt> +<a name="var-MLPREFIX"></a>MLPREFIX</dt> +<dd><p> + Specifies a prefix has been added to + <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> to create a special version + of a recipe or package, such as 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 + <a class="link" href="ref-variables-glos.html#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable). + <code class="filename">MLPREFIX</code> gets set when a prefix has been + added to <code class="filename">PN</code>. + </p></dd> +<dt> +<a name="var-MULTIMACH_TARGET_SYS"></a>MULTIMACH_TARGET_SYS</dt> +<dd><p> + Separates files for different machines such that you can build + for multiple target machines using the same output directories. + See the <a class="link" href="ref-variables-glos.html#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> variable + for an example. + </p></dd> +</dl> +</div> +<div class="glossdiv" title="O"> +<h3 class="title">O</h3> +<dl> +<dt> +<a name="var-OE_TERMINAL"></a>OE_TERMINAL</dt> +<dd> +<p> + Controls how the OpenEmbedded build system spawns + interactive terminals on the host development system + (e.g. using the BitBake command with the + <code class="filename">-c devshell</code> command-line option). + For more information, see the + "<a class="link" href="../dev-manual/platdev-appdev-devshell.html" target="_self">Using a Development Shell</a>" section + in the Yocto Project Development Manual. + </p> +<p> + You can use the following values for the + <code class="filename">OE_TERMINAL</code> variable: + </p> +<pre class="literallayout"> + auto + gnome + xfce + rxvt + screen + konsole + none + </pre> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>Konsole support only works for KDE 3.x. + Also, "auto" is the default behavior for + <code class="filename">OE_TERMINAL</code> +</div> +<p> + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="P"> +<h3 class="title">P</h3> +<dl> +<dt> +<a name="var-P"></a>P</dt> +<dd> +<p>The recipe name and version. + <code class="filename">P</code> is comprised of the following: + </p> +<pre class="literallayout"> + ${PN}-${PV} + </pre> +</dd> +<dt> +<a name="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt> +<dd><p>The architecture of the resulting package or packages.</p></dd> +<dt> +<a name="var-PACKAGE_BEFORE_PN"></a>PACKAGE_BEFORE_PN</dt> +<dd><p>Enables easily adding packages to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + before <code class="filename">${PN}</code> so that the packages can pick + up files that would normally be included in the default package.</p></dd> +<dt> +<a name="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt> +<dd> +<p>This variable, which is set in the <code class="filename">local.conf</code> configuration + file found in the <code class="filename">conf</code> folder of the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>, + specifies the package manager to use when packaging data. + You can provide one or more arguments for the variable with the first + argument being the package manager used to create images: + </p> +<pre class="literallayout"> + PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" + </pre> +<p> + For information on build performance effects as a result of the + package manager use, see + <a class="link" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a> + in this manual. + </p> +</dd> +<dt> +<a name="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt> +<dd><p>Specifies the list of architectures compatible with the device CPU. + This variable is useful when you build for several different devices that use + miscellaneous processors such as XScale and ARM926-EJS).</p></dd> +<dt> +<a name="var-PACKAGECONFIG"></a>PACKAGECONFIG</dt> +<dd> +<p> + This variable provides a means of enabling or disabling + features of a recipe on a per-recipe basis. + The <code class="filename">PACKAGECONFIG</code> + variable itself specifies a space-separated list of the + features to enable. + The features themselves are specified as flags on the + <code class="filename">PACKAGECONFIG</code> variable. + You can provide up to four arguments, which are separated by + commas, to determine the behavior of each feature + when it is enabled or disabled. + You can omit any argument you like but must retain the + separating commas. + The arguments specify the following: + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"><p>Extra arguments + that should be added to the configure script argument list + (<a class="link" href="ref-variables-glos.html#var-EXTRA_OECONF" title="EXTRA_OECONF"><code class="filename">EXTRA_OECONF</code></a>) + if the feature is enabled.</p></li> +<li class="listitem"><p>Extra arguments + that should be added to <code class="filename">EXTRA_OECONF</code> + if the feature is disabled. + </p></li> +<li class="listitem"><p>Additional build dependencies + (<a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS"><code class="filename">DEPENDS</code></a>) + that should be added if the feature is enabled. + </p></li> +<li class="listitem"><p>Additional runtime dependencies + (<a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a>) + that should be added if the feature is enabled. + </p></li> +</ol></div> +<p> + </p> +<p> + Consider the following example taken from the + <code class="filename">librsvg</code> recipe. + In this example the feature is <code class="filename">croco</code>, which + has three arguments that determine the feature's behavior. + </p> +<pre class="literallayout"> + PACKAGECONFIG ??= "croco" + PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" + </pre> +<p> + The <code class="filename">--with-croco</code> and + <code class="filename">libcroco</code> arguments apply only if + the feature is enabled. + In this case, <code class="filename">--with-croco</code> is + added to the configure script argument list and + <code class="filename">libcroco</code> is added to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS">DEPENDS</a></code>. + On the other hand, if the feature is disabled say through + a <code class="filename">.bbappend</code> file in another layer, then + the second argument <code class="filename">--without-croco</code> is + added to the configure script rather than + <code class="filename">--with-croco</code>. + </p> +</dd> +<dt> +<a name="var-PACKAGES"></a>PACKAGES</dt> +<dd> +<p>The list of packages to be created from the recipe. + The default value is the following: + </p> +<pre class="literallayout"> + ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + </pre> +</dd> +<dt> +<a name="var-PACKAGES_DYNAMIC"></a>PACKAGES_DYNAMIC</dt> +<dd> +<p> + A promise that your recipe satisfies runtime dependencies + for optional modules that are found in other recipes. + <code class="filename">PACKAGES_DYNAMIC</code> + does not actually satisfy the dependencies, it only states that + they should be satisfied. + For example, if a hard, runtime dependency + (<code class="filename">RDEPENDS</code>) of another package is satisfied + at build time through the <code class="filename">PACKAGES_DYNAMIC</code> + variable, but a package with the module name is never actually + produced, then the other package will be broken. + Thus, if you attempt to include that package in an image, + you will get a dependency failure from the packaging system + during <code class="filename">do_rootfs</code>. + Typically, if there is a chance that such a situation can + occur and the package that is not created is valid + without the dependency being satisfied, then you should use + <code class="filename">RRECOMMENDS</code> (a soft runtime dependency) + instead of <code class="filename">RDEPENDS</code>. + </p> +<p> + For an example of how to use the <code class="filename">PACKAGES_DYNAMIC</code> + variable when you are splitting packages, see the + "<a class="link" href="../dev-manual/handling-optional-module-packaging.html" target="_self">Handling Optional Module Packaging</a>" section + in the Yocto Project Development Manual. + </p> +</dd> +<dt> +<a name="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt> +<dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the + compile tasks. + This variable is usually in the form <code class="filename">-j 4</code>, where the number + represents the maximum number of parallel threads make can run. + If you development host supports multiple cores a good rule of thumb is to set + this variable to twice the number of cores on the host.</p></dd> +<dt> +<a name="var-PF"></a>PF</dt> +<dd> +<p>Specifies the recipe or package name and includes all version and revision + numbers (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and + <code class="filename">bash-4.2-r1/</code>). + This variable is comprised of the following: + </p> +<pre class="literallayout"> + ${PN}-${EXTENDPE}${PV}-${PR} + </pre> +</dd> +<dt> +<a name="var-PN"></a>PN</dt> +<dd> +<p>This variable can have two separate functions depending on the context: a recipe + name or a resulting package name.</p> +<p><code class="filename">PN</code> refers to a recipe name in the context of a file used + by the OpenEmbedded build system as input to create a package. + The name is normally extracted from the recipe file name. + For example, if the recipe is named + <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PN</code> + will be "expat".</p> +<p> + The variable refers to a package name in the context of a file created or produced by the + OpenEmbedded build system.</p> +<p>If applicable, the <code class="filename">PN</code> variable also contains any special + suffix or prefix. + For example, using <code class="filename">bash</code> to build packages for the native + machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>. + Using <code class="filename">bash</code> to build packages for the target and for Multilib, + <code class="filename">PN</code> would be <code class="filename">bash</code> and + <code class="filename">lib64-bash</code>, respectively. + </p> +</dd> +<dt> +<a name="var-PR"></a>PR</dt> +<dd><p>The revision of the recipe. + The default value for this variable is "r0". + </p></dd> +<dt> +<a name="var-PRINC"></a>PRINC</dt> +<dd> +<p>Causes the <code class="filename">PR</code> variable of + <code class="filename">.bbappend</code> files to dynamically increment. + This increment minimizes the impact of layer ordering.</p> +<p>In order to ensure multiple <code class="filename">.bbappend</code> files can co-exist, + <code class="filename">PRINC</code> should be self referencing. + This variable defaults to 0.</p> +<p>Following is an example that increments <code class="filename">PR</code> by two: + </p> +<pre class="literallayout"> + PRINC := "${@int(PRINC) + 2}" + </pre> +<p> + It is adviseable not to use strings such as ".= '.1'" with the variable because + this usage is very sensitive to layer ordering. + Explicit assignments should be avoided as they cannot adequately represent multiple + <code class="filename">.bbappend</code> files.</p> +</dd> +<dt> +<a name="var-PV"></a>PV</dt> +<dd><p>The version of the recipe. + The version is normally extracted from the recipe filename. + For example, if the recipe is named + <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PV</code> + will be "2.0.1". + <code class="filename">PV</code> is generally not overridden within + a recipe unless it is building an unstable (i.e. development) version from a source code repository + (e.g. Git or Subversion). + </p></dd> +<dt> +<a name="var-PE"></a>PE</dt> +<dd><p> + the epoch of the recipe. + The default value is "0". + The field is used to make upgrades possible when the versioning scheme changes in + some backwards incompatible way. + </p></dd> +<dt> +<a name="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt> +<dd> +<p> + If multiple recipes provide an item, this variable + determines which recipe should be given preference. + The variable must always be suffixed with the name of the + provided item, and should be set to the + <code class="filename">PN</code> of the recipe + to which you want to give precedence. + Here is an example: + </p> +<pre class="literallayout"> + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt> +<dd> +<p> + If there are multiple versions of recipes available, this + variable determines which recipe should be given preference. + The variable must always be suffixed with the <code class="filename">PN</code> + for which to select, and should be set to the + <code class="filename">PV</code> to which you want to give precedence. + You can use the "<code class="filename">%</code>" character as a wildcard + to match any number of characters, which can be useful when + specifying versions that contain long revision number that could + potentially change. + Here are two examples: + </p> +<pre class="literallayout"> + PREFERRED_VERSION_python = "2.6.6" + PREFERRED_VERSION_linux-yocto = "3.0+git%" + </pre> +<p> + </p> +</dd> +</dl> +</div> +<div class="glossdiv" title="R"> +<h3 class="title">R</h3> +<dl> +<dt> +<a name="var-RCONFLICTS"></a>RCONFLICTS</dt> +<dd> +<p>The list of packages that conflict with a package. + Note that the package will not be installed if the conflicting packages are not + first removed.</p> +<p> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + </p> +<pre class="literallayout"> + RCONFLICTS_${PN} = "another-conflicting-package-name" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-RDEPENDS"></a>RDEPENDS</dt> +<dd> +<p> + Lists a package's run-time dependencies (i.e. other packages) + that must be installed for the package to be built. + In other words, in order for the package to be built and + run correctly, it depends on the listed packages. + If a package in this list cannot be found, it is probable + that a dependency error would occur before the build. + </p> +<p> + The names of the variables you list with + <code class="filename">RDEPENDS</code> must be the names of other + packages as listed in the + <a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES"><code class="filename">PACKAGES</code></a> + variable. + You should not list recipe names (<code class="filename">PN</code>). + </p> +<p> + Because the <code class="filename">RDEPENDS</code> variable applies + to packages being built, you should + always attach a package name to the variable to specify the + particular run-time package that has the dependency. + For example, suppose you are building a development package + that depends on the <code class="filename">perl</code> package. + In this case, you would use the following + <code class="filename">RDEPENDS</code> statement: + </p> +<pre class="literallayout"> + RDEPENDS_${PN}-dev += "perl" + </pre> +<p> + In the example, the package name + (<code class="filename">${PN}-dev</code>) must appear as it would + in the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + namespace before any renaming of the output package by + classes like <code class="filename">debian.bbclass</code>. + </p> +<p> + In many cases you do not need to explicitly add dependencies + to <code class="filename">RDEPENDS</code> since some automatic + handling occurs: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If + a run-time package contains a shared library + (<code class="filename">.so</code>), the build + processes the library in order to determine other + libraries to which it is dynamically linked. + The build process adds these libraries to + <code class="filename">RDEPENDS</code> when creating the run-time + package.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If + the package ships a <code class="filename">pkg-config</code> + information file, the build process uses this file + to add items to the <code class="filename">RDEPENDS</code> + variable to create the run-time packages. + </p></li> +</ul></div> +<p> + </p> +</dd> +<dt> +<a name="var-RRECOMMENDS"></a>RRECOMMENDS</dt> +<dd> +<p> + A list of packages that extend the usability of a package being + built. + The package being built does not depend on this list of packages in + order to successfully build, but needs them for the extended usability. + To specify runtime dependencies for packages, see the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable. + </p> +<p> + The OpenEmbedded build process automatically installs the list of packages + as part of the built package. + However, you can remove them later if you want. + If, during the build, a package from the list cannot be found, the build + process continues without an error. + </p> +<p> + Because the <code class="filename">RRECOMMENDS</code> variable applies to packages + being built, you should + always attach an override to the variable to specify the particular package + whose usability is being extended. + For example, suppose you are building a development package that is extended + to support wireless functionality. + In this case, you would use the following: + </p> +<pre class="literallayout"> + RRECOMMENDS_${PN}-dev += "<wireless_package_name>" + </pre> +<p> + In the example, the package name (<code class="filename">${PN}-dev</code>) must + appear as it would in the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any + renaming of the output package by classes like <code class="filename">debian.bbclass</code>. + </p> +</dd> +<dt> +<a name="var-RREPLACES"></a>RREPLACES</dt> +<dd><p>The list of packages that are replaced with this package.</p></dd> +</dl> +</div> +<div class="glossdiv" title="S"> +<h3 class="title">S</h3> +<dl> +<dt> +<a name="var-S"></a>S</dt> +<dd> +<p> + The location in the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> + where unpacked package source code resides. + This location is within the working directory + (<code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which + is not static. + The unpacked source location depends on the package name + (<code class="filename"><a class="link" href="ref-variables-glos.html#var-PN" title="PN">PN</a></code>) and + package version (<code class="filename"><a class="link" href="ref-variables-glos.html#var-PV" title="PV">PV</a></code>) as + follows: + </p> +<pre class="literallayout"> + ${WORKDIR}/${PN}-${PV} + </pre> +<p> + As an example, assume a + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> top-level + folder named <code class="filename">poky</code> + and a default <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">db</code> package is the following: + </p> +<pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19 + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-SDKIMAGE_FEATURES"></a>SDKIMAGE_FEATURES</dt> +<dd><p>Equivalent to + <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>. + However, this variable applies to the SDK generated from an image using + <code class="filename">bitbake -c populate_sdk imagename</code>). + </p></dd> +<dt> +<a name="var-SECTION"></a>SECTION</dt> +<dd><p>The section in which packages should be categorized. + Package management utilities can make use of this variable.</p></dd> +<dt> +<a name="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt> +<dd><p> + The variable takes the value of + <code class="filename"><a class="link" href="ref-variables-glos.html#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code> + unless <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1". + In this case the value of + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used. + </p></dd> +<dt> +<a name="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt> +<dd><p>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 and after booting occurs <code class="filename">getty</code> is started on that port + so remote login is possible.</p></dd> +<dt> +<a name="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt> +<dd><p> + Specifies the endian byte order of the target system. + The value should be either "le" for little-endian or "be" for big-endian. + </p></dd> +<dt> +<a name="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt> +<dd><p> + Specifies the number of bits for the target system CPU. + The value should be either "32" or "64". + </p></dd> +<dt> +<a name="var-SPECIAL_PKGSUFFIX"></a>SPECIAL_PKGSUFFIX</dt> +<dd><p> + A list of prefixes for <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> used by the + OpenEmbedded build system to create variants of recipes or packages. + The list specifies the prefixes to strip off during certain circumstances + such as the generation of the <a class="link" href="ref-variables-glos.html#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable. + </p></dd> +<dt> +<a name="var-SRC_URI"></a>SRC_URI</dt> +<dd> +<p>The list of source files - local or remote. + This variable tells the OpenEmbedded build system which bits to pull + in for the build and how to pull them in. + For example, if the recipe only needs to fetch a tarball from the + internet, the recipe uses a single <code class="filename">SRC_URI</code> entry. + On the other hand, if the recipe needs to fetch a tarball, apply + two patches, and include a custom file, the recipe would include four + instances of the variable.</p> +<p>The following list explains the available URI protocols: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> +<p><span class="emphasis"><em><code class="filename">file://</code> -</em></span> Fetches files, which is usually + a file shipped with the metadata, from the local machine. + The path is relative to the + <a class="link" href="ref-variables-glos.html#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> + variable. + Thus, the build system searches, in order, from the following directories, + which are assumed to be a subdirectories of the directory in which the + recipe file resides: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">${PN}</code> -</em></span> The recipe name + with any special suffix or prefix, if applicable. + For example, using <code class="filename">bash</code> to build for the native + machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>. + Using <code class="filename">bash</code> to build for the target and for Multilib, + <code class="filename">PN</code> would be <code class="filename">bash</code> and + <code class="filename">lib64-bash</code>, respectively. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">${PF}</code> - </em></span> + <code class="filename">${PN}-${EXTENDPE}${PV}-${PR}</code>. + The recipe name including all version and revision numbers + (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and + <code class="filename">bash-4.2-r1/</code>).</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">${P}</code> -</em></span> + <code class="filename">${PN}-${PV}</code>. + The recipe name and version (i.e. <code class="filename">bash-4.2</code>). + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">${BPN}</code> -</em></span> The + base recipe name without any special suffix or version numbers. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">${BP}</code> -</em></span> + <code class="filename">${BPN}-${PV}</code>. + The base recipe name and version but without any special + package name suffix.</p></li> +<li class="listitem"><p><span class="emphasis"><em>Files -</em></span> Files beneath the directory in which the recipe + resides.</p></li> +<li class="listitem"><p><span class="emphasis"><em>Directory -</em></span> The directory itself in which the recipe + resides.</p></li> +</ul></div> +</li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">bzr://</code> -</em></span> Fetches files from a + Bazaar revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">git://</code> -</em></span> Fetches files from a + Git revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">osc://</code> -</em></span> Fetches files from + an OSC (OpenSuse Build service) revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">repo://</code> -</em></span> Fetches files from + a repo (Git) repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">svk://</code> -</em></span> Fetches files from + an SVK revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">http://</code> -</em></span> Fetches files from + the Internet using <code class="filename">http</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">https://</code> -</em></span> Fetches files + from the Internet using <code class="filename">https</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">ftp://</code> -</em></span> Fetches files + from the Internet using <code class="filename">ftp</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">cvs://</code> -</em></span> Fetches files from + a CVS revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">hg://</code> -</em></span> Fetches files from + a Mercurial (<code class="filename">hg</code>) revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">p4://</code> -</em></span> Fetches files from + a Perforce (<code class="filename">p4</code>) revision control repository.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">ssh://</code> -</em></span> Fetches files from + a secure shell.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">svn://</code> -</em></span> Fetches files from + a Subversion (<code class="filename">svn</code>) revision control repository.</p></li> +</ul></div> +<p> + </p> +<p>Standard and recipe-specific options for <code class="filename">SRC_URI</code> exist. + Here are standard options: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">apply</code> -</em></span> Whether to apply + the patch or not. + The default action is to apply the patch.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">striplevel</code> -</em></span> Which + striplevel to use when applying the patch. + The default level is 1.</p></li> +</ul></div> +<p> + </p> +<p>Here are options specific to recipes building code from a revision control system: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">mindate</code> -</em></span> Only applies + the patch if <a class="link" href="ref-variables-glos.html#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a> + is equal to or greater than <code class="filename">mindate</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">maxdate</code> -</em></span> Only applies + the patch if <a class="link" href="ref-variables-glos.html#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a> + is not later than <code class="filename">mindate</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">minrev</code> -</em></span> Only applies + the patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is equal to or greater than <code class="filename">minrev</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">maxrev</code> -</em></span> Only applies + the patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is not later than <code class="filename">maxrev</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">rev</code> -</em></span> Only applies the + patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is equal to <code class="filename">rev</code>.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">notrev</code> -</em></span> Only applies + the patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is not equal to <code class="filename">rev</code>.</p></li> +</ul></div> +<p> + </p> +<p>Here are some additional options worth mentioning: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">unpack</code> -</em></span> Controls + whether or not to unpack the file if it is an archive. + The default action is to upack the file.</p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">subdir</code> -</em></span> Places the file + (or extracts its contents) into the specified + subdirectory of <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>. + This option is useful for unusual tarballs or other archives that + don't have their files already in a subdirectory within the archive. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">name</code> -</em></span> Specifies a + name to be used for association with <code class="filename">SRC_URI</code> checksums + when you have more than one file specified in <code class="filename">SRC_URI</code>. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><code class="filename">downloadfilename</code> -</em></span> Specifies + the filename used when storing the downloaded file.</p></li> +</ul></div> +<p> + </p> +</dd> +<dt> +<a name="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt> +<dd> +<p></p> +<p> + By default, the OpenEmbedded build system automatically detects whether + <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> + contains files that are machine-specific. + If so, the build system automatically changes + <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>. + Setting this variable to "0" disables this behavior. + </p> +</dd> +<dt> +<a name="var-SRCDATE"></a>SRCDATE</dt> +<dd><p> + The date of the source code used to build the package. + This variable applies only if the source was fetched from a Source Code Manager (SCM). + </p></dd> +<dt> +<a name="var-SRCREV"></a>SRCREV</dt> +<dd><p> + The revision of the source code used to build the package. + This variable applies to Subversion, Git, Mercurial and Bazaar + only. + Note that if you wish to build a fixed revision and you wish + to avoid performing a query on the remote repository every time + BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a + full revision identifier and not just a tag. + </p></dd> +<dt> +<a name="var-SSTATE_DIR"></a>SSTATE_DIR</dt> +<dd><p>The directory for the shared state.</p></dd> +<dt> +<a name="var-SSTATE_MIRRORS"></a>SSTATE_MIRRORS</dt> +<dd> +<p> + Configures the OpenEmbedded build system to search other + mirror locations for prebuilt cache data objects before + building out the data. + This variable works like fetcher + <code class="filename">MIRRORS</code>/<code class="filename">PREMIRRORS</code> + and points to the cache locations to check for the shared + objects. + </p> +<p> + You can specify a filesystem directory or a remote URL such + as HTTP or FTP. + The locations you specify need to contain the shared state + cache (sstate-cache) results from previous builds. + The sstate-cache you point to can also be from builds on + other machines. + </p> +<p> + If a mirror uses the same structure as + <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a>, + you need to add + "PATH" at the end as shown in the examples below. + The build system substitues the correct path within the + directory structure. + </p> +<pre class="literallayout"> + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt> +<dd><p> + The directory with kernel headers that are required to build out-of-tree + modules. + </p></dd> +<dt> +<a name="var-STAMP"></a>STAMP</dt> +<dd> +<p> + Specifies the base path used to create recipe stamp files. + The path to an actual stamp file is constructed by evaluating this + string and then appending additional information. + Currently, the default assignment for <code class="filename">STAMP</code> + as set in the <code class="filename">meta/conf/bitbake.conf</code> file + is: + </p> +<pre class="literallayout"> + STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}-${EXTENDPE}${PV}-${PR}" + </pre> +<p> + See <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, + <a class="link" href="ref-variables-glos.html#var-MULTIMACH_TARGET_SYS" title="MULTIMACH_TARGET_SYS"><code class="filename">MULTIMACH_TARGET_SYS</code></a>, + <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a>, + <a class="link" href="ref-variables-glos.html#var-EXTENDPE" title="EXTENDPE"><code class="filename">EXTENDPE</code></a>, + <a class="link" href="ref-variables-glos.html#var-PV" title="PV"><code class="filename">PV</code></a>, and + <a class="link" href="ref-variables-glos.html#var-PR" title="PR"><code class="filename">PR</code></a> for related variable + information. + </p> +</dd> +<dt> +<a name="var-SUMMARY"></a>SUMMARY</dt> +<dd><p>The short (72 characters or less) summary of the binary package for packaging + systems such as <code class="filename">opkg</code>, <code class="filename">rpm</code> or + <code class="filename">dpkg</code>. + By default, <code class="filename">SUMMARY</code> is used to define + the <a class="link" href="ref-variables-glos.html#var-DESCRIPTION" title="DESCRIPTION"><code class="filename">DESCRIPTION</code></a> + variable if <code class="filename">DESCRIPTION</code> is not set + in the recipe. + </p></dd> +</dl> +</div> +<div class="glossdiv" title="T"> +<h3 class="title">T</h3> +<dl> +<dt> +<a name="var-T"></a>T</dt> +<dd> +<p>This variable points to a directory were Bitbake places temporary + files when building a particular package. + It is typically set as follows: + </p> +<pre class="literallayout"> + T = ${WORKDIR}/temp + </pre> +<p> + The <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a> + is the directory into which Bitbake unpacks and builds the package. + The default <code class="filename">bitbake.conf</code> file sets this variable.</p> +<p>The <code class="filename">T</code> variable is not to be confused with + the <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> variable, + which points to the root of the directory tree where Bitbake + places the output of an entire build. + </p> +</dd> +<dt> +<a name="var-TARGET_ARCH"></a>TARGET_ARCH</dt> +<dd><p>The architecture of the device being built. + While a number of values are possible, the OpenEmbedded build system primarily supports + <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd> +<dt> +<a name="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt> +<dd><p> + Flags passed to the C compiler for the target system. + This variable evaluates to the same as + <code class="filename"><a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>. + </p></dd> +<dt> +<a name="var-TARGET_FPU"></a>TARGET_FPU</dt> +<dd><p>Specifies the method for handling FPU code. + For FPU-less targets, which include most ARM CPUs, the variable must be + set to "soft". + If not, the kernel emulation gets used, which results in a performance penalty.</p></dd> +<dt> +<a name="var-TARGET_OS"></a>TARGET_OS</dt> +<dd><p>Specifies the target's operating system. + The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and + to "linux-uclibc" for <code class="filename">uclibc</code>. + For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-uclibc-gnueabi" values possible.</p></dd> +<dt> +<a name="var-TCLIBC"></a>TCLIBC</dt> +<dd> +<p> + Specifies which variant of the GNU standard C library (<code class="filename">libc</code>) + to use during the build process. + This variable replaces <code class="filename">POKYLIBC</code>, which is no longer + supported. + </p> +<p> + You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + This release of the Yocto Project does not support the + <code class="filename">glibc</code> implementation of <code class="filename">libc</code>. + </div> +<p> + </p> +</dd> +<dt> +<a name="var-TCMODE"></a>TCMODE</dt> +<dd> +<p> + The toolchain selector. + This variable replaces <code class="filename">POKYMODE</code>, which is no longer + supported. + </p> +<p> + The <code class="filename">TCMODE</code> variable selects the external toolchain + built using the OpenEmbedded build system or a few supported combinations of + the upstream GCC or CodeSourcery Labs toolchain. + The variable identifies the <code class="filename">tcmode-*</code> files used in + the <code class="filename">meta/conf/distro/include</code> directory, which is found in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </p> +<p> + By default, <code class="filename">TCMODE</code> is set to "default", which + chooses the <code class="filename">tcmode-default.inc</code> file. + The variable is similar to + <a class="link" href="ref-variables-glos.html#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls + the variant of the GNU standard C library (<code class="filename">libc</code>) + used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. + </p> +</dd> +<dt> +<a name="var-TMPDIR"></a>TMPDIR</dt> +<dd> +<p> + This variable is the temporary directory the OpenEmbedded build system + uses when it does its work building images. + By default, the <code class="filename">TMPDIR</code> variable is named + <code class="filename">tmp</code> within the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + </p> +<p> + If you want to establish this directory in a location other than the + default, you can uncomment the following statement in the + <code class="filename">conf/local.conf</code> file in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>: + </p> +<pre class="literallayout"> + #TMPDIR = "${TOPDIR}/tmp" + </pre> +<p> + </p> +</dd> +<dt> +<a name="var-TOPDIR"></a>TOPDIR</dt> +<dd><p> + This variable is the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + BitBake automatically sets this variable. + The OpenEmbedded build system uses the Build Directory when building images. + </p></dd> +</dl> +</div> +<div class="glossdiv" title="W"> +<h3 class="title">W</h3> +<dl> +<dt> +<a name="var-WORKDIR"></a>WORKDIR</dt> +<dd> +<p> + The pathname of the working directory in which the OpenEmbedded build system + builds a recipe. + This directory is located within the + <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes + as different packages are built. + </p> +<p> + The actual <code class="filename">WORKDIR</code> directory depends on several things: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem">The temporary directory - <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> +</li> +<li class="listitem">The package architecture - <a class="link" href="ref-variables-glos.html#var-PACKAGE_ARCH" title="PACKAGE_ARCH"><code class="filename">PACKAGE_ARCH</code></a> +</li> +<li class="listitem">The target machine - <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a> +</li> +<li class="listitem">The target operating system - <a class="link" href="ref-variables-glos.html#var-TARGET_OS" title="TARGET_OS"><code class="filename">TARGET_OS</code></a> +</li> +<li class="listitem">The recipe name - <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> +</li> +<li class="listitem">The recipe version - <a class="link" href="ref-variables-glos.html#var-PV" title="PV"><code class="filename">PV</code></a> +</li> +<li class="listitem">The recipe revision - <a class="link" href="ref-variables-glos.html#var-PR" title="PR"><code class="filename">PR</code></a> +</li> +</ul></div> +<p> + </p> +<p> + For packages that are not dependent on a particular machine, + <code class="filename">WORKDIR</code> is defined as follows: + </p> +<pre class="literallayout"> + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + </pre> +<p> + As an example, assume a + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> top-level + folder name <code class="filename">poky</code> and a default + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">v86d</code> package is the following: + </p> +<pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0 + </pre> +<p> + </p> +<p> + For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code> + is defined slightly different: + </p> +<pre class="literallayout"> + ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + </pre> +<p> + As an example, again assume a Source Directory top-level folder + named <code class="filename">poky</code> and a default Build Directory + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">acl</code> recipe, which is being built for a + MIPS-based device, is the following: + </p> +<pre class="literallayout"> + ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 + </pre> +<p> + </p> +</dd> +</dl> +</div> +</div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-distro.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-distro.html new file mode 100644 index 0000000000..ba26400d5a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-distro.html @@ -0,0 +1,40 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.1.1. Distribution (Distro)</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-configuration.html" title="11.1. Configuration"> +<link rel="prev" href="ref-varlocality-configuration.html" title="11.1. Configuration"> +<link rel="next" href="ref-varlocality-config-machine.html" title="11.1.2. Machine"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1.1. Distribution (Distro)"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-config-distro"></a>11.1.1. Distribution (Distro)</h3></div></div></div> +<p> + This section lists variables whose context is the distribution, or distro. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TCMODE" title="TCMODE">TCMODE</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TCLIBC" title="TCLIBC">TCLIBC</a></code> + </p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-local.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-local.html new file mode 100644 index 0000000000..2067374c26 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-local.html @@ -0,0 +1,42 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.1.3. Local</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-configuration.html" title="11.1. Configuration"> +<link rel="prev" href="ref-varlocality-config-machine.html" title="11.1.2. Machine"> +<link rel="next" href="ref-varlocality-recipes.html" title="11.2. Recipes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1.3. Local"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-config-local"></a>11.1.3. Local</h3></div></div></div> +<p> + This section lists variables whose context is the local configuration through the + <code class="filename">local.conf</code> file. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO" title="DISTRO">DISTRO</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-BBFILES" title="BBFILES">BBFILES</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES + </a></code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION"> + ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-machine.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-machine.html new file mode 100644 index 0000000000..82ee2a4e6d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-machine.html @@ -0,0 +1,41 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.1.2. Machine</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-configuration.html" title="11.1. Configuration"> +<link rel="prev" href="ref-varlocality-config-distro.html" title="11.1.1. Distribution (Distro)"> +<link rel="next" href="ref-varlocality-config-local.html" title="11.1.3. Local"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1.2. Machine"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-config-machine"></a>11.1.2. Machine</h3></div></div></div> +<p> + This section lists variables whose context is the machine. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS + </a></code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS + </a></code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS + </a></code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-configuration.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-configuration.html new file mode 100644 index 0000000000..c6a1c87198 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-configuration.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.1. Configuration</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality.html" title="Chapter 11. Variable Context"> +<link rel="prev" href="ref-varlocality.html" title="Chapter 11. Variable Context"> +<link rel="next" href="ref-varlocality-config-distro.html" title="11.1.1. Distribution (Distro)"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1. Configuration"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-varlocality-configuration"></a>11.1. Configuration</h2></div></div></div> +<p> + The following subsections provide lists of variables whose context is + configuration: distribution, machine, and local. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-build.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-build.html new file mode 100644 index 0000000000..3068ceb8d2 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-build.html @@ -0,0 +1,33 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.2.4. Extra Build Information</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes"> +<link rel="prev" href="ref-varlocality-recipe-paths.html" title="11.2.3. Paths"> +<link rel="next" href="faq.html" title="Chapter 12. FAQ"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.4. Extra Build Information"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-recipe-build"></a>11.2.4. Extra Build Information</h3></div></div></div> +<p> + This section lists variables that define extra build information for recipes. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + </p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE + </a></code></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-dependencies.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-dependencies.html new file mode 100644 index 0000000000..4a172a7751 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-dependencies.html @@ -0,0 +1,33 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.2.2. Dependencies</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes"> +<link rel="prev" href="ref-varlocality-recipe-required.html" title="11.2.1. Required"> +<link rel="next" href="ref-varlocality-recipe-paths.html" title="11.2.3. Paths"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.2. Dependencies"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-recipe-dependencies"></a>11.2.2. Dependencies</h3></div></div></div> +<p> + This section lists variables that define recipe dependencies. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS">DEPENDS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RREPLACES" title="RREPLACES">RREPLACES</a> + </code></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-paths.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-paths.html new file mode 100644 index 0000000000..92003d344f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-paths.html @@ -0,0 +1,29 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.2.3. Paths</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes"> +<link rel="prev" href="ref-varlocality-recipe-dependencies.html" title="11.2.2. Dependencies"> +<link rel="next" href="ref-varlocality-recipe-build.html" title="11.2.4. Extra Build Information"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.3. Paths"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-recipe-paths"></a>11.2.3. Paths</h3></div></div></div> +<p> + This section lists variables that define recipe paths. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-S" title="S">S</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-FILES" title="FILES">FILES</a> + </code></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-required.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-required.html new file mode 100644 index 0000000000..bb0355cced --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-required.html @@ -0,0 +1,30 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.2.1. Required</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes"> +<link rel="prev" href="ref-varlocality-recipes.html" title="11.2. Recipes"> +<link rel="next" href="ref-varlocality-recipe-dependencies.html" title="11.2.2. Dependencies"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.1. Required"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="ref-varlocality-recipe-required"></a>11.2.1. Required</h3></div></div></div> +<p> + This section lists variables that are required for recipes. + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-LICENSE" title="LICENSE">LICENSE</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a> + </code></p></li> +<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> - used + in recipes that fetch local or remote files. + </p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipes.html new file mode 100644 index 0000000000..5959cdc5ed --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipes.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>11.2. Recipes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-varlocality.html" title="Chapter 11. Variable Context"> +<link rel="prev" href="ref-varlocality-config-local.html" title="11.1.3. Local"> +<link rel="next" href="ref-varlocality-recipe-required.html" title="11.2.1. Required"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2. Recipes"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="ref-varlocality-recipes"></a>11.2. Recipes</h2></div></div></div> +<p> + The following subsections provide lists of variables whose context is + recipes: required, dependencies, path, and extra build information. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality.html new file mode 100644 index 0000000000..3cf716975f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality.html @@ -0,0 +1,41 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 11. Variable Context</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="ref-variables-glos.html" title="Chapter 10. Variables Glossary"> +<link rel="next" href="ref-varlocality-configuration.html" title="11.1. Configuration"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 11. Variable Context"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="ref-varlocality"></a>Chapter 11. Variable Context</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="ref-varlocality-configuration.html">11.1. Configuration</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-varlocality-config-distro.html">11.1.1. Distribution (Distro)</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-config-machine.html">11.1.2. Machine</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-config-local.html">11.1.3. Local</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="ref-varlocality-recipes.html">11.2. Recipes</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="ref-varlocality-recipe-required.html">11.2.1. Required</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-recipe-dependencies.html">11.2.2. Dependencies</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-recipe-paths.html">11.2.3. Paths</a></span></dt> +<dt><span class="section"><a href="ref-varlocality-recipe-build.html">11.2.4. Extra Build Information</a></span></dt> +</dl></dd> +</dl> +</div> +<p> + While most variables can be used in almost any context such as + <code class="filename">.conf</code>, <code class="filename">.bbclass</code>, + <code class="filename">.inc</code>, and <code class="filename">.bb</code> files, + some variables are often associated with a particular locality or context. + This chapter describes some common associations. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/required-packages-for-the-host-development-system.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/required-packages-for-the-host-development-system.html new file mode 100644 index 0000000000..5100bbcb29 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/required-packages-for-the-host-development-system.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3.2. Required Packages for the Host Development System</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="intro-requirements.html" title="1.3. System Requirements"> +<link rel="prev" href="detailed-supported-distros.html" title="1.3.1. Supported Linux Distributions"> +<link rel="next" href="ubuntu-packages.html" title="1.3.2.1. Ubuntu"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2. Required Packages for the Host Development System"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="required-packages-for-the-host-development-system"></a>1.3.2. Required Packages for the Host Development System</h3></div></div></div> +<p> + 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 by Linux distribution and + further categorized by function. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-bugtracker.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-bugtracker.html new file mode 100644 index 0000000000..4b4f994671 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-bugtracker.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>13.2. Tracking Bugs</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="prev" href="resources-intro.html" title="13.1. Introduction"> +<link rel="next" href="resources-mailinglist.html" title="13.3. Mailing lists"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.2. Tracking Bugs"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="resources-bugtracker"></a>13.2. Tracking Bugs</h2></div></div></div> +<p> + If you find problems with the Yocto Project, you should report them using the + Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_self">http://bugzilla.yoctoproject.org</a>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-contributions.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-contributions.html new file mode 100644 index 0000000000..c7d8c539ae --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-contributions.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>13.6. Contributions</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="prev" href="resources-links.html" title="13.5. Links"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.6. Contributions"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="resources-contributions"></a>13.6. Contributions</h2></div></div></div> +<p> + The Yocto Project gladly accepts contributions. + You can submit changes to the project either by creating and sending pull requests, + or by submitting patches through email. + For information on how to do both, see the + "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">How to Submit a Change</a>" + section in the Yocto Project Development Manual. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-intro.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-intro.html new file mode 100644 index 0000000000..c7340ff313 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-intro.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>13.1. Introduction</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="prev" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="next" href="resources-bugtracker.html" title="13.2. Tracking Bugs"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.1. Introduction"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="resources-intro"></a>13.1. Introduction</h2></div></div></div> +<p> + The Yocto Project team is happy for people to experiment with the Yocto Project. + A number of places exist to find help if you run into difficulties or find bugs. + To find out how to download source code, + see the "<a class="link" href="../dev-manual/local-yp-release.html" target="_self">Yocto Project Release</a>" + list item in the Yocto Project Development Manual. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-irc.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-irc.html new file mode 100644 index 0000000000..5a611fa6a8 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-irc.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>13.4. Internet Relay Chat (IRC)</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="prev" href="resources-mailinglist.html" title="13.3. Mailing lists"> +<link rel="next" href="resources-links.html" title="13.5. Links"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.4. Internet Relay Chat (IRC)"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="resources-irc"></a>13.4. Internet Relay Chat (IRC)</h2></div></div></div> +<p> + Two IRC channels on freenode are available for the Yocto Project and Poky discussions: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="filename">#yocto</code></p></li> +<li class="listitem"><p><code class="filename">#poky</code></p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-links.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-links.html new file mode 100644 index 0000000000..0a153b8f01 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-links.html @@ -0,0 +1,42 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>13.5. Links</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="prev" href="resources-irc.html" title="13.4. Internet Relay Chat (IRC)"> +<link rel="next" href="resources-contributions.html" title="13.6. Contributions"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.5. Links"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="resources-links"></a>13.5. Links</h2></div></div></div> +<p> + Following is a list of resources you will find helpful: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_self">The Yocto Project website</a>: + </em></span> The home site for the Yocto Project.</p></li> +<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_self">Intel Corporation</a>:</em></span> + The company who acquired OpenedHand in 2008 and began development on the + Yocto Project.</p></li> +<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_self">OpenEmbedded</a>:</em></span> + The upstream, generic, embedded distribution used as the basis for the build system in the + Yocto Project. + Poky derives from and contributes back to the OpenEmbedded project.</p></li> +<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_self"> + BitBake</a>:</em></span> The tool used to process metadata.</p></li> +<li class="listitem"><p><span class="emphasis"><em>BitBake User Manual:</em></span> + A comprehensive guide to the BitBake tool. + You can find the BitBake User Manual in the <code class="filename">bitbake/doc/manual</code> + directory, which is found in the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </p></li> +<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_self">QEMU</a>: + </em></span> An open source machine emulator and virtualizer.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-mailinglist.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-mailinglist.html new file mode 100644 index 0000000000..3cc05beea4 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources-mailinglist.html @@ -0,0 +1,39 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>13.3. Mailing lists</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project"> +<link rel="prev" href="resources-bugtracker.html" title="13.2. Tracking Bugs"> +<link rel="next" href="resources-irc.html" title="13.4. Internet Relay Chat (IRC)"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.3. Mailing lists"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="resources-mailinglist"></a>13.3. Mailing lists</h2></div></div></div> +<p> + There are a number of mailing lists maintained by the Yocto Project as well as + related OpenEmbedded mailing lists for discussion, patch submission and announcements. + To subscribe to one of the following mailing lists, click on the appropriate URL + in the following list and follow the instructions: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_self">http://lists.yoctoproject.org/listinfo/yocto</a> - + General Yocto Project discussion mailing list. </p></li> +<li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_self">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core</a> - + Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li> +<li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_self">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel</a> - + Discussion mailing list about OpenEmbedded.</p></li> +<li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_self">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel</a> - + Discussion mailing list about the BitBake build tool.</p></li> +<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_self">http://lists.yoctoproject.org/listinfo/poky</a> - + Discussion mailing list about Poky.</p></li> +<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_self">http://lists.yoctoproject.org/listinfo/yocto-announce</a> - + Mailing list to receive official Yocto Project release and milestone + announcements.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/resources.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources.html new file mode 100644 index 0000000000..c97f06e0c2 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/resources.html @@ -0,0 +1,27 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 13. Contributing to the Yocto Project</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="faq.html" title="Chapter 12. FAQ"> +<link rel="next" href="resources-intro.html" title="13.1. Introduction"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 13. Contributing to the Yocto Project"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="resources"></a>Chapter 13. Contributing to the Yocto Project</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="resources-intro.html">13.1. Introduction</a></span></dt> +<dt><span class="section"><a href="resources-bugtracker.html">13.2. Tracking Bugs</a></span></dt> +<dt><span class="section"><a href="resources-mailinglist.html">13.3. Mailing lists</a></span></dt> +<dt><span class="section"><a href="resources-irc.html">13.4. Internet Relay Chat (IRC)</a></span></dt> +<dt><span class="section"><a href="resources-links.html">13.5. Links</a></span></dt> +<dt><span class="section"><a href="resources-contributions.html">13.6. Contributions</a></span></dt> +</dl> +</div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state-cache.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state-cache.html new file mode 100644 index 0000000000..8f2f5a5ed6 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state-cache.html @@ -0,0 +1,60 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2. Shared State Cache</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details"> +<link rel="prev" href="usingpoky-components-configuration.html" title="3.1.4. Configuration"> +<link rel="next" href="overall-architecture.html" title="3.2.1. Overall Architecture"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2. Shared State Cache"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div> +<p> + By design, the OpenEmbedded build system builds everything from scratch unless + BitBake can determine that parts don't 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. + </p> +<p> + 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 don't necessarily need rebuilt. + </p> +<p> + 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: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem">What pieces of the system have changed and what pieces have not changed?</li> +<li class="listitem">How are changed pieces of software removed and replaced?</li> +<li class="listitem">How are pre-built components that don't need to be rebuilt from scratch + used when they are available?</li> +</ul></div> +<p> + </p> +<p> + 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. + </p> +<p> + The rest of this section goes into detail about the overall incremental build + architecture, the checksums (signatures), shared state, and some tips and tricks. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html new file mode 100644 index 0000000000..e14e306eb5 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html @@ -0,0 +1,134 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2.3. Shared State</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache"> +<link rel="prev" href="checksums.html" title="3.2.2. Checksums (Signatures)"> +<link rel="next" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.3. Shared State"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="shared-state"></a>3.2.3. Shared State</h3></div></div></div> +<p> + Checksums and dependencies, as discussed in the previous section, solve half the + problem. + 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. + </p> +<p> + The shared state class (<code class="filename">sstate.bbclass</code>) + 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 doesn't need to worry about its source. + </p> +<p> + There are two types of output, one is just about creating a directory + in <code class="filename">WORKDIR</code>. + A good example is the output of either <code class="filename">do_install</code> or + <code class="filename">do_package</code>. + The other type of output occurs when a set of data is merged into a shared directory + tree such as the sysroot. + </p> +<p> + The Yocto Project team has tried to keep the details of the implementation hidden in + <code class="filename">sstate.bbclass</code>. + From a user's perspective, adding shared state wrapping to a task + is as simple as this <code class="filename">do_deploy</code> example taken from + <code class="filename">do_deploy.bbclass</code>: + </p> +<pre class="literallayout"> + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-name] = "deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + </pre> +<p> + In the 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 <code class="filename">_setscene</code> variant of the task and add the task + name to the <code class="filename">SSTATETASKS</code> list. + </p> +<p> + If you have a directory whose contents you need to preserve, you can do this with + a line like the following: + </p> +<pre class="literallayout"> + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + </pre> +<p> + This method, as well as the following example, also works for multiple directories. + </p> +<pre class="literallayout"> + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + do_package[sstate-lockfile] = "${PACKAGELOCK}" + </pre> +<p> + 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. + </p> +<p> + Behind the scenes, the shared state code works by looking in + <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> and + <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a> + for shared state files. + Here is an example: + </p> +<pre class="literallayout"> + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + </pre> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + The shared state directory (<code class="filename">SSTATE_DIR</code>) 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 <code class="filename">SSTATE_DIR</code>, you must + specify "PATH" as part of the URI to enable the build system + to map to the appropriate subdirectory. + </div> +<p> + </p> +<p> + 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. + </p> +<p> + The build processes uses the <code class="filename">*_setscene</code> 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. + </p> +<p> + As a real world example, the aim is when building an IPK-based image, + only the <code class="filename">do_package_write_ipk</code> 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-basic-top-level.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-basic-top-level.html new file mode 100644 index 0000000000..62bdd6b748 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-basic-top-level.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.11. LICENSE, README, and README.hardware</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-script.html" title="5.1.10. oe-init-build-env"> +<link rel="next" href="structure-build.html" title="5.2. The Build Directory - build/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.11. LICENSE, README, and README.hardware"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-basic-top-level"></a>5.1.11. <code class="filename">LICENSE, README, and README.hardware</code> +</h3></div></div></div> +<p> + These files are standard top-level files. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-bblayers.conf.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-bblayers.conf.html new file mode 100644 index 0000000000..74f7729330 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-bblayers.conf.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.3. build/conf/bblayers.conf</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-conf-local.conf.html" title="5.2.2. build/conf/local.conf"> +<link rel="next" href="structure-build-conf-sanity_info.html" title="5.2.4. build/conf/sanity_info"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.3. build/conf/bblayers.conf"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-conf-bblayers.conf"></a>5.2.3. <code class="filename">build/conf/bblayers.conf</code> +</h3></div></div></div> +<p> + This file defines layers, which is a directory tree, traversed (or walked) by BitBake. + If <code class="filename">bblayers.conf</code> + is not present, it is created from <code class="filename">bblayers.conf.sample</code> when + you <code class="filename">source</code> the environment setup script. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-local.conf.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-local.conf.html new file mode 100644 index 0000000000..30f1c10881 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-local.conf.html @@ -0,0 +1,37 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.2. build/conf/local.conf</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-pseudodone.html" title="5.2.1. build/pseudodone"> +<link rel="next" href="structure-build-conf-bblayers.conf.html" title="5.2.3. build/conf/bblayers.conf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.2. build/conf/local.conf"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-conf-local.conf"></a>5.2.2. <code class="filename">build/conf/local.conf</code> +</h3></div></div></div> +<p> + This file contains all the local user configuration for your build environment. + If there is no <code class="filename">local.conf</code> present, it is created from + <code class="filename">local.conf.sample</code>. + The <code class="filename">local.conf</code> file contains documentation on the various configuration options. + Any variable set here overrides any variable set elsewhere within the environment unless + that variable is hard-coded within a file (e.g. by using '=' instead of '?='). + Some variables are hard-coded for various reasons but these variables are + relatively rare. + </p> +<p> + Edit this file to set the <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a></code> + for which you want to build, which package types you wish to use + (<a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES"><code class="filename">PACKAGE_CLASSES</code></a>), + where you want to downloaded files + (<code class="filename"><a class="link" href="ref-variables-glos.html#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>), + and how you want your host machine to use resources + (<a class="link" href="ref-variables-glos.html#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS"><code class="filename">BB_NUMBER_THREADS</code></a> and + <a class="link" href="ref-variables-glos.html#var-PARALLEL_MAKE" title="PARALLEL_MAKE"><code class="filename">PARALLEL_MAKE</code></a>). + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-sanity_info.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-sanity_info.html new file mode 100644 index 0000000000..7cb04282b9 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-sanity_info.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.4. build/conf/sanity_info</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-conf-bblayers.conf.html" title="5.2.3. build/conf/bblayers.conf"> +<link rel="next" href="structure-build-downloads.html" title="5.2.5. build/downloads/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.4. build/conf/sanity_info"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-conf-sanity_info"></a>5.2.4. <code class="filename">build/conf/sanity_info</code> +</h3></div></div></div> +<p> + This file is created during the build to indicate the state of the sanity checks. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-downloads.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-downloads.html new file mode 100644 index 0000000000..5ca90d8d8d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-downloads.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.5. build/downloads/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-conf-sanity_info.html" title="5.2.4. build/conf/sanity_info"> +<link rel="next" href="structure-build-sstate-cache.html" title="5.2.6. build/sstate-cache/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.5. build/downloads/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-downloads"></a>5.2.5. <code class="filename">build/downloads/</code> +</h3></div></div></div> +<p> + This directory is used for the upstream source tarballs. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-pseudodone.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-pseudodone.html new file mode 100644 index 0000000000..74f4cd4a90 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-pseudodone.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.1. build/pseudodone</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="next" href="structure-build-conf-local.conf.html" title="5.2.2. build/conf/local.conf"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.1. build/pseudodone"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-pseudodone"></a>5.2.1. <code class="filename">build/pseudodone</code> +</h3></div></div></div> +<p> + This tag file indicates that the initial pseudo binary was created. + The file is built the first time BitBake is invoked. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-sstate-cache.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-sstate-cache.html new file mode 100644 index 0000000000..f1cb3d291b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-sstate-cache.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.6. build/sstate-cache/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-downloads.html" title="5.2.5. build/downloads/"> +<link rel="next" href="structure-build-tmp.html" title="5.2.7. build/tmp/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.6. build/sstate-cache/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-sstate-cache"></a>5.2.6. <code class="filename">build/sstate-cache/</code> +</h3></div></div></div> +<p> + This directory is used for the shared state cache. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-buildstats.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-buildstats.html new file mode 100644 index 0000000000..c1ad81c98a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-buildstats.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.8. build/tmp/buildstats/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp.html" title="5.2.7. build/tmp/"> +<link rel="next" href="structure-build-tmp-cache.html" title="5.2.9. build/tmp/cache/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.8. build/tmp/buildstats/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-buildstats"></a>5.2.8. <code class="filename">build/tmp/buildstats/</code> +</h3></div></div></div> +<p> + This directory stores the build statistics. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-cache.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-cache.html new file mode 100644 index 0000000000..d18f201c6c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-cache.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.9. build/tmp/cache/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-buildstats.html" title="5.2.8. build/tmp/buildstats/"> +<link rel="next" href="structure-build-tmp-deploy.html" title="5.2.10. build/tmp/deploy/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.9. build/tmp/cache/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-cache"></a>5.2.9. <code class="filename">build/tmp/cache/</code> +</h3></div></div></div> +<p> + When BitBake parses the metadata, it creates a cache file of the result that can + be used when subsequently running commands. + These results are stored here on a per-machine basis. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-deb.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-deb.html new file mode 100644 index 0000000000..42647f54d0 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-deb.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.11. build/tmp/deploy/deb/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-deploy.html" title="5.2.10. build/tmp/deploy/"> +<link rel="next" href="structure-build-tmp-deploy-rpm.html" title="5.2.12. build/tmp/deploy/rpm/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.11. build/tmp/deploy/deb/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-deploy-deb"></a>5.2.11. <code class="filename">build/tmp/deploy/deb/</code> +</h3></div></div></div> +<p> + This directory receives any <code class="filename">.deb</code> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-images.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-images.html new file mode 100644 index 0000000000..b2810d2a76 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-images.html @@ -0,0 +1,44 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.14. build/tmp/deploy/images/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-deploy-licenses.html" title="5.2.13. build/tmp/deploy/licenses/"> +<link rel="next" href="structure-build-tmp-deploy-ipk.html" title="5.2.15. build/tmp/deploy/ipk/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.14. build/tmp/deploy/images/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-deploy-images"></a>5.2.14. <code class="filename">build/tmp/deploy/images/</code> +</h3></div></div></div> +<p> + This directory receives complete filesystem images. + If you want to flash the resulting image from a build onto a device, look here for the image. + </p> +<p> + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>, + etc.). + However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.), + bootloader and other supplementary files might be deployed here prior to building an + image. + Because these files, however, are not directly produced from the image, if you + delete them they will not be automatically re-created when you build the image again. + </p> +<p> + If you do accidentally delete files here, you will need to force them to be + re-created. + In order to do that, you will need to know the target that produced them. + For example, these commands rebuild and re-create the kernel files: + </p> +<pre class="literallayout"> + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-ipk.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-ipk.html new file mode 100644 index 0000000000..9975833326 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-ipk.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.15. build/tmp/deploy/ipk/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-deploy-images.html" title="5.2.14. build/tmp/deploy/images/"> +<link rel="next" href="structure-build-tmp-sysroots.html" title="5.2.16. build/tmp/sysroots/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.15. build/tmp/deploy/ipk/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-deploy-ipk"></a>5.2.15. <code class="filename">build/tmp/deploy/ipk/</code> +</h3></div></div></div> +<p> + This directory receives <code class="filename">.ipk</code> packages produced by + the build process.</p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-licenses.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-licenses.html new file mode 100644 index 0000000000..b3ec898551 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-licenses.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.13. build/tmp/deploy/licenses/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-deploy-rpm.html" title="5.2.12. build/tmp/deploy/rpm/"> +<link rel="next" href="structure-build-tmp-deploy-images.html" title="5.2.14. build/tmp/deploy/images/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.13. build/tmp/deploy/licenses/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-deploy-licenses"></a>5.2.13. <code class="filename">build/tmp/deploy/licenses/</code> +</h3></div></div></div> +<p> + This directory receives package licensing information. + For example, the directory contains sub-directories for <code class="filename">bash</code>, + <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn + contain appropriate <code class="filename">COPYING</code> license files with other licensing information. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-rpm.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-rpm.html new file mode 100644 index 0000000000..1579e1131e --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-rpm.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.12. build/tmp/deploy/rpm/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-deploy-deb.html" title="5.2.11. build/tmp/deploy/deb/"> +<link rel="next" href="structure-build-tmp-deploy-licenses.html" title="5.2.13. build/tmp/deploy/licenses/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.12. build/tmp/deploy/rpm/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-deploy-rpm"></a>5.2.12. <code class="filename">build/tmp/deploy/rpm/</code> +</h3></div></div></div> +<p> + This directory receives any <code class="filename">.rpm</code> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy.html new file mode 100644 index 0000000000..b50f20802f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.10. build/tmp/deploy/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-cache.html" title="5.2.9. build/tmp/cache/"> +<link rel="next" href="structure-build-tmp-deploy-deb.html" title="5.2.11. build/tmp/deploy/deb/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.10. build/tmp/deploy/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-deploy"></a>5.2.10. <code class="filename">build/tmp/deploy/</code> +</h3></div></div></div> +<p> + This directory contains any 'end result' output from the OpenEmbedded build process. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-log.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-log.html new file mode 100644 index 0000000000..bd7f7053cf --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-log.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.18. build/tmp/log/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-stamps.html" title="5.2.17. build/tmp/stamps/"> +<link rel="next" href="structure-build-tmp-pkgdata.html" title="5.2.19. build/tmp/pkgdata/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.18. build/tmp/log/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-log"></a>5.2.18. <code class="filename">build/tmp/log/</code> +</h3></div></div></div> +<p> + This directory contains general logs that are not otherwise placed using the + package's <code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>. + Examples of logs are the output from the <code class="filename">check_pkg</code> or + <code class="filename">distro_check</code> tasks. + Running a build does not necessarily mean this directory is created. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-pkgdata.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-pkgdata.html new file mode 100644 index 0000000000..2fdad1ee31 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-pkgdata.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.19. build/tmp/pkgdata/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-log.html" title="5.2.18. build/tmp/log/"> +<link rel="next" href="structure-build-tmp-work.html" title="5.2.20. build/tmp/work/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.19. build/tmp/pkgdata/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-pkgdata"></a>5.2.19. <code class="filename">build/tmp/pkgdata/</code> +</h3></div></div></div> +<p> + This directory contains intermediate packaging data that is used later in the packaging process. + For more information, see the "<a class="link" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-stamps.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-stamps.html new file mode 100644 index 0000000000..a6f77c8ff3 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-stamps.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.17. build/tmp/stamps/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-sysroots.html" title="5.2.16. build/tmp/sysroots/"> +<link rel="next" href="structure-build-tmp-log.html" title="5.2.18. build/tmp/log/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.17. build/tmp/stamps/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-stamps"></a>5.2.17. <code class="filename">build/tmp/stamps/</code> +</h3></div></div></div> +<p> + This directory holds information that that BitBake uses for accounting purposes + to track what tasks have run and when they have run. + The directory is sub-divided by architecture. + The files in the directory are empty of data. + However, BitBake uses the filenames and timestamps for tracking purposes. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-sysroots.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-sysroots.html new file mode 100644 index 0000000000..10a74d805e --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-sysroots.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.16. build/tmp/sysroots/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-deploy-ipk.html" title="5.2.15. build/tmp/deploy/ipk/"> +<link rel="next" href="structure-build-tmp-stamps.html" title="5.2.17. build/tmp/stamps/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.16. build/tmp/sysroots/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-sysroots"></a>5.2.16. <code class="filename">build/tmp/sysroots/</code> +</h3></div></div></div> +<p> + This directory contains shared header files and libraries as well as other shared + data. + Packages that need to share output with other packages do so within this directory. + The directory is subdivided by architecture so multiple builds can run within + the one Build Directory. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-work.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-work.html new file mode 100644 index 0000000000..aa78c18b5d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-work.html @@ -0,0 +1,52 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.20. build/tmp/work/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-tmp-pkgdata.html" title="5.2.19. build/tmp/pkgdata/"> +<link rel="next" href="structure-meta.html" title="5.3. The Metadata - meta/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.20. build/tmp/work/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp-work"></a>5.2.20. <code class="filename">build/tmp/work/</code> +</h3></div></div></div> +<p> + This directory contains architecture-specific work sub-directories for packages built by BitBake. + All tasks execute from a work directory. + For example, the source for a particular package is unpacked, patched, configured and compiled all + within its own work directory. + Within the work directory, organization is based on the package group for which the source + is being compiled. + </p> +<p> + It is worth considering the structure of a typical work directory. + As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code> + on the machine <code class="filename">qemux86</code> + built within the Yocto Project. + For this package, a work directory of + <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+<.....></code>, + referred to as <code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created. + Within this directory, the source is unpacked to + <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt + (see the + "<a class="link" href="../dev-manual/using-a-quilt-workflow.html" target="_self">Modifying Package + Source Code with Quilt</a>" section in the Yocto Project Development Manual. + Within the <code class="filename">linux-qemux86-standard-build</code> directory, + standard Quilt directories <code class="filename">linux-3.0/patches</code> + and <code class="filename">linux-3.0/.pc</code> are created, + and standard Quilt commands can be used. + </p> +<p> + There are other directories generated within WORKDIR. + The most important directory is WORKDIR<code class="filename">/temp/</code>, which has log files for each + task (<code class="filename">log.do_*.pid</code>) and contains the scripts BitBake runs for + each task (<code class="filename">run.do_*.pid</code>). + The WORKDIR<code class="filename">/image/</code> directory is where "make + install" places its output that is then split into sub-packages + within WORKDIR<code class="filename">/packages-split/</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp.html new file mode 100644 index 0000000000..216d255c78 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp.html @@ -0,0 +1,26 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2.7. build/tmp/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/"> +<link rel="prev" href="structure-build-sstate-cache.html" title="5.2.6. build/sstate-cache/"> +<link rel="next" href="structure-build-tmp-buildstats.html" title="5.2.8. build/tmp/buildstats/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.7. build/tmp/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-build-tmp"></a>5.2.7. <code class="filename">build/tmp/</code> +</h3></div></div></div> +<p> + This directory receives all the OpenEmbedded build system's output. + BitBake creates this directory if it does not exist. + As a last resort, to clean up a build and start it from scratch (other than the downloads), + you can remove everything in the <code class="filename">tmp</code> directory or get rid of the + directory completely. + If you do, you should also completely remove the <code class="filename">build/sstate-cache</code> + directory as well. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build.html new file mode 100644 index 0000000000..c3b9ae5054 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build.html @@ -0,0 +1,15 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.2. The Build Directory - build/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-structure.html" title="Chapter 5. Source Directory Structure"> +<link rel="prev" href="structure-basic-top-level.html" title="5.1.11. LICENSE, README, and README.hardware"> +<link rel="next" href="structure-build-pseudodone.html" title="5.2.1. build/pseudodone"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2. The Build Directory - build/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="structure-build"></a>5.2. The Build Directory - <code class="filename">build/</code> +</h2></div></div></div></div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-bitbake.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-bitbake.html new file mode 100644 index 0000000000..aca036d970 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-bitbake.html @@ -0,0 +1,40 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.1. bitbake/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core.html" title="5.1. Top level core components"> +<link rel="next" href="structure-core-build.html" title="5.1.2. build/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.1. bitbake/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-bitbake"></a>5.1.1. <code class="filename">bitbake/</code> +</h3></div></div></div> +<p> + The <a class="ulink" href="source-directory" target="_self">Source Directory</a> + includes a copy of BitBake for ease of use. + The copy usually matches the current stable BitBake release from the BitBake project. + BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks + defined by that data. + Failures are usually from the metadata and not from BitBake itself. + Consequently, most users do not need to worry about BitBake. + </p> +<p> + When you run the <code class="filename">bitbake</code> command, the wrapper script in + <code class="filename">scripts/</code> is executed to run the main BitBake executable, + which resides in the <code class="filename">bitbake/bin/</code> directory. + Sourcing the <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">oe-init-build-env</a> + script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code> + directories (in that order) into the shell's <code class="filename">PATH</code> environment + variable. + </p> +<p> + For more information on BitBake, see the BitBake documentation + inculded in the <code class="filename">bitbake/doc/manual</code> directory of the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-build.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-build.html new file mode 100644 index 0000000000..23f5549b5b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-build.html @@ -0,0 +1,33 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.2. build/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-bitbake.html" title="5.1.1. bitbake/"> +<link rel="next" href="handbook.html" title="5.1.3. documentation"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.2. build/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-build"></a>5.1.2. <code class="filename">build/</code> +</h3></div></div></div> +<p> + This directory contains user configuration files and the output + generated by the OpenEmbedded build system in its standard configuration where + the source tree is combined with the output. + The <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> + is created initially when you <code class="filename">source</code> + the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>. + </p> +<p> + It is also possible to place output and configuration + files in a directory separate from the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> + by providing a directory name when you <code class="filename">source</code> + the setup script. + For information on separating output from your local Source Directory files, see <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">oe-init-build-env</a>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto-bsp.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto-bsp.html new file mode 100644 index 0000000000..29eff27053 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto-bsp.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.6. meta-yocto-bsp/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-meta-yocto.html" title="5.1.5. meta-yocto/"> +<link rel="next" href="structure-meta-hob.html" title="5.1.7. meta-hob/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.6. meta-yocto-bsp/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-meta-yocto-bsp"></a>5.1.6. <code class="filename">meta-yocto-bsp/</code> +</h3></div></div></div> +<p> + This directory contains the Yocto Project reference + hardware BSPs. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto.html new file mode 100644 index 0000000000..e9a8e8e56b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.5. meta-yocto/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-meta.html" title="5.1.4. meta/"> +<link rel="next" href="structure-core-meta-yocto-bsp.html" title="5.1.6. meta-yocto-bsp/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.5. meta-yocto/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-meta-yocto"></a>5.1.5. <code class="filename">meta-yocto/</code> +</h3></div></div></div> +<p> + This directory contains the configuration for the Poky + reference distribution. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta.html new file mode 100644 index 0000000000..9a7cee2c13 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.4. meta/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="handbook.html" title="5.1.3. documentation"> +<link rel="next" href="structure-core-meta-yocto.html" title="5.1.5. meta-yocto/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.4. meta/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-meta"></a>5.1.4. <code class="filename">meta/</code> +</h3></div></div></div> +<p> + This directory contains the OpenEmbedded Core metadata. + The directory holds recipes, common classes, and machine + configuration for emulated targets (qemux86, qemuarm, + and so on.) + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-script.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-script.html new file mode 100644 index 0000000000..64266a9482 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-script.html @@ -0,0 +1,53 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.10. oe-init-build-env</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-scripts.html" title="5.1.9. scripts/"> +<link rel="next" href="structure-basic-top-level.html" title="5.1.11. LICENSE, README, and README.hardware"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.10. oe-init-build-env"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-script"></a>5.1.10. <code class="filename">oe-init-build-env</code> +</h3></div></div></div> +<p> + This script sets up the OpenEmbedded build environment. + Running this script with the <code class="filename">source</code> command in + a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the + current working directory. + You need to run this script before running BitBake commands. + The script uses other scripts within the <code class="filename">scripts</code> directory to do + the bulk of the work. + </p> +<p> + By default, running this script without a Build Directory argument creates the + <code class="filename">build</code> directory. + If you provide a Build Directory argument when you <code class="filename">source</code> + the script, you direct OpenEmbedded build system to create a + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> of your choice. + For example, the following command creates a Build Directory named + <code class="filename">mybuilds</code> that is outside of the + <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>: + </p> +<pre class="literallayout"> + $ source oe-init-build-env ~/mybuilds + </pre> +<p> + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3> + The OpenEmbedded build system does not support file or directory names that + contain spaces. + If you attempt to run the <code class="filename">oe-init-build-env</code> script + from a Source Directory that contains spaces in either the filenames + or directory names, the script returns an error indicating no such + file or directory. + Be sure to use a Source Directory free of names containing spaces. + </div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-scripts.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-scripts.html new file mode 100644 index 0000000000..6bc3bed649 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-scripts.html @@ -0,0 +1,28 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.9. scripts/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-meta-skeleton.html" title="5.1.8. meta-skeleton/"> +<link rel="next" href="structure-core-script.html" title="5.1.10. oe-init-build-env"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.9. scripts/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-core-scripts"></a>5.1.9. <code class="filename">scripts/</code> +</h3></div></div></div> +<p> + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">oe-init-build-env</a> script appends this + directory to the shell's <code class="filename">PATH</code> environment variable. + </p> +<p> + The <code class="filename">scripts</code> directory has useful scripts that assist contributing + back to the Yocto Project, such as <code class="filename">create_pull_request</code> and + <code class="filename">send_pull_request</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core.html new file mode 100644 index 0000000000..51b6994b08 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core.html @@ -0,0 +1,14 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1. Top level core components</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-structure.html" title="Chapter 5. Source Directory Structure"> +<link rel="prev" href="ref-structure.html" title="Chapter 5. Source Directory Structure"> +<link rel="next" href="structure-core-bitbake.html" title="5.1.1. bitbake/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1. Top level core components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="structure-core"></a>5.1. Top level core components</h2></div></div></div></div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-classes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-classes.html new file mode 100644 index 0000000000..34cc0ffe32 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-classes.html @@ -0,0 +1,30 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.1. meta/classes/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="next" href="structure-meta-conf.html" title="5.3.2. meta/conf/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.1. meta/classes/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-classes"></a>5.3.1. <code class="filename">meta/classes/</code> +</h3></div></div></div> +<p> + This directory contains the <code class="filename">*.bbclass</code> files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the <code class="filename">base.bbclass</code> file. + Examples of other important classes are <code class="filename">autotools.bbclass</code>, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions + for working with the Linux kernel. + Functions like image generation or packaging also have their specific class files + such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and + <code class="filename">package*.bbclass</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-distro.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-distro.html new file mode 100644 index 0000000000..b8b4fe0c01 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-distro.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.4. meta/conf/distro/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-conf-machine.html" title="5.3.3. meta/conf/machine/"> +<link rel="next" href="structure-meta-recipes-bsp.html" title="5.3.5. meta/recipes-bsp/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.4. meta/conf/distro/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-conf-distro"></a>5.3.4. <code class="filename">meta/conf/distro/</code> +</h3></div></div></div> +<p> + Any distribution-specific configuration is controlled from this directory. + For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here. + This directory includes the versions and the + <code class="filename">SRCDATE</code> definitions for applications that are configured here. + An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>. + Although this file mainly inherits its configuration from Poky. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-machine.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-machine.html new file mode 100644 index 0000000000..80ccb8dedc --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-machine.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.3. meta/conf/machine/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-conf.html" title="5.3.2. meta/conf/"> +<link rel="next" href="structure-meta-conf-distro.html" title="5.3.4. meta/conf/distro/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.3. meta/conf/machine/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-conf-machine"></a>5.3.3. <code class="filename">meta/conf/machine/</code> +</h3></div></div></div> +<p> + This directory contains all the machine configuration files. + If you set <code class="filename">MACHINE="qemux86"</code>, + the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this + directory. + The <code class="filename">include</code> directory contains various data common to multiple machines. + If you want to add support for a new machine to the Yocto Project, look in this directory. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf.html new file mode 100644 index 0000000000..da88f4b111 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf.html @@ -0,0 +1,27 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.2. meta/conf/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-classes.html" title="5.3.1. meta/classes/"> +<link rel="next" href="structure-meta-conf-machine.html" title="5.3.3. meta/conf/machine/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.2. meta/conf/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-conf"></a>5.3.2. <code class="filename">meta/conf/</code> +</h3></div></div></div> +<p> + This directory contains the core set of configuration files that start from + <code class="filename">bitbake.conf</code> and from which all other configuration + files are included. + See the include statements at the end of the file and you will note that even + <code class="filename">local.conf</code> is loaded from there. + While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override + these by using the (<code class="filename">local.conf</code>) file, machine file or + the distribution configuration file. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-hob.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-hob.html new file mode 100644 index 0000000000..a8fb22fc08 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-hob.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.7. meta-hob/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-core-meta-yocto-bsp.html" title="5.1.6. meta-yocto-bsp/"> +<link rel="next" href="structure-meta-skeleton.html" title="5.1.8. meta-skeleton/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.7. meta-hob/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-hob"></a>5.1.7. <code class="filename">meta-hob/</code> +</h3></div></div></div> +<p> + This directory contains template recipes used by the + <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_self">Hob</a> + build UI. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-bsp.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-bsp.html new file mode 100644 index 0000000000..7adf2d392c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-bsp.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.5. meta/recipes-bsp/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-conf-distro.html" title="5.3.4. meta/conf/distro/"> +<link rel="next" href="structure-meta-recipes-connectivity.html" title="5.3.6. meta/recipes-connectivity/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.5. meta/recipes-bsp/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-bsp"></a>5.3.5. <code class="filename">meta/recipes-bsp/</code> +</h3></div></div></div> +<p> + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-connectivity.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-connectivity.html new file mode 100644 index 0000000000..112544e110 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-connectivity.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.6. meta/recipes-connectivity/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-bsp.html" title="5.3.5. meta/recipes-bsp/"> +<link rel="next" href="structure-meta-recipes-core.html" title="5.3.7. meta/recipes-core/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.6. meta/recipes-connectivity/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-connectivity"></a>5.3.6. <code class="filename">meta/recipes-connectivity/</code> +</h3></div></div></div> +<p> + This directory contains libraries and applications related to communication with other devices. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-core.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-core.html new file mode 100644 index 0000000000..bd0542eb92 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-core.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.7. meta/recipes-core/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-connectivity.html" title="5.3.6. meta/recipes-connectivity/"> +<link rel="next" href="structure-meta-recipes-devtools.html" title="5.3.8. meta/recipes-devtools/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.7. meta/recipes-core/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-core"></a>5.3.7. <code class="filename">meta/recipes-core/</code> +</h3></div></div></div> +<p> + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-devtools.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-devtools.html new file mode 100644 index 0000000000..25a38d9f01 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-devtools.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.8. meta/recipes-devtools/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-core.html" title="5.3.7. meta/recipes-core/"> +<link rel="next" href="structure-meta-recipes-extended.html" title="5.3.9. meta/recipes-extended/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.8. meta/recipes-devtools/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-devtools"></a>5.3.8. <code class="filename">meta/recipes-devtools/</code> +</h3></div></div></div> +<p> + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-extended.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-extended.html new file mode 100644 index 0000000000..b5506ff651 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-extended.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.9. meta/recipes-extended/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-devtools.html" title="5.3.8. meta/recipes-devtools/"> +<link rel="next" href="structure-meta-recipes-gnome.html" title="5.3.10. meta/recipes-gnome/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.9. meta/recipes-extended/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-extended"></a>5.3.9. <code class="filename">meta/recipes-extended/</code> +</h3></div></div></div> +<p> + This directory contains non-essential applications that add features compared to the + alternatives in core. + You might need this directory for full tool functionality or for Linux Standard Base (LSB) + compliance. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-gnome.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-gnome.html new file mode 100644 index 0000000000..769447f2ff --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-gnome.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.10. meta/recipes-gnome/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-extended.html" title="5.3.9. meta/recipes-extended/"> +<link rel="next" href="structure-meta-recipes-graphics.html" title="5.3.11. meta/recipes-graphics/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.10. meta/recipes-gnome/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-gnome"></a>5.3.10. <code class="filename">meta/recipes-gnome/</code> +</h3></div></div></div> +<p> + This directory contains all things related to the GTK+ application framework. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-graphics.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-graphics.html new file mode 100644 index 0000000000..7a0a3e4253 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-graphics.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.11. meta/recipes-graphics/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-gnome.html" title="5.3.10. meta/recipes-gnome/"> +<link rel="next" href="structure-meta-recipes-kernel.html" title="5.3.12. meta/recipes-kernel/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.11. meta/recipes-graphics/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-graphics"></a>5.3.11. <code class="filename">meta/recipes-graphics/</code> +</h3></div></div></div> +<p> + This directory contains X and other graphically related system libraries + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-kernel.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-kernel.html new file mode 100644 index 0000000000..1cb7a06f81 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-kernel.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.12. meta/recipes-kernel/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-graphics.html" title="5.3.11. meta/recipes-graphics/"> +<link rel="next" href="structure-meta-recipes-multimedia.html" title="5.3.13. meta/recipes-multimedia/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.12. meta/recipes-kernel/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-kernel"></a>5.3.12. <code class="filename">meta/recipes-kernel/</code> +</h3></div></div></div> +<p> + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-multimedia.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-multimedia.html new file mode 100644 index 0000000000..08c9f3cda9 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-multimedia.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.13. meta/recipes-multimedia/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-kernel.html" title="5.3.12. meta/recipes-kernel/"> +<link rel="next" href="structure-meta-recipes-qt.html" title="5.3.14. meta/recipes-qt/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.13. meta/recipes-multimedia/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-multimedia"></a>5.3.13. <code class="filename">meta/recipes-multimedia/</code> +</h3></div></div></div> +<p> + This directory contains codecs and support utilities for audio, images and video. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-qt.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-qt.html new file mode 100644 index 0000000000..bb6eca2742 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-qt.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.14. meta/recipes-qt/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-multimedia.html" title="5.3.13. meta/recipes-multimedia/"> +<link rel="next" href="structure-meta-recipes-rt.html" title="5.3.15. meta/recipes-rt/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.14. meta/recipes-qt/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-qt"></a>5.3.14. <code class="filename">meta/recipes-qt/</code> +</h3></div></div></div> +<p> + This directory contains all things related to the Qt application framework. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-rt.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-rt.html new file mode 100644 index 0000000000..249e442891 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-rt.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.15. meta/recipes-rt/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-qt.html" title="5.3.14. meta/recipes-qt/"> +<link rel="next" href="structure-meta-recipes-sato.html" title="5.3.16. meta/recipes-sato/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.15. meta/recipes-rt/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-rt"></a>5.3.15. <code class="filename">meta/recipes-rt/</code> +</h3></div></div></div> +<p> + This directory contains package and image recipes for using and testing + the <code class="filename">PREEMPT_RT</code> kernel. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-sato.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-sato.html new file mode 100644 index 0000000000..d6a27ffb4f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-sato.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.16. meta/recipes-sato/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-rt.html" title="5.3.15. meta/recipes-rt/"> +<link rel="next" href="structure-meta-recipes-support.html" title="5.3.17. meta/recipes-support/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.16. meta/recipes-sato/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-sato"></a>5.3.16. <code class="filename">meta/recipes-sato/</code> +</h3></div></div></div> +<p> + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-support.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-support.html new file mode 100644 index 0000000000..7e152acfa2 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-support.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.17. meta/recipes-support/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-sato.html" title="5.3.16. meta/recipes-sato/"> +<link rel="next" href="structure-meta-site.html" title="5.3.18. meta/site/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.17. meta/recipes-support/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-support"></a>5.3.17. <code class="filename">meta/recipes-support/</code> +</h3></div></div></div> +<p> + This directory contains recipes that used by other recipes, but that are not directly + included in images (i.e. dependencies of other recipes). + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-txt.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-txt.html new file mode 100644 index 0000000000..42bb7a678d --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-txt.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.19. meta/recipes.txt</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-site.html" title="5.3.18. meta/site/"> +<link rel="next" href="ref-bitbake.html" title="Chapter 6. BitBake"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.19. meta/recipes.txt"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-recipes-txt"></a>5.3.19. <code class="filename">meta/recipes.txt</code> +</h3></div></div></div> +<p> + This file is a description of the contents of <code class="filename">recipes-*</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-site.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-site.html new file mode 100644 index 0000000000..567eec8221 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-site.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3.18. meta/site/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/"> +<link rel="prev" href="structure-meta-recipes-support.html" title="5.3.17. meta/recipes-support/"> +<link rel="next" href="structure-meta-recipes-txt.html" title="5.3.19. meta/recipes.txt"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.18. meta/site/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-site"></a>5.3.18. <code class="filename">meta/site/</code> +</h3></div></div></div> +<p> + This directory contains a list of cached results for various architectures. + Because certain "autoconf" test results cannot be determined when cross-compiling due to + the tests not able to run on a live system, the information in this directory is + passed to "autoconf" for the various architectures. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-skeleton.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-skeleton.html new file mode 100644 index 0000000000..b67bb60e48 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-skeleton.html @@ -0,0 +1,20 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.1.8. meta-skeleton/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="structure-core.html" title="5.1. Top level core components"> +<link rel="prev" href="structure-meta-hob.html" title="5.1.7. meta-hob/"> +<link rel="next" href="structure-core-scripts.html" title="5.1.9. scripts/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.8. meta-skeleton/"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="structure-meta-skeleton"></a>5.1.8. <code class="filename">meta-skeleton/</code> +</h3></div></div></div> +<p> + This directory contains template recipes for BSP and kernel development. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta.html new file mode 100644 index 0000000000..7f132b54fb --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta.html @@ -0,0 +1,21 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>5.3. The Metadata - meta/</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="ref-structure.html" title="Chapter 5. Source Directory Structure"> +<link rel="prev" href="structure-build-tmp-work.html" title="5.2.20. build/tmp/work/"> +<link rel="next" href="structure-meta-classes.html" title="5.3.1. meta/classes/"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3. The Metadata - meta/"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="structure-meta"></a>5.3. The Metadata - <code class="filename">meta/</code> +</h2></div></div></div> +<p> + As mentioned previously, metadata is the core of the Yocto Project. + Metadata has several important subdivisions: + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/support.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/support.html new file mode 100644 index 0000000000..4e0a1efb0f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/support.html @@ -0,0 +1,34 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.3.1. Support</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="x32.html" title="3.3. x32"> +<link rel="prev" href="x32.html" title="3.3. x32"> +<link rel="next" href="future-development-and-limitations.html" title="3.3.2. Future Development and Limitations"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.1. Support"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="support"></a>3.3.1. Support</h3></div></div></div> +<p> + While the x32 psABI specifications are not fully finalized, this Yocto Project + release supports current development specifications of x32 psABI. + As of this release of the Yocto Project, x32 psABI support exists as follows: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets. + </p></li> +<li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code> + layer on top of the OE-core/Yocto layer.</p></li> +<li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer + is used for building x32 psABI program binaries.</p></li> +<li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li> +<li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and + <code class="filename">core-image-sato</code> images.</p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/technical-details.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/technical-details.html new file mode 100644 index 0000000000..1a54121c49 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/technical-details.html @@ -0,0 +1,50 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 3. Technical Details</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="examining-build-history-information.html" title="2.4.2.4. Examining Build History Information"> +<link rel="next" href="usingpoky-components.html" title="3.1. Yocto Project Components"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 3. Technical Details"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="usingpoky-components.html">3.1. Yocto Project Components</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-components-bitbake.html">3.1.1. BitBake</a></span></dt> +<dt><span class="section"><a href="usingpoky-components-metadata.html">3.1.2. Metadata (Recipes)</a></span></dt> +<dt><span class="section"><a href="usingpoky-components-classes.html">3.1.3. Classes</a></span></dt> +<dt><span class="section"><a href="usingpoky-components-configuration.html">3.1.4. Configuration</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="shared-state-cache.html">3.2. Shared State Cache</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="overall-architecture.html">3.2.1. Overall Architecture</a></span></dt> +<dt><span class="section"><a href="checksums.html">3.2.2. Checksums (Signatures)</a></span></dt> +<dt><span class="section"><a href="shared-state.html">3.2.3. Shared State</a></span></dt> +<dt><span class="section"><a href="tips-and-tricks.html">3.2.4. Tips and Tricks</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="x32.html">3.3. x32</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="support.html">3.3.1. Support</a></span></dt> +<dt><span class="section"><a href="future-development-and-limitations.html">3.3.2. Future Development and Limitations</a></span></dt> +<dt><span class="section"><a href="using-x32-right-now.html">3.3.3. Using x32 Right Now</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="licenses.html">3.4. Licenses</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-configuring-LIC_FILES_CHKSUM.html">3.4.1. Tracking License Changes</a></span></dt> +<dt><span class="section"><a href="enabling-commercially-licensed-recipes.html">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt> +</dl></dd> +</dl> +</div> +<p> + This chapter provides technical details for various parts of the Yocto Project. + Currently, topics include Yocto Project components and shared state (sstate) cache. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/tips-and-tricks.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/tips-and-tricks.html new file mode 100644 index 0000000000..78773b954a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/tips-and-tricks.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.2.4. Tips and Tricks</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache"> +<link rel="prev" href="shared-state.html" title="3.2.3. Shared State"> +<link rel="next" href="debugging.html" title="3.2.4.1. Debugging"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.4. Tips and Tricks"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div> +<p> + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/ubuntu-packages.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/ubuntu-packages.html new file mode 100644 index 0000000000..63c0118692 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/ubuntu-packages.html @@ -0,0 +1,60 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>1.3.2.1. Ubuntu</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System"> +<link rel="prev" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System"> +<link rel="next" href="fedora-packages.html" title="1.3.2.2. Fedora Packages"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.1. Ubuntu"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="ubuntu-packages"></a>1.3.2.1. Ubuntu</h4></div></div></div> +<p> + The following list shows the required packages by function + given a supported Ubuntu Linux distribution: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> +<p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image on a headless + system: + </p> +<pre class="literallayout"> + $ sudo apt-get install gawk wget git-core diffstat unzip texinfo \ + build-essential chrpath + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p> +<pre class="literallayout"> + $ sudo apt-get install libsdl1.2-dev xterm + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p> +<pre class="literallayout"> + $ sudo apt-get install make xsltproc docbook-utils fop + </pre> +</li> +<li class="listitem"> +<p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>: + </p> +<pre class="literallayout"> + $ sudo apt-get install autoconf automake libtool libglib2.0-dev + </pre> +</li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/understanding-what-the-build-history-contains.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/understanding-what-the-build-history-contains.html new file mode 100644 index 0000000000..cdaa962f57 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/understanding-what-the-build-history-contains.html @@ -0,0 +1,25 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4.2. Understanding What the Build History Contains</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality"> +<link rel="prev" href="enabling-and-disabling-build-history.html" title="2.4.1. Enabling and Disabling Build History"> +<link rel="next" href="build-history-package-information.html" title="2.4.2.1. Build History Package Information"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2. Understanding What the Build History Contains"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="understanding-what-the-build-history-contains"></a>2.4.2. Understanding What the Build History Contains</h3></div></div></div> +<p> + Build history information is kept in + <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">$TMPDIR</code></a><code class="filename">/buildhistory</code> + in the Build Directory. + The following is an example abbreviated listing: + </p> +<table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/buildhistory.png" align="middle" width="540"></td></tr></table> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/using-build-history-to-gather-image-information-only.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/using-build-history-to-gather-image-information-only.html new file mode 100644 index 0000000000..26c2a4d080 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/using-build-history-to-gather-image-information-only.html @@ -0,0 +1,34 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.4.2.3. Using Build History to Gather Image Information Only</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains"> +<link rel="prev" href="build-history-image-information.html" title="2.4.2.2. Build History Image Information"> +<link rel="next" href="examining-build-history-information.html" title="2.4.2.4. Examining Build History Information"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.3. Using Build History to Gather Image Information Only"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="using-build-history-to-gather-image-information-only"></a>2.4.2.3. Using Build History to Gather Image Information Only</h4></div></div></div> +<p> + 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 history or any package information, + you can enable writing only image information without + any history by adding the following + to your <code class="filename">conf/local.conf</code> file found in the + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>: + </p> +<pre class="literallayout"> + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "0" + BUILDHISTORY_FEATURES = "image" + </pre> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/using-x32-right-now.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/using-x32-right-now.html new file mode 100644 index 0000000000..614b31ddaa --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/using-x32-right-now.html @@ -0,0 +1,70 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.3.3. Using x32 Right Now</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="x32.html" title="3.3. x32"> +<link rel="prev" href="future-development-and-limitations.html" title="3.3.2. Future Development and Limitations"> +<link rel="next" href="licenses.html" title="3.4. Licenses"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.3. Using x32 Right Now"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div> +<p> + Despite the fact the x32 psABI support is in development state for this release of the + Yocto Project, you can follow these steps to use the x32 spABI: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>. + You can find the <code class="filename">experimental/meta-x32</code> source repository at + <a class="ulink" href="http://git.yoctoproject.org" target="_self">http://git.yoctoproject.org</a>.</p></li> +<li class="listitem"> +<p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes + the <code class="filename">meta-x32</code>. + Here is an example: + </p> +<pre class="literallayout"> + BBLAYERS ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + /home/nitin/prj/poky.git/meta-yocto-bsp \ + /home/nitin/prj/meta-x32.git \ + " + </pre> +</li> +<li class="listitem"> +<p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code> + machines by editing the <code class="filename">conf/local.conf</code> like this: + </p> +<pre class="literallayout"> + MACHINE = "qemux86-64" + DEFAULTTUNE = "x86-64-x32" + baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ + or 'INVALID'), True) or 'lib'}" + #MACHINE = "atom-pc" + #DEFAULTTUNE = "core2-64-x32" + </pre> +</li> +<li class="listitem"> +<p>As usual, use BitBake to build an image that supports the x32 psABI. + Here is an example: + </p> +<pre class="literallayout"> + $ bitake core-image-sato + </pre> +</li> +<li class="listitem"> +<p>As usual, run your image using QEMU: + </p> +<pre class="literallayout"> + $ runqemu qemux86-64 core-image-sato + </pre> +</li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html new file mode 100644 index 0000000000..e702578a24 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html @@ -0,0 +1,58 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4.1.2. Explanation of Syntax</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes"> +<link rel="prev" href="usingpoky-specifying-LIC_FILES_CHKSUM.html" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"> +<link rel="next" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.1.2. Explanation of Syntax"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div> +<p> + As mentioned in the previous section, the + <code class="filename">LIC_FILES_CHKSUM</code> 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. + </p> +<p> + 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. + </p> +<p> + There is no limit to how many files you can specify using the + <code class="filename">LIC_FILES_CHKSUM</code> 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. + </p> +<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Tip</h3> + 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. + </div> +<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Tip</h3> + If the whole file contains only license text, you do not need to use the "beginline" and + "endline" parameters. + </div> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-build.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-build.html new file mode 100644 index 0000000000..c1fa0e6c00 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-build.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.1. Running a Build</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project"> +<link rel="prev" href="usingpoky.html" title="Chapter 2. Using the Yocto Project"> +<link rel="next" href="build-overview.html" title="2.1.1. Build Overview"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1. Running a Build"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div> +<p> + 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 + "<a class="link" href="../yocto-project-qs/building-image.html" target="_self">Building an Image</a>" + section of the Yocto Project Quick Start. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-bitbake.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-bitbake.html new file mode 100644 index 0000000000..184ffdbd2c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-bitbake.html @@ -0,0 +1,66 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.1.1. BitBake</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components"> +<link rel="prev" href="usingpoky-components.html" title="3.1. Yocto Project Components"> +<link rel="next" href="usingpoky-components-metadata.html" title="3.1.2. Metadata (Recipes)"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.1. BitBake"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div> +<p> + BitBake is the tool at the heart of the OpenEmbedded build system and is responsible + for parsing the metadata, generating a list of tasks from it, + and then executing those tasks. + To see a list of the options BitBake supports, use the following help command: + </p> +<pre class="literallayout"> + $ bitbake --help + </pre> +<p> + </p> +<p> + The most common usage for BitBake is <code class="filename">bitbake <packagename></code>, where + <code class="filename">packagename</code> 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 <code class="filename">.bb</code> filename. + So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you + might type the following: + </p> +<pre class="literallayout"> + $ bitbake matchbox-desktop + </pre> +<p> + Several different versions of <code class="filename">matchbox-desktop</code> 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 + "<a class="link" href="ref-bitbake-providers.html" title="6.2. Preferences and Providers">Preferences and Providers</a>" section. + </p> +<p> + BitBake also tries to execute any dependent tasks first. + So for example, before building <code class="filename">matchbox-desktop</code>, BitBake + would build a cross compiler and <code class="filename">eglibc</code> if they had not already + been built. + </p> +<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code> + GNU version of the Unix standard C library. By default, the OpenEmbedded build system + builds with <code class="filename">eglibc</code>.</div> +<p> + </p> +<p> + A useful BitBake option to consider is the <code class="filename">-k</code> or + <code class="filename">--continue</code> option. + This option instructs BitBake to try and continue processing the job as much + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-classes.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-classes.html new file mode 100644 index 0000000000..92427061ea --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-classes.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.1.3. Classes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components"> +<link rel="prev" href="usingpoky-components-metadata.html" title="3.1.2. Metadata (Recipes)"> +<link rel="next" href="usingpoky-components-configuration.html" title="3.1.4. Configuration"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.3. Classes"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div> +<p> + Class files (<code class="filename">.bbclass</code>) contain information that is useful to share + between metadata files. + An example is the Autotools class, which contains + common settings for any application that Autotools uses. + The "<a class="link" href="ref-classes.html" title="Chapter 7. Classes">Classes</a>" chapter provides details + about common classes and how to use them. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-configuration.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-configuration.html new file mode 100644 index 0000000000..49e4e14649 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-configuration.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.1.4. Configuration</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components"> +<link rel="prev" href="usingpoky-components-classes.html" title="3.1.3. Classes"> +<link rel="next" href="shared-state-cache.html" title="3.2. Shared State Cache"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.4. Configuration"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div> +<p> + The configuration files (<code class="filename">.conf</code>) 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 (<code class="filename">local.conf</code>, which is found + in the <a class="ulink" href="build-directory" target="_self">Build Directory</a>). + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-metadata.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-metadata.html new file mode 100644 index 0000000000..4f73445d8f --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-metadata.html @@ -0,0 +1,29 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.1.2. Metadata (Recipes)</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components"> +<link rel="prev" href="usingpoky-components-bitbake.html" title="3.1.1. BitBake"> +<link rel="next" href="usingpoky-components-classes.html" title="3.1.3. Classes"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.2. Metadata (Recipes)"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div> +<p> + The <code class="filename">.bb</code> files are usually referred to as "recipes." + In general, a recipe contains information about a single piece of software. + The information includes the location from which to download the source patches + (if any are needed), which special configuration options to apply, + how to compile the source files, and how to package the compiled output. + </p> +<p> + The term "package" can also be used to describe recipes. + However, since the same word is used for the packaged output from the OpenEmbedded + build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files), + this document avoids using the term "package" when referring to recipes. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components.html new file mode 100644 index 0000000000..ccd3ae5fbd --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components.html @@ -0,0 +1,52 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.1. Yocto Project Components</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details"> +<link rel="prev" href="technical-details.html" title="Chapter 3. Technical Details"> +<link rel="next" href="usingpoky-components-bitbake.html" title="3.1.1. BitBake"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1. Yocto Project Components"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div> +<p> + The BitBake task executor together with various types of configuration files form the + OpenEmbedded Core. + This section overviews the BitBake task executor and the + configuration files by describing what they are used for and how they interact. + </p> +<p> + BitBake handles the parsing and execution of the data files. + The data itself is of various types: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular + pieces of software</p></li> +<li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build + information (e.g. how to build a Linux kernel).</p></li> +<li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings, + policy decisions, etc. + Configuration data acts as the glue to bind everything together.</p></li> +</ul></div> +<p> + For more information on data, see the + "<a class="link" href="../dev-manual/yocto-project-terms.html" target="_self">Yocto Project Terms</a>" + section in the Yocto Project Development Manual. + </p> +<p> + BitBake knows how to combine multiple data sources together and refers to each data source + as a layer. + For information on layers, see the + "<a class="link" href="../dev-manual/understanding-and-creating-layers.html" target="_self">Understanding and + Creating Layers</a>" section of the Yocto Project Development Manual. + </p> +<p> + Following are some brief details on these core components. + For more detailed information on these components see the + "<a class="link" href="ref-structure.html" title="Chapter 5. Source Directory Structure">Directory Structure</a>" chapter. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-configuring-LIC_FILES_CHKSUM.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-configuring-LIC_FILES_CHKSUM.html new file mode 100644 index 0000000000..ffcfd24e15 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-configuring-LIC_FILES_CHKSUM.html @@ -0,0 +1,23 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4.1. Tracking License Changes</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="licenses.html" title="3.4. Licenses"> +<link rel="prev" href="licenses.html" title="3.4. Licenses"> +<link rel="next" href="usingpoky-specifying-LIC_FILES_CHKSUM.html" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.1. Tracking License Changes"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div> +<p> + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code> + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-bitbake.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-bitbake.html new file mode 100644 index 0000000000..06a3b7f9fa --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-bitbake.html @@ -0,0 +1,30 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.4. General BitBake Problems</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging-dependencies.html" title="2.3.3. Dependency Graphs"> +<link rel="next" href="usingpoky-debugging-buildfile.html" title="2.3.5. Building with No Dependencies"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.4. General BitBake Problems"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div> +<p> + You can see debug output from BitBake by using the <code class="filename">-D</code> option. + The debug output gives more information about what BitBake + is doing and the reason behind it. + Each <code class="filename">-D</code> option you use increases the logging level. + The most common usage is <code class="filename">-DDD</code>. + </p> +<p> + The output from <code class="filename">bitbake -DDD -v targetname</code> 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-buildfile.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-buildfile.html new file mode 100644 index 0000000000..9450f1aaff --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-buildfile.html @@ -0,0 +1,24 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.5. Building with No Dependencies</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging-bitbake.html" title="2.3.4. General BitBake Problems"> +<link rel="next" href="usingpoky-debugging-variables.html" title="2.3.6. Variables"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.5. Building with No Dependencies"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div> +<p> + If you really want to build a specific <code class="filename">.bb</code> file, you can use + the command form <code class="filename">bitbake -b <somepath/somefile.bb></code>. + This command form does not check for dependencies so you should use it + only when you know its dependencies already exist. + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-dependencies.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-dependencies.html new file mode 100644 index 0000000000..c48b00e97a --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-dependencies.html @@ -0,0 +1,26 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.3. Dependency Graphs</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging-taskrunning.html" title="2.3.2. Running Specific Tasks"> +<link rel="next" href="usingpoky-debugging-bitbake.html" title="2.3.4. General BitBake Problems"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.3. Dependency Graphs"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div> +<p> + Sometimes it can be hard to see why BitBake wants to build some other packages before a given + package you have specified. + The <code class="filename">bitbake -g targetname</code> command creates the + <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>, + and <code class="filename">task-depends.dot</code> files in the current directory. + These files show the package and task dependencies and are useful for debugging problems. + You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to + display the results in a more human-readable form. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-others.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-others.html new file mode 100644 index 0000000000..a83f4cc4e4 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-others.html @@ -0,0 +1,34 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.8. Other Tips</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="logging-with-bash.html" title="2.3.7.2. Logging With Bash"> +<link rel="next" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.8. Other Tips"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div> +<p> + Here are some other tips that you might find useful: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>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 + <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>. + </p></li> +<li class="listitem"><p>If you want to remove the psplash boot splashscreen, + add <code class="filename">psplash=false</code> to the kernel command line. + Doing so prevents psplash 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). + </p></li> +</ul></div> +<p> + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskfailures.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskfailures.html new file mode 100644 index 0000000000..709af32619 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskfailures.html @@ -0,0 +1,27 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.1. Task Failures</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="next" href="usingpoky-debugging-taskrunning.html" title="2.3.2. Running Specific Tasks"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.1. Task Failures"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div> +<p>The log file for shell tasks is available in + <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. + For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86 + machine (<code class="filename">qemux86</code>) might be + <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</code>. + To see what BitBake runs to generate that log, look at the corresponding + <code class="filename">run.do_taskname.pid</code> file located in the same directory. + </p> +<p> + Presently, the output from Python tasks is sent directly to the console. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskrunning.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskrunning.html new file mode 100644 index 0000000000..998d9d03c7 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskrunning.html @@ -0,0 +1,68 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.2. Running Specific Tasks</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging-taskfailures.html" title="2.3.1. Task Failures"> +<link rel="next" href="usingpoky-debugging-dependencies.html" title="2.3.3. Dependency Graphs"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.2. Running Specific Tasks"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div> +<p> + Any given package consists of a set of tasks. + The standard BitBake behavior in most cases is: <code class="filename">fetch</code>, + <code class="filename">unpack</code>, + <code class="filename">patch</code>, <code class="filename">configure</code>, + <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>, + <code class="filename">package_write</code>, and <code class="filename">build</code>. + The default task is <code class="filename">build</code> and any tasks on which it depends + build first. + Some tasks exist, such as <code class="filename">devshell</code>, that 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 + <code class="filename">-c</code> option in BitBake as follows: + </p> +<pre class="literallayout"> + $ bitbake matchbox-desktop -c devshell + </pre> +<p> + </p> +<p> + If you wish to rerun a task, use the <code class="filename">-f</code> force option. + For example, the following sequence forces recompilation after changing files in the + working directory. + </p> +<pre class="literallayout"> + $ bitbake matchbox-desktop + . + . + [make some changes to the source code in the working directory] + . + . + $ bitbake matchbox-desktop -c compile -f + $ bitbake matchbox-desktop + </pre> +<p> + </p> +<p> + This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it. + The last command reruns all tasks (basically the packaging tasks) after the compile. + BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore + understands that the other tasks also need to be run again. + </p> +<p> + You can view a list of tasks in a given package by running the + <code class="filename">listtasks</code> task as follows: + </p> +<pre class="literallayout"> + $ bitbake matchbox-desktop -c listtasks + </pre> +<p> + The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-variables.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-variables.html new file mode 100644 index 0000000000..ae185be166 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-variables.html @@ -0,0 +1,22 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3.6. Variables</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +<link rel="prev" href="usingpoky-debugging-buildfile.html" title="2.3.5. Building with No Dependencies"> +<link rel="next" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.6. Variables"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div> +<p> + The <code class="filename">-e</code> option dumps the resulting environment for + either the configuration (no package specified) or for a + specific package when specified; or <code class="filename">-b recipename</code> + to show the environment from parsing a single recipe file only. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging.html new file mode 100644 index 0000000000..9a8b72dc96 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging.html @@ -0,0 +1,26 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.3. Debugging Build Failures</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project"> +<link rel="prev" href="usingpoky-install.html" title="2.2. Installing and Using the Result"> +<link rel="next" href="usingpoky-debugging-taskfailures.html" title="2.3.1. Task Failures"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3. Debugging Build Failures"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div> +<p> + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-install.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-install.html new file mode 100644 index 0000000000..d8d60e1c6b --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-install.html @@ -0,0 +1,28 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>2.2. Installing and Using the Result</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project"> +<link rel="prev" href="building-an-image-using-gpl-components.html" title="2.1.2. Building an Image Using GPL Components"> +<link rel="next" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.2. Installing and Using the Result"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div> +<p> + 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 + <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> in + <code class="filename">tmp/deploy/images</code>. + For information on how to run pre-built images such as <code class="filename">qemux86</code> + and <code class="filename">qemuarm</code>, see the + "<a class="link" href="../yocto-project-qs/using-pre-built.html" target="_self">Using Pre-Built Binaries and QEMU</a>" + section in the Yocto Project Quick Start. + For information about how to install these images, see the documentation for your + particular board/machine. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-specifying-LIC_FILES_CHKSUM.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-specifying-LIC_FILES_CHKSUM.html new file mode 100644 index 0000000000..b518fce8a1 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-specifying-LIC_FILES_CHKSUM.html @@ -0,0 +1,57 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes"> +<link rel="prev" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes"> +<link rel="next" href="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html" title="3.4.1.2. Explanation of Syntax"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.4.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div> +<p> + The <code class="filename">LIC_FILES_CHKSUM</code> + variable contains checksums of the license text in the source code for the recipe. + Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>: + </p> +<pre class="literallayout"> + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + </pre> +<p> + </p> +<p> + The build system uses the + <code class="filename"><a class="link" href="ref-variables-glos.html#var-S" title="S">S</a></code> variable as the + default directory used when searching files listed in + <code class="filename">LIC_FILES_CHKSUM</code>. + The previous example employs the default directory. + </p> +<p> + You can also use relative paths as shown in the following example: + </p> +<pre class="literallayout"> + LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + </pre> +<p> + </p> +<p> + In this example, the first line locates a file in + <code class="filename">${S}/src/ls.c</code>. + The second line refers to a file in + <code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent + of <code class="filename"><a class="link" href="ref-variables-glos.html#var-S" title="S">S</a></code>. + </p> +<p> + Note that this variable is mandatory for all recipes, unless the + <code class="filename">LICENSE</code> variable is set to "CLOSED". + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky.html new file mode 100644 index 0000000000..95be1f1041 --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky.html @@ -0,0 +1,48 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 2. Using the Yocto Project</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="prev" href="intro-getit-dev.html" title="1.5. Development Checkouts"> +<link rel="next" href="usingpoky-build.html" title="2.1. Running a Build"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 2. Using the Yocto Project"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="usingpoky-build.html">2.1. Running a Build</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="build-overview.html">2.1.1. Build Overview</a></span></dt> +<dt><span class="section"><a href="building-an-image-using-gpl-components.html">2.1.2. Building an Image Using GPL Components</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="usingpoky-install.html">2.2. Installing and Using the Result</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging.html">2.3. Debugging Build Failures</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="usingpoky-debugging-taskfailures.html">2.3.1. Task Failures</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-taskrunning.html">2.3.2. Running Specific Tasks</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-dependencies.html">2.3.3. Dependency Graphs</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-bitbake.html">2.3.4. General BitBake Problems</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-buildfile.html">2.3.5. Building with No Dependencies</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-variables.html">2.3.6. Variables</a></span></dt> +<dt><span class="section"><a href="recipe-logging-mechanisms.html">2.3.7. Recipe Logging Mechanisms</a></span></dt> +<dt><span class="section"><a href="usingpoky-debugging-others.html">2.3.8. Other Tips</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="maintaining-build-output-quality.html">2.4. Maintaining Build Output Quality</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="enabling-and-disabling-build-history.html">2.4.1. Enabling and Disabling Build History</a></span></dt> +<dt><span class="section"><a href="understanding-what-the-build-history-contains.html">2.4.2. Understanding What the Build History Contains</a></span></dt> +</dl></dd> +</dl> +</div> +<p> + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/html/poky-ref-manual/x32.html b/documentation/ref-manual/eclipse/html/poky-ref-manual/x32.html new file mode 100644 index 0000000000..5be350886c --- /dev/null +++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/x32.html @@ -0,0 +1,35 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>3.3. x32</title> +<link rel="stylesheet" type="text/css" href="../book.css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="index.html" title="The Yocto Project Reference Manual"> +<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details"> +<link rel="prev" href="invalidating-shared-state.html" title="3.2.4.2. Invalidating Shared State"> +<link rel="next" href="support.html" title="3.3.1. Support"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3. x32"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="x32"></a>3.3. x32</h2></div></div></div> +<p> + x32 is a new 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. + </p> +<p> + 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. + </p> +</div></body> +</html> diff --git a/documentation/ref-manual/eclipse/poky-ref-manual-toc.xml b/documentation/ref-manual/eclipse/poky-ref-manual-toc.xml new file mode 100644 index 0000000000..8624641cf5 --- /dev/null +++ b/documentation/ref-manual/eclipse/poky-ref-manual-toc.xml @@ -0,0 +1,217 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<toc label="The Yocto Project Reference Manual" topic="html/poky-ref-manual/index.html"> + <topic label="Introduction" href="html/poky-ref-manual/intro.html"> + <topic label="Introduction" href="html/poky-ref-manual/intro-welcome.html"/> + <topic label="Documentation Overview" href="html/poky-ref-manual/intro-manualoverview.html"/> + <topic label="System Requirements" href="html/poky-ref-manual/intro-requirements.html"> + <topic label="Supported Linux Distributions" href="html/poky-ref-manual/detailed-supported-distros.html"/> + <topic label="Required Packages for the Host Development System" href="html/poky-ref-manual/required-packages-for-the-host-development-system.html"> + <topic label="Ubuntu" href="html/poky-ref-manual/ubuntu-packages.html"/> + <topic label="Fedora Packages" href="html/poky-ref-manual/fedora-packages.html"/> + <topic label="OpenSUSE Packages" href="html/poky-ref-manual/opensuse-packages.html"/> + <topic label="CentOS Packages" href="html/poky-ref-manual/centos-packages.html"/> + </topic> + </topic> + <topic label="Obtaining the Yocto Project" href="html/poky-ref-manual/intro-getit.html"/> + <topic label="Development Checkouts" href="html/poky-ref-manual/intro-getit-dev.html"/> + </topic> + <topic label="Using the Yocto Project" href="html/poky-ref-manual/usingpoky.html"> + <topic label="Running a Build" href="html/poky-ref-manual/usingpoky-build.html"> + <topic label="Build Overview" href="html/poky-ref-manual/build-overview.html"/> + <topic label="Building an Image Using GPL Components" href="html/poky-ref-manual/building-an-image-using-gpl-components.html"/> + </topic> + <topic label="Installing and Using the Result" href="html/poky-ref-manual/usingpoky-install.html"/> + <topic label="Debugging Build Failures" href="html/poky-ref-manual/usingpoky-debugging.html"> + <topic label="Task Failures" href="html/poky-ref-manual/usingpoky-debugging-taskfailures.html"/> + <topic label="Running Specific Tasks" href="html/poky-ref-manual/usingpoky-debugging-taskrunning.html"/> + <topic label="Dependency Graphs" href="html/poky-ref-manual/usingpoky-debugging-dependencies.html"/> + <topic label="General BitBake Problems" href="html/poky-ref-manual/usingpoky-debugging-bitbake.html"/> + <topic label="Building with No Dependencies" href="html/poky-ref-manual/usingpoky-debugging-buildfile.html"/> + <topic label="Variables" href="html/poky-ref-manual/usingpoky-debugging-variables.html"/> + <topic label="Recipe Logging Mechanisms" href="html/poky-ref-manual/recipe-logging-mechanisms.html"> + <topic label="Logging With Python" href="html/poky-ref-manual/logging-with-python.html"/> + <topic label="Logging With Bash" href="html/poky-ref-manual/logging-with-bash.html"/> + </topic> + <topic label="Other Tips" href="html/poky-ref-manual/usingpoky-debugging-others.html"/> + </topic> + <topic label="Maintaining Build Output Quality" href="html/poky-ref-manual/maintaining-build-output-quality.html"> + <topic label="Enabling and Disabling Build History" href="html/poky-ref-manual/enabling-and-disabling-build-history.html"/> + <topic label="Understanding What the Build History Contains" href="html/poky-ref-manual/understanding-what-the-build-history-contains.html"> + <topic label="Build History Package Information" href="html/poky-ref-manual/build-history-package-information.html"/> + <topic label="Build History Image Information" href="html/poky-ref-manual/build-history-image-information.html"/> + <topic label="Using Build History to Gather Image Information Only" href="html/poky-ref-manual/using-build-history-to-gather-image-information-only.html"/> + <topic label="Examining Build History Information" href="html/poky-ref-manual/examining-build-history-information.html"/> + </topic> + </topic> + </topic> + <topic label="Technical Details" href="html/poky-ref-manual/technical-details.html"> + <topic label="Yocto Project Components" href="html/poky-ref-manual/usingpoky-components.html"> + <topic label="BitBake" href="html/poky-ref-manual/usingpoky-components-bitbake.html"/> + <topic label="Metadata (Recipes)" href="html/poky-ref-manual/usingpoky-components-metadata.html"/> + <topic label="Classes" href="html/poky-ref-manual/usingpoky-components-classes.html"/> + <topic label="Configuration" href="html/poky-ref-manual/usingpoky-components-configuration.html"/> + </topic> + <topic label="Shared State Cache" href="html/poky-ref-manual/shared-state-cache.html"> + <topic label="Overall Architecture" href="html/poky-ref-manual/overall-architecture.html"/> + <topic label="Checksums (Signatures)" href="html/poky-ref-manual/checksums.html"/> + <topic label="Shared State" href="html/poky-ref-manual/shared-state.html"/> + <topic label="Tips and Tricks" href="html/poky-ref-manual/tips-and-tricks.html"> + <topic label="Debugging" href="html/poky-ref-manual/debugging.html"/> + <topic label="Invalidating Shared State" href="html/poky-ref-manual/invalidating-shared-state.html"/> + </topic> + </topic> + <topic label="x32" href="html/poky-ref-manual/x32.html"> + <topic label="Support" href="html/poky-ref-manual/support.html"/> + <topic label="Future Development and Limitations" href="html/poky-ref-manual/future-development-and-limitations.html"/> + <topic label="Using x32 Right Now" href="html/poky-ref-manual/using-x32-right-now.html"/> + </topic> + <topic label="Licenses" href="html/poky-ref-manual/licenses.html"> + <topic label="Tracking License Changes" href="html/poky-ref-manual/usingpoky-configuring-LIC_FILES_CHKSUM.html"> + <topic label="Specifying the LIC_FILES_CHKSUM Variable" href="html/poky-ref-manual/usingpoky-specifying-LIC_FILES_CHKSUM.html"/> + <topic label="Explanation of Syntax" href="html/poky-ref-manual/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html"/> + </topic> + <topic label="Enabling Commercially Licensed Recipes" href="html/poky-ref-manual/enabling-commercially-licensed-recipes.html"> + <topic label="License Flag Matching" href="html/poky-ref-manual/license-flag-matching.html"/> + <topic label="Other Variables Related to Commercial Licenses" href="html/poky-ref-manual/other-variables-related-to-commercial-licenses.html"/> + </topic> + </topic> + </topic> + <topic label="Migrating to a Newer Yocto Project Release" href="html/poky-ref-manual/migration.html"> + <topic label="Moving to the Yocto Project 1.3 Release" href="html/poky-ref-manual/moving-to-the-yocto-project-1.3-release.html"> + <topic label="Local Configuration" href="html/poky-ref-manual/1.3-local-configuration.html"> + <topic label="SSTATE_MIRRORS" href="html/poky-ref-manual/migration-1.3-sstate-mirrors.html"/> + <topic label="bblayers.conf" href="html/poky-ref-manual/migration-1.3-bblayers-conf.html"/> + </topic> + <topic label="Recipes" href="html/poky-ref-manual/1.3-recipes.html"> + <topic label="Python Function Whitespace" href="html/poky-ref-manual/migration-1.3-python-function-whitespace.html"/> + <topic label="proto= in SRC_URI" href="html/poky-ref-manual/migration-1.3-proto=-in-src-uri.html"/> + <topic label="nativesdk" href="html/poky-ref-manual/migration-1.3-nativesdk.html"/> + <topic label="Task Recipes" href="html/poky-ref-manual/migration-1.3-task-recipes.html"/> + <topic label="IMAGE_FEATURES" href="html/poky-ref-manual/migration-1.3-image-features.html"/> + <topic label="Removed Recipes" href="html/poky-ref-manual/migration-1.3-removed-recipes.html"/> + </topic> + </topic> + </topic> + <topic label="Source Directory Structure" href="html/poky-ref-manual/ref-structure.html"> + <topic label="Top level core components" href="html/poky-ref-manual/structure-core.html"> + <topic label="bitbake/" href="html/poky-ref-manual/structure-core-bitbake.html"/> + <topic label="build/" href="html/poky-ref-manual/structure-core-build.html"/> + <topic label="documentation" href="html/poky-ref-manual/handbook.html"/> + <topic label="meta/" href="html/poky-ref-manual/structure-core-meta.html"/> + <topic label="meta-yocto/" href="html/poky-ref-manual/structure-core-meta-yocto.html"/> + <topic label="meta-yocto-bsp/" href="html/poky-ref-manual/structure-core-meta-yocto-bsp.html"/> + <topic label="meta-hob/" href="html/poky-ref-manual/structure-meta-hob.html"/> + <topic label="meta-skeleton/" href="html/poky-ref-manual/structure-meta-skeleton.html"/> + <topic label="scripts/" href="html/poky-ref-manual/structure-core-scripts.html"/> + <topic label="oe-init-build-env" href="html/poky-ref-manual/structure-core-script.html"/> + <topic label="LICENSE, README, and README.hardware" href="html/poky-ref-manual/structure-basic-top-level.html"/> + </topic> + <topic label="The Build Directory - build/" href="html/poky-ref-manual/structure-build.html"> + <topic label="build/pseudodone" href="html/poky-ref-manual/structure-build-pseudodone.html"/> + <topic label="build/conf/local.conf" href="html/poky-ref-manual/structure-build-conf-local.conf.html"/> + <topic label="build/conf/bblayers.conf" href="html/poky-ref-manual/structure-build-conf-bblayers.conf.html"/> + <topic label="build/conf/sanity_info" href="html/poky-ref-manual/structure-build-conf-sanity_info.html"/> + <topic label="build/downloads/" href="html/poky-ref-manual/structure-build-downloads.html"/> + <topic label="build/sstate-cache/" href="html/poky-ref-manual/structure-build-sstate-cache.html"/> + <topic label="build/tmp/" href="html/poky-ref-manual/structure-build-tmp.html"/> + <topic label="build/tmp/buildstats/" href="html/poky-ref-manual/structure-build-tmp-buildstats.html"/> + <topic label="build/tmp/cache/" href="html/poky-ref-manual/structure-build-tmp-cache.html"/> + <topic label="build/tmp/deploy/" href="html/poky-ref-manual/structure-build-tmp-deploy.html"/> + <topic label="build/tmp/deploy/deb/" href="html/poky-ref-manual/structure-build-tmp-deploy-deb.html"/> + <topic label="build/tmp/deploy/rpm/" href="html/poky-ref-manual/structure-build-tmp-deploy-rpm.html"/> + <topic label="build/tmp/deploy/licenses/" href="html/poky-ref-manual/structure-build-tmp-deploy-licenses.html"/> + <topic label="build/tmp/deploy/images/" href="html/poky-ref-manual/structure-build-tmp-deploy-images.html"/> + <topic label="build/tmp/deploy/ipk/" href="html/poky-ref-manual/structure-build-tmp-deploy-ipk.html"/> + <topic label="build/tmp/sysroots/" href="html/poky-ref-manual/structure-build-tmp-sysroots.html"/> + <topic label="build/tmp/stamps/" href="html/poky-ref-manual/structure-build-tmp-stamps.html"/> + <topic label="build/tmp/log/" href="html/poky-ref-manual/structure-build-tmp-log.html"/> + <topic label="build/tmp/pkgdata/" href="html/poky-ref-manual/structure-build-tmp-pkgdata.html"/> + <topic label="build/tmp/work/" href="html/poky-ref-manual/structure-build-tmp-work.html"/> + </topic> + <topic label="The Metadata - meta/" href="html/poky-ref-manual/structure-meta.html"> + <topic label="meta/classes/" href="html/poky-ref-manual/structure-meta-classes.html"/> + <topic label="meta/conf/" href="html/poky-ref-manual/structure-meta-conf.html"/> + <topic label="meta/conf/machine/" href="html/poky-ref-manual/structure-meta-conf-machine.html"/> + <topic label="meta/conf/distro/" href="html/poky-ref-manual/structure-meta-conf-distro.html"/> + <topic label="meta/recipes-bsp/" href="html/poky-ref-manual/structure-meta-recipes-bsp.html"/> + <topic label="meta/recipes-connectivity/" href="html/poky-ref-manual/structure-meta-recipes-connectivity.html"/> + <topic label="meta/recipes-core/" href="html/poky-ref-manual/structure-meta-recipes-core.html"/> + <topic label="meta/recipes-devtools/" href="html/poky-ref-manual/structure-meta-recipes-devtools.html"/> + <topic label="meta/recipes-extended/" href="html/poky-ref-manual/structure-meta-recipes-extended.html"/> + <topic label="meta/recipes-gnome/" href="html/poky-ref-manual/structure-meta-recipes-gnome.html"/> + <topic label="meta/recipes-graphics/" href="html/poky-ref-manual/structure-meta-recipes-graphics.html"/> + <topic label="meta/recipes-kernel/" href="html/poky-ref-manual/structure-meta-recipes-kernel.html"/> + <topic label="meta/recipes-multimedia/" href="html/poky-ref-manual/structure-meta-recipes-multimedia.html"/> + <topic label="meta/recipes-qt/" href="html/poky-ref-manual/structure-meta-recipes-qt.html"/> + <topic label="meta/recipes-rt/" href="html/poky-ref-manual/structure-meta-recipes-rt.html"/> + <topic label="meta/recipes-sato/" href="html/poky-ref-manual/structure-meta-recipes-sato.html"/> + <topic label="meta/recipes-support/" href="html/poky-ref-manual/structure-meta-recipes-support.html"/> + <topic label="meta/site/" href="html/poky-ref-manual/structure-meta-site.html"/> + <topic label="meta/recipes.txt" href="html/poky-ref-manual/structure-meta-recipes-txt.html"/> + </topic> + </topic> + <topic label="BitBake" href="html/poky-ref-manual/ref-bitbake.html"> + <topic label="Parsing" href="html/poky-ref-manual/ref-bitbake-parsing.html"/> + <topic label="Preferences and Providers" href="html/poky-ref-manual/ref-bitbake-providers.html"/> + <topic label="Dependencies" href="html/poky-ref-manual/ref-bitbake-dependencies.html"/> + <topic label="The Task List" href="html/poky-ref-manual/ref-bitbake-tasklist.html"/> + <topic label="Running a Task" href="html/poky-ref-manual/ref-bitbake-runtask.html"/> + <topic label="BitBake Command Line" href="html/poky-ref-manual/ref-bitbake-commandline.html"/> + <topic label="Fetchers" href="html/poky-ref-manual/ref-bitbake-fetchers.html"/> + </topic> + <topic label="Classes" href="html/poky-ref-manual/ref-classes.html"> + <topic label="The base class - base.bbclass" href="html/poky-ref-manual/ref-classes-base.html"/> + <topic label="Autotooled Packages - autotools.bbclass" href="html/poky-ref-manual/ref-classes-autotools.html"/> + <topic label="Alternatives - update-alternatives.bbclass" href="html/poky-ref-manual/ref-classes-update-alternatives.html"/> + <topic label="Initscripts - update-rc.d.bbclass" href="html/poky-ref-manual/ref-classes-update-rc.d.html"/> + <topic label="Binary config scripts - binconfig.bbclass" href="html/poky-ref-manual/ref-classes-binconfig.html"/> + <topic label="Debian renaming - debian.bbclass" href="html/poky-ref-manual/ref-classes-debian.html"/> + <topic label="Pkg-config - pkgconfig.bbclass" href="html/poky-ref-manual/ref-classes-pkgconfig.html"/> + <topic label="Distribution of sources - src_distribute_local.bbclass" href="html/poky-ref-manual/ref-classes-src-distribute.html"/> + <topic label="Perl modules - cpan.bbclass" href="html/poky-ref-manual/ref-classes-perl.html"/> + <topic label="Python extensions - distutils.bbclass" href="html/poky-ref-manual/ref-classes-distutils.html"/> + <topic label="Developer Shell - devshell.bbclass" href="html/poky-ref-manual/ref-classes-devshell.html"/> + <topic label="Package Groups - packagegroup.bbclass" href="html/poky-ref-manual/ref-classes-packagegroup.html"/> + <topic label="Packaging - package*.bbclass" href="html/poky-ref-manual/ref-classes-package.html"/> + <topic label="Building kernels - kernel.bbclass" href="html/poky-ref-manual/ref-classes-kernel.html"/> + <topic label="Creating images - image.bbclass and rootfs*.bbclass" href="html/poky-ref-manual/ref-classes-image.html"/> + <topic label="Host System sanity checks - sanity.bbclass" href="html/poky-ref-manual/ref-classes-sanity.html"/> + <topic label="Generated output quality assurance checks - insane.bbclass" href="html/poky-ref-manual/ref-classes-insane.html"/> + <topic label="Autotools configuration data cache - siteinfo.bbclass" href="html/poky-ref-manual/ref-classes-siteinfo.html"/> + <topic label="Adding Users - useradd.bbclass" href="html/poky-ref-manual/ref-classes-useradd.html"/> + <topic label="Using External Source - externalsrc.bbclass" href="html/poky-ref-manual/ref-classes-externalsrc.html"/> + <topic label="Other Classes" href="html/poky-ref-manual/ref-classes-others.html"/> + </topic> + <topic label="Images" href="html/poky-ref-manual/ref-images.html"/> + <topic label="Reference: Features" href="html/poky-ref-manual/ref-features.html"> + <topic label="Distro" href="html/poky-ref-manual/ref-features-distro.html"/> + <topic label="Machine" href="html/poky-ref-manual/ref-features-machine.html"/> + <topic label="Images" href="html/poky-ref-manual/ref-features-image.html"/> + <topic label="Feature Backfilling" href="html/poky-ref-manual/ref-features-backfill.html"/> + </topic> + <topic label="Variables Glossary" href="html/poky-ref-manual/ref-variables-glos.html"> + <topic label="Glossary" href="html/poky-ref-manual/ref-variables-glos.html#ref-variables-glossary"/> + </topic> + <topic label="Variable Context" href="html/poky-ref-manual/ref-varlocality.html"> + <topic label="Configuration" href="html/poky-ref-manual/ref-varlocality-configuration.html"> + <topic label="Distribution (Distro)" href="html/poky-ref-manual/ref-varlocality-config-distro.html"/> + <topic label="Machine" href="html/poky-ref-manual/ref-varlocality-config-machine.html"/> + <topic label="Local" href="html/poky-ref-manual/ref-varlocality-config-local.html"/> + </topic> + <topic label="Recipes" href="html/poky-ref-manual/ref-varlocality-recipes.html"> + <topic label="Required" href="html/poky-ref-manual/ref-varlocality-recipe-required.html"/> + <topic label="Dependencies" href="html/poky-ref-manual/ref-varlocality-recipe-dependencies.html"/> + <topic label="Paths" href="html/poky-ref-manual/ref-varlocality-recipe-paths.html"/> + <topic label="Extra Build Information" href="html/poky-ref-manual/ref-varlocality-recipe-build.html"/> + </topic> + </topic> + <topic label="FAQ" href="html/poky-ref-manual/faq.html"/> + <topic label="Contributing to the Yocto Project" href="html/poky-ref-manual/resources.html"> + <topic label="Introduction" href="html/poky-ref-manual/resources-intro.html"/> + <topic label="Tracking Bugs" href="html/poky-ref-manual/resources-bugtracker.html"/> + <topic label="Mailing lists" href="html/poky-ref-manual/resources-mailinglist.html"/> + <topic label="Internet Relay Chat (IRC)" href="html/poky-ref-manual/resources-irc.html"/> + <topic label="Links" href="html/poky-ref-manual/resources-links.html"/> + <topic label="Contributions" href="html/poky-ref-manual/resources-contributions.html"/> + </topic> +</toc> diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb new file mode 100644 index 0000000000..5dfb0b30cf --- /dev/null +++ b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb @@ -0,0 +1,8 @@ +DESCRIPTION = "GNU Helloworld application" +SECTION = "examples" +LICENSE = "GPLv3" +LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010" + +SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2" + +inherit autotools diff --git a/documentation/ref-manual/examples/hello-single/files/helloworld.c b/documentation/ref-manual/examples/hello-single/files/helloworld.c new file mode 100644 index 0000000000..fc7169b7b8 --- /dev/null +++ b/documentation/ref-manual/examples/hello-single/files/helloworld.c @@ -0,0 +1,8 @@ +#include <stdio.h> + +int main(void) +{ + printf("Hello world!\n"); + + return 0; +} diff --git a/documentation/ref-manual/examples/hello-single/hello.bb b/documentation/ref-manual/examples/hello-single/hello.bb new file mode 100644 index 0000000000..0812743e39 --- /dev/null +++ b/documentation/ref-manual/examples/hello-single/hello.bb @@ -0,0 +1,17 @@ +DESCRIPTION = "Simple helloworld application" +SECTION = "examples" +LICENSE = "MIT" +LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302" + +SRC_URI = "file://helloworld.c" + +S = "${WORKDIR}" + +do_compile() { + ${CC} helloworld.c -o helloworld +} + +do_install() { + install -d ${D}${bindir} + install -m 0755 helloworld ${D}${bindir} +} diff --git a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb new file mode 100644 index 0000000000..b58d4d7bd1 --- /dev/null +++ b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb @@ -0,0 +1,14 @@ +require xorg-lib-common.inc + +DESCRIPTION = "X11 Pixmap library" +LICENSE = "X-BSD" +LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" +DEPENDS += "libxext" +PR = "r2" +PE = "1" + +XORG_PN = "libXpm" + +PACKAGES =+ "sxpm cxpm" +FILES_cxpm = "${bindir}/cxpm" +FILES_sxpm = "${bindir}/sxpm" diff --git a/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb new file mode 100644 index 0000000000..5d05a437a4 --- /dev/null +++ b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb @@ -0,0 +1,15 @@ +DESCRIPTION = "Tools for managing memory technology devices." +SECTION = "base" +DEPENDS = "zlib" +HOMEPAGE = "http://www.linux-mtd.infradead.org/" +LICENSE = "GPLv2" +LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ + file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" + +SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz" + +CFLAGS_prepend = "-I ${S}/include " + +do_install() { + oe_runmake install DESTDIR=${D} +} diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml new file mode 100644 index 0000000000..176573de28 --- /dev/null +++ b/documentation/ref-manual/faq.xml @@ -0,0 +1,606 @@ +<!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='faq'> +<title>FAQ</title> +<qandaset> + <qandaentry> + <question> + <para> + How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>? + </para> + </question> + <answer> + <para> + The term "Poky" refers to the specific reference build system that + the Yocto Project provides. + Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> + and BitBake. + Thus, the generic term used here for the build system is + the "OpenEmbedded build system." + Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with + changes always being merged to OE-Core or BitBake first before being pulled back + into Poky. + This practice benefits both projects immediately. + For a fuller description of the term "Poky", see the + <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project + Development Manual. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. + Can I still use the Yocto Project? + </para> + </question> + <answer> + <para> + You can use a stand-alone tarball to provide Python 2.6. + You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem> + <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem> + </itemizedlist> + </para> + <para> + These tarballs are self-contained with all required libraries and should work + on most Linux systems. + To use the tarballs extract them into the root + directory and run the appropriate command: + <literallayout class='monospaced'> + $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH + $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH + </literallayout> + </para> + <para> + Once you run the command, BitBake uses Python 2.6. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How can you claim Poky / OpenEmbedded-Core is stable? + </para> + </question> + <answer> + <para> + There are three areas that help with stability; + <itemizedlist> + <listitem><para>The Yocto Project team keeps + <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small + and focused, containing around 830 recipes as opposed to the thousands + available in other OpenEmbedded community layers. + Keeping it small makes it easy to test and maintain.</para></listitem> + <listitem><para>The Yocto Project team runs manual and automated tests + using a small, fixed set of reference hardware as well as emulated + targets.</para></listitem> + <listitem><para>The Yocto Project uses an an autobuilder, + which provides continuous build and integration tests.</para></listitem> + </itemizedlist> + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I get support for my board added to the Yocto Project? + </para> + </question> + <answer> + <para> + Support for an additional board is added by creating a BSP layer for it. + For more information on how to create a BSP layer, see the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </para> + <para> + Usually, if the board is not completely exotic, adding support in + the Yocto Project is fairly straightforward. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + Are there any products built using the OpenEmbedded build system? + </para> + </question> + <answer> + <para> + The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink> + is built using the OpenEmbedded build system. + See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink> + website for more information. + There are a number of pre-production devices using the OpenEmbedded build system + and the Yocto Project team + announces them as soon as they are released. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + What does the OpenEmbedded build system produce as output? + </para> + </question> + <answer> + <para> + Because the same set of recipes can be used to create output of various formats, the + output of an OpenEmbedded build depends on how it was started. + Usually, the output is a flashable image ready for the target device. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I add my package to the Yocto Project? + </para> + </question> + <answer> + <para> + To add a package, you need to create a BitBake recipe. + For information on how to add a package, see the section + "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>" + in the Yocto Project Development Manual. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + </para> + </question> + <answer> + <para> + The OpenEmbedded build system can build packages in various formats such as + <filename>ipk</filename> for <filename>opkg</filename>, + Debian package (<filename>.deb</filename>), or RPM. + The packages can then be upgraded using the package tools on the device, much like + on a desktop distribution such as Ubuntu or Fedora. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + </para> + </question> + <answer> + <para> + GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink> + platform targeted at mobile and embedded devices. + The the main difference between GNOME Mobile and standard GNOME is that + desktop-orientated libraries have been removed, along with deprecated libraries, + creating a much smaller footprint. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'. + What is wrong? + </para> + </question> + <answer> + <para> + You are probably running the build on an NTFS filesystem. + Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I make the Yocto Project work in RHEL/CentOS? + </para> + </question> + <answer> + <para> + To get the Yocto Project working under RHEL/CentOS 5.1 you need to first + install some required packages. + The standard CentOS packages needed are: + <itemizedlist> + <listitem><para>"Development tools" (selected during installation)</para></listitem> + <listitem><para><filename>texi2html</filename></para></listitem> + <listitem><para><filename>compat-gcc-34</filename></para></listitem> + </itemizedlist> + On top of these, you need the following external packages: + <itemizedlist> + <listitem><para><filename>python-sqlite2</filename> from + <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink> + </para></listitem> + <listitem><para><filename>help2man</filename> from + <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem> + </itemizedlist> + </para> + + <para> + Once these packages are installed, the OpenEmbedded build system will be able + to build standard images. + However, there might be a problem with the QEMU emulator segfaulting. + You can either disable the generation of binary locales by setting + <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link> + </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename> + from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I see lots of 404 responses for files on + <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong? + </para> + </question> + <answer> + <para> + Nothing is wrong. + The OpenEmbedded build system checks any configured source mirrors before downloading + from the upstream sources. + The build system does this searching for both source archives and + pre-checked out versions of SCM managed software. + These checks help in large installations because it can reduce load on the SCM servers + themselves. + The address above is one of the default mirrors configured into the + build system. + Consequently, if an upstream source disappears, the team + can place sources there so builds continue to work. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + </para> + </question> + <answer> + <para> + Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link> + </filename> = "0" in the <filename>.bb</filename> file but make sure the package is + manually marked as + machine-specific in the case that needs it. + The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I'm behind a firewall and need to use a proxy server. How do I do that? + </para> + </question> + <answer> + <para> + Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename> + and you therefore need to specify the proxy settings in a + <filename>.wgetrc</filename> file in your home directory. + Example settings in that file would be + <literallayout class='monospaced'> + http_proxy = http://proxy.yoyodyne.com:18023/ + ftp_proxy = http://proxy.yoyodyne.com:18023/ + </literallayout> + The Yocto Project also includes a <filename>site.conf.sample</filename> + file that shows how to configure CVS and Git proxy servers + if needed. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>? + </para> + </question> + <answer> + <para> + The <filename>*-native</filename> targets are designed to run on the system + being used for the build. + These are usually tools that are needed to assist the build in some way such as + <filename>quilt-native</filename>, which is used to apply patches. + The non-native version is the one that runs on the target device. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I'm seeing random build failures. Help?! + </para> + </question> + <answer> + <para> + If the same build is failing in totally different and random ways, + the most likely explanation is that either the hardware you're running the + build on has some problem, or, if you are running the build under virtualisation, + the virtualisation probably has bugs. + The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and + CPU activity and is sensitive to even single bit failures in any of these areas. + True random failures have always been traced back to hardware or virtualisation issues. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + What do we need to ship for license compliance? + </para> + </question> + <answer> + <para> + This is a difficult question and you need to consult your lawyer for the answer + for your specific case. + It is worth bearing in mind that for GPL compliance there needs to be enough + information shipped to allow someone else to rebuild the same end result + you are shipping. + This means sharing the source code, any patches applied to it, and also any + configuration information about how that package was configured and built. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I disable the cursor on my touchscreen device? + </para> + </question> + <answer> + <para> + You need to create a form factor file as described in the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>" + section and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one as follows: + <literallayout class='monospaced'> + HAVE_TOUCHSCREEN=1 + </literallayout> + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I make sure connected network interfaces are brought up by default? + </para> + </question> + <answer> + <para> + The default interfaces file provided by the netbase recipe does not + automatically bring up network interfaces. + Therefore, you will need to add a BSP-specific netbase that includes an interfaces + file. + See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>" + section for information on creating these types of miscellaneous recipe files. + </para> + <para> + For example, add the following files to your layer: + <literallayout class='monospaced'> + meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces + meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend + </literallayout> + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I create images with more free space? + </para> + </question> + <answer> + <para> + Images are created to be 1.2 times the size of the populated root filesystem. + To modify this ratio so that there is more free space available, you need to + set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>. + For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets + the image size ratio to one and a half times the size of the populated + root filesystem. + <literallayout class='monospaced'> + IMAGE_OVERHEAD_FACTOR = "1.5" + </literallayout> + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + Why don't you support directories with spaces in the pathnames? + </para> + </question> + <answer> + <para> + The Yocto Project team has tried to do this before but too many of the tools + the OpenEmbedded build system depends on such as <filename>autoconf</filename> + break when they find spaces in pathnames. + Until that situation changes, the team will not support spaces in pathnames. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + How do I use an external toolchain? + </para> + </question> + <answer> + <para> + The toolchain configuration is very flexible and customizable. + It is primarily controlled with the + <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable. + This variable controls which <filename>tcmode-*.inc</filename> file to include + from the <filename>meta/conf/distro/include</filename> directory within the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. + </para> + + <para> + The default value of <filename>TCMODE</filename> is "default" + (i.e. <filename>tcmode-default.inc</filename>). + However, other patterns are accepted. + In particular, "external-*" refers to external toolchains of which there are some + basic examples included in the OpenEmbedded Core (<filename>meta</filename>). + You can use your own custom toolchain definition in your own layer + (or as defined in the <filename>local.conf</filename> file) at the location + <filename>conf/distro/include/tcmode-*.inc</filename>. + </para> + + <para> + In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. + This recipe file needs to package up any pre-built objects in the toolchain such as + <filename>libgcc</filename>, <filename>libstdcc++</filename>, + any locales, and <filename>libc</filename>. + An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located + in <filename>meta/recipes-core/meta/</filename> within the source directory. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'> + How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server? + </para> + </question> + <answer> + <para> + The way the build system obtains source code is highly configurable. + You can setup the build system to get source code in most environments if + HTTP transport is available. + </para> + <para> + When the build system searches for source code, it first tries the local download directory. + If that location fails, Poky tries PREMIRRORS, the upstream source, + and then MIRRORS in that order. + </para> + <para> + By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS + for SCM-based sources, + upstreams for normal tarballs, and then falls back to a number of other mirrors + including the Yocto Project source mirror if those fail. + </para> + <para> + As an example, you could add a specific server for Poky to attempt before any + others by adding something like the following to the <filename>local.conf</filename> + configuration file: + <literallayout class='monospaced'> + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + </literallayout> + </para> + <para> + These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS + requests and direct them to the <filename>http://</filename> sources mirror. + You can use <filename>file://</filename> URLs to point to local directories + or network shares as well. + </para> + <para> + Aside from the previous technique, these options also exist: + <literallayout class='monospaced'> + BB_NO_NETWORK = "1" + </literallayout> + This statement tells BitBake to throw an error instead of trying to access the + Internet. + This technique is useful if you want to ensure code builds only from local sources. + </para> + <para> + Here is another technique: + <literallayout class='monospaced'> + BB_FETCH_PREMIRRORONLY = "1" + </literallayout> + This statement limits Poky to pulling source from the PREMIRRORS only. + Again, this technique is useful for reproducing builds. + </para> + <para> + Here is another technique: + <literallayout class='monospaced'> + BB_GENERATE_MIRROR_TARBALLS = "1" + </literallayout> + This statement tells Poky to generate mirror tarballs. + This technique is useful if you want to create a mirror server. + If not, however, the technique can simply waste time during the build. + </para> + <para> + Finally, consider an example where you are behind an HTTP-only firewall. + You could make the following changes to the <filename>local.conf</filename> + configuration file as long as the PREMIRROR server is up to date: + <literallayout class='monospaced'> + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + BB_FETCH_PREMIRRORONLY = "1" + </literallayout> + These changes would cause Poky to successfully fetch source over HTTP and + any network accesses to anything other than the PREMIRROR would fail. + </para> + <para> + The build system also honors the standard shell environment variables + <filename>http_proxy</filename>, <filename>ftp_proxy</filename>, + <filename>https_proxy</filename>, and <filename>all_proxy</filename> + to redirect requests through proxy servers. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + Can I get rid of build output so I can start over? + </para> + </question> + <answer> + <para> + Yes - you can easily do this. + When you use BitBake to build an image, all the build output goes into the + directory created when you source the <filename>oe-init-build-env</filename> + setup file. + By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink> + is named <filename>build</filename> but can be named + anything you want. + </para> + + <para> + Within the build directory is the <filename>tmp</filename> directory. + To remove all the build output yet preserve any source code or downloaded files + from previous builds, simply remove the <filename>tmp</filename> directory. + </para> + </answer> + </qandaentry> + + +</qandaset> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/figures/buildhistory-web.png Binary files differnew file mode 100644 index 0000000000..f6db86c977 --- /dev/null +++ b/documentation/ref-manual/figures/buildhistory-web.png diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png Binary files differnew file mode 100644 index 0000000000..614b8ee2e4 --- /dev/null +++ b/documentation/ref-manual/figures/buildhistory.png diff --git a/documentation/ref-manual/figures/poky-title.png b/documentation/ref-manual/figures/poky-title.png Binary files differnew file mode 100644 index 0000000000..2893d84620 --- /dev/null +++ b/documentation/ref-manual/figures/poky-title.png diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml new file mode 100644 index 0000000000..38c58da262 --- /dev/null +++ b/documentation/ref-manual/introduction.xml @@ -0,0 +1,322 @@ +<!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='intro'> +<title>Introduction</title> + +<section id='intro-welcome'> + <title>Introduction</title> + + <para> + This manual provides reference information for the current release of the Yocto Project. + The Yocto Project is an open-source collaboration project focused on embedded Linux + developers. + Amongst other things, the Yocto Project uses the OpenEmbedded build system, which + is based on the Poky project, to construct complete Linux images. + You can find complete introductory and getting started information on the Yocto Project + by reading the + <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. + For task-based information using the Yocto Project, see the + <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. + You can also find lots of information on the Yocto Project on the + <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. + </para> +</section> + +<section id='intro-manualoverview'> + <title>Documentation Overview</title> + <para> + This reference manual consists of the following: + <itemizedlist> + <listitem><para><emphasis> + <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> This chapter + provides an overview of the components that make up the Yocto Project + followed by information about debugging images created in the Yocto Project. + </para></listitem> + <listitem><para><emphasis> + <link linkend='technical-details'>Technical Details</link>:</emphasis> + This chapter describes fundamental Yocto Project components as well as an explanation + behind how the Yocto Project uses shared state (sstate) cache to speed build time. + </para></listitem> + <listitem><para><emphasis> + <link linkend='ref-structure'>Directory Structure</link>:</emphasis> + This chapter describes the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> created + either by unpacking a released Yocto Project tarball on your host development system, + or by cloning the upstream + <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. + </para></listitem> + <listitem><para><emphasis> + <link linkend='ref-bitbake'>BitBake</link>:</emphasis> + This chapter provides an overview of the BitBake tool and its role within + the Yocto Project.</para></listitem> + <listitem><para><emphasis> + <link linkend='ref-classes'>Classes</link>:</emphasis> + This chapter describes the classes used in the Yocto Project.</para></listitem> + <listitem><para><emphasis> + <link linkend='ref-images'>Images</link>:</emphasis> + This chapter describes the standard images that the Yocto Project supports. + </para></listitem> + <listitem><para><emphasis> + <link linkend='ref-features'>Features</link>:</emphasis> + This chapter describes mechanisms for creating distribution, machine, and image + features during the build process using the OpenEmbedded build system.</para></listitem> + <listitem><para><emphasis> + <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis> + This chapter presents most variables used by the OpenEmbedded build system, which + using BitBake. + Entries describe the function of the variable and how to apply them. + </para></listitem> + <listitem><para><emphasis> + <link linkend='ref-varlocality'>Variable Context</link>:</emphasis> + This chapter provides variable locality or context.</para></listitem> + <listitem><para><emphasis> + <link linkend='faq'>FAQ</link>:</emphasis> + This chapter provides answers for commonly asked questions in the Yocto Project + development environment.</para></listitem> + <listitem><para><emphasis> + <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis> + This chapter provides guidance on how you can contribute back to the Yocto + Project.</para></listitem> + </itemizedlist> + </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'>What You Need and How You Get It</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: + <itemizedlist> + <listitem><para>Ubuntu 10.04.4 LTS</para></listitem> + <listitem><para>Ubuntu 11.10</para></listitem> + <listitem><para>Ubuntu 12.04.1 LTS</para></listitem> + <listitem><para>Ubuntu 12.04.1 LTS</para></listitem> + <listitem><para>Ubuntu 12.10</para></listitem> + <listitem><para>Fedora release 16 (Verne)</para></listitem> + <listitem><para>Fedora release 17 (Beefy Miracle)</para></listitem> + <listitem><para>Fedora release 18 (Spherical Cow)</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>Debian GNU/Linux 6.0.6 (squeeze)</para></listitem> + <listitem><para>openSUSE 11.4</para></listitem> + <listitem><para>openSUSE 12.1</para></listitem> + <listitem><para>openSUSE 12.2</para></listitem> + </itemizedlist> + </para> + + <note> + For additional information on distributions that support the + Yocto Project, see the + <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page. + </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 by Linux distribution and + further categorized by function. + </para> + + <section id='ubuntu-packages'> + <title>Ubuntu</title> + + <para> + The following list shows the required packages by function + given a supported Ubuntu Linux distribution: + <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 Extras:</emphasis> + Packages recommended if the host system has graphics support: + <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 + </literallayout></para></listitem> + <listitem><para><emphasis>ADT Installer Extras:</emphasis> + Packages needed if you are going to be using the + <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + <literallayout class='monospaced'> + $ sudo apt-get install autoconf automake libtool libglib2.0-dev + </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 yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; + </literallayout></para></listitem> + <listitem><para><emphasis>Graphical Extras:</emphasis> + Packages recommended if the host system has graphics support: + <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 + </literallayout></para></listitem> + <listitem><para><emphasis>ADT Installer Extras:</emphasis> + Packages needed if you are going to be using the + <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + <literallayout class='monospaced'> + $ sudo yum install autoconf automake libtool glib2-devel + </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 Extras:</emphasis> + Packages recommended if the host system has graphics support: + <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 fop xsltproc + </literallayout></para></listitem> + <listitem><para><emphasis>ADT Installer Extras:</emphasis> + Packages needed if you are going to be using the + <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + <literallayout class='monospaced'> + $ sudo zypper install autoconf automake libtool glib2-devel + </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 -y install &CENTOS_HOST_PACKAGES_ESSENTIAL; + </literallayout></para></listitem> + <listitem><para><emphasis>Graphical Extras:</emphasis> + Packages recommended if the host system has graphics support: + <literallayout class='monospaced'> + $ sudo yum -y 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 -y install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt + </literallayout></para></listitem> + <listitem><para><emphasis>ADT Installer Extras:</emphasis> + Packages needed if you are going to be using the + <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + <literallayout class='monospaced'> + $ sudo yum -y install autoconf automake libtool glib2-devel + </literallayout></para></listitem> + </itemizedlist> + <note>Depending on the CentOS version you are using, other requirements + and dependencies might exist. + For details, you should look at the CentOS sections on the + <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink> + wiki page.</note> + </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>Releases:</emphasis> Stable, tested releases are available through + <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem> + <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at + <ulink url='http://autobuilder.yoctoproject.org/nightly'/>. + These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and + experimental builds.</para></listitem> + <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find 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 + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, + or by cloning a copy of the upstream + <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. + For information on both these methods, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml new file mode 100644 index 0000000000..40c570f8ca --- /dev/null +++ b/documentation/ref-manual/migration.xml @@ -0,0 +1,235 @@ +<!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='migration'> +<title>Migrating to a Newer Yocto Project Release</title> + + <para> + This chapter provides information you can use to migrate work to a + newer Yocto Project release. You can find the same information in the + release notes for a given release. + </para> + +<section id='moving-to-the-yocto-project-1.3-release'> + <title>Moving to the Yocto Project 1.3 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.3 Release. + </para> + + <section id='1.3-local-configuration'> + <title>Local Configuration</title> + + <para> + Differences include changes for + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + and <filename>bblayers.conf</filename>. + </para> + + <section id='migration-1.3-sstate-mirrors'> + <title>SSTATE_MIRRORS</title> + + <para> + The shared state cache (sstate-cache) as pointed to by + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default + now has two-character subdirectories to prevent there being an issue with too + many files in the same directory. + Also, native sstate-cache packages will go into a subdirectory named using + the distro ID string. + If you copy the newly structured sstate-cache to a mirror location + (either local or remote) and then point to it in + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>, + you need to append "PATH" to the end of the mirror URL so that + the path used by BitBake before the mirror substitution is + appended to the path used to access the mirror. + Here is an example: + <literallayout class='monospaced'> + SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" + </literallayout> + </para> + </section> + + <section id='migration-1.3-bblayers-conf'> + <title>bblayers.conf</title> + + <para> + The <filename>meta-yocto</filename> layer has been split into + two parts: <filename>meta-yocto</filename> and + <filename>meta-yocto-bsp</filename>, corresponding to the + Poky reference distro configuration and the reference + hardware Board Support Packages (BSPs), respectively. + When running BitBake or Hob for the first time after upgrading, + your <filename>conf/bblayers.conf</filename> file will be + updated to handle this change and you will be asked to + re-run/restart for the changes to take effect. + </para> + </section> + </section> + + <section id='1.3-recipes'> + <title>Recipes</title> + + <para> + Differences include changes for the following: + <itemizedlist> + <listitem><para>Python function whitespace</para></listitem> + <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem> + <listitem><para><filename>nativesdk</filename></para></listitem> + <listitem><para>Task recipes</para></listitem> + <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem> + <listitem><para>Removed recipes</para></listitem> + </itemizedlist> + </para> + + <section id='migration-1.3-python-function-whitespace'> + <title>Python Function Whitespace</title> + + <para> + All Python functions must now use four spaces for indentation. + Previously, an inconsistent mix of spaces and tabs existed, + which made extending these functions using + <filename>_append</filename> or <filename>_prepend</filename> + complicated given that Python treats whitespace as + syntactically significant. + If you are defining or extending any Python functions (e.g. + <filename>populate_packages</filename>, <filename>do_unpack</filename>, + <filename>do_patch</filename> and so forth) in custom recipes + or classes, you need to ensure you are using consistent + four-space indentation. + </para> + </section> + + <section id='migration-1.3-proto=-in-src-uri'> + <title>proto= in SRC_URI</title> + + <para> + Any use of <filename>proto=</filename> in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + needs to be changed to <filename>protocol=</filename>. + In particular, this applies to the following URIs: + <itemizedlist> + <listitem><para><filename>svn://</filename></para></listitem> + <listitem><para><filename>bzr://</filename></para></listitem> + <listitem><para><filename>hg://</filename></para></listitem> + <listitem><para><filename>osc://</filename></para></listitem> + </itemizedlist> + Other URIs were already using <filename>protocol=</filename>. + This change improves consistency. + </para> + </section> + + <section id='migration-1.3-nativesdk'> + <title>nativesdk</title> + + <para> + The suffix <filename>nativesdk</filename> is now implemented + as a prefix, which simplifies a lot of the packaging code for + <filename>nativesdk</filename> recipes. + All custom <filename>nativesdk</filename> recipes and any + references need to be updated to use + <filename>nativesdk-*</filename> instead of + <filename>*-nativesdk</filename>. + </para> + </section> + + <section id='migration-1.3-task-recipes'> + <title>Task Recipes</title> + + <para> + "Task" recipes are now known as "Package groups" and have + been renamed from <filename>task-*.bb</filename> to + <filename>packagegroup-*.bb</filename>. + Existing references to the previous <filename>task-*</filename> + names should work in most cases as there is an automatic + upgrade path for most packages. + However, you should update references in your own recipes and + configurations as they could be removed in future releases. + You should also rename any custom <filename>task-*</filename> + recipes to <filename>packagegroup-*</filename>, and change + them to inherit <filename>packagegroup</filename> instead of + <filename>task</filename>, as well as taking the opportunity + to remove anything now handled by + <filename>packagegroup.bbclass</filename>, such as providing + <filename>-dev</filename> and <filename>-dbg</filename> + packages, setting + <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>, + and so forth. + See the + "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>" + section for further details. + </para> + </section> + + <section id='migration-1.3-image-features'> + <title>IMAGE_FEATURES</title> + + <para> + Image recipes that previously included "apps-console-core" + in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> + should now include "splash" instead to enable the boot-up + splash screen. + Retaining "apps-console-core" will still include the splash + screen generates a warning. + The "apps-x11-core" and "apps-x11-games" + <filename>IMAGE_FEATURES</filename> features have been removed. + </para> + </section> + + <section id='migration-1.3-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed. + For most of them, it is unlikely that you would have any + references to them in your own metadata. + However, you should check your metadata against this list to be sure: + <itemizedlist> + <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>: + Replaced by <filename>libx11</filename>, which has a negligible + size difference with modern Xorg.</para></listitem> + <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>: + Use <filename>xserver-xorg</filename>, which has a negligible + size difference when DRI and GLX modules are not installed.</para></listitem> + <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>: + Effectively unmaintained for many years.</para></listitem> + <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>: + No longer serves any purpose.</para></listitem> + <listitem><para><emphasis><filename>galago</filename></emphasis>: + Replaced by telepathy.</para></listitem> + <listitem><para><emphasis><filename>gail</filename></emphasis>: + Functionality was integrated into GTK+ 2.13.</para></listitem> + <listitem><para><emphasis><filename>eggdbus</filename></emphasis>: + No longer needed.</para></listitem> + <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>: + The build has been restructured to avoid the need for + this step.</para></listitem> + <listitem><para><emphasis><filename>libgsmd</filename></emphasis>: + Unmaintained for many years. + Functionality now provided by + <filename>ofono</filename> instead.</para></listitem> + <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>: + Largely unmaintained PIM application suite. + It has been moved to <filename>meta-gnome</filename> + in <filename>meta-openembedded</filename>.</para></listitem> + </itemizedlist> + In addition to the previously listed changes, the + <filename>meta-demoapps</filename> directory has also been removed + because the recipes in it were not being maintained and many + had become obsolete or broken. + Additionally, these recipes were not parsed in the default configuration. + Many of these recipes are already provided in an updated and + maintained form within OpenEmbedded community layers such as + <filename>meta-oe</filename> and <filename>meta-gnome</filename>. + For the remainder, you can now find them in the + <filename>meta-extras</filename> repository, which is in the + Yocto Project source repositories. + </para> + </section> + </section> +</section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml new file mode 100644 index 0000000000..4d4b9d6188 --- /dev/null +++ b/documentation/ref-manual/ref-bitbake.xml @@ -0,0 +1,419 @@ +<!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 metadata 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 metadata + that consists 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 + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + 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 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 or class files the <filename>.bb</filename> + file depends on changes. + </para> + </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>eglibc</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 + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + 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;#building-image'>Building an Image</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 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] [package ...] + +Executes the specified task (default is 'build') for a given set of BitBake files. +It expects that BBFILES is defined, which is a space separated list of files to +be executed. BBFILES does support wildcards. +Default BBFILES are the .bb files in the current directory. + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + -b BUILDFILE, --buildfile=BUILDFILE + execute the task against this .bb file, rather than a + package from BBFILES. Does not handle any + dependencies. + -k, --continue continue as much as possible after an error. While the + target that failed, and those that depend on it, + cannot be remade, the other dependencies of these + targets can be processed all the same. + -a, --tryaltconfigs continue with builds by trying to use alternative + providers where possible. + -f, --force force run of specified cmd, regardless of stamp status + -c CMD, --cmd=CMD Specify task to execute. Note that this only executes + the specified task for the providee and the packages + it depends on, i.e. 'compile' does not implicitly call + stage for the dependencies (IOW: use only if you know + what you are doing). Depending on the base.bbclass a + listtasks tasks is defined and will show available + tasks + -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 chit-chat 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 files (developers only) + -s, --show-versions show current and preferred versions of all packages + -e, --environment show the global or per-package environment (this is + what used to be bbread) + -g, --graphviz emit the dependency trees of the specified packages 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 print a report + -u UI, --ui=UI userinterface to use + -t SERVERTYPE, --servertype=SERVERTYPE + Choose which server to use, none, process or xmlrpc + --revisions-changed Set the exit code depending on whether upstream + floating revisions have changed or not + </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 + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </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 Manual for more information. + </para> + + </section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 spell spelllang=en_gb +--> diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml new file mode 100644 index 0000000000..2caea272a4 --- /dev/null +++ b/documentation/ref-manual/ref-classes.xml @@ -0,0 +1,720 @@ +<!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-classes'> +<title>Classes</title> + +<para> + Class files are used to abstract common functionality and share it amongst multiple + <filename>.bb</filename> files. + Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class + file. + Class files are identified by the extension <filename>.bbclass</filename> and are usually placed + in a <filename>classes/</filename> directory beneath the + <filename>meta*/</filename> directory found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + Class files can also be pointed to by BUILDDIR (e.g. <filename>build/</filename>)in the same way as + <filename>.conf</filename> files in the <filename>conf</filename> directory. + Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link> + using the same method by which <filename>.conf</filename> files are searched. +</para> + +<para> + In most cases inheriting the class is enough to enable its features, although + for some classes you might need to set variables or override some of the + default behaviour. +</para> + +<section id='ref-classes-base'> + <title>The base class - <filename>base.bbclass</filename></title> + + <para> + The base class is special in that every <filename>.bb</filename> + file inherits it automatically. + This class contains definitions for standard basic + tasks such as fetching, unpacking, configuring (empty by default), compiling + (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging + (empty by default). + These classes are often overridden or extended by other classes + such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>. + The class also contains some commonly used functions such as <filename>oe_runmake</filename>. + </para> +</section> + +<section id='ref-classes-autotools'> + <title>Autotooled Packages - <filename>autotools.bbclass</filename></title> + + <para> + Autotools (<filename>autoconf</filename>, <filename>automake</filename>, + and <filename>libtool</filename>) bring standardization. + This class defines a set of tasks (configure, compile etc.) that + work for all Autotooled packages. + It should usually be enough to define a few standard variables + and then simply <filename>inherit autotools</filename>. + This class can also work with software that emulates Autotools. + For more information, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>" + section in the Yocto Project Development Manual. + </para> + + <para> + It's useful to have some idea of how the tasks defined by this class work + and what they do behind the scenes. + <itemizedlist> + <listitem><para><filename>do_configure</filename> ‐ regenerates the + configure script (using <filename>autoreconf</filename>) and then launches it + with a standard set of arguments used during cross-compilation. + You can pass additional parameters to <filename>configure</filename> through the + <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. + </para></listitem> + <listitem><para><filename>do_compile</filename> ‐ runs <filename>make</filename> with + arguments that specify the compiler and linker. + You can pass additional arguments through + the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. + </para></listitem> + <listitem><para><filename>do_install</filename> ‐ runs <filename>make install</filename> + and passes a DESTDIR option, which takes its value from the standard + <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-update-alternatives'> + <title>Alternatives - <filename>update-alternatives.bbclass</filename></title> + + <para> + Several programs can fulfill the same or similar function and be installed with the same name. + For example, the <filename>ar</filename> command is available from the + <filename>busybox</filename>, <filename>binutils</filename> and + <filename>elfutils</filename> packages. + The <filename>update-alternatives.bbclass</filename> class handles renaming the + binaries so that multiple packages can be installed without conflicts. + The <filename>ar</filename> command still works regardless of which packages are installed + or subsequently removed. + The class renames the conflicting binary in each package and symlinks the highest + priority binary during installation or removal of packages. + </para> + <para> + Four variables control this class: + <itemizedlist> + <listitem><para><filename>ALTERNATIVE_NAME</filename> ‐ The name of the + binary that is replaced (<filename>ar</filename> in this example).</para></listitem> + <listitem><para><filename>ALTERNATIVE_LINK</filename> ‐ The path to + the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem> + <listitem><para><filename>ALTERNATIVE_PATH</filename> ‐ The path to the + real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem> + <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> ‐ The priority of + the binary. + The version with the most features should have the highest priority.</para></listitem> + </itemizedlist> + </para> + + <para> + Currently, the OpenEmbedded build system supports only one binary per package. + </para> +</section> + +<section id='ref-classes-update-rc.d'> + <title>Initscripts - <filename>update-rc.d.bbclass</filename></title> + + <para> + This class uses <filename>update-rc.d</filename> to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system takes care of details such as making sure the script is stopped before + a package is removed and started when the package is installed. + Three variables control this class: + <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>, + <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and + <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>. + See the variable links for details. + </para> +</section> + +<section id='ref-classes-binconfig'> + <title>Binary config scripts - <filename>binconfig.bbclass</filename></title> + + <para> + Before <filename>pkg-config</filename> had become widespread, libraries shipped shell + scripts to give information about the libraries and include paths needed + to build software (usually named <filename>LIBNAME-config</filename>). + This class assists any recipe using such scripts. + </para> + + <para> + During staging, BitBake installs such scripts into the + <filename>sysroots/</filename> directory. + BitBake also changes all paths to point into the <filename>sysroots/</filename> + directory so all builds that use the script will use the correct + directories for the cross compiling layout. + </para> +</section> + +<section id='ref-classes-debian'> + <title>Debian renaming - <filename>debian.bbclass</filename></title> + + <para> + This class renames packages so that they follow the Debian naming + policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename> + and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>. + </para> +</section> + +<section id='ref-classes-pkgconfig'> + <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title> + + <para> + <filename>pkg-config</filename> brought standardization and this class aims to make its + integration smooth for all libraries that make use of it. + </para> + + <para> + During staging, BitBake installs <filename>pkg-config</filename> data into the + <filename>sysroots/</filename> directory. + By making use of sysroot functionality within <filename>pkg-config</filename>, + this class no longer has to manipulate the files. + </para> +</section> + +<section id='ref-classes-src-distribute'> + <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title> + + <para> + Many software licenses require that source files be provided along with the binaries. + To simplify this process, two classes were created: + <filename>src_distribute.bbclass</filename> and + <filename>src_distribute_local.bbclass</filename>. + </para> + + <para> + The results of these classes are <filename>tmp/deploy/source/</filename> + subdirs with sources sorted by + <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field. + If recipes list few licenses (or have entries like "Bitstream Vera"), + the source archive is placed in each license directory. + </para> + + <para> + This class operates using three modes: + <itemizedlist> + <listitem><para><emphasis>copy:</emphasis> Copies the files to the + distribute directory.</para></listitem> + <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the + distribute directory.</para></listitem> + <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into + the distribute directory and then symlinks them back.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-perl'> + <title>Perl modules - <filename>cpan.bbclass</filename></title> + + <para> + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and then inherit the + proper <filename>.bbclass</filename> file. + Building is split into two methods depending on which method the module authors used. + </para> + + <para> + Modules that use old <filename>Makefile.PL</filename>-based build system require + <filename>cpan.bbclass</filename> in their recipes. + </para> + + <para> + Modules that use <filename>Build.PL</filename>-based build system require + using <filename>cpan_build.bbclass</filename> in their recipes. + </para> +</section> + +<section id='ref-classes-distutils'> + <title>Python extensions - <filename>distutils.bbclass</filename></title> + + <para> + Recipes for Python extensions are simple. + These recipes usually only need to point to the source's archive and then inherit + the proper <filename>.bbclass</filename> file. + Building is split into two methods dependling on which method the module authors used. + </para> + + <para> + Extensions that use an Autotools-based build system require Autotools and + <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes. + </para> + + <para> + Extensions that use <filename>distutils</filename>-based build systems require + <filename>distutils.bbclass</filename> in their recipes. + </para> +</section> + +<section id='ref-classes-devshell'> + <title>Developer Shell - <filename>devshell.bbclass</filename></title> + + <para> + This class adds the <filename>devshell</filename> task. + Distribution policy dictates whether to include this class. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section + in the Yocto Project Development Manual for more information about using <filename>devshell</filename>. + </para> +</section> + +<section id='ref-classes-packagegroup'> + <title>Package Groups - <filename>packagegroup.bbclass</filename></title> + + <para> + This class sets default values appropriate for package group recipes (such as + <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>, + <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>, + <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>, + and so forth. + It is highly recommended that all package group recipes inherit this class. + </para> + <para> + For information on how to use this class, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Tasks</ulink>" + section in the Yocto Project Development Manual. + </para> + <para> + Previously, this class was named <filename>task.bbclass</filename>. + </para> +</section> + + +<section id='ref-classes-package'> + <title>Packaging - <filename>package*.bbclass</filename></title> + + <para> + The packaging classes add support for generating packages from a build's + output. + The core generic functionality is in <filename>package.bbclass</filename>. + The code specific to particular package types is contained in various sub-classes such as + <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>, + and <filename>package_rpm.bbclass</filename>. + Most users will want one or more of these classes. + </para> + + <para> + You can control the list of resulting package formats by using the + <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename> + variable defined in the <filename>local.conf</filename> configuration file, + which is located in the <filename>conf</filename> folder of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + </para> + + <para> + The package class you choose can affect build-time performance and has space + ramifications. + In general, building a package with RPM takes about thirty percent more time as + compared to using IPK to build the same or similar package. + This comparison takes into account a complete build of the package with all + dependencies previously built. + The reason for this discrepancy is because the RPM package manager creates and + processes more metadata than the IPK package manager. + Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename> + to "package_ipk" if you are building smaller systems. + </para> + + <para> + Keep in mind, however, that RPM starts to provide more abilities than IPK due to + the fact that it processes more metadata. + For example, this information includes individual file types, file checksum generation + and evaluation on install, sparse file support, conflict detection and resolution + for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks. + </para> + + <para> + Another consideration for packages built using the RPM package manager is space. + For smaller systems, the extra space used for the Berkley Database and the amount + of metadata can affect your ability to do on-device upgrades. + </para> + + <para> + You can find additional information on the effects of the package class at these + two Yocto Project mailing list links: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-kernel'> + <title>Building kernels - <filename>kernel.bbclass</filename></title> + + <para> + This class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename> + directory to allow out-of-tree module builds using <filename>module.bbclass</filename>. + </para> + + <para> + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the <filename>modinfo</filename> output. + If all modules are required, then installing the <filename>kernel-modules</filename> + package installs all packages with modules and various other kernel packages + such as <filename>kernel-vmlinux</filename>. + </para> + + <para> + Various other classes are used by the kernel and module classes internally including + <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>, + <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>. + </para> +</section> + +<section id='ref-classes-image'> + <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title> + + <para> + These classes add support for creating images in several formats. + First, the root filesystem is created from packages using + one of the <filename>rootfs_*.bbclass</filename> + files (depending on the package format used) and then the image is created. + </para> + + <para> + The <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename> + variable controls the types of images to generate. + </para> + + <para> + The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> + variable controls the list of packages to install into the image. + </para> +</section> + +<section id='ref-classes-sanity'> + <title>Host System sanity checks - <filename>sanity.bbclass</filename></title> + + <para> + This class checks to see if prerequisite software is present so that + users can be notified of potential problems that might affect their build. + The class also performs basic user configuration checks from + the <filename>local.conf</filename> configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually determines whether to include this class. + </para> +</section> + +<section id='ref-classes-insane'> + <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title> + + <para> + This class adds a step to the package generation process that sanity checks the + packages generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + </para> + + <para> + You can configure the sanity checks so that specific test failures either raise a warning or + an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error message + once the metadata is in a known and good condition. + You use the <filename>WARN_QA</filename> variable to specify tests for which you + want to generate a warning message on failure. + You use the <filename>ERROR_QA</filename> variable to specify tests for which you + want to generate an error message on failure. + </para> + + <para> + The following list shows the tests you can list with the <filename>WARN_QA</filename> + and <filename>ERROR_QA</filename> variables: + <itemizedlist> + <listitem><para><emphasis><filename>ldflags:</filename></emphasis> + Ensures that the binaries were linked with the + <filename>LDFLAGS</filename> options provided by the build system. + If this test fails, check that the <filename>LDFLAGS</filename> variable + is being passed to the linker command.</para></listitem> + <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + <filename>/lib</filename> and <filename>/usr/lib</filename>). + While these paths will not cause any breakage, they do waste space and + are unnecessary.</para></listitem> + <listitem><para><emphasis><filename>rpaths:</filename></emphasis> + Checks for rpaths in the binaries that contain build system paths such + as <filename>TMPDIR</filename>. + If this test fails, bad <filename>-rpath</filename> options are being + passed to the linker commands and your binaries have potential security + issues.</para></listitem> + <listitem><para><emphasis><filename>dev-so:</filename></emphasis> + Checks that the <filename>.so</filename> symbolic links are in the + <filename>-dev</filename> package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the <filename>-dev</filename> package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + </para></listitem> + <listitem><para><emphasis><filename>debug-files:</filename></emphasis> + Checks for <filename>.debug</filename> directories in anything but the + <filename>-dbg</filename> package. + The debug files should all be in the <filename>-dbg</filename> package. + Thus, anything packaged elsewhere is incorrect packaging.</para></listitem> + <listitem><para><emphasis><filename>arch:</filename></emphasis> + Checks the Executable and Linkable Format (ELF) type, bit size and endianness + of any binaries to ensure it matches the target architecture. + This test fails if any binaries don't match the type since there would be an + incompatibility. + Sometimes software, like bootloaders, might need to bypass this check. + </para></listitem> + <listitem><para><emphasis><filename>debug-deps:</filename></emphasis> + Checks that <filename>-dbg</filename> packages only depend on other + <filename>-dbg</filename> packages and not on any other types of packages, + which would cause a packaging bug.</para></listitem> + <listitem><para><emphasis><filename>dev-deps:</filename></emphasis> + Checks that <filename>-dev</filename> packages only depend on other + <filename>-dev</filename> packages and not on any other types of packages, + which would be a packaging bug.</para></listitem> + <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis> + Checks <filename>.pc</filename> files for any + <filename>TMPDIR/WORKDIR</filename> paths. + Any <filename>.pc</filename> file containing these paths is incorrect + since <filename>pkg-config</filename> itself adds the correct sysroot prefix + when the files are accessed.</para></listitem> + <listitem><para><emphasis><filename>la:</filename></emphasis> + Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> + paths. + Any <filename>.la</filename> file continaing these paths is incorrect since + <filename>libtool</filename> adds the correct sysroot prefix when using the + files automatically itself.</para></listitem> + <listitem><para><emphasis><filename>desktop:</filename></emphasis> + Runs the <filename>desktop-file-validate</filename> program against any + <filename>.desktop</filename> files to validate their contents against + the specification for <filename>.desktop</filename> files.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-siteinfo'> + <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title> + + <para> + Autotools can require tests that must execute on the target hardware. + Since this is not possible in general when cross compiling, site information is + used to provide cached test results so these tests can be skipped over but + still make the correct values available. + The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename> + contains test results sorted into different categories such as architecture, endianness, and + the <filename>libc</filename> used. + Site information provides a list of files containing data relevant to + the current build in the + <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable + that Autotools automatically picks up. + </para> + + <para> + The class also provides variables like + <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename> + and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename> + that can be used elsewhere in the metadata. + </para> + + <para> + Because this class is included from <filename>base.bbclass</filename>, it is always active. + </para> +</section> + +<section id='ref-classes-useradd'> + <title>Adding Users - <filename>useradd.bbclass</filename></title> + + <para> + If you have packages that install files that are owned by custom users or groups, + you can use this class to specify those packages and associate the users and groups + with those packages. + The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> + recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + provides a simple exmample that shows how to add three + users and groups to two packages. + See the <filename>useradd-example.bb</filename> for more information on how to + use this class. + </para> +</section> + +<section id='ref-classes-externalsrc'> + <title>Using External Source - <filename>externalsrc.bbclass</filename></title> + + <para> + You can use this class to build software from source code that is external to the + OpenEmbedded build system. + In other words, your source code resides in an external tree outside of the Yocto Project. + Building software from an external source tree means that the normal fetch, unpack, and + patch process is not used. + </para> + + <para> + To use the class, you need to define the + <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files. + You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class. + </para> + + <para> + This class expects the source code to support recipe builds that use the + <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in + which the OpenEmbedded build system places the generated objects built from the recipes. + By default, the <filename>B</filename> directory is set to the following, which is separate from the + Source Directory (<filename>S</filename>): + <literallayout class='monospaced'> + ${WORKDIR}/${BPN}/{PV}/ + </literallayout> + See the glossary entries for the + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, + <link linkend='var-BPN'><filename>BPN</filename></link>, + <link linkend='var-PV'><filename>PV</filename></link>, + <link linkend='var-S'><filename>S</filename></link>, and + <link linkend='var-B'><filename>B</filename></link> for more information. + </para> + + <para> + You can build object files in the external tree by setting the + <filename>B</filename> variable equal to <filename>"${S}"</filename>. + However, this practice does not work well if you use the source for more than one variant + (i.e., "natives" such as <filename>quilt-native</filename>, + or "crosses" such as <filename>gcc-cross</filename>). + So, be sure there are no "native", "cross", or "multilib" variants of the recipe. + </para> + + <para> + If you do want to build different variants of a recipe, you can use the + <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable. + When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the + recipe's ability to build variants in different working directories. + Most autotools-based recipes support separating these directories. + The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename> + and some kernel recipes. + Alternatively, you can make sure that separate recipes exist that each + use the <filename>BBCLASSEXTEND</filename> variable to build each variant. + The separate recipes can inherit a single target recipe. + </para> + + <para> + For information on how to use this class, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building + Software from an External Source</ulink>" section in the Yocto Project Development Manual. + </para> +</section> + +<section id='ref-classes-others'> + <title>Other Classes</title> + + <para> + Thus far, this chapter has discussed only the most useful and important + classes. + However, other classes exist within the <filename>meta/classes</filename> directory + in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + You can examine the <filename>.bbclass</filename> files directly for more + information. + </para> +</section> + +<!-- Undocumented classes are: + allarch.bbclass + archive*.bbclass + binconfig.bbclass + blacklist.bbclass + bootimg.bbclass + boot-directdisk.bbclass + bugzilla.bbclass + buildhistory.bbclass + buildstats.bbclass + ccache.bbclass + chrpath.bbclass + cmake.bbclass + cml1.bbclass + copyleft_compliance.bbclass + core-image.bbclass + cross.bbclass + cross-canadian.bbclass + crosssdk.bbclass + deploy.bbclass + distrodata.bbclass + dummy.bbclass + gconf.bbclass + gettext.bbclass + gnomebase.bbclass + gnome.bbclass + gtk-doc.bbclass + gtk-icon-cache.bbclass + gzipnative.bbclass + icecc.bbclass + image-empty.bbclass + image-live.bbclass + image-vmdk.bbclass + image-mklibs.bbclass + image-prelink.bbclass + image-swab.bbclass + imagetest-dummy.bbclass + imagetest-qemu.bbclass + image_types.bbclass + image_types_uboot.bbclass + insserv.bbclass + kernel-arch.bbclass + kernel-yocto.bbclass + lib_package.bbclass + linux-kernel-base.bbclass + license.bbclass + logging.bbclass + meta.bbclass + metadata_scm.bbclass + mime.bbclass + mirrors.bbclass + multilib*.bbclass + native.bbclass + nativesdk.bbclass + oelint.bbclass + own-mirrors.bbclass + packagedata.bbclass + packageinfo.bbclass + patch.bbclass + perlnative.bbclass + pkg_distribute.bbclass + pkg_metainfo.bbclass + populate_sdk*.bbclass + prexport.bbclass + primport.bbclass + prserv.bbclass + python-dir.bbclass + pythonnative.bbclass + qemu.bbclass + qmake*.bbclass + qt4*.bbclass + recipe_sanity.bbclass + relocatable.bbclass + rm_work.bbclass + scons.bbclass + sdl.bbclass + setuptools.bbclass + sip.bbclass + siteconfig.bbclass + sourcepkg.bbclass + sstate.bbclass + staging.bbclass + syslinux.bbclass + terminal.bbclass + tinderclient.bbclass + toolchain-scripts.bbclass + typecheck.bbclass + utility-tasks.bbclass + utils.bbclass +--> + + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml new file mode 100644 index 0000000000..77c31275ae --- /dev/null +++ b/documentation/ref-manual/ref-features.xml @@ -0,0 +1,294 @@ +<!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-features'> + <title>Reference: Features</title> + + <para> + Features provide a mechanism for working out which packages + should be included in the generated images. + Distributions can select which features they want to support through the + <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> + variable, which is set in the <filename>poky.conf</filename> distribution configuration file. + Machine features are set in the + <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> + variable, which is set in the machine configuration file and + specifies the hardware features for a given machine. + </para> + + <para> + These two variables combine to work out which kernel modules, + utilities, and other packages to include. + A given distribution can support a selected subset of features so some machine features might not + be included if the distribution itself does not support them. + </para> + + <para> + One method you can use to determine which recipes are checking to see if a + particular feature is contained or not is to <filename>grep</filename> through + the metadata for the feature. + Here is an example that discovers the recipes whose build is potentially + changed based on a given feature: + <literallayout class='monospaced'> + $ cd $HOME/poky + $ git grep 'contains.*MACHINE_FEATURES.*<feature>' + </literallayout> + </para> + + <para> + This chapter provides a reference of shipped machine and distro features + you can include as part of the image, a reference on image types you can + build, and a reference on feature backfilling. + </para> + + + <section id='ref-features-distro'> + <title>Distro</title> + + <para> + The items below are features you can use with + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within <filename>do_configure</filename> for a particular + recipe. + </para> + + <para> + This list only represents features as shipped with the Yocto Project metadata: + <itemizedlist> + <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility + kernel modules will be installed if available).</para></listitem> + <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only) + </para></listitem> + <listitem><para><emphasis>ext2:</emphasis> Include tools for supporting for devices with internal + HDD/Microdrive for storing files (instead of Flash only devices) + </para></listitem> + <listitem><para><emphasis>irda:</emphasis> Include Irda support + </para></listitem> + <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be + loaded during boot). + </para></listitem> + <listitem><para><emphasis>pci:</emphasis> Include PCI bus support + </para></listitem> + <listitem><para><emphasis>pcmcia:</emphasis> Include PCMCIA/CompactFlash support + </para></listitem> + <listitem><para><emphasis>usbgadget:</emphasis> USB Gadget Device support (for USB + networking/serial/storage) + </para></listitem> + <listitem><para><emphasis>usbhost:</emphasis> USB Host support (allows to connect external + keyboard, mouse, storage, network etc) + </para></listitem> + <listitem><para><emphasis>wifi:</emphasis> WiFi support (integrated only) + </para></listitem> + <listitem><para><emphasis>cramfs:</emphasis> CramFS support + </para></listitem> + <listitem><para><emphasis>ipsec:</emphasis> IPSec support + </para></listitem> + <listitem><para><emphasis>ipv6:</emphasis> IPv6 support + </para></listitem> + <listitem><para><emphasis>nfs:</emphasis> NFS client support (for mounting NFS exports on + device)</para></listitem> + <listitem><para><emphasis>ppp:</emphasis> PPP dialup support</para></listitem> + <listitem><para><emphasis>smbfs:</emphasis> SMB networks client support (for mounting + Samba/Microsoft Windows shares on device)</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-features-machine'> + <title>Machine</title> + + <para> + The items below are features you can use with + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within <filename>do_configure</filename> for a particular + recipe. + </para> + + <para> + This feature list only represents features as shipped with the Yocto Project metadata: + <itemizedlist> + <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only) + </para></listitem> + <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers + </para></listitem> + <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation) + </para></listitem> + <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT + </para></listitem> + <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive + </para></listitem> + <listitem><para><emphasis>irda:</emphasis> Hardware has Irda support + </para></listitem> + <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard + </para></listitem> + <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus + </para></listitem> + <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets + </para></listitem> + <listitem><para><emphasis>screen:</emphasis> Hardware has a screen + </para></listitem> + <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232) + </para></listitem> + <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen + </para></listitem> + <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable + </para></listitem> + <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable + </para></listitem> + <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-features-image'> + <title>Images</title> + + <para> + The contents of images generated by the OpenEmbedded build system can be controlled by the + <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> + and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> + variables that you typically configure in your image recipes. + Through these variables you can add several different + predefined packages such as development utilities or packages with debug + information needed to investigate application problems or profile applications. + </para> + + <para> + Current list of + <filename>IMAGE_FEATURES</filename> contains the following: + <itemizedlist> + <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot. + By default, this screen is provided by <filename>psplash</filename>, which does + allow customization. + If you prefer to use an alternative splash screen package, you can do so by + setting the <filename>SPLASH</filename> variable + to a different package name (or names) within the image recipe or at the distro + configuration level.</para></listitem> + <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal + SSH server. + </para></listitem> + <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server, + which is more full-featured than Dropbear. + Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server + are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take + precedence and Dropbear will not be installed.</para></listitem> + <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem> + <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a + minimal environment.</para></listitem> + <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment. + </para></listitem> + <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. + </para></listitem> + <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as + <filename>strace</filename> and <filename>gdb</filename>. + </para></listitem> + <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as + <filename>oprofile</filename>, <filename>exmap</filename>, and + <filename>LTTng</filename>.</para></listitem> + <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g. + touchscreen debugging).</para></listitem> + <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem> + <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and + extra library links) for all packages installed in a given image.</para></listitem> + <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development + packages (i.e. static libraries containing <filename>*.a</filename> files) for all + packages installed in a given image.</para></listitem> + <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages + installed in a given image.</para></listitem> + <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages + installed in a given image.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-features-backfill'> + <title>Feature Backfilling</title> + + <para> + Sometimes it is necessary in the OpenEmbedded build system to extend + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> + or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + to control functionality that was previously enabled and not able + to be disabled. + For these cases, we need to add an + additional feature item to appear in one of these variables, + but we do not want to force developers who have existing values + of the variables in their configuration to add the new feature + in order to retain the same overall level of functionality. + Thus, the OpenEmbedded build system has a mechanism to + automatically "backfill" these added features into existing + distro or machine configurations. + You can see the list of features for which this is done by + finding the + <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link> + and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link> + variables in the <filename>meta/conf/bitbake.conf</filename> file. + </para> + + <para> + Because such features are backfilled by default into all + configurations as described in the previous paragraph, developers + who wish to disable the new features need to be able to selectively + prevent the backfilling from occurring. + They can do this by adding the undesired feature or features to the + <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> + or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link> + variables for distro features and machine features respectively. + </para> + + <para> + Here are two examples to help illustrate feature backfilling: + <itemizedlist> + <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>: + Previously, PulseAudio support was enabled within the Qt and + GStreamer frameworks. + Because of this, the feature is backfilled and thus + enabled for all distros through the + <filename>DISTRO_FEATURES_BACKFILL</filename> + variable in the <filename>meta/conf/bitbake.conf</filename> file. + However, your distro needs to disable the feature. + You can disable the feature without affecting + other existing distro configurations that need PulseAudio support + by adding "pulseaudio" to + <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename> + in your distro's <filename>.conf</filename> file. + Adding the feature to this variable when it also + exists in the <filename>DISTRO_FEATURES_BACKFILL</filename> + variable prevents the build system from adding the feature to + your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling + the feature for that particular distro.</para></listitem> + <listitem><para><emphasis>The "rtc" machine feature option</emphasis>: + Previously, real time clock (RTC) support was enabled for all + target devices. + Because of this, the feature is backfilled and thus enabled + for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename> + variable in the <filename>meta/conf/bitbake.conf</filename> file. + However, your target device does not have this capability. + You can disable RTC support for your device without + affecting other machines that need RTC support + by adding the feature to your machine's + <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename> + list in the machine's <filename>.conf</filename> file. + Adding the feature to this variable when it also + exists in the <filename>MACHINE_FEATURES_BACKFILL</filename> + variable prevents the build system from adding the feature to + your configuration's <filename>MACHINE_FEATURES</filename>, effectively + disabling RTC support for that particular machine.</para></listitem> + </itemizedlist> + </para> + </section> +</chapter> + +<!-- +vim: expandtab tw=80 ts=4 spell spelllang=en_gb +--> diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml new file mode 100644 index 0000000000..0a827ca235 --- /dev/null +++ b/documentation/ref-manual/ref-images.xml @@ -0,0 +1,132 @@ +<!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-images'> + <title>Images</title> + + <para> + The OpenEmbedded build process supports several types of images to satisfy different needs. + When you issue the <filename>bitbake</filename> command you provide a “top-level†recipe + that essentially begins the build for the type of image you want. + </para> + + <note> + Building an image without GNU General Public License Version 3 (GPLv3) components + is only supported for minimal and base images. + Furthermore, if you are going to build an image using non-GPLv3 components, + you must make the following changes in the <filename>local.conf</filename> file + before using the BitBake command to build the minimal or base image: + <literallayout class='monospaced'> + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPLv3" + </literallayout> + </note> + + <para> + From within the <filename>poky</filename> Git repository, use the following command to list + the supported images: + <literallayout class='monospaced'> + $ ls meta*/recipes*/images/*.bb + </literallayout> + These recipes reside in the <filename>meta/recipes-core/images</filename>, + <filename>meta/recipes-extended/images</filename>, + <filename>meta/recipes-graphics/images</filename>, and + <filename>meta/recipes-sato/images</filename> directories + within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>. + Although the recipe names are somewhat explanatory, here is a list that describes them: + </para> + + <itemizedlist> + <listitem><para><emphasis><filename>core-image-base</filename>:</emphasis> + A console-only image that fully supports the target device hardware.</para></listitem> + <listitem><para><emphasis><filename>core-image-minimal</filename>:</emphasis> + A small image just capable of allowing a device to boot.</para></listitem> + <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis> + A <filename>core-image-minimal</filename> image suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </para></listitem> + <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis> + A <filename>core-image-minimal</filename> image that has the Minimal RAM-based + Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel, + which allows the system to find the first “init†program more efficiently. + </para></listitem> + <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis> + A <filename>core-image-minimal</filename> image that has support + for the Minimal MTD Utilities, which let the user interact with the + MTD subsystem in the kernel to perform operations on flash devices. + </para></listitem> + <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis> + A very basic X11 image with a terminal. + </para></listitem> + <listitem><para><emphasis><filename>core-image-basic</filename>:</emphasis> + A console-only image with more full-featured Linux system + functionality installed.</para></listitem> + <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis> + An image that conforms to the Linux Standard Base (LSB) specification.</para></listitem> + <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis> + A <filename>core-image-lsb</filename> image that is suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </para></listitem> + <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis> + A <filename>core-image-lsb</filename> that includes everything in meta-toolchain + but also includes development headers and libraries to form a complete standalone SDK. + This image is suitable for development using the target.</para></listitem> + <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis> + An image with support for the Open GL-based toolkit Clutter, which enables development of + rich and animated graphical user interfaces.</para></listitem> + <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis> + An image with Sato support, a mobile environment and visual style that works well + with mobile devices. + The image supports X11 with a Sato theme and applications such as + a terminal, editor, file manager, media player, and so forth.</para></listitem> + <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis> + A <filename>core-image-sato</filename> image suitable for development + using the host. + The image includes libraries needed to build applications on the device itself, + testing and profiling tools, and debug symbols. + This image was formerly <filename>core-image-sdk</filename>.</para></listitem> + <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis> + A <filename>core-image-sato</filename> image that includes everything in meta-toolchain. + The image also includes development headers and libraries to form a complete standalone SDK + and is suitable for development using the target.</para></listitem> + <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis> + A <filename>core-image-minimal</filename> image plus a real-time test suite and + tools appropriate for real-time use.</para></listitem> + <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis> + A <filename>core-image-rt</filename> image that includes everything in + <filename>meta-toolchain</filename>. + The image also includes development headers and libraries to form a complete + stand-alone SDK and is suitable for development using the target.</para></listitem> + <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis> + An image that uses <filename>gtk+</filename> over <filename>directfb</filename> + instead of X11. + In order to build, this image requires specific distro configuration that enables + <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem> + <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis> + An image you can boot and run 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>. + 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> + </itemizedlist> + + <tip> + From the Yocto Project release 1.1 onwards, <filename>-live</filename> and + <filename>-directdisk</filename> images have been replaced by a "live" + option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an + image file that can be + copied directly to a CD or USB device and run as is. + To build a live image, simply add + "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename> + file or wherever appropriate and then build the desired image as normal. + </tip> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl new file mode 100644 index 0000000000..362ebed131 --- /dev/null +++ b/documentation/ref-manual/ref-manual-customization.xsl @@ -0,0 +1,6 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + +</xsl:stylesheet> diff --git a/documentation/ref-manual/ref-manual.html b/documentation/ref-manual/ref-manual.html new file mode 100644 index 0000000000..d491bd023d --- /dev/null +++ b/documentation/ref-manual/ref-manual.html @@ -0,0 +1,5283 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title></title><link rel="stylesheet" type="text/css" href="ref-style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="ref-manual"></a></h1></div><div><div class="authorgroup"> + <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"> + <span class="orgname">Linux Foundation<br /></span> + </div><code class="email"><<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>></code></div> + + </div></div><div><p class="copyright">Copyright © 2010-2013 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="idm153280"></a> + <p> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</a> as published by Creative Commons. + </p> + <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/ref-manual/ref-manual.html" target="_top">Yocto Project Reference Manual</a> on + the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website. + For the latest version of this manual, see the manual on the website. + </div> + </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><strong>Revision History</strong></th></tr> + <tr><td align="left">Revision 4.0+git</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr> + <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr> + <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr> + <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr> + <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr> + <tr><td align="left">Revision 1.3</td><td align="left">October 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr> + <tr><td align="left">Revision 1.4</td><td align="left">Sometime in 2013</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.4 Release.</td></tr> + </table></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#detailed-supported-distros">1.3.1. Supported Linux Distributions</a></span></dt><dt><span class="section"><a href="#required-packages-for-the-host-development-system">1.3.2. Required Packages for the Host Development System</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#usingpoky">2. Using the Yocto Project</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd><dt><span class="section"><a href="#maintaining-build-output-quality">2.4. Maintaining Build Output Quality</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-and-disabling-build-history">2.4.1. Enabling and Disabling Build History</a></span></dt><dt><span class="section"><a href="#understanding-what-the-build-history-contains">2.4.2. Understanding What the Build History Contains</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#technical-details">3. Technical Details</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#migration">4. Migrating to a Newer Yocto Project Release</a></span></dt><dd><dl><dt><span class="section"><a href="#moving-to-the-yocto-project-1.3-release">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt><dd><dl><dt><span class="section"><a href="#1.3-local-configuration">4.1.1. Local Configuration</a></span></dt><dt><span class="section"><a href="#1.3-recipes">4.1.2. Recipes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref-structure">5. Source Directory Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core">5.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">5.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">5.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">5.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">5.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto-bsp">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-hob">5.1.7. <code class="filename">meta-hob/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">5.1.9. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">5.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">5.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">5.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">5.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">5.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref-bitbake">6. BitBake</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-bitbake-parsing">6.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">6.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">6.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">6.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">6.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">6.7. Fetchers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-classes">7. Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-classes-base">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-packagegroup">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">7.21. Other Classes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-images">8. Images</a></span></dt><dt><span class="chapter"><a href="#ref-features">9. Reference: Features</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-features-distro">9.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">9.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">9.3. Images</a></span></dt><dt><span class="section"><a href="#ref-features-backfill">9.4. Feature Backfilling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-variables-glos">10. Variables Glossary</a></span></dt><dd><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-varlocality">11. Variable Context</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-configuration">11.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">11.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">11.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">11.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">11.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">11.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">11.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">11.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">11.2.4. Extra Build Information</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#faq">12. FAQ</a></span></dt><dt><span class="chapter"><a href="#resources">13. Contributing to the Yocto Project</a></span></dt><dd><dl><dt><span class="section"><a href="#resources-intro">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">13.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">13.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">13.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">13.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">13.6. Contributions</a></span></dt></dl></dd></dl></div> + + + <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#detailed-supported-distros">1.3.1. Supported Linux Distributions</a></span></dt><dt><span class="section"><a href="#required-packages-for-the-host-development-system">1.3.2. Required Packages for the Host Development System</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-welcome"></a>1.1. Introduction</h2></div></div></div><p> + This manual provides reference information for the current release of the Yocto Project. + The Yocto Project is an open-source collaboration project focused on embedded Linux + developers. + Amongst other things, the Yocto Project uses the OpenEmbedded build system, which + is based on the Poky project, to construct complete Linux images. + You can find complete introductory and getting started information on the Yocto Project + by reading the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html" target="_top">Yocto Project Quick Start</a>. + For task-based information using the Yocto Project, see the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html" target="_top">Yocto Project Development Manual</a>. + You can also find lots of information on the Yocto Project on the + <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>. + </p></div><div class="section" title="1.2. Documentation Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div><p> + This reference manual consists of the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#usingpoky" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter + provides an overview of the components that make up the Yocto Project + followed by information about debugging images created in the Yocto Project. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#technical-details" title="Chapter 3. Technical Details">Technical Details</a>:</em></span> + This chapter describes fundamental Yocto Project components as well as an explanation + behind how the Yocto Project uses shared state (sstate) cache to speed build time. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-structure" title="Chapter 5. Source Directory Structure">Directory Structure</a>:</em></span> + This chapter describes the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a> created + either by unpacking a released Yocto Project tarball on your host development system, + or by cloning the upstream + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">Poky</a> Git repository. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-bitbake" title="Chapter 6. BitBake">BitBake</a>:</em></span> + This chapter provides an overview of the BitBake tool and its role within + the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-classes" title="Chapter 7. Classes">Classes</a>:</em></span> + This chapter describes the classes used in the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>:</em></span> + This chapter describes the standard images that the Yocto Project supports. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-features" title="Chapter 9. Reference: Features">Features</a>:</em></span> + This chapter describes mechanisms for creating distribution, machine, and image + features during the build process using the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-variables-glos" title="Chapter 10. Variables Glossary">Variables Glossary</a>:</em></span> + This chapter presents most variables used by the OpenEmbedded build system, which + using BitBake. + Entries describe the function of the variable and how to apply them. + </p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#ref-varlocality" title="Chapter 11. Variable Context">Variable Context</a>:</em></span> + This chapter provides variable locality or context.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#faq" title="Chapter 12. FAQ">FAQ</a>:</em></span> + This chapter provides answers for commonly asked questions in the Yocto Project + development environment.</p></li><li class="listitem"><p><span class="emphasis"><em> + <a class="link" href="#resources" title="Chapter 13. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span> + This chapter provides guidance on how you can contribute back to the Yocto + Project.</p></li></ul></div><p> + </p></div><div class="section" title="1.3. System Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-requirements"></a>1.3. System Requirements</h2></div></div></div><p> + For general Yocto Project system requirements, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#yp-resources" target="_top">What You Need and How You Get It</a>" section + in the Yocto Project Quick Start. + The remainder of this section provides details on system requirements + not covered in the Yocto Project Quick Start. + </p><div class="section" title="1.3.1. Supported Linux Distributions"><div class="titlepage"><div><div><h3 class="title"><a id="detailed-supported-distros"></a>1.3.1. Supported Linux Distributions</h3></div></div></div><p> + Currently, the Yocto Project is supported on the following distributions: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Ubuntu 10.04.4 LTS</p></li><li class="listitem"><p>Ubuntu 11.10</p></li><li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li><li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li><li class="listitem"><p>Ubuntu 12.10</p></li><li class="listitem"><p>Fedora release 16 (Verne)</p></li><li class="listitem"><p>Fedora release 17 (Beefy Miracle)</p></li><li class="listitem"><p>Fedora release 18 (Spherical Cow)</p></li><li class="listitem"><p>CentOS release 5.6 (Final)</p></li><li class="listitem"><p>CentOS release 5.7 (Final)</p></li><li class="listitem"><p>CentOS release 5.8 (Final)</p></li><li class="listitem"><p>CentOS release 6.3 (Final)</p></li><li class="listitem"><p>Debian GNU/Linux 6.0.6 (squeeze)</p></li><li class="listitem"><p>openSUSE 11.4</p></li><li class="listitem"><p>openSUSE 12.1</p></li><li class="listitem"><p>openSUSE 12.2</p></li></ul></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + For additional information on distributions that support the + Yocto Project, see the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_top">Distribution Support</a> wiki page. + </div></div><div class="section" title="1.3.2. Required Packages for the Host Development System"><div class="titlepage"><div><div><h3 class="title"><a id="required-packages-for-the-host-development-system"></a>1.3.2. Required Packages for the Host Development System</h3></div></div></div><p> + 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 by Linux distribution and + further categorized by function. + </p><div class="section" title="1.3.2.1. Ubuntu"><div class="titlepage"><div><div><h4 class="title"><a id="ubuntu-packages"></a>1.3.2.1. Ubuntu</h4></div></div></div><p> + The following list shows the required packages by function + given a supported Ubuntu Linux distribution: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image on a headless + system: + </p><pre class="literallayout"> + $ sudo apt-get install gawk wget git-core diffstat unzip texinfo \ + build-essential chrpath + </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p><pre class="literallayout"> + $ sudo apt-get install libsdl1.2-dev xterm + </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p><pre class="literallayout"> + $ sudo apt-get install make xsltproc docbook-utils fop + </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>: + </p><pre class="literallayout"> + $ sudo apt-get install autoconf automake libtool libglib2.0-dev + </pre></li></ul></div><p> + </p></div><div class="section" title="1.3.2.2. Fedora Packages"><div class="titlepage"><div><div><h4 class="title"><a id="fedora-packages"></a>1.3.2.2. Fedora Packages</h4></div></div></div><p> + The following list shows the required packages by function + given a supported Fedora Linux distribution: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image for a headless + system: + </p><pre class="literallayout"> + $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ + diffutils diffstat git cpp gcc gcc-c++ eglibc-devel texinfo chrpath \ + ccache + </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p><pre class="literallayout"> + $ sudo yum install SDL-devel xterm + </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p><pre class="literallayout"> + $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt + </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>: + </p><pre class="literallayout"> + $ sudo yum install autoconf automake libtool glib2-devel + </pre></li></ul></div><p> + </p></div><div class="section" title="1.3.2.3. OpenSUSE Packages"><div class="titlepage"><div><div><h4 class="title"><a id="opensuse-packages"></a>1.3.2.3. OpenSUSE Packages</h4></div></div></div><p> + The following list shows the required packages by function + given a supported OpenSUSE Linux distribution: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image for a headless + system: + </p><pre class="literallayout"> + $ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \ + diffstat texinfo python-curses + </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p><pre class="literallayout"> + $ sudo zypper install libSDL-devel xterm + </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p><pre class="literallayout"> + $ sudo zypper install make fop xsltproc + </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>: + </p><pre class="literallayout"> + $ sudo zypper install autoconf automake libtool glib2-devel + </pre></li></ul></div><p> + </p></div><div class="section" title="1.3.2.4. CentOS Packages"><div class="titlepage"><div><div><h4 class="title"><a id="centos-packages"></a>1.3.2.4. CentOS Packages</h4></div></div></div><p> + The following list shows the required packages by function + given a supported CentOS Linux distribution: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span> + Packages needed to build an image for a headless + system: + </p><pre class="literallayout"> + $ sudo yum -y install gawk make wget tar bzip2 gzip python unzip perl patch \ + diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath + </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span> + Packages recommended if the host system has graphics support: + </p><pre class="literallayout"> + $ sudo yum -y install SDL-devel xterm + </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span> + Packages needed if you are going to build out the + Yocto Project documentation manuals: + </p><pre class="literallayout"> + $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt + </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span> + Packages needed if you are going to be using the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>: + </p><pre class="literallayout"> + $ sudo yum -y install autoconf automake libtool glib2-devel + </pre></li></ul></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Depending on the CentOS version you are using, other requirements + and dependencies might exist. + For details, you should look at the CentOS sections on the + <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_top">Poky/GettingStarted/Dependencies</a> + wiki page.</div><p> + </p></div></div></div><div class="section" title="1.4. Obtaining the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div><p> + The Yocto Project development team makes the Yocto Project available through a number + of methods: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through + <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_top">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at + <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_top">http://autobuilder.yoctoproject.org/nightly</a>. + These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and + experimental builds.</p></li><li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases + of the Yocto Project and supported BSPs at the + <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>. + Along with these downloads, you can find lots of other information at this site. + </p></li></ul></div><p> + </p></div><div class="section" title="1.5. Development Checkouts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div><p> + Development using the Yocto Project requires a local + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, + or by cloning a copy of the upstream + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">Poky</a> Git repository. + For information on both these methods, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#getting-setup" target="_top">Getting Setup</a>" + section in the Yocto Project Development Manual. + </p></div></div> + + <div class="chapter" title="Chapter 2. Using the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd><dt><span class="section"><a href="#maintaining-build-output-quality">2.4. Maintaining Build Output Quality</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-and-disabling-build-history">2.4.1. Enabling and Disabling Build History</a></span></dt><dt><span class="section"><a href="#understanding-what-the-build-history-contains">2.4.2. Understanding What the Build History Contains</a></span></dt></dl></dd></dl></div><p> + 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. + </p><div class="section" title="2.1. Running a Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div><p> + 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 + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#building-image" target="_top">Building an Image</a>" + section of the Yocto Project Quick Start. + </p><div class="section" title="2.1.1. Build Overview"><div class="titlepage"><div><div><h3 class="title"><a id="build-overview"></a>2.1.1. Build Overview</h3></div></div></div><p> + The first thing you need to do is set up the OpenEmbedded build environment by sourcing + the <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">environment setup script</a> as follows: + </p><pre class="literallayout"> + $ source oe-init-build-env [build_dir] + </pre><p> + </p><p> + The <code class="filename">build_dir</code> is optional and specifies the directory the + OpenEmbedded build system uses for the build - + the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + If you do not specify a Build Directory it defaults to <code class="filename">build</code> + in your current working directory. + A common practice is to use a different Build Directory for different targets. + For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code> + target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target. + See <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a> + for more information on this script. + </p><p> + Once the build environment is set up, you can build a target using: + </p><pre class="literallayout"> + $ bitbake <target> + </pre><p> + </p><p> + The <code class="filename">target</code> is the name of the recipe you want to build. + Common targets are the images in <code class="filename">meta/recipes-core/images</code>, + <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + Or, the target can be the name of a recipe for a specific piece of software such as + <span class="application">busybox</span>. + For more details about the images the OpenEmbedded build system supports, see the + "<a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>" chapter. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Building an image without GNU General Public License Version 3 (GPLv3) components + is only supported for minimal and base images. + See the "<a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>" chapter for more information. + </div></div><div class="section" title="2.1.2. Building an Image Using GPL Components"><div class="titlepage"><div><div><h3 class="title"><a id="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div><p> + 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. + </p></div></div><div class="section" title="2.2. Installing and Using the Result"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div><p> + 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 + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> in + <code class="filename">tmp/deploy/images</code>. + For information on how to run pre-built images such as <code class="filename">qemux86</code> + and <code class="filename">qemuarm</code>, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>" + section in the Yocto Project Quick Start. + For information about how to install these images, see the documentation for your + particular board/machine. + </p></div><div class="section" title="2.3. Debugging Build Failures"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div><p> + 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. + </p><div class="section" title="2.3.1. Task Failures"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in + <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. + For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86 + machine (<code class="filename">qemux86</code>) might be + <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</code>. + To see what BitBake runs to generate that log, look at the corresponding + <code class="filename">run.do_taskname.pid</code> file located in the same directory. + </p><p> + Presently, the output from Python tasks is sent directly to the console. + </p></div><div class="section" title="2.3.2. Running Specific Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div><p> + Any given package consists of a set of tasks. + The standard BitBake behavior in most cases is: <code class="filename">fetch</code>, + <code class="filename">unpack</code>, + <code class="filename">patch</code>, <code class="filename">configure</code>, + <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>, + <code class="filename">package_write</code>, and <code class="filename">build</code>. + The default task is <code class="filename">build</code> and any tasks on which it depends + build first. + Some tasks exist, such as <code class="filename">devshell</code>, that 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 + <code class="filename">-c</code> option in BitBake as follows: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop -c devshell + </pre><p> + </p><p> + If you wish to rerun a task, use the <code class="filename">-f</code> force option. + For example, the following sequence forces recompilation after changing files in the + working directory. + </p><pre class="literallayout"> + $ bitbake matchbox-desktop + . + . + [make some changes to the source code in the working directory] + . + . + $ bitbake matchbox-desktop -c compile -f + $ bitbake matchbox-desktop + </pre><p> + </p><p> + This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it. + The last command reruns all tasks (basically the packaging tasks) after the compile. + BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore + understands that the other tasks also need to be run again. + </p><p> + You can view a list of tasks in a given package by running the + <code class="filename">listtasks</code> task as follows: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop -c listtasks + </pre><p> + The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>. + </p></div><div class="section" title="2.3.3. Dependency Graphs"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div><p> + Sometimes it can be hard to see why BitBake wants to build some other packages before a given + package you have specified. + The <code class="filename">bitbake -g targetname</code> command creates the + <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>, + and <code class="filename">task-depends.dot</code> files in the current directory. + These files show the package and task dependencies and are useful for debugging problems. + You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to + display the results in a more human-readable form. + </p></div><div class="section" title="2.3.4. General BitBake Problems"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div><p> + You can see debug output from BitBake by using the <code class="filename">-D</code> option. + The debug output gives more information about what BitBake + is doing and the reason behind it. + Each <code class="filename">-D</code> option you use increases the logging level. + The most common usage is <code class="filename">-DDD</code>. + </p><p> + The output from <code class="filename">bitbake -DDD -v targetname</code> 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. + </p></div><div class="section" title="2.3.5. Building with No Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div><p> + If you really want to build a specific <code class="filename">.bb</code> file, you can use + the command form <code class="filename">bitbake -b <somepath/somefile.bb></code>. + This command form does not check for dependencies so you should use it + only when you know its dependencies already exist. + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match. + </p></div><div class="section" title="2.3.6. Variables"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div><p> + The <code class="filename">-e</code> option dumps the resulting environment for + either the configuration (no package specified) or for a + specific package when specified; or <code class="filename">-b recipename</code> + to show the environment from parsing a single recipe file only. + </p></div><div class="section" title="2.3.7. Recipe Logging Mechanisms"><div class="titlepage"><div><div><h3 class="title"><a id="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div><p> + Best practices exist while writing recipes that both log build progress and + act on build conditions such as warnings and errors. + Both Python and Bash language bindings exist for the logging mechanism: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake + supports several loglevels: <code class="filename">bb.fatal</code>, + <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>, + <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>, + and <code class="filename">bb.debug</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set + of loglevels exist and are accessed with a similar syntax: + <code class="filename">bbfatal</code>, <code class="filename">bberror</code>, + <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>, + <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li></ul></div><p> + </p><p> + For guidance on how logging is handled in both Python and Bash recipes, see the + <code class="filename">logging.bbclass</code> file in the + <code class="filename">meta/classes</code> folder of the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </p><div class="section" title="2.3.7.1. Logging With Python"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div><p> + 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. + </p><p> + Following is an example written in Python. + The code handles logging for a function that determines the number of tasks + needed to be run: + </p><pre class="literallayout"> + 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") + } + </pre><p> + </p></div><div class="section" title="2.3.7.2. Logging With Bash"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div><p> + 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. + </p><p> + Following is an example written in Bash. + The code logs the progress of the <code class="filename">do_my_function</code> function. + </p><pre class="literallayout"> + 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" + } + </pre><p> + </p></div></div><div class="section" title="2.3.8. Other Tips"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div><p> + Here are some other tips that you might find useful: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>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 + <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>. + </p></li><li class="listitem"><p>If you want to remove the psplash boot splashscreen, + add <code class="filename">psplash=false</code> to the kernel command line. + Doing so prevents psplash 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). + </p></li></ul></div><p> + </p></div></div><div class="section" title="2.4. Maintaining Build Output Quality"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="maintaining-build-output-quality"></a>2.4. Maintaining Build Output Quality</h2></div></div></div><p> + A build's quality can be influenced by many things. + 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, + then 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. + </p><p> + The <code class="filename">buildhistory</code> 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. + </p><p> + The remainder of this section describes the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>How you can enable and disable + build history</p></li><li class="listitem"><p>How to understand what the build history contains + </p></li><li class="listitem"><p>How to limit the information used for build history + </p></li><li class="listitem"><p>How to examine the build history from both a + command-line and web interface</p></li></ul></div><p> + </p><div class="section" title="2.4.1. Enabling and Disabling Build History"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-and-disabling-build-history"></a>2.4.1. Enabling and Disabling Build History</h3></div></div></div><p> + Build history is disabled by default. + To enable it, add the following statements to the end of your + <code class="filename">conf/local.conf</code> file found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>: + </p><pre class="literallayout"> + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + </pre><p> + Enabling build history as previously described + causes the build process to collect build + output information and commit it to a local + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#git" target="_top">Git</a> repository. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Enabling build history increases your build times slightly, + particularly for images, and increases the amount of disk + space used during the build. + </div><p> + </p><p> + You can disable build history by removing the previous statements + from your <code class="filename">conf/local.conf</code> file. + However, you should realize that enabling and disabling + build history in this manner can change the + <code class="filename">do_package</code> task checksums, which if you + are using the OEBasicHash signature generator (the default + for many current distro configurations including + <code class="filename">DISTRO = "poky"</code> and + <code class="filename">DISTRO = ""</code>) will result in the packaging + tasks being re-run during the subsequent build. + </p><p> + To disable the build history functionality without causing the + packaging tasks to be re-run, add just this statement to your + <code class="filename">conf/local.conf</code> file: + </p><pre class="literallayout"> + BUILDHISTORY_FEATURES = "" + </pre><p> + </p></div><div class="section" title="2.4.2. Understanding What the Build History Contains"><div class="titlepage"><div><div><h3 class="title"><a id="understanding-what-the-build-history-contains"></a>2.4.2. Understanding What the Build History Contains</h3></div></div></div><p> + Build history information is kept in + <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">$TMPDIR</code></a><code class="filename">/buildhistory</code> + in the Build Directory. + The following is an example abbreviated listing: + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/buildhistory.png" align="middle" width="540" /></td></tr></table><p> + </p><div class="section" title="2.4.2.1. Build History Package Information"><div class="titlepage"><div><div><h4 class="title"><a id="build-history-package-information"></a>2.4.2.1. Build History Package Information</h4></div></div></div><p> + The history for each package contains a text file that has + name-value pairs with information about the package. + For example, <code class="filename">buildhistory/packages/core2-poky-linux/busybox/busybox/latest</code> + contains the following: + </p><pre class="literallayout"> + PV = 1.19.3 + PR = r3 + RDEPENDS = update-rc.d eglibc (>= 2.13) + RRECOMMENDS = busybox-syslog busybox-udhcpc + PKGSIZE = 564701 + FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ + /etc /com /var /bin/* /sbin/* /lib/*.so.* /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 = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh + </pre><p> + Most of these name-value pairs corresponds to variables used + to produce the package. + The exceptions are <code class="filename">FILELIST</code>, which is the + actual list of files in the package, and + <code class="filename">PKGSIZE</code>, which is the total size of files + in the package in bytes. + </p><p> + There is also a file corresponding to the recipe from which the + package came (e.g. + <code class="filename">buildhistory/packages/core2-poky-linux/busybox/latest</code>): + </p><pre class="literallayout"> + PV = 1.19.3 + PR = r3 + DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ + virtual/libc update-rc.d-native + PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ + busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ + busybox-staticdev busybox-locale + </pre><p> + </p></div><div class="section" title="2.4.2.2. Build History Image Information"><div class="titlepage"><div><div><h4 class="title"><a id="build-history-image-information"></a>2.4.2.2. Build History Image Information</h4></div></div></div><p> + The files produced for each image are as follows: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>build-id:</em></span> + Human-readable information about the build configuration + and metadata source revisions.</p></li><li class="listitem"><p><span class="emphasis"><em>*.dot:</em></span> + Dependency graphs for the image that are + compatible with <code class="filename">graphviz</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>files-in-image.txt:</em></span> + A list of files in the image with permissions, + owner, group, size, and symlink information. + </p></li><li class="listitem"><p><span class="emphasis"><em>image-info.txt:</em></span> + A text file containing name-value pairs with information + about the image. + See the following listing example for more information. + </p></li><li class="listitem"><p><span class="emphasis"><em>installed-package-names.txt:</em></span> + A list of installed packages by name only.</p></li><li class="listitem"><p><span class="emphasis"><em>installed-package-sizes.txt:</em></span> + A list of installed packages ordered by size. + </p></li><li class="listitem"><p><span class="emphasis"><em>installed-packages.txt:</em></span> + A list of installed packages with fuill package + filenames.</p></li></ul></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Installed package information is able to be gathered and + produced even if package management is disabled for the final + image. + </div><p> + </p><p> + Here is an example of <code class="filename">image-info.txt</code>: + </p><pre class="literallayout"> + DISTRO = poky + DISTRO_VERSION = 1.1+snapshot-20120207 + USER_CLASSES = image-mklibs image-prelink + IMAGE_CLASSES = image_types + IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ + package-management ssh-server-dropbear package-management + IMAGE_LINGUAS = en-us en-gb + IMAGE_INSTALL = task-core-boot task-base-extended + BAD_RECOMMENDATIONS = + ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + IMAGESIZE = 171816 + </pre><p> + Other than <code class="filename">IMAGESIZE</code>, 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. + </p></div><div class="section" title="2.4.2.3. Using Build History to Gather Image Information Only"><div class="titlepage"><div><div><h4 class="title"><a id="using-build-history-to-gather-image-information-only"></a>2.4.2.3. Using Build History to Gather Image Information Only</h4></div></div></div><p> + 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 history or any package information, + you can enable writing only image information without + any history by adding the following + to your <code class="filename">conf/local.conf</code> file found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>: + </p><pre class="literallayout"> + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "0" + BUILDHISTORY_FEATURES = "image" + </pre><p> + </p></div><div class="section" title="2.4.2.4. Examining Build History Information"><div class="titlepage"><div><div><h4 class="title"><a id="examining-build-history-information"></a>2.4.2.4. Examining Build History Information</h4></div></div></div><p> + You can examine build history output from the command line or + from a web interface. + </p><p> + To see any changes that have occurred (assuming you have + <code class="filename">BUILDHISTORY_COMMIT = "1"</code>), you can simply + use any Git command that allows you to view the history of + a repository. + Here is one method: + </p><pre class="literallayout"> + $ git log -p + </pre><p> + 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). + </p><p> + A command-line tool called <code class="filename">buildhistory-diff</code> + 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: + </p><pre class="literallayout"> + $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ + Changes to images/qemux86_64/eglibc/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/eglibc/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" + </pre><p> + </p><p> + To see changes to the build history using a web interface, follow + the instruction in the <code class="filename">README</code> file here. + <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/</a>. + </p><p> + Here is a sample screenshot of the interface: + </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="130%"><tr><td align="center"><img src="figures/buildhistory-web.png" align="middle" height="468" /></td></tr></table><p> + </p></div></div></div></div> + + <div class="chapter" title="Chapter 3. Technical Details"><div class="titlepage"><div><div><h2 class="title"><a id="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></div><p> + This chapter provides technical details for various parts of the Yocto Project. + Currently, topics include Yocto Project components and shared state (sstate) cache. + </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div><p> + The BitBake task executor together with various types of configuration files form the + OpenEmbedded Core. + This section overviews the BitBake task executor and the + configuration files by describing what they are used for and how they interact. + </p><p> + BitBake handles the parsing and execution of the data files. + The data itself is of various types: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular + pieces of software</p></li><li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build + information (e.g. how to build a Linux kernel).</p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings, + policy decisions, etc. + Configuration data acts as the glue to bind everything together.</p></li></ul></div><p> + For more information on data, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#yocto-project-terms" target="_top">Yocto Project Terms</a>" + section in the Yocto Project Development Manual. + </p><p> + BitBake knows how to combine multiple data sources together and refers to each data source + as a layer. + For information on layers, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and + Creating Layers</a>" section of the Yocto Project Development Manual. + </p><p> + Following are some brief details on these core components. + For more detailed information on these components see the + "<a class="link" href="#ref-structure" title="Chapter 5. Source Directory Structure">Directory Structure</a>" chapter. + </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div><p> + BitBake is the tool at the heart of the OpenEmbedded build system and is responsible + for parsing the metadata, generating a list of tasks from it, + and then executing those tasks. + To see a list of the options BitBake supports, use the following help command: + </p><pre class="literallayout"> + $ bitbake --help + </pre><p> + </p><p> + The most common usage for BitBake is <code class="filename">bitbake <packagename></code>, where + <code class="filename">packagename</code> 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 <code class="filename">.bb</code> filename. + So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you + might type the following: + </p><pre class="literallayout"> + $ bitbake matchbox-desktop + </pre><p> + Several different versions of <code class="filename">matchbox-desktop</code> 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 + "<a class="link" href="#ref-bitbake-providers" title="6.2. Preferences and Providers">Preferences and Providers</a>" section. + </p><p> + BitBake also tries to execute any dependent tasks first. + So for example, before building <code class="filename">matchbox-desktop</code>, BitBake + would build a cross compiler and <code class="filename">eglibc</code> if they had not already + been built. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code> + GNU version of the Unix standard C library. By default, the OpenEmbedded build system + builds with <code class="filename">eglibc</code>.</div><p> + </p><p> + A useful BitBake option to consider is the <code class="filename">-k</code> or + <code class="filename">--continue</code> option. + This option instructs BitBake to try and continue processing the job as much + 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. + </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div><p> + The <code class="filename">.bb</code> files are usually referred to as "recipes." + In general, a recipe contains information about a single piece of software. + The information includes the location from which to download the source patches + (if any are needed), which special configuration options to apply, + how to compile the source files, and how to package the compiled output. + </p><p> + The term "package" can also be used to describe recipes. + However, since the same word is used for the packaged output from the OpenEmbedded + build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files), + this document avoids using the term "package" when referring to recipes. + </p></div><div class="section" title="3.1.3. Classes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div><p> + Class files (<code class="filename">.bbclass</code>) contain information that is useful to share + between metadata files. + An example is the Autotools class, which contains + common settings for any application that Autotools uses. + The "<a class="link" href="#ref-classes" title="Chapter 7. Classes">Classes</a>" chapter provides details + about common classes and how to use them. + </p></div><div class="section" title="3.1.4. Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div><p> + The configuration files (<code class="filename">.conf</code>) 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 (<code class="filename">local.conf</code>, which is found + in the <a class="ulink" href="build-directory" target="_top">Build Directory</a>). + </p></div></div><div class="section" title="3.2. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div><p> + By design, the OpenEmbedded build system builds everything from scratch unless + BitBake can determine that parts don't 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. + </p><p> + 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 don't necessarily need rebuilt. + </p><p> + 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: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">What pieces of the system have changed and what pieces have not changed?</li><li class="listitem">How are changed pieces of software removed and replaced?</li><li class="listitem">How are pre-built components that don't need to be rebuilt from scratch + used when they are available?</li></ul></div><p> + </p><p> + 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. + </p><p> + The rest of this section goes into detail about the overall incremental build + architecture, the checksums (signatures), shared state, and some tips and tricks. + </p><div class="section" title="3.2.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title"><a id="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div><p> + When determining what parts of the system need to be built, BitBake + uses a per-task basis and does not use 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, <code class="filename">do_install</code> and <code class="filename">do_package</code> + output are still valid. + However, with a per-recipe approach, the build would not include the + <code class="filename">.deb</code> files. + Consequently, you would have to invalidate the whole build and rerun it. + Rerunning everything is not the best situation. + 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. + </p></div><div class="section" title="3.2.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title"><a id="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div><p> + 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. + </p><p> + 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 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>. + It does not matter if the working directory changes because it should not + affect the output for target packages. + Also, the build process has the objective of making native/cross packages relocatable. + The checksum therefore needs to exclude <code class="filename">WORKDIR</code>. + The simplistic approach for excluding the working directory is to set + <code class="filename">WORKDIR</code> to some fixed value and create the checksum + for the "run" script. + </p><p> + 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. + </p><p> + 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. + </p><p> + Like the <code class="filename">WORKDIR</code> 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: + </p><pre class="literallayout"> + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + </pre><p> + This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not + depend on the value of <code class="filename">MACHINE</code>, even if it does reference it. + </p><p> + 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: + </p><pre class="literallayout"> + PACKAGE_ARCHS[vardeps] = "MACHINE" + </pre><p> + This example explicitly adds the <code class="filename">MACHINE</code> variable as a + dependency for <code class="filename">PACKAGE_ARCHS</code>. + </p><p> + Consider a case with inline python, for example, where BitBake is not + able to figure out dependencies. + When running in debug mode (i.e. using <code class="filename">-DDD</code>), 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. + </p><p> + 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 Build Directory. + 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. + </p><p> + 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 statements effectively result in a list of global variable + dependency excludes - variables never included in any checksum: + </p><pre class="literallayout"> + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" + BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" + BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" + BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" + </pre><p> + The previous example actually excludes + <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a> + since it is actually constructed as a path within + <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on + the whitelist. + </p><p> + 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 <code class="filename">meta/lib/oe/sstatesig.py</code> 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 <code class="filename">OE-Core</code> + 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. + <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default + through this setting in the <code class="filename">bitbake.conf</code> file: + </p><pre class="literallayout"> + BB_SIGNATURE_HANDLER ?= "OEBasic" + </pre><p> + The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the + "OEBasic" version but adds the task hash to the stamp files. + 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 <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> + values and changes to metadata automatically ripple across the build. + Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code> + but is the default in <code class="filename">poky</code>. + </p><p> + 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: + </p><pre class="literallayout"> + BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe + BB_BASEHASH_<filename:taskname> - the base hashes for each dependent task + BBHASHDEPS_<filename:taskname> - The task dependencies for each task + BB_TASKHASH - the hash of the currently running task + </pre><p> + </p></div><div class="section" title="3.2.3. Shared State"><div class="titlepage"><div><div><h3 class="title"><a id="shared-state"></a>3.2.3. Shared State</h3></div></div></div><p> + Checksums and dependencies, as discussed in the previous section, solve half the + problem. + 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. + </p><p> + The shared state class (<code class="filename">sstate.bbclass</code>) + 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 doesn't need to worry about its source. + </p><p> + There are two types of output, one is just about creating a directory + in <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>. + A good example is the output of either <code class="filename">do_install</code> or + <code class="filename">do_package</code>. + The other type of output occurs when a set of data is merged into a shared directory + tree such as the sysroot. + </p><p> + The Yocto Project team has tried to keep the details of the implementation hidden in + <code class="filename">sstate.bbclass</code>. + From a user's perspective, adding shared state wrapping to a task + is as simple as this <code class="filename">do_deploy</code> example taken from + <code class="filename">do_deploy.bbclass</code>: + </p><pre class="literallayout"> + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-name] = "deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + </pre><p> + In the 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 <code class="filename">_setscene</code> variant of the task and add the task + name to the <code class="filename">SSTATETASKS</code> list. + </p><p> + If you have a directory whose contents you need to preserve, you can do this with + a line like the following: + </p><pre class="literallayout"> + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + </pre><p> + This method, as well as the following example, also works for multiple directories. + </p><pre class="literallayout"> + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + do_package[sstate-lockfile] = "${PACKAGELOCK}" + </pre><p> + 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. + </p><p> + Behind the scenes, the shared state code works by looking in + <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> and + <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a> + for shared state files. + Here is an example: + </p><pre class="literallayout"> + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The shared state directory (<code class="filename">SSTATE_DIR</code>) 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 <code class="filename">SSTATE_DIR</code>, you must + specify "PATH" as part of the URI to enable the build system + to map to the appropriate subdirectory. + </div><p> + </p><p> + 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. + </p><p> + The build processes uses the <code class="filename">*_setscene</code> 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. + </p><p> + As a real world example, the aim is when building an IPK-based image, + only the <code class="filename">do_package_write_ipk</code> 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. + </p></div><div class="section" title="3.2.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title"><a id="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div><p> + 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. + </p><div class="section" title="3.2.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title"><a id="debugging"></a>3.2.4.1. Debugging</h4></div></div></div><p> + When things go wrong, debugging needs to be straightforward. + Because of this, the Yocto Project team included strong debugging + tools: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Whenever a shared state package is written out, so is a + corresponding <code class="filename">.siginfo</code> file. + This practice results in a pickled python database of all + the metadata that went into creating the hash for a given shared state + package.</p></li><li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code> + (or <code class="filename">-S</code>) option, BitBake dumps out + <code class="filename">.siginfo</code> files in + the stamp directory for every task it would have executed instead of + building the specified target package.</p></li><li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that + can process these <code class="filename">.siginfo</code> files. + If one file is specified, it will dump out the dependency + information in the file. + If two files are specified, it will compare the two files and dump out + the differences between the two. + This allows the question of "What changed between X and Y?" to be + answered easily.</p></li></ul></div><p> + </p></div><div class="section" title="3.2.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title"><a id="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div><p> + The shared state code uses checksums and shared state + cache to avoid unnecessarily rebuilding tasks. + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes that are not factored + into the checksum calculation, but do affect a task's output. + A good example is perhaps when a tool changes its output. + Let's say that the output of <code class="filename">rpmdeps</code> needed to change. + The result of the change should be that all the "package", "package_write_rpm", + and "package_deploy-rpm" shared state cache items would become invalid. + But, because this is a change that is external to the code and therefore implicit, + the associated shared state cache items do not become invalidated. + In this case, the build process would use the cached items rather than running the + task again. + Obviously, these types of implicit changes can cause problems. + </p><p> + To avoid these problems during the build, you need to understand the effects of any + change you make. + Note that any changes you make directly to a function automatically are factored into + the checksum calculation and thus, will invalidate the associated area of sstate cache. + 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. + Once you are aware of such a change, you can take steps to invalidate the cache + and force the task to run. + The step to take is 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 <code class="filename">do_package</code> or the comments of one of the functions it calls. + The change is purely cosmetic, but it causes the checksum to be recalculated and + forces the task to be run again. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + For an example of a commit that makes a cosmetic change to invalidate + a shared state, see this + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>. + </div></div></div></div><div class="section" title="3.3. x32"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="x32"></a>3.3. x32</h2></div></div></div><p> + x32 is a new 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. + </p><p> + 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. + </p><div class="section" title="3.3.1. Support"><div class="titlepage"><div><div><h3 class="title"><a id="support"></a>3.3.1. Support</h3></div></div></div><p> + While the x32 psABI specifications are not fully finalized, this Yocto Project + release supports current development specifications of x32 psABI. + As of this release of the Yocto Project, x32 psABI support exists as follows: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets. + </p></li><li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code> + layer on top of the OE-core/Yocto layer.</p></li><li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer + is used for building x32 psABI program binaries.</p></li><li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li><li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and + <code class="filename">core-image-sato</code> images.</p></li></ul></div><p> + </p></div><div class="section" title="3.3.2. Future Development and Limitations"><div class="titlepage"><div><div><h3 class="title"><a id="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div><p> + As of this Yocto Project release, the x32 psABI kernel and library interfaces + specifications are not finalized. + </p><p> + Future Plans for the x32 psABI in the Yocto Project include the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enhance and fix the few remaining recipes so they + work with and support x32 toolchains.</p></li><li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li><li class="listitem"><p>Support larger images.</p></li><li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from + <code class="filename">experimental/meta-x32</code> into OE-core.</p></li></ul></div><p> + </p></div><div class="section" title="3.3.3. Using x32 Right Now"><div class="titlepage"><div><div><h3 class="title"><a id="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div><p> + Despite the fact the x32 psABI support is in development state for this release of the + Yocto Project, you can follow these steps to use the x32 spABI: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + You can find the <code class="filename">experimental/meta-x32</code> source repository at + <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>.</p></li><li class="listitem"><p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes + the <code class="filename">meta-x32</code>. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + /home/nitin/prj/poky.git/meta-yocto-bsp \ + /home/nitin/prj/meta-x32.git \ + " + BBLAYERS_NON_REMOVABLE ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + " + </pre></li><li class="listitem"><p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code> + machines by editing the <code class="filename">conf/local.conf</code> like this: + </p><pre class="literallayout"> + MACHINE = "qemux86-64" + DEFAULTTUNE = "x86-64-x32" + baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \ + or 'INVALID'), True) or 'lib'}" + #MACHINE = "atom-pc" + #DEFAULTTUNE = "core2-64-x32" + </pre></li><li class="listitem"><p>As usual, use BitBake to build an image that supports the x32 psABI. + Here is an example: + </p><pre class="literallayout"> + $ bitake core-image-sato + </pre></li><li class="listitem"><p>As usual, run your image using QEMU: + </p><pre class="literallayout"> + $ runqemu qemux86-64 core-image-sato + </pre></li></ul></div><p> + </p></div></div><div class="section" title="3.4. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licenses"></a>3.4. Licenses</h2></div></div></div><p> + 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. + </p><p> + For information that can help you maintain compliance with various open + source licensing during the lifecycle of the product, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#maintaining-open-source-license-compliance-during-your-products-lifecycle" target="_top">Maintaining Open Source License Compliance During Your Project's Lifecycle</a>" section + in the Yocto Project Development Manual. + </p><div class="section" title="3.4.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div><p> + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code> + 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. + </p><div class="section" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.4.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div><p> + The <code class="filename">LIC_FILES_CHKSUM</code> + variable contains checksums of the license text in the source code for the recipe. + Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>: + </p><pre class="literallayout"> + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + </pre><p> + </p><p> + The build system uses the + <code class="filename"><a class="link" href="#var-S" title="S">S</a></code> variable as the + default directory used when searching files listed in + <code class="filename">LIC_FILES_CHKSUM</code>. + The previous example employs the default directory. + </p><p> + You can also use relative paths as shown in the following example: + </p><pre class="literallayout"> + LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + </pre><p> + </p><p> + In this example, the first line locates a file in + <code class="filename">${S}/src/ls.c</code>. + The second line refers to a file in + <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent + of <code class="filename"><a class="link" href="#var-S" title="S">S</a></code>. + </p><p> + Note that this variable is mandatory for all recipes, unless the + <code class="filename">LICENSE</code> variable is set to "CLOSED". + </p></div><div class="section" title="3.4.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div><p> + As mentioned in the previous section, the + <code class="filename">LIC_FILES_CHKSUM</code> 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. + </p><p> + 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. + </p><p> + There is no limit to how many files you can specify using the + <code class="filename">LIC_FILES_CHKSUM</code> 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. + </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + 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. + </div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + If the whole file contains only license text, you do not need to use the "beginline" and + "endline" parameters. + </div></div></div><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div><p> + 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 <code class="filename">LICENSE_FLAGS</code> variable + definition in the affected recipe. + For instance, the + <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> + recipe contains the following statement: + </p><pre class="literallayout"> + LICENSE_FLAGS = "commercial" + </pre><p> + Here is a slightly more complicated example that contains both an + explicit recipe name and version (after variable expansion): + </p><pre class="literallayout"> + LICENSE_FLAGS = "license_${PN}_${PV}" + </pre><p> + In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code> + definition to be enabled and included in an image, it + needs to have a matching entry in the global + <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable + typically defined in your <code class="filename">local.conf</code> file. + For example, to enable + the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code> + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>. + See the + "<a class="link" href="#license-flag-matching" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section + for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works. + Here is the example: + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + </pre><p> + Likewise, to additionally enable the package built from the recipe containing + <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming + that the actual recipe name was <code class="filename">emgd_1.10.bb</code>, + the following string would enable that package as well as + the original <code class="filename">gst-plugins-ugly</code> package: + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + </pre><p> + 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". + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial license" + </pre><p> + </p><div class="section" title="3.4.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title"><a id="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div><p> + The definition of 'matching' in reference to a + recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple. + However, some things exist that you should know about in order to + correctly and effectively use it. + </p><p> + Before a flag + defined by a particular recipe is tested against the + contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the + string <code class="filename">_${PN}</code> (with + <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is + appended to the flag, thus automatically making each + <code class="filename">LICENSE_FLAGS</code> value recipe-specific. + That string is + then matched against the whitelist. + So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe + "foo" for example, the string <code class="filename">"commercial_foo"</code> + would normally be what is specified in the whitelist in order for it to + match. + </p><p> + You can broaden the match by + putting any "_"-separated beginning subset of a + <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also + match. + For example, simply specifying "commercial" in + the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code> + definition starting with "commercial" such as + "commercial_foo" and "commercial_bar", which are the + strings that would be automatically generated for + hypothetical "foo" and "bar" recipes assuming those + recipes had simply specified the following: + </p><pre class="literallayout"> + LICENSE_FLAGS = "commercial" + </pre><p> + </p><p> + Broadening the match allows for a range of specificity for the items + in the whitelist, from more general to perfectly + specific. + So you have the choice of exhaustively + enumerating each license flag in the whitelist to + allow only those specific recipes into the image, or + of using a more general string to pick up anything + matching just the first component or components of the specified + string. + </p><p> + This scheme works even if the flag already + has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is + redundant, but does not affect the outcome. + For example, a license flag of "commercial_1.2_foo" would + turn into "commercial_1.2_foo_foo" and would match + both the general "commercial" and the specific + "commercial_1.2_foo", as expected. + The flag would also match + "commercial_1.2_foo_foo" and "commercial_1.2", which + does not make much sense regarding use in the whitelist. + </p><p> + For a versioned string, you could instead specify + "commercial_foo_1.2", which would turn into + "commercial_foo_1.2_foo". + And, as expected, this flag allows + you to pick up this package along with + anything else "commercial" when you specify "commercial" + in the whitelist. + Or, the flag allows you to pick up this package along with anything "commercial_foo" + regardless of version when you use "commercial_foo" in the whitelist. + Finally, you can be completely specific about the package and version and specify + "commercial_foo_1.2" package and version. + </p></div><div class="section" title="3.4.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title"><a id="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div><p> + Other helpful variables related to commercial + license handling exist and are defined in the + <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file: + </p><pre class="literallayout"> + COMMERCIAL_AUDIO_PLUGINS ?= "" + COMMERCIAL_VIDEO_PLUGINS ?= "" + COMMERCIAL_QT = "" + </pre><p> + If you want to enable these components, you can do so by making sure you have + the following statements in your <code class="filename">local.conf</code> configuration file: + </p><pre class="literallayout"> + 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" + COMMERCIAL_QT ?= "qmmp" + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" + </pre><p> + 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 <code class="filename">LICENSE_FLAGS</code> containing + "commercial", which you may or may not want: + </p><pre class="literallayout"> + LICENSE_FLAGS_WHITELIST = "commercial" + </pre><p> + </p><p> + Specifying audio and video plug-ins as part of the + <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and + <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements + or commercial qt components as part of + the <code class="filename">COMMERCIAL_QT</code> statement (along + with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the + plug-ins or components into built images, thus adding + support for media formats or components. + </p></div></div></div></div> + + <div class="chapter" title="Chapter 4. Migrating to a Newer Yocto Project Release"><div class="titlepage"><div><div><h2 class="title"><a id="migration"></a>Chapter 4. Migrating to a Newer Yocto Project Release</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#moving-to-the-yocto-project-1.3-release">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt><dd><dl><dt><span class="section"><a href="#1.3-local-configuration">4.1.1. Local Configuration</a></span></dt><dt><span class="section"><a href="#1.3-recipes">4.1.2. Recipes</a></span></dt></dl></dd></dl></div><p> + This chapter provides information you can use to migrate work to a + newer Yocto Project release. You can find the same information in the + release notes for a given release. + </p><div class="section" title="4.1. Moving to the Yocto Project 1.3 Release"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="moving-to-the-yocto-project-1.3-release"></a>4.1. Moving to the Yocto Project 1.3 Release</h2></div></div></div><p> + This section provides migration information for moving to the + Yocto Project 1.3 Release. + </p><div class="section" title="4.1.1. Local Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="1.3-local-configuration"></a>4.1.1. Local Configuration</h3></div></div></div><p> + Differences include changes for + <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a> + and <code class="filename">bblayers.conf</code>. + </p><div class="section" title="4.1.1.1. SSTATE_MIRRORS"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-sstate-mirrors"></a>4.1.1.1. SSTATE_MIRRORS</h4></div></div></div><p> + The shared state cache (sstate-cache) as pointed to by + <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> by default + now has two-character subdirectories to prevent there being an issue with too + many files in the same directory. + Also, native sstate-cache packages will go into a subdirectory named using + the distro ID string. + If you copy the newly structured sstate-cache to a mirror location + (either local or remote) and then point to it in + <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>, + you need to append "PATH" to the end of the mirror URL so that + the path used by BitBake before the mirror substitution is + appended to the path used to access the mirror. + Here is an example: + </p><pre class="literallayout"> + SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" + </pre><p> + </p></div><div class="section" title="4.1.1.2. bblayers.conf"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-bblayers-conf"></a>4.1.1.2. bblayers.conf</h4></div></div></div><p> + The <code class="filename">meta-yocto</code> layer has been split into + two parts: <code class="filename">meta-yocto</code> and + <code class="filename">meta-yocto-bsp</code>, corresponding to the + Poky reference distro configuration and the reference + hardware Board Support Packages (BSPs), respectively. + When running BitBake or Hob for the first time after upgrading, + your <code class="filename">conf/bblayers.conf</code> file will be + updated to handle this change and you will be asked to + re-run/restart for the changes to take effect. + </p></div></div><div class="section" title="4.1.2. Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="1.3-recipes"></a>4.1.2. Recipes</h3></div></div></div><p> + Differences include changes for the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Python function whitespace</p></li><li class="listitem"><p><code class="filename">proto=</code> in <code class="filename">SRC_URI</code></p></li><li class="listitem"><p><code class="filename">nativesdk</code></p></li><li class="listitem"><p>Task recipes</p></li><li class="listitem"><p><code class="filename">IMAGE_FEATURES</code></p></li><li class="listitem"><p>Removed recipes</p></li></ul></div><p> + </p><div class="section" title="4.1.2.1. Python Function Whitespace"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-python-function-whitespace"></a>4.1.2.1. Python Function Whitespace</h4></div></div></div><p> + All Python functions must now use four spaces for indentation. + Previously, an inconsistent mix of spaces and tabs existed, + which made extending these functions using + <code class="filename">_append</code> or <code class="filename">_prepend</code> + complicated given that Python treats whitespace as + syntactically significant. + If you are defining or extending any Python functions (e.g. + <code class="filename">populate_packages</code>, <code class="filename">do_unpack</code>, + <code class="filename">do_patch</code> and so forth) in custom recipes + or classes, you need to ensure you are using consistent + four-space indentation. + </p></div><div class="section" title="4.1.2.2. proto= in SRC_URI"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-proto=-in-src-uri"></a>4.1.2.2. proto= in SRC_URI</h4></div></div></div><p> + Any use of <code class="filename">proto=</code> in + <a class="link" href="#var-SRC_URI" title="SRC_URI"><code class="filename">SRC_URI</code></a> + needs to be changed to <code class="filename">protocol=</code>. + In particular, this applies to the following URIs: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">svn://</code></p></li><li class="listitem"><p><code class="filename">bzr://</code></p></li><li class="listitem"><p><code class="filename">hg://</code></p></li><li class="listitem"><p><code class="filename">osc://</code></p></li></ul></div><p> + Other URIs were already using <code class="filename">protocol=</code>. + This change improves consistency. + </p></div><div class="section" title="4.1.2.3. nativesdk"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-nativesdk"></a>4.1.2.3. nativesdk</h4></div></div></div><p> + The suffix <code class="filename">nativesdk</code> is now implemented + as a prefix, which simplifies a lot of the packaging code for + <code class="filename">nativesdk</code> recipes. + All custom <code class="filename">nativesdk</code> recipes and any + references need to be updated to use + <code class="filename">nativesdk-*</code> instead of + <code class="filename">*-nativesdk</code>. + </p></div><div class="section" title="4.1.2.4. Task Recipes"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-task-recipes"></a>4.1.2.4. Task Recipes</h4></div></div></div><p> + "Task" recipes are now known as "Package groups" and have + been renamed from <code class="filename">task-*.bb</code> to + <code class="filename">packagegroup-*.bb</code>. + Existing references to the previous <code class="filename">task-*</code> + names should work in most cases as there is an automatic + upgrade path for most packages. + However, you should update references in your own recipes and + configurations as they could be removed in future releases. + You should also rename any custom <code class="filename">task-*</code> + recipes to <code class="filename">packagegroup-*</code>, and change + them to inherit <code class="filename">packagegroup</code> instead of + <code class="filename">task</code>, as well as taking the opportunity + to remove anything now handled by + <code class="filename">packagegroup.bbclass</code>, such as providing + <code class="filename">-dev</code> and <code class="filename">-dbg</code> + packages, setting + <a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM"><code class="filename">LIC_FILES_CHKSUM</code></a>, + and so forth. + See the + "<a class="link" href="#ref-classes-packagegroup" title="7.12. Package Groups - packagegroup.bbclass">Package Groups - packagegroup.bbclass</a>" + section for further details. + </p></div><div class="section" title="4.1.2.5. IMAGE_FEATURES"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-image-features"></a>4.1.2.5. IMAGE_FEATURES</h4></div></div></div><p> + Image recipes that previously included "apps-console-core" + in <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES"><code class="filename">IMAGE_FEATURES</code></a> + should now include "splash" instead to enable the boot-up + splash screen. + Retaining "apps-console-core" will still include the splash + screen generates a warning. + The "apps-x11-core" and "apps-x11-games" + <code class="filename">IMAGE_FEATURES</code> features have been removed. + </p></div><div class="section" title="4.1.2.6. Removed Recipes"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-removed-recipes"></a>4.1.2.6. Removed Recipes</h4></div></div></div><p> + The following recipes have been removed. + For most of them, it is unlikely that you would have any + references to them in your own metadata. + However, you should check your metadata against this list to be sure: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">libx11-trim</code></em></span>: + Replaced by <code class="filename">libx11</code>, which has a negligible + size difference with modern Xorg.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-xorg-lite</code></em></span>: + Use <code class="filename">xserver-xorg</code>, which has a negligible + size difference when DRI and GLX modules are not installed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-kdrive</code></em></span>: + Effectively unmaintained for many years.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">mesa-xlib</code></em></span>: + No longer serves any purpose.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">galago</code></em></span>: + Replaced by telepathy.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gail</code></em></span>: + Functionality was integrated into GTK+ 2.13.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">eggdbus</code></em></span>: + No longer needed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gcc-*-intermediate</code></em></span>: + The build has been restructured to avoid the need for + this step.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">libgsmd</code></em></span>: + Unmaintained for many years. + Functionality now provided by + <code class="filename">ofono</code> instead.</p></li><li class="listitem"><p><span class="emphasis"><em>contacts, dates, tasks, eds-tools</em></span>: + Largely unmaintained PIM application suite. + It has been moved to <code class="filename">meta-gnome</code> + in <code class="filename">meta-openembedded</code>.</p></li></ul></div><p> + In addition to the previously listed changes, the + <code class="filename">meta-demoapps</code> directory has also been removed + because the recipes in it were not being maintained and many + had become obsolete or broken. + Additionally, these recipes were not parsed in the default configuration. + Many of these recipes are already provided in an updated and + maintained form within OpenEmbedded community layers such as + <code class="filename">meta-oe</code> and <code class="filename">meta-gnome</code>. + For the remainder, you can now find them in the + <code class="filename">meta-extras</code> repository, which is in the + Yocto Project source repositories. + </p></div></div></div></div> + + <div class="chapter" title="Chapter 5. Source Directory Structure"><div class="titlepage"><div><div><h2 class="title"><a id="ref-structure"></a>Chapter 5. Source Directory Structure</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#structure-core">5.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">5.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">5.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">5.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">5.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto-bsp">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-hob">5.1.7. <code class="filename">meta-hob/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">5.1.9. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">5.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">5.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">5.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">5.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">5.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></div><p> + The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> consists of several components. + Understanding them and knowing where they are located is key to using the Yocto Project well. + This chapter describes the Source Directory and gives information about the various + files and directories. +</p><p> + For information on how to establish a local Source Directory on your development system, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#getting-setup" target="_top">Getting Set Up</a>" + section in the Yocto Project Development Manual. +</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + 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. +</div><div class="section" title="5.1. Top level core components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-core"></a>5.1. Top level core components</h2></div></div></div><div class="section" title="5.1.1. bitbake/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-bitbake"></a>5.1.1. <code class="filename">bitbake/</code></h3></div></div></div><p> + The <a class="ulink" href="source-directory" target="_top">Source Directory</a> + includes a copy of BitBake for ease of use. + The copy usually matches the current stable BitBake release from the BitBake project. + BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks + defined by that data. + Failures are usually from the metadata and not from BitBake itself. + Consequently, most users do not need to worry about BitBake. + </p><p> + When you run the <code class="filename">bitbake</code> command, the wrapper script in + <code class="filename">scripts/</code> is executed to run the main BitBake executable, + which resides in the <code class="filename">bitbake/bin/</code> directory. + Sourcing the <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a> + script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code> + directories (in that order) into the shell's <code class="filename">PATH</code> environment + variable. + </p><p> + For more information on BitBake, see the BitBake documentation + inculded in the <code class="filename">bitbake/doc/manual</code> directory of the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </p></div><div class="section" title="5.1.2. build/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-build"></a>5.1.2. <code class="filename">build/</code></h3></div></div></div><p> + This directory contains user configuration files and the output + generated by the OpenEmbedded build system in its standard configuration where + the source tree is combined with the output. + The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> + is created initially when you <code class="filename">source</code> + the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>. + </p><p> + It is also possible to place output and configuration + files in a directory separate from the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> + by providing a directory name when you <code class="filename">source</code> + the setup script. + For information on separating output from your local Source Directory files, see <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>. + </p></div><div class="section" title="5.1.3. documentation"><div class="titlepage"><div><div><h3 class="title"><a id="handbook"></a>5.1.3. <code class="filename">documentation</code></h3></div></div></div><p> + This directory holds the source for the Yocto Project documentation + as well as templates and tools that allow you to generate PDF and HTML + versions of the manuals. + Each manual is contained in a sub-folder. + For example, the files for this manual reside in + <code class="filename">ref-manual</code>. + </p></div><div class="section" title="5.1.4. meta/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta"></a>5.1.4. <code class="filename">meta/</code></h3></div></div></div><p> + This directory contains the OpenEmbedded Core metadata. + The directory holds recipes, common classes, and machine + configuration for emulated targets (qemux86, qemuarm, + and so on.) + </p></div><div class="section" title="5.1.5. meta-yocto/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-yocto"></a>5.1.5. <code class="filename">meta-yocto/</code></h3></div></div></div><p> + This directory contains the configuration for the Poky + reference distribution. + </p></div><div class="section" title="5.1.6. meta-yocto-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-yocto-bsp"></a>5.1.6. <code class="filename">meta-yocto-bsp/</code></h3></div></div></div><p> + This directory contains the Yocto Project reference + hardware BSPs. + </p></div><div class="section" title="5.1.7. meta-hob/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-hob"></a>5.1.7. <code class="filename">meta-hob/</code></h3></div></div></div><p> + This directory contains template recipes used by the + <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a> + build UI. + </p></div><div class="section" title="5.1.8. meta-skeleton/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-skeleton"></a>5.1.8. <code class="filename">meta-skeleton/</code></h3></div></div></div><p> + This directory contains template recipes for BSP and kernel development. + </p></div><div class="section" title="5.1.9. scripts/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-scripts"></a>5.1.9. <code class="filename">scripts/</code></h3></div></div></div><p> + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a> script appends this + directory to the shell's <code class="filename">PATH</code> environment variable. + </p><p> + The <code class="filename">scripts</code> directory has useful scripts that assist contributing + back to the Yocto Project, such as <code class="filename">create_pull_request</code> and + <code class="filename">send_pull_request</code>. + </p></div><div class="section" title="5.1.10. oe-init-build-env"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-script"></a>5.1.10. <code class="filename">oe-init-build-env</code></h3></div></div></div><p> + This script sets up the OpenEmbedded build environment. + Running this script with the <code class="filename">source</code> command in + a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the + current working directory. + You need to run this script before running BitBake commands. + The script uses other scripts within the <code class="filename">scripts</code> directory to do + the bulk of the work. + </p><p> + By default, running this script without a Build Directory argument creates the + <code class="filename">build</code> directory. + If you provide a Build Directory argument when you <code class="filename">source</code> + the script, you direct OpenEmbedded build system to create a + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> of your choice. + For example, the following command creates a Build Directory named + <code class="filename">mybuilds</code> that is outside of the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>: + </p><pre class="literallayout"> + $ source oe-init-build-env ~/mybuilds + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + The OpenEmbedded build system does not support file or directory names that + contain spaces. + If you attempt to run the <code class="filename">oe-init-build-env</code> script + from a Source Directory that contains spaces in either the filenames + or directory names, the script returns an error indicating no such + file or directory. + Be sure to use a Source Directory free of names containing spaces. + </div><p> + </p></div><div class="section" title="5.1.11. LICENSE, README, and README.hardware"><div class="titlepage"><div><div><h3 class="title"><a id="structure-basic-top-level"></a>5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></h3></div></div></div><p> + These files are standard top-level files. + </p></div></div><div class="section" title="5.2. The Build Directory - build/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-build"></a>5.2. The Build Directory - <code class="filename">build/</code></h2></div></div></div><div class="section" title="5.2.1. build/pseudodone"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-pseudodone"></a>5.2.1. <code class="filename">build/pseudodone</code></h3></div></div></div><p> + This tag file indicates that the initial pseudo binary was created. + The file is built the first time BitBake is invoked. + </p></div><div class="section" title="5.2.2. build/conf/local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-local.conf"></a>5.2.2. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p> + This file contains all the local user configuration for your build environment. + If there is no <code class="filename">local.conf</code> present, it is created from + <code class="filename">local.conf.sample</code>. + The <code class="filename">local.conf</code> file contains documentation on the various configuration options. + Any variable set here overrides any variable set elsewhere within the environment unless + that variable is hard-coded within a file (e.g. by using '=' instead of '?='). + Some variables are hard-coded for various reasons but these variables are + relatively rare. + </p><p> + Edit this file to set the <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> + for which you want to build, which package types you wish to use + (<a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES"><code class="filename">PACKAGE_CLASSES</code></a>), + where you want to downloaded files + (<code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>), + and how you want your host machine to use resources + (<a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS"><code class="filename">BB_NUMBER_THREADS</code></a> and + <a class="link" href="#var-PARALLEL_MAKE" title="PARALLEL_MAKE"><code class="filename">PARALLEL_MAKE</code></a>). + </p></div><div class="section" title="5.2.3. build/conf/bblayers.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-bblayers.conf"></a>5.2.3. <code class="filename">build/conf/bblayers.conf</code></h3></div></div></div><p> + This file defines layers, which are directory trees, traversed (or walked) by BitBake. + If <code class="filename">bblayers.conf</code> + is not present, it is created from <code class="filename">bblayers.conf.sample</code> when + you <code class="filename">source</code> the environment setup script. + </p><p> + The <code class="filename">bblayers.conf</code> file uses the + <a class="link" href="#var-BBLAYERS" title="BBLAYERS"><code class="filename">BBLAYERS</code></a> variable to + list the layers BitBake tries to find. + The file uses the + <a class="link" href="#var-BBLAYERS_NON_REMOVABLE" title="BBLAYERS_NON_REMOVABLE"><code class="filename">BBLAYERS_NON_REMOVABLE</code></a> + variable to list layers that must not be removed. + </p></div><div class="section" title="5.2.4. build/conf/sanity_info"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-sanity_info"></a>5.2.4. <code class="filename">build/conf/sanity_info</code></h3></div></div></div><p> + This file is created during the build to indicate the state of the sanity checks. + </p></div><div class="section" title="5.2.5. build/downloads/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-downloads"></a>5.2.5. <code class="filename">build/downloads/</code></h3></div></div></div><p> + This directory is used for the upstream source tarballs. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable. + </p></div><div class="section" title="5.2.6. build/sstate-cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-sstate-cache"></a>5.2.6. <code class="filename">build/sstate-cache/</code></h3></div></div></div><p> + This directory is used for the shared state cache. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <code class="filename"><a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable. + </p></div><div class="section" title="5.2.7. build/tmp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp"></a>5.2.7. <code class="filename">build/tmp/</code></h3></div></div></div><p> + This directory receives all the OpenEmbedded build system's output. + BitBake creates this directory if it does not exist. + As a last resort, to clean up a build and start it from scratch (other than the downloads), + you can remove everything in the <code class="filename">tmp</code> directory or get rid of the + directory completely. + If you do, you should also completely remove the <code class="filename">build/sstate-cache</code> + directory as well. + </p></div><div class="section" title="5.2.8. build/tmp/buildstats/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-buildstats"></a>5.2.8. <code class="filename">build/tmp/buildstats/</code></h3></div></div></div><p> + This directory stores the build statistics. + </p></div><div class="section" title="5.2.9. build/tmp/cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-cache"></a>5.2.9. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p> + When BitBake parses the metadata, it creates a cache file of the result that can + be used when subsequently running commands. + These results are stored here on a per-machine basis. + </p></div><div class="section" title="5.2.10. build/tmp/deploy/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy"></a>5.2.10. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p> + This directory contains any 'end result' output from the OpenEmbedded build process. + </p></div><div class="section" title="5.2.11. build/tmp/deploy/deb/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-deb"></a>5.2.11. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p> + This directory receives any <code class="filename">.deb</code> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </p></div><div class="section" title="5.2.12. build/tmp/deploy/rpm/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-rpm"></a>5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></h3></div></div></div><p> + This directory receives any <code class="filename">.rpm</code> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </p></div><div class="section" title="5.2.13. build/tmp/deploy/licenses/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-licenses"></a>5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></h3></div></div></div><p> + This directory receives package licensing information. + For example, the directory contains sub-directories for <code class="filename">bash</code>, + <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn + contain appropriate <code class="filename">COPYING</code> license files with other licensing information. + </p></div><div class="section" title="5.2.14. build/tmp/deploy/images/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-images"></a>5.2.14. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p> + This directory receives complete filesystem images. + If you want to flash the resulting image from a build onto a device, look here for the image. + </p><p> + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>, + etc.). + However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.), + bootloader and other supplementary files might be deployed here prior to building an + image. + Because these files, however, are not directly produced from the image, if you + delete them they will not be automatically re-created when you build the image again. + </p><p> + If you do accidentally delete files here, you will need to force them to be + re-created. + In order to do that, you will need to know the target that produced them. + For example, these commands rebuild and re-create the kernel files: + </p><pre class="literallayout"> + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + </pre><p> + </p></div><div class="section" title="5.2.15. build/tmp/deploy/ipk/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-ipk"></a>5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p> + This directory receives <code class="filename">.ipk</code> packages produced by + the build process.</p></div><div class="section" title="5.2.16. build/tmp/sysroots/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-sysroots"></a>5.2.16. <code class="filename">build/tmp/sysroots/</code></h3></div></div></div><p> + This directory contains shared header files and libraries as well as other shared + data. + Packages that need to share output with other packages do so within this directory. + The directory is subdivided by architecture so multiple builds can run within + the one Build Directory. + </p></div><div class="section" title="5.2.17. build/tmp/stamps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-stamps"></a>5.2.17. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p> + This directory holds information that BitBake uses for accounting purposes + to track what tasks have run and when they have run. + The directory is sub-divided by architecture, package name, and + version. + Following is an example: + </p><pre class="literallayout"> + stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do + </pre><p> + Although the files in the directory are empty of data, + BitBake uses the filenames and timestamps for tracking purposes. + </p></div><div class="section" title="5.2.18. build/tmp/log/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-log"></a>5.2.18. <code class="filename">build/tmp/log/</code></h3></div></div></div><p> + This directory contains general logs that are not otherwise placed using the + package's <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>. + Examples of logs are the output from the <code class="filename">check_pkg</code> or + <code class="filename">distro_check</code> tasks. + Running a build does not necessarily mean this directory is created. + </p></div><div class="section" title="5.2.19. build/tmp/pkgdata/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-pkgdata"></a>5.2.19. <code class="filename">build/tmp/pkgdata/</code></h3></div></div></div><p> + This directory contains intermediate packaging data that is used later in the packaging process. + For more information, see the "<a class="link" href="#ref-classes-package" title="7.13. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section. + </p></div><div class="section" title="5.2.20. build/tmp/work/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-work"></a>5.2.20. <code class="filename">build/tmp/work/</code></h3></div></div></div><p> + This directory contains architecture-specific work sub-directories + for packages built by BitBake. + All tasks execute from the appropriate work directory. + For example, the source for a particular package is unpacked, + patched, configured and compiled all within its own work directory. + Within the work directory, organization is based on the package group + and version for which the source is being compiled + as defined by the + <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>. + </p><p> + It is worth considering the structure of a typical work directory. + As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code> + on the machine <code class="filename">qemux86</code> + built within the Yocto Project. + For this package, a work directory of + <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....></code>, + referred to as the + <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created. + Within this directory, the source is unpacked to + <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt + (see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#using-a-quilt-workflow" target="_top">Modifying Package + Source Code with Quilt</a>" section in the Yocto Project Development Manual. + Within the <code class="filename">linux-qemux86-standard-build</code> directory, + standard Quilt directories <code class="filename">linux-3.0/patches</code> + and <code class="filename">linux-3.0/.pc</code> are created, + and standard Quilt commands can be used. + </p><p> + There are other directories generated within <code class="filename">WORKDIR</code>. + The most important directory is <code class="filename">WORKDIR/temp/</code>, + which has log files for each task (<code class="filename">log.do_*.pid</code>) + and contains the scripts BitBake runs for each task + (<code class="filename">run.do_*.pid</code>). + The <code class="filename">WORKDIR/image/</code> directory is where "make + install" places its output that is then split into sub-packages + within <code class="filename">WORKDIR/packages-split/</code>. + </p></div></div><div class="section" title="5.3. The Metadata - meta/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-meta"></a>5.3. The Metadata - <code class="filename">meta/</code></h2></div></div></div><p> + As mentioned previously, metadata is the core of the Yocto Project. + Metadata has several important subdivisions: + </p><div class="section" title="5.3.1. meta/classes/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-classes"></a>5.3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p> + This directory contains the <code class="filename">*.bbclass</code> files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the <code class="filename">base.bbclass</code> file. + Examples of other important classes are <code class="filename">autotools.bbclass</code>, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions + for working with the Linux kernel. + Functions like image generation or packaging also have their specific class files + such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and + <code class="filename">package*.bbclass</code>. + </p></div><div class="section" title="5.3.2. meta/conf/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf"></a>5.3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p> + This directory contains the core set of configuration files that start from + <code class="filename">bitbake.conf</code> and from which all other configuration + files are included. + See the include statements at the end of the file and you will note that even + <code class="filename">local.conf</code> is loaded from there. + While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override + these by using the (<code class="filename">local.conf</code>) file, machine file or + the distribution configuration file. + </p></div><div class="section" title="5.3.3. meta/conf/machine/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-machine"></a>5.3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p> + This directory contains all the machine configuration files. + If you set <code class="filename">MACHINE="qemux86"</code>, + the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this + directory. + The <code class="filename">include</code> directory contains various data common to multiple machines. + If you want to add support for a new machine to the Yocto Project, look in this directory. + </p></div><div class="section" title="5.3.4. meta/conf/distro/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-distro"></a>5.3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p> + Any distribution-specific configuration is controlled from this directory. + For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here. + This directory includes the versions and the + <code class="filename">SRCDATE</code> definitions for applications that are configured here. + An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>. + Although this file mainly inherits its configuration from Poky. + </p></div><div class="section" title="5.3.5. meta/recipes-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-bsp"></a>5.3.5. <code class="filename">meta/recipes-bsp/</code></h3></div></div></div><p> + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + </p></div><div class="section" title="5.3.6. meta/recipes-connectivity/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-connectivity"></a>5.3.6. <code class="filename">meta/recipes-connectivity/</code></h3></div></div></div><p> + This directory contains libraries and applications related to communication with other devices. + </p></div><div class="section" title="5.3.7. meta/recipes-core/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-core"></a>5.3.7. <code class="filename">meta/recipes-core/</code></h3></div></div></div><p> + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + </p></div><div class="section" title="5.3.8. meta/recipes-devtools/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-devtools"></a>5.3.8. <code class="filename">meta/recipes-devtools/</code></h3></div></div></div><p> + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + </p></div><div class="section" title="5.3.9. meta/recipes-extended/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-extended"></a>5.3.9. <code class="filename">meta/recipes-extended/</code></h3></div></div></div><p> + This directory contains non-essential applications that add features compared to the + alternatives in core. + You might need this directory for full tool functionality or for Linux Standard Base (LSB) + compliance. + </p></div><div class="section" title="5.3.10. meta/recipes-gnome/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-gnome"></a>5.3.10. <code class="filename">meta/recipes-gnome/</code></h3></div></div></div><p> + This directory contains all things related to the GTK+ application framework. + </p></div><div class="section" title="5.3.11. meta/recipes-graphics/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-graphics"></a>5.3.11. <code class="filename">meta/recipes-graphics/</code></h3></div></div></div><p> + This directory contains X and other graphically related system libraries + </p></div><div class="section" title="5.3.12. meta/recipes-kernel/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-kernel"></a>5.3.12. <code class="filename">meta/recipes-kernel/</code></h3></div></div></div><p> + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + </p></div><div class="section" title="5.3.13. meta/recipes-multimedia/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-multimedia"></a>5.3.13. <code class="filename">meta/recipes-multimedia/</code></h3></div></div></div><p> + This directory contains codecs and support utilities for audio, images and video. + </p></div><div class="section" title="5.3.14. meta/recipes-qt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-qt"></a>5.3.14. <code class="filename">meta/recipes-qt/</code></h3></div></div></div><p> + This directory contains all things related to the Qt application framework. + </p></div><div class="section" title="5.3.15. meta/recipes-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-rt"></a>5.3.15. <code class="filename">meta/recipes-rt/</code></h3></div></div></div><p> + This directory contains package and image recipes for using and testing + the <code class="filename">PREEMPT_RT</code> kernel. + </p></div><div class="section" title="5.3.16. meta/recipes-sato/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-sato"></a>5.3.16. <code class="filename">meta/recipes-sato/</code></h3></div></div></div><p> + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + </p></div><div class="section" title="5.3.17. meta/recipes-support/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-support"></a>5.3.17. <code class="filename">meta/recipes-support/</code></h3></div></div></div><p> + This directory contains recipes that used by other recipes, but that are not directly + included in images (i.e. dependencies of other recipes). + </p></div><div class="section" title="5.3.18. meta/site/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-site"></a>5.3.18. <code class="filename">meta/site/</code></h3></div></div></div><p> + This directory contains a list of cached results for various architectures. + Because certain "autoconf" test results cannot be determined when cross-compiling due to + the tests not able to run on a live system, the information in this directory is + passed to "autoconf" for the various architectures. + </p></div><div class="section" title="5.3.19. meta/recipes.txt"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-txt"></a>5.3.19. <code class="filename">meta/recipes.txt</code></h3></div></div></div><p> + This file is a description of the contents of <code class="filename">recipes-*</code>. + </p></div></div></div> + + <div class="chapter" title="Chapter 6. BitBake"><div class="titlepage"><div><div><h2 class="title"><a id="ref-bitbake"></a>Chapter 6. BitBake</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-bitbake-parsing">6.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">6.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">6.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">6.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">6.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">6.7. Fetchers</a></span></dt></dl></div><p> + BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded + build system. + At some point, developers wonder what actually happens when you enter: + </p><pre class="literallayout"> + $ bitbake core-image-sato + </pre><p> + </p><p> + This chapter provides an overview of what happens behind the scenes from BitBake's perspective. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + 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 metadata + that consists of variables in a certain format that get passed to the tasks. + </div><div class="section" title="6.1. Parsing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-parsing"></a>6.1. Parsing</h2></div></div></div><p> + BitBake parses configuration files, classes, and <code class="filename">.bb</code> files. + </p><p> + The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file. + This file resides in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> + within the <code class="filename">meta/conf/</code> directory. + BitBake finds it by examining its + <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment + variable and looking for the <code class="filename">meta/conf/</code> + directory. + </p><p> + The <code class="filename">bitbake.conf</code> file lists other configuration + files to include from a <code class="filename">conf/</code> + directory below the directories listed in <code class="filename">BBPATH</code>. + In general, the most important configuration file from a user's perspective + is <code class="filename">local.conf</code>, which contains a user's customized + settings for the OpenEmbedded build environment. + Other notable configuration files are the distribution + configuration file (set by the + <code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> variable) + and the machine configuration file + (set by the + <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> variable). + The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment + variables are both usually set in + the <code class="filename">local.conf</code> file. + Valid distribution + configuration files are available in the <code class="filename">meta/conf/distro/</code> directory + and valid machine configuration + files in the <code class="filename">meta/conf/machine/</code> directory. + Within the <code class="filename">meta/conf/machine/include/</code> + directory are various <code class="filename">tune-*.inc</code> configuration files that provide common + "tuning" settings specific to and shared between particular architectures and machines. + </p><p> + After the parsing of the configuration files, some standard classes are included. + The <code class="filename">base.bbclass</code> file is always included. + Other classes that are specified in the configuration using the + <code class="filename"><a class="link" href="#var-INHERIT" title="INHERIT">INHERIT</a></code> + variable are also included. + Class files are searched for in a <code class="filename">classes</code> subdirectory + under the paths in <code class="filename">BBPATH</code> in the same way as + configuration files. + </p><p> + After classes are included, the variable + <code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code> + is set, usually in + <code class="filename">local.conf</code>, and defines the list of places to search for + <code class="filename">.bb</code> files. + By default, the <code class="filename">BBFILES</code> variable specifies the + <code class="filename">meta/recipes-*/</code> directory within Poky. + Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of + BitBake layers as described in the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and + Creating Layers</a>" section of the Yocto Project Development Manual. + </p><p> + BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and + stores the values of various variables. + In summary, for each <code class="filename">.bb</code> + file the configuration plus the base class of variables are set, followed + by the data in the <code class="filename">.bb</code> file + itself, followed by any inherit commands that + <code class="filename">.bb</code> file might contain. + </p><p> + Because parsing <code class="filename">.bb</code> files is a time + consuming process, a cache is kept to speed up subsequent parsing. + This cache is invalid if the timestamp of the <code class="filename">.bb</code> + file itself changes, or if the timestamps of any of the include, + configuration or class files the <code class="filename">.bb</code> + file depends on changes. + </p></div><div class="section" title="6.2. Preferences and Providers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-providers"></a>6.2. Preferences and Providers</h2></div></div></div><p> + Once all the <code class="filename">.bb</code> files have been + parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code> + 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 <code class="filename">core-image-sato</code>, it would lead to + <code class="filename">packagegroup-core-x11-sato</code>, + which in turn leads to recipes like <code class="filename">matchbox-terminal</code>, + <code class="filename">pcmanfm</code> and <code class="filename">gthumb</code>. + These recipes in turn depend on <code class="filename">eglibc</code> and the toolchain. + </p><p> + 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: + </p><pre class="literallayout"> + PREFERRED_PROVIDER_virtual/kernel = "linux-yocto" + </pre><p> + The default <code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code> + is the provider with the same name as the target. + </p><p> + 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 + <code class="filename"><a class="link" href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code> + variable to specify a particular version (usually in the distro configuration). + You can influence the order by using the + <code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code> + variable. + By default, files have a preference of "0". + Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the + package unlikely to be used unless it is explicitly referenced. + Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used. + <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting. + <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package + versions until they have undergone sufficient testing to be considered stable. + </p><p> + In summary, BitBake has created a list of providers, which is prioritized, for each target. + </p></div><div class="section" title="6.3. Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-dependencies"></a>6.3. Dependencies</h2></div></div></div><p> + Each target BitBake builds consists of multiple tasks such as + <code class="filename">fetch</code>, <code class="filename">unpack</code>, + <code class="filename">patch</code>, <code class="filename">configure</code>, + and <code class="filename">compile</code>. + For best performance on multi-core systems, BitBake considers each task as an independent + entity with its own set of dependencies. + </p><p> + Dependencies are defined through several variables. + You can find information about variables BitBake uses in the BitBake documentation, + which is found in the <code class="filename">bitbake/doc/manual</code> directory within the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + At a basic level, it is sufficient to know that BitBake uses the + <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and + <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when + calculating dependencies. + </p></div><div class="section" title="6.4. The Task List"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-tasklist"></a>6.4. The Task List</h2></div></div></div><p> + 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 + <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></code> 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. + </p><p> + It is worth noting that you can greatly speed up the build time by properly setting + the <code class="filename">BB_NUMBER_THREADS</code> variable. + See the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#building-image" target="_top">Building an Image</a>" + section in the Yocto Project Quick Start for more information. + </p><p> + As each task completes, a timestamp is written to the directory specified by the + <code class="filename"><a class="link" href="#var-STAMP" title="STAMP">STAMP</a></code> variable. + On subsequent runs, BitBake looks within the <code class="filename">/build/tmp/stamps</code> + 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 + <code class="filename">.bb</code> 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. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Some tasks are marked as "nostamp" tasks. + No timestamp file is created when these tasks are run. + Consequently, "nostamp" tasks are always rerun. + </div></div><div class="section" title="6.5. Running a Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-runtask"></a>6.5. Running a Task</h2></div></div></div><p> + Tasks can either be a shell task or a Python task. + For shell tasks, BitBake writes a shell script to + <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> 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 <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>. + Looking at the expanded shell functions in the run file and the output in the log files + is a useful debugging technique. + </p><p> + 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 way similar to shell tasks as well. + </p><p> + Once all the tasks have been completed BitBake exits. + </p><p> + 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: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Tell BitBake to load what you want from the environment + into the data store. + You can do so through the <code class="filename">BB_ENV_EXTRAWHITE</code> + variable. + For example, assume you want to prevent the build system from + accessing your <code class="filename">$HOME/.ccache</code> directory. + The following command tells BitBake to load + <code class="filename">CCACHE_DIR</code> from the environment into the data + store: + </p><pre class="literallayout"> + export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" + </pre></li><li class="listitem"><p>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 + <code class="filename">local.conf</code> or distro configuration file: + </p><pre class="literallayout"> + export CCACHE_DIR + </pre></li></ol></div><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + 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 <code class="filename">BB_HASHBASE_WHITELIST</code> + example in the "<a class="link" href="#checksums" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section. + </div></div><div class="section" title="6.6. BitBake Command Line"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-commandline"></a>6.6. BitBake Command Line</h2></div></div></div><p> + Following is the BitBake help output: + </p><pre class="screen"> +$ bitbake --help +Usage: bitbake [options] [package ...] + +Executes the specified task (default is 'build') for a given set of BitBake files. +It expects that BBFILES is defined, which is a space separated list of files to +be executed. BBFILES does support wildcards. +Default BBFILES are the .bb files in the current directory. + +Options: + --version show program's version number and exit + -h, --help show this help message and exit + -b BUILDFILE, --buildfile=BUILDFILE + execute the task against this .bb file, rather than a + package from BBFILES. Does not handle any + dependencies. + -k, --continue continue as much as possible after an error. While the + target that failed, and those that depend on it, + cannot be remade, the other dependencies of these + targets can be processed all the same. + -a, --tryaltconfigs continue with builds by trying to use alternative + providers where possible. + -f, --force force run of specified cmd, regardless of stamp status + -c CMD, --cmd=CMD Specify task to execute. Note that this only executes + the specified task for the providee and the packages + it depends on, i.e. 'compile' does not implicitly call + stage for the dependencies (IOW: use only if you know + what you are doing). Depending on the base.bbclass a + listtasks tasks is defined and will show available + tasks + -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 chit-chat 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 files (developers only) + -s, --show-versions show current and preferred versions of all packages + -e, --environment show the global or per-package environment (this is + what used to be bbread) + -g, --graphviz emit the dependency trees of the specified packages 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 print a report + -u UI, --ui=UI userinterface to use + -t SERVERTYPE, --servertype=SERVERTYPE + Choose which server to use, none, process or xmlrpc + --revisions-changed Set the exit code depending on whether upstream + floating revisions have changed or not + </pre></div><div class="section" title="6.7. Fetchers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-fetchers"></a>6.7. Fetchers</h2></div></div></div><p> + 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 <code class="filename">cvs/subversion/git</code>. + </p><p> + Fetchers are usually triggered by entries in + <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>. + You can find information about the options and formats of entries for specific + fetchers in the BitBake manual located in the + <code class="filename">bitbake/doc/manual</code> directory of the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </p><p> + 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 <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code> + variable. + See the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-srcrev" target="_top">Using an External SCM</a>" section + in the Yocto Project Development Manual for more information. + </p></div></div> + + <div class="chapter" title="Chapter 7. Classes"><div class="titlepage"><div><div><h2 class="title"><a id="ref-classes"></a>Chapter 7. Classes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-classes-base">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-packagegroup">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">7.21. Other Classes</a></span></dt></dl></div><p> + Class files are used to abstract common functionality and share it amongst multiple + <code class="filename">.bb</code> files. + Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class + file. + Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed + in a <code class="filename">classes/</code> directory beneath the + <code class="filename">meta*/</code> directory found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as + <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. + Class files are searched for in <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> + using the same method by which <code class="filename">.conf</code> files are searched. +</p><p> + In most cases inheriting the class is enough to enable its features, although + for some classes you might need to set variables or override some of the + default behaviour. +</p><div class="section" title="7.1. The base class - base.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-base"></a>7.1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p> + The base class is special in that every <code class="filename">.bb</code> + file inherits it automatically. + This class contains definitions for standard basic + tasks such as fetching, unpacking, configuring (empty by default), compiling + (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging + (empty by default). + These classes are often overridden or extended by other classes + such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>. + The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>. + </p></div><div class="section" title="7.2. Autotooled Packages - autotools.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-autotools"></a>7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p> + Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>, + and <code class="filename">libtool</code>) bring standardization. + This class defines a set of tasks (configure, compile etc.) that + work for all Autotooled packages. + It should usually be enough to define a few standard variables + and then simply <code class="filename">inherit autotools</code>. + This class can also work with software that emulates Autotools. + For more information, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-addpkg-autotools" target="_top">Autotooled Package</a>" + section in the Yocto Project Development Manual. + </p><p> + It's useful to have some idea of how the tasks defined by this class work + and what they do behind the scenes. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">do_configure</code> †regenerates the + configure script (using <code class="filename">autoreconf</code>) and then launches it + with a standard set of arguments used during cross-compilation. + You can pass additional parameters to <code class="filename">configure</code> through the + <code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable. + </p></li><li class="listitem"><p><code class="filename">do_compile</code> †runs <code class="filename">make</code> with + arguments that specify the compiler and linker. + You can pass additional arguments through + the <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable. + </p></li><li class="listitem"><p><code class="filename">do_install</code> †runs <code class="filename">make install</code> + and passes a DESTDIR option, which takes its value from the standard + <code class="filename"><a class="link" href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable. + </p></li></ul></div><p> + </p></div><div class="section" title="7.3. Alternatives - update-alternatives.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-alternatives"></a>7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p> + Several programs can fulfill the same or similar function and be installed with the same name. + For example, the <code class="filename">ar</code> command is available from the + <code class="filename">busybox</code>, <code class="filename">binutils</code> and + <code class="filename">elfutils</code> packages. + The <code class="filename">update-alternatives.bbclass</code> class handles renaming the + binaries so that multiple packages can be installed without conflicts. + The <code class="filename">ar</code> command still works regardless of which packages are installed + or subsequently removed. + The class renames the conflicting binary in each package and symlinks the highest + priority binary during installation or removal of packages. + </p><p> + Four variables control this class: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> †The name of the + binary that is replaced (<code class="filename">ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> †The path to + the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> †The path to the + real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> †The priority of + the binary. + The version with the most features should have the highest priority.</p></li></ul></div><p> + </p><p> + Currently, the OpenEmbedded build system supports only one binary per package. + </p></div><div class="section" title="7.4. Initscripts - update-rc.d.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-rc.d"></a>7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p> + This class uses <code class="filename">update-rc.d</code> to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system takes care of details such as making sure the script is stopped before + a package is removed and started when the package is installed. + Three variables control this class: + <code class="filename"><a class="link" href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>, + <code class="filename"><a class="link" href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and + <code class="filename"><a class="link" href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>. + See the variable links for details. + </p></div><div class="section" title="7.5. Binary config scripts - binconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-binconfig"></a>7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p> + Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell + scripts to give information about the libraries and include paths needed + to build software (usually named <code class="filename">LIBNAME-config</code>). + This class assists any recipe using such scripts. + </p><p> + During staging, BitBake installs such scripts into the + <code class="filename">sysroots/</code> directory. + BitBake also changes all paths to point into the <code class="filename">sysroots/</code> + directory so all builds that use the script will use the correct + directories for the cross compiling layout. + </p></div><div class="section" title="7.6. Debian renaming - debian.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-debian"></a>7.6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p> + This class renames packages so that they follow the Debian naming + policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code> + and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>. + </p></div><div class="section" title="7.7. Pkg-config - pkgconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-pkgconfig"></a>7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p> + <code class="filename">pkg-config</code> brought standardization and this class aims to make its + integration smooth for all libraries that make use of it. + </p><p> + During staging, BitBake installs <code class="filename">pkg-config</code> data into the + <code class="filename">sysroots/</code> directory. + By making use of sysroot functionality within <code class="filename">pkg-config</code>, + this class no longer has to manipulate the files. + </p></div><div class="section" title="7.8. Distribution of sources - src_distribute_local.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-src-distribute"></a>7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p> + Many software licenses require that source files be provided along with the binaries. + To simplify this process, two classes were created: + <code class="filename">src_distribute.bbclass</code> and + <code class="filename">src_distribute_local.bbclass</code>. + </p><p> + The results of these classes are <code class="filename">tmp/deploy/source/</code> + subdirs with sources sorted by + <code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a></code> field. + If recipes list few licenses (or have entries like "Bitstream Vera"), + the source archive is placed in each license directory. + </p><p> + This class operates using three modes: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the + distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the + distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into + the distribute directory and then symlinks them back.</p></li></ul></div><p> + </p></div><div class="section" title="7.9. Perl modules - cpan.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-perl"></a>7.9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p> + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and then inherit the + proper <code class="filename">.bbclass</code> file. + Building is split into two methods depending on which method the module authors used. + </p><p> + Modules that use old <code class="filename">Makefile.PL</code>-based build system require + <code class="filename">cpan.bbclass</code> in their recipes. + </p><p> + Modules that use <code class="filename">Build.PL</code>-based build system require + using <code class="filename">cpan_build.bbclass</code> in their recipes. + </p></div><div class="section" title="7.10. Python extensions - distutils.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-distutils"></a>7.10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p> + Recipes for Python extensions are simple. + These recipes usually only need to point to the source's archive and then inherit + the proper <code class="filename">.bbclass</code> file. + Building is split into two methods dependling on which method the module authors used. + </p><p> + Extensions that use an Autotools-based build system require Autotools and + <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes. + </p><p> + Extensions that use <code class="filename">distutils</code>-based build systems require + <code class="filename">distutils.bbclass</code> in their recipes. + </p></div><div class="section" title="7.11. Developer Shell - devshell.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-devshell"></a>7.11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p> + This class adds the <code class="filename">devshell</code> task. + Distribution policy dictates whether to include this class. + See the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section + in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>. + </p></div><div class="section" title="7.12. Package Groups - packagegroup.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-packagegroup"></a>7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></h2></div></div></div><p> + This class sets default values appropriate for package group recipes (such as + <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>, + <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>, + <code class="filename"><a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">ALLOW_EMPTY</a></code>, + and so forth. + It is highly recommended that all package group recipes inherit this class. + </p><p> + For information on how to use this class, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks" target="_top">Customizing Images Using Custom Package Tasks</a>" + section in the Yocto Project Development Manual. + </p><p> + Previously, this class was named <code class="filename">task.bbclass</code>. + </p></div><div class="section" title="7.13. Packaging - package*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-package"></a>7.13. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p> + The packaging classes add support for generating packages from a build's + output. + The core generic functionality is in <code class="filename">package.bbclass</code>. + The code specific to particular package types is contained in various sub-classes such as + <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>, + and <code class="filename">package_rpm.bbclass</code>. + Most users will want one or more of these classes. + </p><p> + You can control the list of resulting package formats by using the + <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code> + variable defined in the <code class="filename">local.conf</code> configuration file, + which is located in the <code class="filename">conf</code> folder of the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + </p><p> + The package class you choose can affect build-time performance and has space + ramifications. + In general, building a package with RPM takes about thirty percent more time as + compared to using IPK to build the same or similar package. + This comparison takes into account a complete build of the package with all + dependencies previously built. + The reason for this discrepancy is because the RPM package manager creates and + processes more metadata than the IPK package manager. + Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code> + to "package_ipk" if you are building smaller systems. + </p><p> + Keep in mind, however, that RPM starts to provide more abilities than IPK due to + the fact that it processes more metadata. + For example, this information includes individual file types, file checksum generation + and evaluation on install, sparse file support, conflict detection and resolution + for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks. + </p><p> + Another consideration for packages built using the RPM package manager is space. + For smaller systems, the extra space used for the Berkley Database and the amount + of metadata can affect your ability to do on-device upgrades. + </p><p> + You can find additional information on the effects of the package class at these + two Yocto Project mailing list links: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_top"> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_top"> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li></ul></div><p> + </p></div><div class="section" title="7.14. Building kernels - kernel.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-kernel"></a>7.14. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p> + This class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + <code class="filename"><a class="link" href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code> + directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>. + </p><p> + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the <code class="filename">modinfo</code> output. + If all modules are required, then installing the <code class="filename">kernel-modules</code> + package installs all packages with modules and various other kernel packages + such as <code class="filename">kernel-vmlinux</code>. + </p><p> + Various other classes are used by the kernel and module classes internally including + <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>, + <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>. + </p></div><div class="section" title="7.15. Creating images - image.bbclass and rootfs*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-image"></a>7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p> + These classes add support for creating images in several formats. + First, the root filesystem is created from packages using + one of the <code class="filename">rootfs_*.bbclass</code> + files (depending on the package format used) and then the image is created. + </p><p> + The <code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code> + variable controls the types of images to generate. + </p><p> + The <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code> + variable controls the list of packages to install into the image. + </p></div><div class="section" title="7.16. Host System sanity checks - sanity.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-sanity"></a>7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p> + This class checks to see if prerequisite software is present so that + users can be notified of potential problems that might affect their build. + The class also performs basic user configuration checks from + the <code class="filename">local.conf</code> configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually determines whether to include this class. + </p></div><div class="section" title="7.17. Generated output quality assurance checks - insane.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-insane"></a>7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p> + This class adds a step to the package generation process that sanity checks the + packages generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + </p><p> + You can configure the sanity checks so that specific test failures either raise a warning or + an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error message + once the metadata is in a known and good condition. + You use the <code class="filename">WARN_QA</code> variable to specify tests for which you + want to generate a warning message on failure. + You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you + want to generate an error message on failure. + </p><p> + The following list shows the tests you can list with the <code class="filename">WARN_QA</code> + and <code class="filename">ERROR_QA</code> variables: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span> + Ensures that the binaries were linked with the + <code class="filename">LDFLAGS</code> options provided by the build system. + If this test fails, check that the <code class="filename">LDFLAGS</code> variable + is being passed to the linker command.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span> + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>). + While these paths will not cause any breakage, they do waste space and + are unnecessary.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span> + Checks for rpaths in the binaries that contain build system paths such + as <code class="filename">TMPDIR</code>. + If this test fails, bad <code class="filename">-rpath</code> options are being + passed to the linker commands and your binaries have potential security + issues.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span> + Checks that the <code class="filename">.so</code> symbolic links are in the + <code class="filename">-dev</code> package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the <code class="filename">-dev</code> package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span> + Checks for <code class="filename">.debug</code> directories in anything but the + <code class="filename">-dbg</code> package. + The debug files should all be in the <code class="filename">-dbg</code> package. + Thus, anything packaged elsewhere is incorrect packaging.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span> + Checks the Executable and Linkable Format (ELF) type, bit size and endianness + of any binaries to ensure it matches the target architecture. + This test fails if any binaries don't match the type since there would be an + incompatibility. + Sometimes software, like bootloaders, might need to bypass this check. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span> + Checks that <code class="filename">-dbg</code> packages only depend on other + <code class="filename">-dbg</code> packages and not on any other types of packages, + which would cause a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span> + Checks that <code class="filename">-dev</code> packages only depend on other + <code class="filename">-dev</code> packages and not on any other types of packages, + which would be a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span> + Checks <code class="filename">.pc</code> files for any + <code class="filename">TMPDIR/WORKDIR</code> paths. + Any <code class="filename">.pc</code> file containing these paths is incorrect + since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix + when the files are accessed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span> + Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code> + paths. + Any <code class="filename">.la</code> file continaing these paths is incorrect since + <code class="filename">libtool</code> adds the correct sysroot prefix when using the + files automatically itself.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span> + Runs the <code class="filename">desktop-file-validate</code> program against any + <code class="filename">.desktop</code> files to validate their contents against + the specification for <code class="filename">.desktop</code> files.</p></li></ul></div><p> + </p></div><div class="section" title="7.18. Autotools configuration data cache - siteinfo.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-siteinfo"></a>7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p> + Autotools can require tests that must execute on the target hardware. + Since this is not possible in general when cross compiling, site information is + used to provide cached test results so these tests can be skipped over but + still make the correct values available. + The <code class="filename"><a class="link" href="#structure-meta-site" title="5.3.18. meta/site/">meta/site directory</a></code> + contains test results sorted into different categories such as architecture, endianness, and + the <code class="filename">libc</code> used. + Site information provides a list of files containing data relevant to + the current build in the + <code class="filename"><a class="link" href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable + that Autotools automatically picks up. + </p><p> + The class also provides variables like + <code class="filename"><a class="link" href="#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code> + and <code class="filename"><a class="link" href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code> + that can be used elsewhere in the metadata. + </p><p> + Because this class is included from <code class="filename">base.bbclass</code>, it is always active. + </p></div><div class="section" title="7.19. Adding Users - useradd.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-useradd"></a>7.19. Adding Users - <code class="filename">useradd.bbclass</code></h2></div></div></div><p> + If you have packages that install files that are owned by custom users or groups, + you can use this class to specify those packages and associate the users and groups + with those packages. + The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code> + recipe in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> + provides a simple exmample that shows how to add three + users and groups to two packages. + See the <code class="filename">useradd-example.bb</code> for more information on how to + use this class. + </p></div><div class="section" title="7.20. Using External Source - externalsrc.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-externalsrc"></a>7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></h2></div></div></div><p> + You can use this class to build software from source code that is external to the + OpenEmbedded build system. + In other words, your source code resides in an external tree outside of the Yocto Project. + Building software from an external source tree means that the normal fetch, unpack, and + patch process is not used. + </p><p> + To use the class, you need to define the + <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> variable to point to the directory that contains the source files. + You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class. + </p><p> + This class expects the source code to support recipe builds that use the + <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable to point to the directory in + which the OpenEmbedded build system places the generated objects built from the recipes. + By default, the <code class="filename">B</code> directory is set to the following, which is separate from the + Source Directory (<code class="filename">S</code>): + </p><pre class="literallayout"> + ${WORKDIR}/${BPN}/{PV}/ + </pre><p> + See the glossary entries for the + <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>, + <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a>, + <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>, + <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>, and + <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> for more information. + </p><p> + You can build object files in the external tree by setting the + <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>. + However, this practice does not work well if you use the source for more than one variant + (i.e., "natives" such as <code class="filename">quilt-native</code>, + or "crosses" such as <code class="filename">gcc-cross</code>). + So, be sure there are no "native", "cross", or "multilib" variants of the recipe. + </p><p> + If you do want to build different variants of a recipe, you can use the + <a class="link" href="#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable. + When you do, the <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable must support the + recipe's ability to build variants in different working directories. + Most autotools-based recipes support separating these directories. + The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code> + and some kernel recipes. + Alternatively, you can make sure that separate recipes exist that each + use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant. + The separate recipes can inherit a single target recipe. + </p><p> + For information on how to use this class, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#building-software-from-an-external-source" target="_top">Building + Software from an External Source</a>" section in the Yocto Project Development Manual. + </p></div><div class="section" title="7.21. Other Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-others"></a>7.21. Other Classes</h2></div></div></div><p> + Thus far, this chapter has discussed only the most useful and important + classes. + However, other classes exist within the <code class="filename">meta/classes</code> directory + in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + You can examine the <code class="filename">.bbclass</code> files directly for more + information. + </p></div></div> + + <div class="chapter" title="Chapter 8. Images"><div class="titlepage"><div><div><h2 class="title"><a id="ref-images"></a>Chapter 8. Images</h2></div></div></div><p> + The OpenEmbedded build process supports several types of images to satisfy different needs. + When you issue the <code class="filename">bitbake</code> command you provide a “top-level†recipe + that essentially begins the build for the type of image you want. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + Building an image without GNU General Public License Version 3 (GPLv3) components + is only supported for minimal and base images. + Furthermore, if you are going to build an image using non-GPLv3 components, + you must make the following changes in the <code class="filename">local.conf</code> file + before using the BitBake command to build the minimal or base image: + <pre class="literallayout"> + 1. Comment out the EXTRA_IMAGE_FEATURES line + 2. Set INCOMPATIBLE_LICENSE = "GPLv3" + </pre></div><p> + From within the <code class="filename">poky</code> Git repository, use the following command to list + the supported images: + </p><pre class="literallayout"> + $ ls meta*/recipes*/images/*.bb + </pre><p> + These recipes reside in the <code class="filename">meta/recipes-core/images</code>, + <code class="filename">meta/recipes-extended/images</code>, + <code class="filename">meta/recipes-graphics/images</code>, and + <code class="filename">meta/recipes-sato/images</code> directories + within the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a>. + Although the recipe names are somewhat explanatory, here is a list that describes them: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span> + A console-only image that fully supports the target device hardware.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span> + A small image just capable of allowing a device to boot.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span> + A <code class="filename">core-image-minimal</code> image suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span> + A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based + Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel, + which allows the system to find the first “init†program more efficiently. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span> + A <code class="filename">core-image-minimal</code> image that has support + for the Minimal MTD Utilities, which let the user interact with the + MTD subsystem in the kernel to perform operations on flash devices. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-x11</code>:</em></span> + A very basic X11 image with a terminal. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span> + A console-only image with more full-featured Linux system + functionality installed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span> + An image that conforms to the Linux Standard Base (LSB) specification.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span> + A <code class="filename">core-image-lsb</code> image that is suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span> + A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain + but also includes development headers and libraries to form a complete standalone SDK. + This image is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span> + An image with support for the Open GL-based toolkit Clutter, which enables development of + rich and animated graphical user interfaces.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span> + An image with Sato support, a mobile environment and visual style that works well + with mobile devices. + The image supports X11 with a Sato theme and applications such as + a terminal, editor, file manager, media player, and so forth.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span> + A <code class="filename">core-image-sato</code> image suitable for development + using the host. + The image includes libraries needed to build applications on the device itself, + testing and profiling tools, and debug symbols. + This image was formerly <code class="filename">core-image-sdk</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span> + A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain. + The image also includes development headers and libraries to form a complete standalone SDK + and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span> + A <code class="filename">core-image-minimal</code> image plus a real-time test suite and + tools appropriate for real-time use.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span> + A <code class="filename">core-image-rt</code> image that includes everything in + <code class="filename">meta-toolchain</code>. + The image also includes development headers and libraries to form a complete + stand-alone SDK and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span> + An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code> + instead of X11. + In order to build, this image requires specific distro configuration that enables + <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span> + An image you can boot and run using either the + <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_top">VMware Player</a> + or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_top">VMware Workstation</a>. + For more information on this image, see the + <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> page on + the Yocto Project website.</p></li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and + <code class="filename">-directdisk</code> images have been replaced by a "live" + option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an + image file that can be + copied directly to a CD or USB device and run as is. + To build a live image, simply add + "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code> + file or wherever appropriate and then build the desired image as normal. + </div></div> + + <div class="chapter" title="Chapter 9. Reference: Features"><div class="titlepage"><div><div><h2 class="title"><a id="ref-features"></a>Chapter 9. Reference: Features</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-features-distro">9.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">9.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">9.3. Images</a></span></dt><dt><span class="section"><a href="#ref-features-backfill">9.4. Feature Backfilling</a></span></dt></dl></div><p> + Features provide a mechanism for working out which packages + should be included in the generated images. + Distributions can select which features they want to support through the + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code> + variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file. + Machine features are set in the + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code> + variable, which is set in the machine configuration file and + specifies the hardware features for a given machine. + </p><p> + These two variables combine to work out which kernel modules, + utilities, and other packages to include. + A given distribution can support a selected subset of features so some machine features might not + be included if the distribution itself does not support them. + </p><p> + One method you can use to determine which recipes are checking to see if a + particular feature is contained or not is to <code class="filename">grep</code> through + the metadata for the feature. + Here is an example that discovers the recipes whose build is potentially + changed based on a given feature: + </p><pre class="literallayout"> + $ cd $HOME/poky + $ git grep 'contains.*MACHINE_FEATURES.*<feature>' + </pre><p> + </p><p> + This chapter provides a reference of shipped machine and distro features + you can include as part of the image, a reference on image types you can + build, and a reference on feature backfilling. + </p><div class="section" title="9.1. Distro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-distro"></a>9.1. Distro</h2></div></div></div><p> + The items below are features you can use with + <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within <code class="filename">do_configure</code> for a particular + recipe. + </p><p> + This list only represents features as shipped with the Yocto Project metadata: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility + kernel modules will be installed if available).</p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only) + </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal + HDD/Microdrive for storing files (instead of Flash only devices) + </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support + </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be + loaded during boot). + </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support + </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support + </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB + networking/serial/storage) + </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external + keyboard, mouse, storage, network etc) + </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only) + </p></li><li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support + </p></li><li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support + </p></li><li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support + </p></li><li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on + device)</p></li><li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li><li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting + Samba/Microsoft Windows shares on device)</p></li></ul></div><p> + </p></div><div class="section" title="9.2. Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-machine"></a>9.2. Machine</h2></div></div></div><p> + The items below are features you can use with + <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>. + Features do not have a one-to-one correspondence to packages, and they can + go beyond simply controlling the installation of a package or packages. + Sometimes a feature can influence how certain recipes are built. + For example, a feature might determine whether a particular configure option + is specified within <code class="filename">do_configure</code> for a particular + recipe. + </p><p> + This feature list only represents features as shipped with the Yocto Project metadata: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only) + </p></li><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers + </p></li><li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation) + </p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT + </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive + </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support + </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard + </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus + </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets + </p></li><li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen + </p></li><li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232) + </p></li><li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen + </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable + </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable + </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi + </p></li></ul></div><p> + </p></div><div class="section" title="9.3. Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-image"></a>9.3. Images</h2></div></div></div><p> + The contents of images generated by the OpenEmbedded build system can be controlled by the + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> + and <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> + variables that you typically configure in your image recipes. + Through these variables you can add several different + predefined packages such as development utilities or packages with debug + information needed to investigate application problems or profile applications. + </p><p> + Current list of + <code class="filename">IMAGE_FEATURES</code> contains the following: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>splash:</em></span> Enables showing a splash screen during boot. + By default, this screen is provided by <code class="filename">psplash</code>, which does + allow customization. + If you prefer to use an alternative splash screen package, you can do so by + setting the <code class="filename">SPLASH</code> variable + to a different package name (or names) within the image recipe or at the distro + configuration level.</p></li><li class="listitem"><p><span class="emphasis"><em>ssh-server-dropbear:</em></span> Installs the Dropbear minimal + SSH server. + </p></li><li class="listitem"><p><span class="emphasis"><em>ssh-server-openssh:</em></span> Installs the OpenSSH SSH server, + which is more full-featured than Dropbear. + Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server + are present in <code class="filename">IMAGE_FEATURES</code>, then OpenSSH will take + precedence and Dropbear will not be installed.</p></li><li class="listitem"><p><span class="emphasis"><em>x11:</em></span> Installs the X server</p></li><li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> Installs the X server with a + minimal environment.</p></li><li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> Installs the OpenedHand Sato environment. + </p></li><li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> Installs a full SDK that runs on the device. + </p></li><li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Installs debugging tools such as + <code class="filename">strace</code> and <code class="filename">gdb</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Installs profiling tools such as + <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and + <code class="filename">LTTng</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Installs device testing tools (e.g. + touchscreen debugging).</p></li><li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> Installs an NFS server.</p></li><li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Installs development packages (headers and + extra library links) for all packages installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>staticdev-pkgs:</em></span> Installs static development + packages (i.e. static libraries containing <code class="filename">*.a</code> files) for all + packages installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Installs debug symbol packages for all packages + installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>doc-pkgs:</em></span> Installs documentation packages for all packages + installed in a given image.</p></li></ul></div><p> + </p></div><div class="section" title="9.4. Feature Backfilling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-backfill"></a>9.4. Feature Backfilling</h2></div></div></div><p> + Sometimes it is necessary in the OpenEmbedded build system to extend + <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a> + or <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a> + to control functionality that was previously enabled and not able + to be disabled. + For these cases, we need to add an + additional feature item to appear in one of these variables, + but we do not want to force developers who have existing values + of the variables in their configuration to add the new feature + in order to retain the same overall level of functionality. + Thus, the OpenEmbedded build system has a mechanism to + automatically "backfill" these added features into existing + distro or machine configurations. + You can see the list of features for which this is done by + finding the + <a class="link" href="#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL"><code class="filename">DISTRO_FEATURES_BACKFILL</code></a> + and <a class="link" href="#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL"><code class="filename">MACHINE_FEATURES_BACKFILL</code></a> + variables in the <code class="filename">meta/conf/bitbake.conf</code> file. + </p><p> + Because such features are backfilled by default into all + configurations as described in the previous paragraph, developers + who wish to disable the new features need to be able to selectively + prevent the backfilling from occurring. + They can do this by adding the undesired feature or features to the + <a class="link" href="#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED"><code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code></a> + or <a class="link" href="#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED"><code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code></a> + variables for distro features and machine features respectively. + </p><p> + Here are two examples to help illustrate feature backfilling: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The "pulseaudio" distro feature option</em></span>: + Previously, PulseAudio support was enabled within the Qt and + GStreamer frameworks. + Because of this, the feature is backfilled and thus + enabled for all distros through the + <code class="filename">DISTRO_FEATURES_BACKFILL</code> + variable in the <code class="filename">meta/conf/bitbake.conf</code> file. + However, your distro needs to disable the feature. + You can disable the feature without affecting + other existing distro configurations that need PulseAudio support + by adding "pulseaudio" to + <code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code> + in your distro's <code class="filename">.conf</code> file. + Adding the feature to this variable when it also + exists in the <code class="filename">DISTRO_FEATURES_BACKFILL</code> + variable prevents the build system from adding the feature to + your configuration's <code class="filename">DISTRO_FEATURES</code>, effectively disabling + the feature for that particular distro.</p></li><li class="listitem"><p><span class="emphasis"><em>The "rtc" machine feature option</em></span>: + Previously, real time clock (RTC) support was enabled for all + target devices. + Because of this, the feature is backfilled and thus enabled + for all machines through the <code class="filename">MACHINE_FEATURES_BACKFILL</code> + variable in the <code class="filename">meta/conf/bitbake.conf</code> file. + However, your target device does not have this capability. + You can disable RTC support for your device without + affecting other machines that need RTC support + by adding the feature to your machine's + <code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code> + list in the machine's <code class="filename">.conf</code> file. + Adding the feature to this variable when it also + exists in the <code class="filename">MACHINE_FEATURES_BACKFILL</code> + variable prevents the build system from adding the feature to + your configuration's <code class="filename">MACHINE_FEATURES</code>, effectively + disabling RTC support for that particular machine.</p></li></ul></div><p> + </p></div></div> + + <div class="chapter" title="Chapter 10. Variables Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glos"></a>Chapter 10. Variables Glossary</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p> + This chapter lists common variables used in the OpenEmbedded build system and gives an overview + of their function and contents. +</p><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glossary"></a>Glossary</h2></div></div></div><p> + <a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a> + <a class="link" href="#var-B" title="B">B</a> + <a class="link" href="#var-CFLAGS" title="CFLAGS">C</a> + <a class="link" href="#var-D" title="D">D</a> + <a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a> + <a class="link" href="#var-FILES" title="FILES">F</a> + + <a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">H</a> + <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a> + + <a class="link" href="#var-KBRANCH" title="KBRANCH">K</a> + <a class="link" href="#var-LAYERDIR" title="LAYERDIR">L</a> + <a class="link" href="#var-MACHINE" title="MACHINE">M</a> + + <a class="link" href="#var-OE_TERMINAL" title="OE_TERMINAL">O</a> + <a class="link" href="#var-P" title="P">P</a> + + <a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">R</a> + <a class="link" href="#var-S" title="S">S</a> + <a class="link" href="#var-T" title="T">T</a> + + + <a class="link" href="#var-WORKDIR" title="WORKDIR">W</a> + + + + </p><div class="glossdiv" title="A"><h3 class="title">A</h3><dl><dt><a id="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt><dd><p> + Specifies if an output package should still be produced if it is empty. + By default, BitBake does not produce empty packages. + This default behavior can cause issues when there is an + <a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or + some other runtime hard-requirement on the existence of the package. + </p><p> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + </p><pre class="literallayout"> + ALLOW_EMPTY_${PN} = "1" + </pre><p> + </p></dd><dt><a id="var-AUTHOR"></a>AUTHOR</dt><dd><p>The email address used to contact the original author or authors in + order to send patches, forward bugs, etc.</p></dd><dt><a id="var-AUTOREV"></a>AUTOREV</dt><dd><p>When <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code> + is set to the value of this variable, it specifies that the latest + source revision in the repository should be used. Here is an example: + </p><pre class="literallayout"> + SRCREV = "${AUTOREV}" + </pre><p> + </p></dd></dl></div><div class="glossdiv" title="B"><h3 class="title">B</h3><dl><dt><a id="var-B"></a>B</dt><dd><p> + The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + The OpenEmbedded build system places generated objects into the Build Directory + during a recipe's build process. + By default, this directory is the same as the <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> + directory: + </p><pre class="literallayout"> + B = ${WORKDIR}/${BPN}/{PV}/ + </pre><p> + You can separate the (<code class="filename">S</code>) directory and the directory pointed to + by the <code class="filename">B</code> variable. + Most autotools-based recipes support separating these directories. + The build system defaults to using separate directories for <code class="filename">gcc</code> + and some kernel recipes. + </p></dd><dt><a id="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt><dd><p> + A list of packages not to install despite being recommended by a recipe. + Support for this variable exists only when using the + <code class="filename">ipk</code> packaging backend. + </p></dd><dt><a id="var-BB_DISKMON_DIRS"></a>BB_DISKMON_DIRS</dt><dd><p> + Monitors disk space and available inodes during the build + and allows you to control the build based on these + parameters. + </p><p> + Disk space monitoring is disabled by default. + To enable monitoring, add the <code class="filename">BB_DISKMON_DIRS</code> + variable to your <code class="filename">conf/local.conf</code> file found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + Use the following form: + </p><pre class="literallayout"> + BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" + + where: + + <action> is: + ABORT: Immediately abort the build when + a threshold is broken. + STOPTASKS: Stop the build after the currently + executing tasks have finished when + a threshold is broken. + WARN: Issue a warning but continue the + build when a threshold is broken. + Subsequent warnings are issued as + defined by the + <a class="link" href="#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL">BB_DISKMON_WARNINTERVAL</a> variable, + which must be defined in the + conf/local.conf file. + + <dir> is: + Any directory you choose. You can specify one or + more directories to monitor by separating the + groupings with a space. If two directories are + on the same device, only the first directory + is monitored. + + <threshold> is: + Either the minimum available disk space, + the minimum number of free inodes, or + both. You must specify at least one. To + omit one or the other, simply omit the value. + Specify the threshold using G, M, K for Gbytes, + Mbytes, and Kbytes, respectively. If you do + not specify G, M, or K, Kbytes is assumed by + default. Do not use GB, MB, or KB. + </pre><p> + </p><p> + Here are some examples: + </p><pre class="literallayout"> + BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" + BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + </pre><p> + The first example works only if you also provide + the <a class="link" href="#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL"><code class="filename">BB_DISKMON_WARNINTERVAL</code></a> variable + in the <code class="filename">conf/local.conf</code>. + This example causes the build system to immediately + abort when either the disk space in <code class="filename">${TMPDIR}</code> drops + below 1 Gbyte or the available free inodes drops below + 100 Kbytes. + Because two directories are provided with the variable, the + build system also issue a + warning when the disk space in the + <code class="filename">${SSTATE_DIR}</code> directory drops + below 1 Gbyte or the number of free inodes drops + below 100 Kbytes. + Subsequent warnings are issued during intervals as + defined by the <code class="filename">BB_DISKMON_WARNINTERVAL</code> + variable. + </p><p> + The second example stops the build after all currently + executing tasks complete when the minimum disk space + in the <code class="filename">${TMPDIR}</code> directory drops + below 1 Gbyte. + No disk monitoring occurs for the free inodes in this case. + </p><p> + The final example immediately aborts the build when the + number of free inodes in the <code class="filename">${TMPDIR}</code> directory + drops below 100 Kbytes. + No disk space monitoring for the directory itself occurs + in this case. + </p></dd><dt><a id="var-BB_DISKMON_WARNINTERVAL"></a>BB_DISKMON_WARNINTERVAL</dt><dd><p> + Defines the disk space and free inode warning intervals. + To set these intervals, define the variable in your + <code class="filename">conf/local.conf</code> file in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + </p><p> + If you are going to use the + <code class="filename">BB_DISKMON_WARNINTERVAL</code> variable, you must + also use the + <a class="link" href="#var-BB_DISKMON_DIRS" title="BB_DISKMON_DIRS"><code class="filename">BB_DISKMON_DIRS</code></a> variable + and define its action as "WARN". + During the build, subsequent warnings are issued each time + disk space or number of free inodes further reduces by + the respective interval. + </p><p> + If you do not provide a <code class="filename">BB_DISKMON_WARNINTERVAL</code> + variable and you do use <code class="filename">BB_DISKMON_DIRS</code> with + the "WARN" action, the disk monitoring interval defaults to + the following: + </p><pre class="literallayout"> + BB_DISKMON_WARNINTERVAL = "50M,5K" + </pre><p> + </p><p> + When specifying the variable in your configuration file, + use the following form: + </p><pre class="literallayout"> + BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" + + where: + + <disk_space_interval> is: + An interval of memory expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + <disk_inode_interval> is: + An interval of free inodes expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + </pre><p> + </p><p> + Here is an example: + </p><pre class="literallayout"> + BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_WARNINTERVAL = "50M,5K" + </pre><p> + These variables cause the OpenEmbedded build system to + issue subsequent warnings each time the available + disk space further reduces by 50 Mbytes or the number + of free inodes further reduces by 5 Kbytes in the + <code class="filename">${SSTATE_DIR}</code> directory. + Subsequent warnings based on the interval occur each time + a respective interval is reached beyond the intial warning + (i.e. 1 Gbytes and 100 Kbytes). + </p></dd><dt><a id="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt><dd><p> + Allows you to extend a recipe so that it builds variants of the software. + Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>, + which is a copy of quilt built to run on the build system; + "crosses" such as <code class="filename">gcc-cross</code>, + which is a compiler built to run on the build machine but produces binaries + that run on the target <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>; + "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>; + and "mulitlibs" in the form "<code class="filename">multilib:<multilib_name></code>". + </p><p> + To build a different variant of the recipe with a minimal amount of code, it usually + is as simple as adding the following to your recipe: + </p><pre class="literallayout"> + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:<multilib_name>" + </pre><p> + </p></dd><dt><a id="var-BBMASK"></a>BBMASK</dt><dd><p>Prevents BitBake from processing recipes and recipe append files. + You can use the <code class="filename">BBMASK</code> variable to "hide" + these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files. + BitBake ignores any recipe or recipe append files that match the expression. + It is as if BitBake does not see them at all. + Consequently, matching files are not parsed or otherwise used by + BitBake.</p><p>The value you provide is passed to python's regular expression compiler. + For complete syntax information, see python's documentation at + <a class="ulink" href="http://docs.python.org/release/2.3/lib/re-syntax.html" target="_top">http://docs.python.org/release/2.3/lib/re-syntax.html</a>. + The expression is compared against the full paths to the files. + For example, the following uses a complete regular expression to tell + BitBake to ignore all recipe and recipe append files in the + <code class="filename">.*/meta-ti/recipes-misc/</code> directory: + </p><pre class="literallayout"> + BBMASK = ".*/meta-ti/recipes-misc/" + </pre><p>Use the <code class="filename">BBMASK</code> variable from within the + <code class="filename">conf/local.conf</code> file found + in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.</p></dd><dt><a id="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>The maximum number of tasks BitBake should run in parallel at any one time. + If your host development system supports multiple cores a good rule of thumb + is to set this variable to twice the number of cores.</p></dd><dt><a id="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt><dd><p>Lists the names of configured layers. + These names are used to find the other <code class="filename">BBFILE_*</code> + variables. + Typically, each layer will append its name to this variable in its + <code class="filename">conf/layer.conf</code> file. + </p></dd><dt><a id="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt><dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer. + This variable is used in the <code class="filename">conf/layer.conf</code> file and must + be suffixed with the name of the specific layer (e.g. + <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd><dt><a id="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt><dd><p>Assigns the priority for recipe files in each layer.</p><p>This variable is useful in situations where the same recipe appears in + more than one layer. + Setting this variable allows you to prioritize a + layer against other layers that contain the same recipe - effectively + letting you control the precedence for the multiple layers. + The precedence established through this variable stands regardless of a + recipe's version (<code class="filename">PV</code> variable). + For example, a layer that has a recipe with a higher <code class="filename">PV</code> value but for + which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a + lower precedence.</p><p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher + precedence. + For example, the value 6 has a higher precedence than the value 5. + If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer + dependencies (see the + <code class="filename"><a class="link" href="#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for + more information. + The default priority, if unspecified + for a layer with no dependencies, is the lowest defined priority + 1 + (or 1 if no priorities are defined).</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + You can use the command <code class="filename">bitbake-layers show_layers</code> to list + all configured layers along with their priorities. + </div></dd><dt><a id="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipe files used by BitBake to build software</p></dd><dt><a id="var-BBPATH"></a>BBPATH</dt><dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files. + This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd><dt><a id="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd><dt><a id="var-BBLAYERS"></a>BBLAYERS</dt><dd><p>Lists the layers to enable during the build. + This variable is defined in the <code class="filename">bblayers.conf</code> configuration + file in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + Here is an example: + </p><pre class="literallayout"> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + " + </pre><p> + This example enables four layers, one of which is a custom, user-defined layer + named <code class="filename">meta-mykernel</code>. + </p></dd><dt><a id="var-BBLAYERS_NON_REMOVABLE"></a>BBLAYERS_NON_REMOVABLE</dt><dd><p>Lists core layers that cannot be removed from the + <code class="filename">bblayers.conf</code> file. + In order for BitBake to build your image, your + <code class="filename">bblayers.conf</code> file must include the + <code class="filename">meta</code> and <code class="filename">meta-yocto</code> + core layers. + Here is an example that shows these two layers listed in + the <code class="filename">BBLAYERS_NON_REMOVABLE</code> statement: + </p><pre class="literallayout"> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + " + </pre><p> + </p></dd><dt><a id="var-BP"></a>BP</dt><dd><p>The base recipe name and version but without any special + recipe name suffix (i.e. <code class="filename">-native</code>, <code class="filename">lib64-</code>, + and so forth). + <code class="filename">BP</code> is comprised of the following: + </p><pre class="literallayout"> + ${BPN}-${PV} + </pre></dd><dt><a id="var-BPN"></a>BPN</dt><dd><p>The bare name of the recipe. + This variable is a version of the <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> variable + but removes common suffixes such as "-native" and "-cross" as well + as removes common prefixes such as multilib's "lib64-" and "lib32-". + The exact list of suffixes removed is specified by the + <a class="link" href="#var-SPECIAL_PKGSUFFIX" title="SPECIAL_PKGSUFFIX"><code class="filename">SPECIAL_PKGSUFFIX</code></a> variable. + The exact list of prefixes removed is specified by the + <a class="link" href="#var-MLPREFIX" title="MLPREFIX"><code class="filename">MLPREFIX</code></a> variable. + Prefixes are removed for multilib and nativesdk cases.</p></dd></dl></div><div class="glossdiv" title="C"><h3 class="title">C</h3><dl><dt><a id="var-CFLAGS"></a>CFLAGS</dt><dd><p> + Flags passed to C compiler for the target system. + This variable evaluates to the same as + <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>. + </p></dd><dt><a id="var-COMBINED_FEATURES"></a>COMBINED_FEATURES</dt><dd><p>A set of features common between + <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a> + and <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>. + See the glossary descriptions for these variables for more information.</p></dd><dt><a id="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt><dd><p>A regular expression which evaluates to match the machines the recipe + works with. + It stops recipes being run on machines for which they are not compatible. + This is particularly useful with kernels. + It also helps to increase parsing speed as further parsing of the recipe is skipped + if it is found the current machine is not compatible.</p></dd><dt><a id="var-CONFFILES"></a>CONFFILES</dt><dd><p> + Identifies editable or configurable files that are part of a package. + If the Package Management System (PMS) is being used to update + packages on the target system, it is possible that + configuration files you have changed after the original installation + and that you now want to remain unchanged are overwritten. + In other words, editable files might exist in the package that you do not + want reset as part of the package update process. + You can use the <code class="filename">CONFFILES</code> variable to list the files in the + package that you wish to prevent the PMS from overwriting during this update process. + </p><p> + To use the <code class="filename">CONFFILES</code> variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files. + Here is an example: + </p><pre class="literallayout"> + CONFFILES_${PN} += "${sysconfdir}/file1 \ + ${sysconfdir}/file2 ${sysconfdir}/file3" + </pre><p> + </p><p> + A relationship exists between the <code class="filename">CONFFILES</code> and + <code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a></code> variables. + The files listed within <code class="filename">CONFFILES</code> must be a subset of + the files listed within <code class="filename">FILES</code>. + Because the configuration files you provide with <code class="filename">CONFFILES</code> + are simply being identified so that the PMS will not overwrite them, + it makes sense that + the files must already be included as part of the package through the + <code class="filename">FILES</code> variable. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + When specifying paths as part of the <code class="filename">CONFFILES</code> variable, + it is good practice to use appropriate path variables. + For example, <code class="filename">${sysconfdir}</code> rather than + <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather + than <code class="filename">/usr/bin</code>. + You can find a list of these variables at the top of the + <code class="filename">/meta/conf/bitbake.conf</code> file in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </div></dd><dt><a id="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p> + A list of files that contains <code class="filename">autoconf</code> test results relevant + to the current build. + This variable is used by the Autotools utilities when running + <code class="filename">configure</code>. + </p></dd><dt><a id="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt><dd><p> + Specifies the list of packages to be added to the image. + This variable should only be set in the <code class="filename">local.conf</code> + configuration file found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + </p><p> + This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported. + </p></dd></dl></div><div class="glossdiv" title="D"><h3 class="title">D</h3><dl><dt><a id="var-D"></a>D</dt><dd><p>The destination directory.</p></dd><dt><a id="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p> + Specifies to build packages with debugging information. + This influences the value of the + <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code> + variable. + </p></dd><dt><a id="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p> + The options to pass in + <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> + and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling + a system for debugging. + This variable defaults to "-O -fno-omit-frame-pointer -g". + </p></dd><dt><a id="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Specifies the priority of recipes.</p></dd><dt><a id="var-DEPENDS"></a>DEPENDS</dt><dd><p> + Lists a recipe's build-time dependencies + (i.e. other recipe files). + The system ensures that all the dependencies listed + have been built and have their contents in the appropriate + sysroots before the recipe's configure task is executed. + </p></dd><dt><a id="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>The package description used by package managers. + If not set, <code class="filename">DESCRIPTION</code> takes + the value of the + <a class="link" href="#var-SUMMARY" title="SUMMARY"><code class="filename">SUMMARY</code></a> + variable. + </p></dd><dt><a id="var-DESTDIR"></a>DESTDIR</dt><dd><p>the destination directory.</p></dd><dt><a id="var-DISTRO"></a>DISTRO</dt><dd><p> + The short name of the distribution. + This variable corresponds to a file with the + extension <code class="filename">.conf</code> + located in a <code class="filename">conf/distro</code> directory + within the metadata that contains the distribution configuration. + The + value must not contain spaces, and is typically all lower-case. + </p><p> + If the variable is blank, a set of default configuration + will be used, which is specified + within <code class="filename">meta/conf/distro/defaultsetup.conf</code>. + </p></dd><dt><a id="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt><dd><p> + Specifies a list of distro-specific packages to add to all images. + This variable takes affect through + <code class="filename">packagegroup-base</code> so the + variable only really applies to the more full-featured + images that include <code class="filename">packagegroup-base</code>. + You can use this variable to keep distro policy out of + generic images. + As with all other distro variables, you set this variable + in the distro <code class="filename">.conf</code> file. + </p></dd><dt><a id="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p> + Specifies a list of distro-specific packages to add to all images + if the packages exist. + The packages might not exist or be empty (e.g. kernel modules). + The list of packages are automatically installed but can be + removed by the user. + </p></dd><dt><a id="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>The features enabled for the distribution. + For a list of features supported by the Yocto Project as shipped, + see the "<a class="link" href="#ref-features-distro" title="9.1. Distro">Distro</a>" + section. + </p></dd><dt><a id="var-DISTRO_FEATURES_BACKFILL"></a>DISTRO_FEATURES_BACKFILL</dt><dd><p>Features to be added to + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code> + if not also present in + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED">DISTRO_FEATURES_BACKFILL_CONSIDERED</a></code>. + </p><p> + This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file. + 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 <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for + more information. + </p></dd><dt><a id="var-DISTRO_FEATURES_BACKFILL_CONSIDERED"></a>DISTRO_FEATURES_BACKFILL_CONSIDERED</dt><dd><p>Features from + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL">DISTRO_FEATURES_BACKFILL</a></code> + that should not backfilled (i.e. added to + <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>) + during the build. + See the "<a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature Backfilling</a>" section for + more information. + </p></dd><dt><a id="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>The long name of the distribution.</p></dd><dt><a id="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt><dd><p>Alias names used for the recipe in various Linux distributions.</p><p>See the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-configuring-DISTRO_PN_ALIAS" target="_top">Handling + a Package Name Alias</a>" section in the Yocto Project Development + Manual for more information.</p></dd><dt><a id="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>the version of the distribution.</p></dd><dt><a id="var-DL_DIR"></a>DL_DIR</dt><dd><p> + The central download directory used by the build process to store downloads. + You can set this directory by defining the <code class="filename">DL_DIR</code> + variable in the <code class="filename">/conf/local.conf</code> file. + This directory is self-maintaining and you should not have + to touch it. + By default, the directory is <code class="filename">downloads</code> in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + </p><pre class="literallayout"> + #DL_DIR ?= "${TOPDIR}/downloads" + </pre><p> + To specify a different download directory, simply uncomment the line + and provide your directory. + </p><p> + During a first build, the system downloads many different source code + tarballs from various upstream projects. + Downloading can take a while, particularly if your network + connection is slow. + Tarballs are all stored in the directory defined by + <code class="filename">DL_DIR</code> and the build system looks there first + to find source tarballs. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + When wiping and rebuilding, you can preserve this directory to speed + up this part of subsequent builds. + </div><p> + </p><p> + You can safely share this directory between multiple builds on the + same development machine. + For additional information on how the build process gets source files + when working behind a firewall or proxy server, see the + "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server">FAQ</a>" + chapter. + </p></dd></dl></div><div class="glossdiv" title="E"><h3 class="title">E</h3><dl><dt><a id="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p></p><p>Variable that controls which locales for <code class="filename">eglibc</code> are + to be generated during the build (useful if the target device has 64Mbytes + of RAM or less).</p></dd><dt><a id="var-EXTENDPE"></a>EXTENDPE</dt><dd><p> + Used with file and pathnames to create a prefix for a recipe's + version based on the recipe's + <a class="link" href="#var-PE" title="PE"><code class="filename">PE</code></a> value. + If <code class="filename">PE</code> is set and greater than zero for a recipe, + <code class="filename">EXTENDPE</code> becomes that value (e.g if + <code class="filename">PE</code> is equal to "1" then <code class="filename">EXTENDPE</code> + becomes "1_"). + If a recipe's <code class="filename">PE</code> is not set (the default) or is equal to + zero, <code class="filename">EXTENDPE</code> becomes "".</p><p>See the <a class="link" href="#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> + variable for an example. + </p></dd><dt><a id="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt><dd><p>Allows extra packages to be added to the generated images. + You set this variable in the <code class="filename">local.conf</code> + configuration file. + Note that some image features are also added using the + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> + variable generally configured in image recipes. + You can use this variable to add more features in addition to those. + Here are some examples of features you can add:</p><pre class="literallayout"> +"dbg-pkgs" - Adds -dbg packages for all installed packages + including symbol information for debugging and + profiling. + +"dev-pkgs" - Adds -dev packages for all installed packages. + This is useful if you want to develop against + the libraries in the image. + +"tools-sdk" - Adds development tools such as gcc, make, + pkgconfig and so forth. + +"tools-debug" - Adds debugging tools such as gdb and + strace. + +"tools-profile" - Adds profiling tools such as oprofile, + exmap, lttng and valgrind (x86 only). + +"tools-testapps" - Adds useful testing tools such as + ts_print, aplay, arecord and so + forth. + +"debug-tweaks" - Makes an image suitable for development. + For example, ssh root access has a blank + password. You should remove this feature + before you produce a production image. + </pre><p>There are other valid features too, see the + <a class="link" href="#ref-features-image" title="9.3. Images">Images</a> + section for more details.</p></dd><dt><a id="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt><dd><p>A list of recipes to be built that do not provide packages to be installed in + the root filesystem. + </p><p>Sometimes a recipe is required to build the final image but is not + needed in the root filesystem. + You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to + list these recipes and thus, specify the dependencies. + A typical example is a required bootloader in a machine configuration. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + To add packages to the root filesystem, see the various + <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code> + variables. + </div></dd><dt><a id="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt><dd><p>Additional <code class="filename">cmake</code> options.</p></dd><dt><a id="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional <code class="filename">configure</code> script options.</p></dd><dt><a id="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU <code class="filename">make</code> options.</p></dd></dl></div><div class="glossdiv" title="F"><h3 class="title">F</h3><dl><dt><a id="var-FILES"></a>FILES</dt><dd><p> + The list of directories or files that are placed in packages. + </p><p> + To use the <code class="filename">FILES</code> variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files or paths that identifies the + files you want included as part of the resulting package. + Here is an example: + </p><pre class="literallayout"> + FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + When specifying paths as part of the <code class="filename">FILES</code> variable, + it is good practice to use appropriate path variables. + For example, <code class="filename">${sysconfdir}</code> rather than + <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather + than <code class="filename">/usr/bin</code>. + You can find a list of these variables at the top of the + <code class="filename">/meta/conf/bitbake.conf</code> file in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </div><p> + If some of the files you provide with the <code class="filename">FILES</code> variable + are editable and you know they should not be + overwritten during the package update process by the Package Management + System (PMS), you can identify these files so that the PMS will not + overwrite them. + See the <code class="filename"><a class="link" href="#var-CONFFILES" title="CONFFILES">CONFFILES</a></code> + variable for information on how to identify these files to the PMS. + </p></dd><dt><a id="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt><dd><p> + Extends the search path the OpenEmbedded build system uses when + looking for files and patches as it processes recipes. + The directories BitBake uses when it processes recipes is defined by the + <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable. + You can add directories to the search path by defining the + <code class="filename">FILESEXTRAPATHS</code> variable. + </p><p> + To add paths to the search order, provide a list of directories and separate + each path using a colon character as follows: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" + </pre><p> + Typically, you want your directories searched first. + To make sure that happens, use <code class="filename">_prepend</code> and + the immediate expansion (<code class="filename">:=</code>) operator as shown in the + previous example. + Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable, + you must include the appropriate beginning or ending (as needed) colon character. + </p><p> + The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in + <code class="filename">.bbappend</code> files to include any additional files provided in that layer. + You typically accomplish this with the following: + </p><pre class="literallayout"> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </pre><p> + </p></dd><dt><a id="var-FILESPATH"></a>FILESPATH</dt><dd><p> + The default set of directories the OpenEmbedded build system uses + when searching for patches and files. + During the build process, BitBake searches each directory in + <code class="filename">FILESPATH</code> in the specified order when looking for + files and patches specified by each <code class="filename">file://</code> URI in a recipe. + </p><p> + The default value for the <code class="filename">FILESPATH</code> variable is defined + in the <code class="filename">base.bbclass</code> class found in + <code class="filename">meta/classes</code> in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>: + </p><pre class="literallayout"> +FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ + "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \ + "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ + "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" + </pre><p> + Do not hand-edit the <code class="filename">FILESPATH</code> variable. + If you want to extend the set of pathnames that BitBake uses when searching for + files and patches, use the + <a class="link" href="#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable. + </p></dd><dt><a id="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt><dd><p>Allows you to define your own file permissions settings table as part of + your configuration for the packaging process. + For example, suppose you need a consistent set of custom permissions for + a set of groups and users across an entire work project. + It is best to do this in the packages themselves but this is not always + possible. + </p><p> + By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which + is located in the <code class="filename">meta/files</code> folder in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + If you create your own file permissions setting table, you should place it in your + layer or the distros layer. + </p><p> + You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the + <code class="filename">conf/local.conf</code> file, which is found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>, to + point to your custom <code class="filename">fs-perms.txt</code>. + You can specify more than a single file permissions setting table. + The paths you specify to these files must be defined within the + <code class="filename">BBPATH</code> variable. + </p><p> + For guidance on how to create your own file permissions settings table file, + examine the existing <code class="filename">fs-perms.txt</code>. + </p></dd><dt><a id="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p> + The options to pass in + <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code> + and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> + when compiling an optimized system. + This variable defaults to + "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". + </p></dd></dl></div><div class="glossdiv" title="H"><h3 class="title">H</h3><dl><dt><a id="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more information about the software the recipe is building + can be found.</p></dd></dl></div><div class="glossdiv" title="I"><h3 class="title">I</h3><dl><dt><a id="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p>The list of features to include in an image. + Typically, you configure this variable in an image recipe. + Note that you can also add extra features to the image by using the + <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> variable. + See the "<a class="link" href="#ref-features-image" title="9.3. Images">Images</a>" section for the + full list of features that can be included in images built by the + OpenEmbedded build system.</p></dd><dt><a id="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of root filesystem images that you want to have created.</p></dd><dt><a id="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p> + Specifies the packages to install into an image. + The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image + recipe and you should use it with care to avoid ordering issues. + </p><p> + Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the + packages to install into an image through <code class="filename">image.bbclass</code>. + Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>, + that can take + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists + and turn these into auto-generated entries in + <code class="filename">IMAGE_INSTALL</code> in addition to its default contents. + </p><p> + Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code> + operator from the <code class="filename">/conf/local.conf</code> file or from within + an image recipe is not recommended as it can cause ordering issues. + Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code> + to a default value using the <code class="filename">?=</code> operator, using a + <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code> + will result in unexpected behavior when used in + <code class="filename">/conf/local.conf</code>. + Furthermore, the same operation from with 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 <code class="filename">+=</code> operator to work. + </p><p> + When you use this variable, it is best to use it as follows: + </p><pre class="literallayout"> + IMAGE_INSTALL_append = " package-name" + </pre><p> + Be sure to include the space between the quotation character and the start of the + package name. + </p></dd><dt><a id="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt><dd><p> + Defines a multiplier that the build system applies to the initial image + size for cases when the multiplier times the returned disk usage value + for the image is greater than the sum of + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> + and + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>. + The result of the multiplier applied to the initial image size creates + free disk space in the image as overhead. + By default, the build process uses a multiplier of 1.3 for this variable. + This default value results in 30% free disk space added to the image when this + method is used to determine the final generated image size. + You should be aware that post install scripts and the package management + system uses disk space inside this overhead area. + Consequently, the multiplier does not produce an image with + all the theoretical free disk space. + See <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code> + for information on how the build system determines the overall image size. + </p><p> + The default 30% free disk space typically gives the image enough room to boot + and allows for basic post installs while still leaving a small amount of + free disk space. + If 30% free space is inadequate, you can increase the default value. + For example, the following setting gives you 50% free space added to the image: + </p><pre class="literallayout"> + IMAGE_OVERHEAD_FACTOR = "1.5" + </pre><p> + </p><p> + Alternatively, you can ensure a specific amount of free disk space is added + to the image by using + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code> + the variable. + </p></dd><dt><a id="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt><dd><p> + Defines additional free disk space created in the image in Kbytes. + By default, this variable is set to "0". + This free disk space is added to the image after the build system determines + the image size as described in + <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>. + </p><p> + This variable is particularly useful when you want to ensure that a + specific amount of free disk space is available on a device after an image + is installed and running. + For example, to be sure 5 Gbytes of free disk space is available, set the + variable as follows: + </p><pre class="literallayout"> + IMAGE_ROOTFS_EXTRA_SPACE = "5242880" + </pre><p> + </p></dd><dt><a id="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt><dd><p> + Defines the size in Kbytes for the generated image. + The OpenEmbedded build system determines the final size for the generated + image using an algorithm that takes into account the initial disk space used + for the generated image, a requested size for the image, and requested + additional free disk space to be added to the image. + Programatically, the build system determines the final size of the + generated image as follows: + </p><pre class="literallayout"> + if (image-du * overhead) < rootfs-size: + internal-rootfs-size = rootfs-size + xspace + else: + internal-rootfs-size = (image-du * overhead) + xspace + + where: + + image-du = Returned value of the du command on + the image. + + overhead = IMAGE_OVERHEAD_FACTOR + + rootfs-size = IMAGE_ROOTFS_SIZE + + internal-rootfs-size = Initial root filesystem + size before any modifications. + + xspace = IMAGE_ROOTFS_EXTRA_SPACE + </pre><p> + + </p></dd><dt><a id="var-INC_PR"></a>INC_PR</dt><dd><p>Helps define the recipe revision for recipes that share + a common <code class="filename">include</code> file. + You can think of this variable as part of the recipe revision + as set from within an include file.</p><p>Suppose, for example, you have a set of recipes that + are used across several projects. + And, within each of those recipes the revision + (its <code class="filename">PR</code> value) is set accordingly. + In this case, when the revision of those recipes changes + the burden is on you to find all those recipes and + be sure that they get changed to reflect the updated + version of the recipe. + In this scenario, it can get complicated when recipes + used in many places and that provide common functionality + are upgraded to a new revision.</p><p>A more efficient way of dealing with this situation is + to set the <code class="filename">INC_PR</code> variable inside + the <code class="filename">include</code> files that the recipes + share and then expand the <code class="filename">INC_PR</code> + variable within the recipes to help + define the recipe revision. + </p><p> + The following provides an example that shows how to use + the <code class="filename">INC_PR</code> variable + given a common <code class="filename">include</code> file that + defines the variable. + Once the variable is defined in the + <code class="filename">include</code> file, you can use the + variable to set the <code class="filename">PR</code> values in + each recipe. + You will notice that when you set a recipe's + <code class="filename">PR</code> you can provide more granular + revisioning by appending values to the + <code class="filename">INC_PR</code> variable: + </p><pre class="literallayout"> +recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" +recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" +recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" +recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + </pre><p> + The first line of the example establishes the baseline + revision to be used for all recipes that use the + <code class="filename">include</code> file. + The remaining lines in the example are from individual + recipes and show how the <code class="filename">PR</code> value + is set.</p></dd><dt><a id="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p> + Causes the build to not strip binaries in resulting packages. + </p></dd><dt><a id="var-INHERIT"></a>INHERIT</dt><dd><p> + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + </p></dd><dt><a id="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p> + A list of the packages that contain initscripts. + If multiple packages are specified, you need to append the package name + to the other <code class="filename">INITSCRIPT_*</code> as an override.</p><p> + This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. + The variable is optional and defaults to the <code class="filename">PN</code> variable. + </p></dd><dt><a id="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p> + The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>. + </p><p> + This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>. + The variable is Mandatory. + </p></dd><dt><a id="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p> + Specifies the options to pass to <code class="filename">update-rc.d</code>. + An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a + runlevel of 99, starts the script in initlevels 2 and 5, and + stops the script in levels 0, 1 and 6. + </p><p> + The variable is mandatory and is used in recipes when using + <code class="filename">update-rc.d.bbclass</code>. + </p></dd></dl></div><div class="glossdiv" title="K"><h3 class="title">K</h3><dl><dt><a id="var-KBRANCH"></a>KBRANCH</dt><dd><p> + A regular expression used by the build process to explicitly identify the kernel + branch that is validated, patched and configured during a build. + The <code class="filename">KBRANCH</code> variable is optional. + You can use it to trigger checks to ensure the exact kernel branch you want is + being used by the build process. + </p><p> + Values for this variable are set in the kernel's recipe file and the kernel's + append file. + For example, if you are using the Yocto Project kernel that is based on the + Linux 3.4 kernel, the kernel recipe file is the + <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.4.bb</code> file. + Following is the default value for <code class="filename">KBRANCH</code> and the default + override for the architectures the Yocto Project supports: + </p><pre class="literallayout"> + KBRANCH_DEFAULT = "standard/base" + KBRANCH = "${KBRANCH_DEFAULT}" + </pre><p> + This branch exists in the <code class="filename">linux-yocto-3.4</code> kernel Git + repository <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads</a>. + </p><p> + This variable is also used from the kernel's append file to identify the kernel + branch specific to a particular machine or target hardware. + The kernel's append file is located in the BSP layer for a given machine. + For example, the kernel append file for the Crown Bay BSP is in the + <code class="filename">meta-intel</code> Git repository and is named + <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</code>. + Here are the related statements from the append file: + </p><pre class="literallayout"> + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/crownbay" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/crownbay" + </pre><p> + The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to + use when building for the Crown Bay BSP. + In this case there are two identical statements: one for each type of + Crown Bay machine. + </p></dd><dt><a id="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt><dd><p>Includes additional metadata from the Yocto Project kernel Git repository. + In the OpenEmbedded build system, the default Board Support Packages (BSPs) + metadata is provided through + the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables. + You can use the <code class="filename">KERNEL_FEATURES</code> variable to further + add metadata for all BSPs.</p><p>The metadata you add through this variable includes config fragments and + features descriptions, + which usually includes patches as well as config fragments. + You typically override the <code class="filename">KERNEL_FEATURES</code> variable + for a specific machine. + In this way, you can provide validated, but optional, sets of kernel + configurations and features.</p><p>For example, the following adds <code class="filename">netfilter</code> to all + the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code> + machine: + </p><pre class="literallayout"> + # Add netfilter to all linux-yocto kernels + KERNEL_FEATURES="features/netfilter" + + # Add sound support to the qemux86 machine + KERNEL_FEATURES_append_qemux86=" cfg/sound" + </pre></dd><dt><a id="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the + machine configuration files and defaults to "zImage". + This variable is used + when building the kernel and is passed to <code class="filename">make</code> as the target to + build.</p></dd><dt><a id="var-KMACHINE"></a>KMACHINE</dt><dd><p> + The machine as known by the kernel. + Sometimes the machine name used by the kernel does not match the machine name + used by the OpenEmbedded build system. + For example, the machine name that the OpenEmbedded build system understands as + <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel. + The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>. + For cases like these, the <code class="filename">KMACHINE</code> variable maps the + kernel machine name to the OpenEmbedded build system machine name. + </p><p> + Kernel machine names are initially defined in the + <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">Yocto Linux Kernel</a> in + the <code class="filename">meta</code> branch. + From the <code class="filename">meta</code> branch, look in + the <code class="filename">meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</code> file. + For example, from the <code class="filename">meta</code> branch in the + <code class="filename">linux-yocto-3.0</code> kernel, the + <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file + has the following: + </p><pre class="literallayout"> + define KMACHINE cedartrail + define KTYPE standard + define KARCH i386 + + include ktypes/standard + branch cedartrail + + include cedartrail.scc + </pre><p> + You can see that the kernel understands the machine name for the Cedar Trail BSP as + <code class="filename">cedartrail</code>. + </p><p> + If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source + repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>, + you will find the following statements among others: + </p><pre class="literallayout"> + COMPATIBLE_MACHINE_cedartrail = "cedartrail" + KMACHINE_cedartrail = "cedartrail" + KBRANCH_cedartrail = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" + KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" + + COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" + KMACHINE_cedartrail-nopvr = "cedartrail" + KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" + </pre><p> + The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that + the OpenEmbedded build system and the Yocto Linux kernel understand the same machine + names. + </p><p> + This append file uses two <code class="filename">KMACHINE</code> statements. + The first is not really necessary but does ensure that the machine known to the + OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine + in the kernel also known as <code class="filename">cedartrail</code>: + </p><pre class="literallayout"> + KMACHINE_cedartrail = "cedartrail" + </pre><p> + </p><p> + The second statement is a good example of why the <code class="filename">KMACHINE</code> variable + is needed. + In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code> + machine name to refer to the Cedar Trail BSP that does not support the propriatory + PowerVR driver. + The kernel, however, uses the machine name <code class="filename">cedartrail</code>. + Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to + the kernel's <code class="filename">cedartrail</code> name: + </p><pre class="literallayout"> + KMACHINE_cedartrail-nopvr = "cedartrail" + </pre><p> + </p><p> + BSPs that ship with the Yocto Project release provide all mappings between the Yocto + Project kernel machine names and the OpenEmbedded machine names. + Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine + name you use is different than that used in the kernel. + </p></dd></dl></div><div class="glossdiv" title="L"><h3 class="title">L</h3><dl><dt><a id="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt><dd><p>Lists the layers that this recipe depends upon, separated by spaces. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" + to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case). + An error will be produced if any dependency is missing or + the version numbers do not match exactly (if specified). + This variable is used in the <code class="filename">conf/layer.conf</code> file + and must be suffixed with the name of the specific layer (e.g. + <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd><dt><a id="var-LAYERDIR"></a>LAYERDIR</dt><dd><p>When used inside the <code class="filename">layer.conf</code> configuration + file, this variable provides the path of the current layer. + This variable requires immediate expansion + (see the BitBake manual) as lazy expansion can result in + the expansion happening in the wrong directory and therefore + giving the wrong value.</p></dd><dt><a id="var-LAYERVERSION"></a>LAYERVERSION</dt><dd><p>Optionally specifies the version of a layer as a single number. + You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to + depend on a specific version of the layer. + This variable is used in the <code class="filename">conf/layer.conf</code> file + and must be suffixed with the name of the specific layer (e.g. + <code class="filename">LAYERVERSION_mylayer</code>).</p></dd><dt><a id="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt><dd><p>Checksums of the license text in the recipe source code.</p><p>This variable tracks changes in license text of the source + code files. + If the license text is changed, it will trigger a build + failure, which gives the developer an opportunity to review any + license change.</p><p> + This variable must be defined for all recipes (unless <code class="filename">LICENSE</code> + is set to "CLOSED")</p><p>For more information, see the + <a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" title="3.4.1. Tracking License Changes"> + Tracking License Changes</a> section</p></dd><dt><a id="var-LICENSE"></a>LICENSE</dt><dd><p> + The list of source licenses for the recipe. + Follow these rules: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Do not use spaces within individual + license names.</p></li><li class="listitem"><p>Separate license names using + | (pipe) when there is a choice between licenses. + </p></li><li class="listitem"><p>Separate license names using + & (ampersand) when multiple licenses exist + that cover different parts of the source. + </p></li><li class="listitem"><p>You can use spaces between license + names.</p></li></ul></div><p> + </p><p> + Here are some examples: + </p><pre class="literallayout"> + LICENSE = "LGPLv2.1 | GPLv3" + LICENSE = "MPL-1 & LGPLv2.1" + LICENSE = "GPLv2+" + </pre><p> + The first example is from the recipes for Qt, which the user + may choose to distribute under either the LGPL version + 2.1 or GPL version 3. + The second example is from Cairo where two licenses cover + different parts of the source code. + The final example is from <code class="filename">sysstat</code>, + which presents a single license. + </p></dd><dt><a id="var-LICENSE_PATH"></a>LICENSE_PATH</dt><dd><p>Path to additional licenses used during the build. + By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code> + to define the directory that holds common license text used during the build. + The <code class="filename">LICENSE_PATH</code> variable allows you to extend that + location to other areas that have additional licenses: + </p><pre class="literallayout"> + LICENSE_PATH += "/path/to/additional/common/licenses" + </pre></dd></dl></div><div class="glossdiv" title="M"><h3 class="title">M</h3><dl><dt><a id="var-MACHINE"></a>MACHINE</dt><dd><p> + Specifies the target device for which the image is built. + You define <code class="filename">MACHINE</code> in the + <code class="filename">local.conf</code> file found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + By default, <code class="filename">MACHINE</code> is set to + "qemux86", which is an x86-based architecture machine to + be emulated using QEMU: + </p><pre class="literallayout"> + MACHINE ?= "qemux86" + </pre><p> + The variable corresponds to a machine configuration file of the + same name, through which machine-specific configurations are set. + Thus, when <code class="filename">MACHINE</code> is set to "qemux86" there + exists the corresponding <code class="filename">qemux86.conf</code> machine + configuration file, which can be found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> + in <code class="filename">meta/conf/machine</code>. + </p><p> + The list of machines supported by the Yocto Project as + shipped include the following: + </p><pre class="literallayout"> + MACHINE ?= "qemuarm" + MACHINE ?= "qemumips" + MACHINE ?= "qemuppc" + MACHINE ?= "qemux86" + MACHINE ?= "qemux86-64" + MACHINE ?= "atom-pc" + MACHINE ?= "beagleboard" + MACHINE ?= "mpc8315e-rdb" + MACHINE ?= "routerstationpro" + </pre><p> + The last four are Yocto Project reference hardware boards, which + are provided in the <code class="filename">meta-yocto-bsp</code> layer. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Adding additional Board Support Package (BSP) layers + to your configuration adds new possible settings for + <code class="filename">MACHINE</code>. + </div><p> + </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt><dd><p></p><p> + 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 + packages are essential for the machine to boot. + The impact of this variable affects images based on + <code class="filename">packagegroup-core-boot</code>, + including the <code class="filename">core-image-minimal</code> image. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code> + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </p><p> + As an example, suppose the machine for which you are building requires + <code class="filename">example-init</code> to be run during boot to initialize the hardware. + In this case, you would use the following in the machine's + <code class="filename">.conf</code> configuration file: + </p><pre class="literallayout"> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" + </pre><p> + </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt><dd><p></p><p> + 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 + packages are essential for the machine to boot. + The impact of this variable affects images based on + <code class="filename">packagegroup-core-boot</code>, + including the <code class="filename">core-image-minimal</code> image. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS</a></code> + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will still build if a package in this list is not found. + Typically, this variable is used to handle essential kernel modules, whose + functionality may be selected to be built into the kernel rather than as a module, + in which case a package will not be produced. + </p><p> + Consider an example where you have a custom kernel where a specific touchscreen + driver is required for the machine to be usable. + However, the driver can be built as a module or + into the kernel depending on the kernel configuration. + If the driver is built as a module, you want it to be installed. + But, when the driver is built into the kernel, you still want the + build to succeed. + This variable sets up a "recommends" relationship so that in the latter case, + the build will not fail due to the missing package. + To accomplish this, assuming the package for the module was called + <code class="filename">kernel-module-ab123</code>, you would use the + following in the machine's <code class="filename">.conf</code> configuration + file: + </p><pre class="literallayout"> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" + </pre><p> + </p><p> + Some examples of these machine essentials are flash, screen, keyboard, mouse, + or touchscreen drivers (depending on the machine). + </p></dd><dt><a id="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p> + A list of machine-specific packages to install as part of the + image being built that are not essential for the machine to boot. + However, the build process for more fully-featured images + depends on the packages being present. + </p><p> + This variable affects all images based on + <code class="filename">packagegroup-base</code>, which does not include the + <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> + images. + </p><p> + The variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code> + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </p><p> + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + the WiFi. + The package containing the firmware for the WiFi hardware is always + expected to exist, so it is acceptable for the build process to depend upon + finding the package. + In this case, assuming the package for the firmware was called + <code class="filename">wifidriver-firmware</code>, you would use the following in the + <code class="filename">.conf</code> file for the machine: + </p><pre class="literallayout"> + MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" + </pre><p> + </p></dd><dt><a id="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt><dd><p></p><p> + A list of machine-specific packages to install as part of the + image being built that are not essential for booting the machine. + The image being built has no build dependency on this list of packages. + </p><p> + This variable affects only images based on + <code class="filename">packagegroup-base</code>, which does not include the + <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code> + images. + </p><p> + This variable is similar to the + <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code> + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will build if a file in this list is not found. + </p><p> + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + WiFi. + In this case, the package containing the WiFi kernel module will not be produced + if the WiFi driver is built into the kernel, in which case you still want the + build to succeed instead of failing as a result of the package not being found. + To accomplish this, assuming the package for the module was called + <code class="filename">kernel-module-examplewifi</code>, you would use the + following in the <code class="filename">.conf</code> file for the machine: + </p><pre class="literallayout"> + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" + </pre><p> + </p></dd><dt><a id="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>Specifies the list of hardware features the + <a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a> supports. + For example, including the "bluetooth" feature causes the + <code class="filename">bluez</code> bluetooth daemon to be built and + added to the image. + It also causes the <code class="filename">connman</code> recipe + to look at <code class="filename">MACHINE_FEATURES</code> and when it + finds "bluetooth" there it enables the bluetooth + support in ConnMan. + </p><p> + For a list of features supported by the Yocto Project as shipped, + see the "<a class="link" href="#ref-features-machine" title="9.2. Machine">Machine</a>" section. + </p></dd><dt><a id="var-MACHINE_FEATURES_BACKFILL"></a>MACHINE_FEATURES_BACKFILL</dt><dd><p>Features to be added to + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code> + if not also present in + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED">MACHINE_FEATURES_BACKFILL_CONSIDERED</a></code>. + </p><p> + This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file. + 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 <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for + more information. + </p></dd><dt><a id="var-MACHINE_FEATURES_BACKFILL_CONSIDERED"></a>MACHINE_FEATURES_BACKFILL_CONSIDERED</dt><dd><p>Features from + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL">MACHINE_FEATURES_BACKFILL</a></code> + that should not be backfilled (i.e. added to + <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>) + during the build. + See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for + more information. + </p></dd><dt><a id="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>The email address of the distribution maintainer.</p></dd><dt><a id="var-MLPREFIX"></a>MLPREFIX</dt><dd><p> + Specifies a prefix has been added to + <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> to create a special version + of a recipe or package, such as 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 + <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable). + <code class="filename">MLPREFIX</code> gets set when a prefix has been + added to <code class="filename">PN</code>. + </p></dd><dt><a id="var-MULTIMACH_TARGET_SYS"></a>MULTIMACH_TARGET_SYS</dt><dd><p> + Separates files for different machines such that you can build + for multiple target machines using the same output directories. + See the <a class="link" href="#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> variable + for an example. + </p></dd></dl></div><div class="glossdiv" title="O"><h3 class="title">O</h3><dl><dt><a id="var-OE_TERMINAL"></a>OE_TERMINAL</dt><dd><p> + Controls how the OpenEmbedded build system spawns + interactive terminals on the host development system + (e.g. using the BitBake command with the + <code class="filename">-c devshell</code> command-line option). + For more information, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section + in the Yocto Project Development Manual. + </p><p> + You can use the following values for the + <code class="filename">OE_TERMINAL</code> variable: + </p><pre class="literallayout"> + auto + gnome + xfce + rxvt + screen + konsole + none + </pre><p> + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Konsole support only works for KDE 3.x. + Also, "auto" is the default behavior for + <code class="filename">OE_TERMINAL</code></div><p> + </p></dd></dl></div><div class="glossdiv" title="P"><h3 class="title">P</h3><dl><dt><a id="var-P"></a>P</dt><dd><p>The recipe name and version. + <code class="filename">P</code> is comprised of the following: + </p><pre class="literallayout"> + ${PN}-${PV} + </pre></dd><dt><a id="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>The architecture of the resulting package or packages.</p></dd><dt><a id="var-PACKAGE_BEFORE_PN"></a>PACKAGE_BEFORE_PN</dt><dd><p>Enables easily adding packages to + <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + before <code class="filename">${PN}</code> so that the packages can pick + up files that would normally be included in the default package.</p></dd><dt><a id="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>This variable, which is set in the <code class="filename">local.conf</code> configuration + file found in the <code class="filename">conf</code> folder of the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>, + specifies the package manager to use when packaging data. + You can provide one or more arguments for the variable with the first + argument being the package manager used to create images: + </p><pre class="literallayout"> + PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" + </pre><p> + For information on build performance effects as a result of the + package manager use, see + <a class="link" href="#ref-classes-package" title="7.13. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a> + in this manual. + </p></dd><dt><a id="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>Specifies the list of architectures compatible with the device CPU. + This variable is useful when you build for several different devices that use + miscellaneous processors such as XScale and ARM926-EJS).</p></dd><dt><a id="var-PACKAGECONFIG"></a>PACKAGECONFIG</dt><dd><p> + This variable provides a means of enabling or disabling + features of a recipe on a per-recipe basis. + The <code class="filename">PACKAGECONFIG</code> + variable itself specifies a space-separated list of the + features to enable. + The features themselves are specified as flags on the + <code class="filename">PACKAGECONFIG</code> variable. + You can provide up to four arguments, which are separated by + commas, to determine the behavior of each feature + when it is enabled or disabled. + You can omit any argument you like but must retain the + separating commas. + The arguments specify the following: + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Extra arguments + that should be added to the configure script argument list + (<a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF"><code class="filename">EXTRA_OECONF</code></a>) + if the feature is enabled.</p></li><li class="listitem"><p>Extra arguments + that should be added to <code class="filename">EXTRA_OECONF</code> + if the feature is disabled. + </p></li><li class="listitem"><p>Additional build dependencies + (<a class="link" href="#var-DEPENDS" title="DEPENDS"><code class="filename">DEPENDS</code></a>) + that should be added if the feature is enabled. + </p></li><li class="listitem"><p>Additional runtime dependencies + (<a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a>) + that should be added if the feature is enabled. + </p></li></ol></div><p> + </p><p> + Consider the following example taken from the + <code class="filename">librsvg</code> recipe. + In this example the feature is <code class="filename">croco</code>, which + has three arguments that determine the feature's behavior. + </p><pre class="literallayout"> + PACKAGECONFIG ??= "croco" + PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" + </pre><p> + The <code class="filename">--with-croco</code> and + <code class="filename">libcroco</code> arguments apply only if + the feature is enabled. + In this case, <code class="filename">--with-croco</code> is + added to the configure script argument list and + <code class="filename">libcroco</code> is added to + <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code>. + On the other hand, if the feature is disabled say through + a <code class="filename">.bbappend</code> file in another layer, then + the second argument <code class="filename">--without-croco</code> is + added to the configure script rather than + <code class="filename">--with-croco</code>. + </p></dd><dt><a id="var-PACKAGES"></a>PACKAGES</dt><dd><p>The list of packages to be created from the recipe. + The default value is the following: + </p><pre class="literallayout"> + ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + </pre></dd><dt><a id="var-PACKAGES_DYNAMIC"></a>PACKAGES_DYNAMIC</dt><dd><p> + A promise that your recipe satisfies runtime dependencies + for optional modules that are found in other recipes. + <code class="filename">PACKAGES_DYNAMIC</code> + does not actually satisfy the dependencies, it only states that + they should be satisfied. + For example, if a hard, runtime dependency + (<code class="filename">RDEPENDS</code>) of another package is satisfied + at build time through the <code class="filename">PACKAGES_DYNAMIC</code> + variable, but a package with the module name is never actually + produced, then the other package will be broken. + Thus, if you attempt to include that package in an image, + you will get a dependency failure from the packaging system + during <code class="filename">do_rootfs</code>. + Typically, if there is a chance that such a situation can + occur and the package that is not created is valid + without the dependency being satisfied, then you should use + <code class="filename">RRECOMMENDS</code> (a soft runtime dependency) + instead of <code class="filename">RDEPENDS</code>. + </p><p> + For an example of how to use the <code class="filename">PACKAGES_DYNAMIC</code> + variable when you are splitting packages, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#handling-optional-module-packaging" target="_top">Handling Optional Module Packaging</a>" section + in the Yocto Project Development Manual. + </p></dd><dt><a id="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt><dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the + compile tasks. + This variable is usually in the form <code class="filename">-j 4</code>, where the number + represents the maximum number of parallel threads make can run. + If you development host supports multiple cores a good rule of thumb is to set + this variable to twice the number of cores on the host.</p></dd><dt><a id="var-PF"></a>PF</dt><dd><p>Specifies the recipe or package name and includes all version and revision + numbers (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and + <code class="filename">bash-4.2-r1/</code>). + This variable is comprised of the following: + </p><pre class="literallayout"> + ${PN}-${EXTENDPE}${PV}-${PR} + </pre></dd><dt><a id="var-PN"></a>PN</dt><dd><p>This variable can have two separate functions depending on the context: a recipe + name or a resulting package name.</p><p><code class="filename">PN</code> refers to a recipe name in the context of a file used + by the OpenEmbedded build system as input to create a package. + The name is normally extracted from the recipe file name. + For example, if the recipe is named + <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PN</code> + will be "expat".</p><p> + The variable refers to a package name in the context of a file created or produced by the + OpenEmbedded build system.</p><p>If applicable, the <code class="filename">PN</code> variable also contains any special + suffix or prefix. + For example, using <code class="filename">bash</code> to build packages for the native + machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>. + Using <code class="filename">bash</code> to build packages for the target and for Multilib, + <code class="filename">PN</code> would be <code class="filename">bash</code> and + <code class="filename">lib64-bash</code>, respectively. + </p></dd><dt><a id="var-PR"></a>PR</dt><dd><p>The revision of the recipe. + The default value for this variable is "r0". + </p></dd><dt><a id="var-PRINC"></a>PRINC</dt><dd><p>Causes the <code class="filename">PR</code> variable of + <code class="filename">.bbappend</code> files to dynamically increment. + This increment minimizes the impact of layer ordering.</p><p>In order to ensure multiple <code class="filename">.bbappend</code> files can co-exist, + <code class="filename">PRINC</code> should be self referencing. + This variable defaults to 0.</p><p>Following is an example that increments <code class="filename">PR</code> by two: + </p><pre class="literallayout"> + PRINC := "${@int(PRINC) + 2}" + </pre><p> + It is adviseable not to use strings such as ".= '.1'" with the variable because + this usage is very sensitive to layer ordering. + Explicit assignments should be avoided as they cannot adequately represent multiple + <code class="filename">.bbappend</code> files.</p></dd><dt><a id="var-PV"></a>PV</dt><dd><p>The version of the recipe. + The version is normally extracted from the recipe filename. + For example, if the recipe is named + <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PV</code> + will be "2.0.1". + <code class="filename">PV</code> is generally not overridden within + a recipe unless it is building an unstable (i.e. development) version from a source code repository + (e.g. Git or Subversion). + </p></dd><dt><a id="var-PE"></a>PE</dt><dd><p> + the epoch of the recipe. + The default value is "0". + The field is used to make upgrades possible when the versioning scheme changes in + some backwards incompatible way. + </p></dd><dt><a id="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p> + If multiple recipes provide an item, this variable + determines which recipe should be given preference. + The variable must always be suffixed with the name of the + provided item, and should be set to the + <code class="filename">PN</code> of the recipe + to which you want to give precedence. + Here is an example: + </p><pre class="literallayout"> + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + </pre><p> + </p></dd><dt><a id="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p> + If there are multiple versions of recipes available, this + variable determines which recipe should be given preference. + The variable must always be suffixed with the <code class="filename">PN</code> + for which to select, and should be set to the + <code class="filename">PV</code> to which you want to give precedence. + You can use the "<code class="filename">%</code>" character as a wildcard + to match any number of characters, which can be useful when + specifying versions that contain long revision number that could + potentially change. + Here are two examples: + </p><pre class="literallayout"> + PREFERRED_VERSION_python = "2.6.6" + PREFERRED_VERSION_linux-yocto = "3.0+git%" + </pre><p> + </p></dd></dl></div><div class="glossdiv" title="R"><h3 class="title">R</h3><dl><dt><a id="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>The list of packages that conflict with a package. + Note that the package will not be installed if the conflicting packages are not + first removed.</p><p> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + </p><pre class="literallayout"> + RCONFLICTS_${PN} = "another-conflicting-package-name" + </pre><p> + </p></dd><dt><a id="var-RDEPENDS"></a>RDEPENDS</dt><dd><p> + Lists a package's run-time dependencies (i.e. other packages) + that must be installed for the package to be built. + In other words, in order for the package to be built and + run correctly, it depends on the listed packages. + If a package in this list cannot be found, it is probable + that a dependency error would occur before the build. + </p><p> + The names of the variables you list with + <code class="filename">RDEPENDS</code> must be the names of other + packages as listed in the + <a class="link" href="#var-PACKAGES" title="PACKAGES"><code class="filename">PACKAGES</code></a> + variable. + You should not list recipe names (<code class="filename">PN</code>). + </p><p> + Because the <code class="filename">RDEPENDS</code> variable applies + to packages being built, you should + always attach a package name to the variable to specify the + particular run-time package that has the dependency. + For example, suppose you are building a development package + that depends on the <code class="filename">perl</code> package. + In this case, you would use the following + <code class="filename">RDEPENDS</code> statement: + </p><pre class="literallayout"> + RDEPENDS_${PN}-dev += "perl" + </pre><p> + In the example, the package name + (<code class="filename">${PN}-dev</code>) must appear as it would + in the + <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + namespace before any renaming of the output package by + classes like <code class="filename">debian.bbclass</code>. + </p><p> + In many cases you do not need to explicitly add dependencies + to <code class="filename">RDEPENDS</code> since some automatic + handling occurs: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If + a run-time package contains a shared library + (<code class="filename">.so</code>), the build + processes the library in order to determine other + libraries to which it is dynamically linked. + The build process adds these libraries to + <code class="filename">RDEPENDS</code> when creating the run-time + package.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If + the package ships a <code class="filename">pkg-config</code> + information file, the build process uses this file + to add items to the <code class="filename">RDEPENDS</code> + variable to create the run-time packages. + </p></li></ul></div><p> + </p></dd><dt><a id="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p> + A list of packages that extend the usability of a package being + built. + The package being built does not depend on this list of packages in + order to successfully build, but needs them for the extended usability. + To specify runtime dependencies for packages, see the + <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable. + </p><p> + The OpenEmbedded build process automatically installs the list of packages + as part of the built package. + However, you can remove them later if you want. + If, during the build, a package from the list cannot be found, the build + process continues without an error. + </p><p> + Because the <code class="filename">RRECOMMENDS</code> variable applies to packages + being built, you should + always attach an override to the variable to specify the particular package + whose usability is being extended. + For example, suppose you are building a development package that is extended + to support wireless functionality. + In this case, you would use the following: + </p><pre class="literallayout"> + RRECOMMENDS_${PN}-dev += "<wireless_package_name>" + </pre><p> + In the example, the package name (<code class="filename">${PN}-dev</code>) must + appear as it would in the + <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any + renaming of the output package by classes like <code class="filename">debian.bbclass</code>. + </p></dd><dt><a id="var-RREPLACES"></a>RREPLACES</dt><dd><p>The list of packages that are replaced with this package.</p></dd></dl></div><div class="glossdiv" title="S"><h3 class="title">S</h3><dl><dt><a id="var-S"></a>S</dt><dd><p> + The location in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> + where unpacked package source code resides. + This location is within the working directory + (<code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which + is not static. + The unpacked source location depends on the package name + (<code class="filename"><a class="link" href="#var-PN" title="PN">PN</a></code>) and + package version (<code class="filename"><a class="link" href="#var-PV" title="PV">PV</a></code>) as + follows: + </p><pre class="literallayout"> + ${WORKDIR}/${PN}/${PV} + </pre><p> + As an example, assume a + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> top-level + folder named <code class="filename">poky</code> + and a default <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">db</code> package is the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 + </pre><p> + </p></dd><dt><a id="var-SDKIMAGE_FEATURES"></a>SDKIMAGE_FEATURES</dt><dd><p>Equivalent to + <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>. + However, this variable applies to the SDK generated from an image using + <code class="filename">bitbake -c populate_sdk imagename</code>). + </p></dd><dt><a id="var-SECTION"></a>SECTION</dt><dd><p>The section in which packages should be categorized. + Package management utilities can make use of this variable.</p></dd><dt><a id="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p> + The variable takes the value of + <code class="filename"><a class="link" href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code> + unless <code class="filename"><a class="link" href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1". + In this case the value of + <code class="filename"><a class="link" href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used. + </p></dd><dt><a id="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>The speed and device for the serial port used to attach the serial console. + This variable is given to the kernel as the "console" + parameter and after booting occurs <code class="filename">getty</code> is started on that port + so remote login is possible.</p></dd><dt><a id="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt><dd><p> + Specifies the endian byte order of the target system. + The value should be either "le" for little-endian or "be" for big-endian. + </p></dd><dt><a id="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p> + Specifies the number of bits for the target system CPU. + The value should be either "32" or "64". + </p></dd><dt><a id="var-SPECIAL_PKGSUFFIX"></a>SPECIAL_PKGSUFFIX</dt><dd><p> + A list of prefixes for <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> used by the + OpenEmbedded build system to create variants of recipes or packages. + The list specifies the prefixes to strip off during certain circumstances + such as the generation of the <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable. + </p></dd><dt><a id="var-SRC_URI"></a>SRC_URI</dt><dd><p>The list of source files - local or remote. + This variable tells the OpenEmbedded build system which bits to pull + in for the build and how to pull them in. + For example, if the recipe only needs to fetch a tarball from the + internet, the recipe uses a single <code class="filename">SRC_URI</code> entry. + On the other hand, if the recipe needs to fetch a tarball, apply + two patches, and include a custom file, the recipe would include four + instances of the variable.</p><p>The following list explains the available URI protocols: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">file://</code> -</em></span> Fetches files, which is usually + a file shipped with the metadata, from the local machine. + The path is relative to the + <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> + variable. + Thus, the build system searches, in order, from the following directories, + which are assumed to be a subdirectories of the directory in which the + recipe file resides: + </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em><code class="filename">${PN}</code> -</em></span> The recipe name + with any special suffix or prefix, if applicable. + For example, using <code class="filename">bash</code> to build for the native + machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>. + Using <code class="filename">bash</code> to build for the target and for Multilib, + <code class="filename">PN</code> would be <code class="filename">bash</code> and + <code class="filename">lib64-bash</code>, respectively. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${PF}</code> - </em></span> + <code class="filename">${PN}-${EXTENDPE}${PV}-${PR}</code>. + The recipe name including all version and revision numbers + (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and + <code class="filename">bash-4.2-r1/</code>).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${P}</code> -</em></span> + <code class="filename">${PN}-${PV}</code>. + The recipe name and version (i.e. <code class="filename">bash-4.2</code>). + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${BPN}</code> -</em></span> The + base recipe name without any special suffix or version numbers. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${BP}</code> -</em></span> + <code class="filename">${BPN}-${PV}</code>. + The base recipe name and version but without any special + package name suffix.</p></li><li class="listitem"><p><span class="emphasis"><em>Files -</em></span> Files beneath the directory in which the recipe + resides.</p></li><li class="listitem"><p><span class="emphasis"><em>Directory -</em></span> The directory itself in which the recipe + resides.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">bzr://</code> -</em></span> Fetches files from a + Bazaar revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git://</code> -</em></span> Fetches files from a + Git revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">osc://</code> -</em></span> Fetches files from + an OSC (OpenSuse Build service) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">repo://</code> -</em></span> Fetches files from + a repo (Git) repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">svk://</code> -</em></span> Fetches files from + an SVK revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">http://</code> -</em></span> Fetches files from + the Internet using <code class="filename">http</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">https://</code> -</em></span> Fetches files + from the Internet using <code class="filename">https</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">ftp://</code> -</em></span> Fetches files + from the Internet using <code class="filename">ftp</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">cvs://</code> -</em></span> Fetches files from + a CVS revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">hg://</code> -</em></span> Fetches files from + a Mercurial (<code class="filename">hg</code>) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">p4://</code> -</em></span> Fetches files from + a Perforce (<code class="filename">p4</code>) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">ssh://</code> -</em></span> Fetches files from + a secure shell.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">svn://</code> -</em></span> Fetches files from + a Subversion (<code class="filename">svn</code>) revision control repository.</p></li></ul></div><p> + </p><p>Standard and recipe-specific options for <code class="filename">SRC_URI</code> exist. + Here are standard options: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">apply</code> -</em></span> Whether to apply + the patch or not. + The default action is to apply the patch.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">striplevel</code> -</em></span> Which + striplevel to use when applying the patch. + The default level is 1.</p></li></ul></div><p> + </p><p>Here are options specific to recipes building code from a revision control system: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">mindate</code> -</em></span> Only applies + the patch if <a class="link" href="#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a> + is equal to or greater than <code class="filename">mindate</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">maxdate</code> -</em></span> Only applies + the patch if <a class="link" href="#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a> + is not later than <code class="filename">mindate</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">minrev</code> -</em></span> Only applies + the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is equal to or greater than <code class="filename">minrev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">maxrev</code> -</em></span> Only applies + the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is not later than <code class="filename">maxrev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rev</code> -</em></span> Only applies the + patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is equal to <code class="filename">rev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">notrev</code> -</em></span> Only applies + the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a> + is not equal to <code class="filename">rev</code>.</p></li></ul></div><p> + </p><p>Here are some additional options worth mentioning: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">unpack</code> -</em></span> Controls + whether or not to unpack the file if it is an archive. + The default action is to upack the file.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">subdir</code> -</em></span> Places the file + (or extracts its contents) into the specified + subdirectory of <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>. + This option is useful for unusual tarballs or other archives that + don't have their files already in a subdirectory within the archive. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">name</code> -</em></span> Specifies a + name to be used for association with <code class="filename">SRC_URI</code> checksums + when you have more than one file specified in <code class="filename">SRC_URI</code>. + </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">downloadfilename</code> -</em></span> Specifies + the filename used when storing the downloaded file.</p></li></ul></div><p> + </p></dd><dt><a id="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p></p><p> + By default, the OpenEmbedded build system automatically detects whether + <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> + contains files that are machine-specific. + If so, the build system automatically changes + <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>. + Setting this variable to "0" disables this behavior. + </p></dd><dt><a id="var-SRCDATE"></a>SRCDATE</dt><dd><p> + The date of the source code used to build the package. + This variable applies only if the source was fetched from a Source Code Manager (SCM). + </p></dd><dt><a id="var-SRCREV"></a>SRCREV</dt><dd><p> + The revision of the source code used to build the package. + This variable applies to Subversion, Git, Mercurial and Bazaar + only. + Note that if you wish to build a fixed revision and you wish + to avoid performing a query on the remote repository every time + BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a + full revision identifier and not just a tag. + </p></dd><dt><a id="var-SSTATE_DIR"></a>SSTATE_DIR</dt><dd><p>The directory for the shared state.</p></dd><dt><a id="var-SSTATE_MIRRORS"></a>SSTATE_MIRRORS</dt><dd><p> + Configures the OpenEmbedded build system to search other + mirror locations for prebuilt cache data objects before + building out the data. + This variable works like fetcher + <code class="filename">MIRRORS</code>/<code class="filename">PREMIRRORS</code> + and points to the cache locations to check for the shared + objects. + </p><p> + You can specify a filesystem directory or a remote URL such + as HTTP or FTP. + The locations you specify need to contain the shared state + cache (sstate-cache) results from previous builds. + The sstate-cache you point to can also be from builds on + other machines. + </p><p> + If a mirror uses the same structure as + <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a>, + you need to add + "PATH" at the end as shown in the examples below. + The build system substitues the correct path within the + directory structure. + </p><pre class="literallayout"> + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + </pre><p> + </p></dd><dt><a id="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p> + The directory with kernel headers that are required to build out-of-tree + modules. + </p></dd><dt><a id="var-STAMP"></a>STAMP</dt><dd><p> + Specifies the base path used to create recipe stamp files. + The path to an actual stamp file is constructed by evaluating this + string and then appending additional information. + Currently, the default assignment for <code class="filename">STAMP</code> + as set in the <code class="filename">meta/conf/bitbake.conf</code> file + is: + </p><pre class="literallayout"> + STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" + </pre><p> + See <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, + <a class="link" href="#var-MULTIMACH_TARGET_SYS" title="MULTIMACH_TARGET_SYS"><code class="filename">MULTIMACH_TARGET_SYS</code></a>, + <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a>, + <a class="link" href="#var-EXTENDPE" title="EXTENDPE"><code class="filename">EXTENDPE</code></a>, + <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>, and + <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> for related variable + information. + </p></dd><dt><a id="var-SUMMARY"></a>SUMMARY</dt><dd><p>The short (72 characters or less) summary of the binary package for packaging + systems such as <code class="filename">opkg</code>, <code class="filename">rpm</code> or + <code class="filename">dpkg</code>. + By default, <code class="filename">SUMMARY</code> is used to define + the <a class="link" href="#var-DESCRIPTION" title="DESCRIPTION"><code class="filename">DESCRIPTION</code></a> + variable if <code class="filename">DESCRIPTION</code> is not set + in the recipe. + </p></dd></dl></div><div class="glossdiv" title="T"><h3 class="title">T</h3><dl><dt><a id="var-T"></a>T</dt><dd><p>This variable points to a directory were Bitbake places temporary + files when building a particular package. + It is typically set as follows: + </p><pre class="literallayout"> + T = ${WORKDIR}/temp + </pre><p> + The <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a> + is the directory into which Bitbake unpacks and builds the package. + The default <code class="filename">bitbake.conf</code> file sets this variable.</p><p>The <code class="filename">T</code> variable is not to be confused with + the <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> variable, + which points to the root of the directory tree where Bitbake + places the output of an entire build. + </p></dd><dt><a id="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device being built. + While a number of values are possible, the OpenEmbedded build system primarily supports + <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd><dt><a id="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p> + Flags passed to the C compiler for the target system. + This variable evaluates to the same as + <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>. + </p></dd><dt><a id="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Specifies the method for handling FPU code. + For FPU-less targets, which include most ARM CPUs, the variable must be + set to "soft". + If not, the kernel emulation gets used, which results in a performance penalty.</p></dd><dt><a id="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Specifies the target's operating system. + The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and + to "linux-uclibc" for <code class="filename">uclibc</code>. + For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-uclibc-gnueabi" values possible.</p></dd><dt><a id="var-TCLIBC"></a>TCLIBC</dt><dd><p> + Specifies which variant of the GNU standard C library (<code class="filename">libc</code>) + to use during the build process. + This variable replaces <code class="filename">POKYLIBC</code>, which is no longer + supported. + </p><p> + You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. + </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + This release of the Yocto Project does not support the + <code class="filename">glibc</code> implementation of <code class="filename">libc</code>. + </div><p> + </p></dd><dt><a id="var-TCMODE"></a>TCMODE</dt><dd><p> + The toolchain selector. + This variable replaces <code class="filename">POKYMODE</code>, which is no longer + supported. + </p><p> + The <code class="filename">TCMODE</code> variable selects the external toolchain + built using the OpenEmbedded build system or a few supported combinations of + the upstream GCC or CodeSourcery Labs toolchain. + The variable identifies the <code class="filename">tcmode-*</code> files used in + the <code class="filename">meta/conf/distro/include</code> directory, which is found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </p><p> + By default, <code class="filename">TCMODE</code> is set to "default", which + chooses the <code class="filename">tcmode-default.inc</code> file. + The variable is similar to + <a class="link" href="#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls + the variant of the GNU standard C library (<code class="filename">libc</code>) + used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>. + </p></dd><dt><a id="var-TMPDIR"></a>TMPDIR</dt><dd><p> + This variable is the temporary directory the OpenEmbedded build system + uses when it does its work building images. + By default, the <code class="filename">TMPDIR</code> variable is named + <code class="filename">tmp</code> within the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + </p><p> + If you want to establish this directory in a location other than the + default, you can uncomment the following statement in the + <code class="filename">conf/local.conf</code> file in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>: + </p><pre class="literallayout"> + #TMPDIR = "${TOPDIR}/tmp" + </pre><p> + </p></dd><dt><a id="var-TOPDIR"></a>TOPDIR</dt><dd><p> + This variable is the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>. + BitBake automatically sets this variable. + The OpenEmbedded build system uses the Build Directory when building images. + </p></dd></dl></div><div class="glossdiv" title="W"><h3 class="title">W</h3><dl><dt><a id="var-WORKDIR"></a>WORKDIR</dt><dd><p> + The pathname of the working directory in which the OpenEmbedded build system + builds a recipe. + This directory is located within the + <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes + as different packages are built. + </p><p> + The actual <code class="filename">WORKDIR</code> directory depends on several things: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The temporary directory - <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a></li><li class="listitem">The package architecture - <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH"><code class="filename">PACKAGE_ARCH</code></a></li><li class="listitem">The target machine - <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a></li><li class="listitem">The target operating system - <a class="link" href="#var-TARGET_OS" title="TARGET_OS"><code class="filename">TARGET_OS</code></a></li><li class="listitem">The recipe name - <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a></li><li class="listitem">The recipe version - <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a></li><li class="listitem">The recipe revision - <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a></li></ul></div><p> + </p><p> + For packages that are not dependent on a particular machine, + <code class="filename">WORKDIR</code> is defined as follows: + </p><pre class="literallayout"> + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR} + </pre><p> + As an example, assume a + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> top-level + folder name <code class="filename">poky</code> and a default + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">v86d</code> package is the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0 + </pre><p> + </p><p> + For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code> + is defined slightly different: + </p><pre class="literallayout"> + ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR} + </pre><p> + As an example, again assume a Source Directory top-level folder + named <code class="filename">poky</code> and a default Build Directory + at <code class="filename">poky/build</code>. + In this case, the working directory the build system uses to build + the <code class="filename">acl</code> recipe, which is being built for a + MIPS-based device, is the following: + </p><pre class="literallayout"> + ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2 + </pre><p> + </p></dd></dl></div></div></div> + + <div class="chapter" title="Chapter 11. Variable Context"><div class="titlepage"><div><div><h2 class="title"><a id="ref-varlocality"></a>Chapter 11. Variable Context</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-varlocality-configuration">11.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">11.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">11.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">11.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">11.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">11.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">11.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">11.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">11.2.4. Extra Build Information</a></span></dt></dl></dd></dl></div><p> + While most variables can be used in almost any context such as + <code class="filename">.conf</code>, <code class="filename">.bbclass</code>, + <code class="filename">.inc</code>, and <code class="filename">.bb</code> files, + some variables are often associated with a particular locality or context. + This chapter describes some common associations. + </p><div class="section" title="11.1. Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-configuration"></a>11.1. Configuration</h2></div></div></div><p> + The following subsections provide lists of variables whose context is + configuration: distribution, machine, and local. + </p><div class="section" title="11.1.1. Distribution (Distro)"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-distro"></a>11.1.1. Distribution (Distro)</h3></div></div></div><p> + This section lists variables whose context is the distribution, or distro. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCLIBC" title="TCLIBC">TCLIBC</a></code> + </p></li></ul></div><p> + </p></div><div class="section" title="11.1.2. Machine"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-machine"></a>11.1.2. Machine</h3></div></div></div><p> + This section lists variables whose context is the machine. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li></ul></div><p> + </p></div><div class="section" title="11.1.3. Local"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-local"></a>11.1.3. Local</h3></div></div></div><p> + This section lists variables whose context is the local configuration through the + <code class="filename">local.conf</code> file. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES + </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION"> + ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li></ul></div><p> + </p></div></div><div class="section" title="11.2. Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-recipes"></a>11.2. Recipes</h2></div></div></div><p> + The following subsections provide lists of variables whose context is + recipes: required, dependencies, path, and extra build information. + </p><div class="section" title="11.2.1. Required"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-required"></a>11.2.1. Required</h3></div></div></div><p> + This section lists variables that are required for recipes. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> - used + in recipes that fetch local or remote files. + </p></li></ul></div><p> + </p></div><div class="section" title="11.2.2. Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-dependencies"></a>11.2.2. Dependencies</h3></div></div></div><p> + This section lists variables that define recipe dependencies. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RREPLACES" title="RREPLACES">RREPLACES</a> + </code></p></li></ul></div><p> + </p></div><div class="section" title="11.2.3. Paths"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-paths"></a>11.2.3. Paths</h3></div></div></div><p> + This section lists variables that define recipe paths. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-S" title="S">S</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a> + </code></p></li></ul></div><p> + </p></div><div class="section" title="11.2.4. Extra Build Information"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-build"></a>11.2.4. Extra Build Information</h3></div></div></div><p> + This section lists variables that define extra build information for recipes. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a> + </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> + </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE + </a></code></p></li></ul></div><p> + </p></div></div></div> + + <div class="chapter" title="Chapter 12. FAQ"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Chapter 12. FAQ</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><a id="idm975296"></a><dl><dt>12.1. <a href="#idm974832"> + How does Poky differ from OpenEmbedded? + </a></dt><dt>12.2. <a href="#idp1801248"> + I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. + Can I still use the Yocto Project? + </a></dt><dt>12.3. <a href="#idm1781424"> + How can you claim Poky / OpenEmbedded-Core is stable? + </a></dt><dt>12.4. <a href="#idm1777456"> + How do I get support for my board added to the Yocto Project? + </a></dt><dt>12.5. <a href="#idm345792"> + Are there any products built using the OpenEmbedded build system? + </a></dt><dt>12.6. <a href="#idm343136"> + What does the OpenEmbedded build system produce as output? + </a></dt><dt>12.7. <a href="#idm341840"> + How do I add my package to the Yocto Project? + </a></dt><dt>12.8. <a href="#idp1600368"> + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + </a></dt><dt>12.9. <a href="#idp1603824"> + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + </a></dt><dt>12.10. <a href="#idp1605872"> + I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'. + What is wrong? + </a></dt><dt>12.11. <a href="#idp1662416"> + How do I make the Yocto Project work in RHEL/CentOS? + </a></dt><dt>12.12. <a href="#idp562304"> + I see lots of 404 responses for files on + http://www.yoctoproject.org/sources/*. Is something wrong? + </a></dt><dt>12.13. <a href="#idp179952"> + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + </a></dt><dt>12.14. <a href="#idp184672"> + I'm behind a firewall and need to use a proxy server. How do I do that? + </a></dt><dt>12.15. <a href="#idp1585952"> + What’s the difference between foo and foo-native? + </a></dt><dt>12.16. <a href="#idp3269536"> + I'm seeing random build failures. Help?! + </a></dt><dt>12.17. <a href="#idp3271104"> + What do we need to ship for license compliance? + </a></dt><dt>12.18. <a href="#idp3272560"> + How do I disable the cursor on my touchscreen device? + </a></dt><dt>12.19. <a href="#idp3244640"> + How do I make sure connected network interfaces are brought up by default? + </a></dt><dt>12.20. <a href="#idp3248256"> + How do I create images with more free space? + </a></dt><dt>12.21. <a href="#idp348464"> + Why don't you support directories with spaces in the pathnames? + </a></dt><dt>12.22. <a href="#idp350512"> + How do I use an external toolchain? + </a></dt><dt>12.23. <a href="#idm184288"> + How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server? + </a></dt><dt>12.24. <a href="#idm1036560"> + Can I get rid of build output so I can start over? + </a></dt></dl><table border="0" width="100%" summary="Q and A Set"><col align="left" width="1%" /><col /><tbody><tr class="question" title="12.1."><td align="left" valign="top"><a id="idm974832"></a><a id="idm974704"></a><p><strong>12.1.</strong></p></td><td align="left" valign="top"><p> + How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The term "Poky" refers to the specific reference build system that + the Yocto Project provides. + Poky is based on <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#oe-core" target="_top">OE-Core</a> + and BitBake. + Thus, the generic term used here for the build system is + the "OpenEmbedded build system." + Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with + changes always being merged to OE-Core or BitBake first before being pulled back + into Poky. + This practice benefits both projects immediately. + For a fuller description of the term "Poky", see the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">poky</a> term in the Yocto Project + Development Manual. + </p></td></tr><tr class="question" title="12.2."><td align="left" valign="top"><a id="idp1801248"></a><a id="idp1801376"></a><p><strong>12.2.</strong></p></td><td align="left" valign="top"><p> + I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7. + Can I still use the Yocto Project? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You can use a stand-alone tarball to provide Python 2.6. + You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2" target="_top">32-bit tarball</a></p></li><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2" target="_top">64-bit tarball</a></p></li></ul></div><p> + </p><p> + These tarballs are self-contained with all required libraries and should work + on most Linux systems. + To use the tarballs extract them into the root + directory and run the appropriate command: + </p><pre class="literallayout"> + $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH + $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH + </pre><p> + </p><p> + Once you run the command, BitBake uses Python 2.6. + </p></td></tr><tr class="question" title="12.3."><td align="left" valign="top"><a id="idm1781424"></a><a id="idm1781296"></a><p><strong>12.3.</strong></p></td><td align="left" valign="top"><p> + How can you claim Poky / OpenEmbedded-Core is stable? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + There are three areas that help with stability; + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Yocto Project team keeps + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#oe-core" target="_top">OE-Core</a> small + and focused, containing around 830 recipes as opposed to the thousands + available in other OpenEmbedded community layers. + Keeping it small makes it easy to test and maintain.</p></li><li class="listitem"><p>The Yocto Project team runs manual and automated tests + using a small, fixed set of reference hardware as well as emulated + targets.</p></li><li class="listitem"><p>The Yocto Project uses an an autobuilder, + which provides continuous build and integration tests.</p></li></ul></div><p> + </p></td></tr><tr class="question" title="12.4."><td align="left" valign="top"><a id="idm1777456"></a><a id="idm1777328"></a><p><strong>12.4.</strong></p></td><td align="left" valign="top"><p> + How do I get support for my board added to the Yocto Project? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Support for an additional board is added by creating a BSP layer for it. + For more information on how to create a BSP layer, see the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>. + </p><p> + Usually, if the board is not completely exotic, adding support in + the Yocto Project is fairly straightforward. + </p></td></tr><tr class="question" title="12.5."><td align="left" valign="top"><a id="idm345792"></a><a id="idm345664"></a><p><strong>12.5.</strong></p></td><td align="left" valign="top"><p> + Are there any products built using the OpenEmbedded build system? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The software running on the <a class="ulink" href="http://vernier.com/labquest/" target="_top">Vernier LabQuest</a> + is built using the OpenEmbedded build system. + See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_top">Vernier LabQuest</a> + website for more information. + There are a number of pre-production devices using the OpenEmbedded build system + and the Yocto Project team + announces them as soon as they are released. + </p></td></tr><tr class="question" title="12.6."><td align="left" valign="top"><a id="idm343136"></a><a id="idm343008"></a><p><strong>12.6.</strong></p></td><td align="left" valign="top"><p> + What does the OpenEmbedded build system produce as output? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Because the same set of recipes can be used to create output of various formats, the + output of an OpenEmbedded build depends on how it was started. + Usually, the output is a flashable image ready for the target device. + </p></td></tr><tr class="question" title="12.7."><td align="left" valign="top"><a id="idm341840"></a><a id="idm341712"></a><p><strong>12.7.</strong></p></td><td align="left" valign="top"><p> + How do I add my package to the Yocto Project? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + To add a package, you need to create a BitBake recipe. + For information on how to add a package, see the section + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-addpkg" target="_top">Adding a Package</a>" + in the Yocto Project Development Manual. + </p></td></tr><tr class="question" title="12.8."><td align="left" valign="top"><a id="idp1600368"></a><a id="idp1600496"></a><p><strong>12.8.</strong></p></td><td align="left" valign="top"><p> + Do I have to reflash my entire board with a new Yocto Project image when recompiling + a package? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The OpenEmbedded build system can build packages in various formats such as + <code class="filename">ipk</code> for <code class="filename">opkg</code>, + Debian package (<code class="filename">.deb</code>), or RPM. + The packages can then be upgraded using the package tools on the device, much like + on a desktop distribution such as Ubuntu or Fedora. + </p></td></tr><tr class="question" title="12.9."><td align="left" valign="top"><a id="idp1603824"></a><a id="idp1603952"></a><p><strong>12.9.</strong></p></td><td align="left" valign="top"><p> + What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_top">GNOME</a> + platform targeted at mobile and embedded devices. + The the main difference between GNOME Mobile and standard GNOME is that + desktop-orientated libraries have been removed, along with deprecated libraries, + creating a much smaller footprint. + </p></td></tr><tr class="question" title="12.10."><td align="left" valign="top"><a id="idp1605872"></a><a id="idp1606000"></a><p><strong>12.10.</strong></p></td><td align="left" valign="top"><p> + I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'. + What is wrong? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You are probably running the build on an NTFS filesystem. + Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead. + </p></td></tr><tr class="question" title="12.11."><td align="left" valign="top"><a id="idp1662416"></a><a id="idp1662544"></a><p><strong>12.11.</strong></p></td><td align="left" valign="top"><p> + How do I make the Yocto Project work in RHEL/CentOS? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + To get the Yocto Project working under RHEL/CentOS 5.1 you need to first + install some required packages. + The standard CentOS packages needed are: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>"Development tools" (selected during installation)</p></li><li class="listitem"><p><code class="filename">texi2html</code></p></li><li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li></ul></div><p> + On top of these, you need the following external packages: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">python-sqlite2</code> from + <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG repository</a> + </p></li><li class="listitem"><p><code class="filename">help2man</code> from + <a class="ulink" href="http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html" target="_top">Karan repository</a></p></li></ul></div><p> + </p><p> + Once these packages are installed, the OpenEmbedded build system will be able + to build standard images. + However, there might be a problem with the QEMU emulator segfaulting. + You can either disable the generation of binary locales by setting + <code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a> + </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code> + from the kernel and rebuilding it since that is the patch that causes the problems with QEMU. + </p></td></tr><tr class="question" title="12.12."><td align="left" valign="top"><a id="idp562304"></a><a id="idp562432"></a><p><strong>12.12.</strong></p></td><td align="left" valign="top"><p> + I see lots of 404 responses for files on + <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Nothing is wrong. + The OpenEmbedded build system checks any configured source mirrors before downloading + from the upstream sources. + The build system does this searching for both source archives and + pre-checked out versions of SCM managed software. + These checks help in large installations because it can reduce load on the SCM servers + themselves. + The address above is one of the default mirrors configured into the + build system. + Consequently, if an upstream source disappears, the team + can place sources there so builds continue to work. + </p></td></tr><tr class="question" title="12.13."><td align="left" valign="top"><a id="idp179952"></a><a id="idp180080"></a><p><strong>12.13.</strong></p></td><td align="left" valign="top"><p> + I have machine-specific data in a package for one machine only but the package is + being marked as machine-specific in all cases, how do I prevent this? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Set <code class="filename"><a class="link" href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a> + </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is + manually marked as + machine-specific in the case that needs it. + The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>. + </p></td></tr><tr class="question" title="12.14."><td align="left" valign="top"><a id="idp184672"></a><a id="idp1581568"></a><p><strong>12.14.</strong></p></td><td align="left" valign="top"><p> + I'm behind a firewall and need to use a proxy server. How do I do that? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code> + and you therefore need to specify the proxy settings in a + <code class="filename">.wgetrc</code> file in your home directory. + Example settings in that file would be + </p><pre class="literallayout"> + http_proxy = http://proxy.yoyodyne.com:18023/ + ftp_proxy = http://proxy.yoyodyne.com:18023/ + </pre><p> + The Yocto Project also includes a <code class="filename">site.conf.sample</code> + file that shows how to configure CVS and Git proxy servers + if needed. + </p></td></tr><tr class="question" title="12.15."><td align="left" valign="top"><a id="idp1585952"></a><a id="idp1586080"></a><p><strong>12.15.</strong></p></td><td align="left" valign="top"><p> + What’s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The <code class="filename">*-native</code> targets are designed to run on the system + being used for the build. + These are usually tools that are needed to assist the build in some way such as + <code class="filename">quilt-native</code>, which is used to apply patches. + The non-native version is the one that runs on the target device. + </p></td></tr><tr class="question" title="12.16."><td align="left" valign="top"><a id="idp3269536"></a><a id="idp3269664"></a><p><strong>12.16.</strong></p></td><td align="left" valign="top"><p> + I'm seeing random build failures. Help?! + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + If the same build is failing in totally different and random ways, + the most likely explanation is that either the hardware you're running the + build on has some problem, or, if you are running the build under virtualisation, + the virtualisation probably has bugs. + The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and + CPU activity and is sensitive to even single bit failures in any of these areas. + True random failures have always been traced back to hardware or virtualisation issues. + </p></td></tr><tr class="question" title="12.17."><td align="left" valign="top"><a id="idp3271104"></a><a id="idp3271232"></a><p><strong>12.17.</strong></p></td><td align="left" valign="top"><p> + What do we need to ship for license compliance? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + This is a difficult question and you need to consult your lawyer for the answer + for your specific case. + It is worth bearing in mind that for GPL compliance there needs to be enough + information shipped to allow someone else to rebuild the same end result + you are shipping. + This means sharing the source code, any patches applied to it, and also any + configuration information about how that package was configured and built. + </p></td></tr><tr class="question" title="12.18."><td align="left" valign="top"><a id="idp3272560"></a><a id="idp3272688"></a><p><strong>12.18.</strong></p></td><td align="left" valign="top"><p> + How do I disable the cursor on my touchscreen device? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You need to create a form factor file as described in the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>" + section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows: + </p><pre class="literallayout"> + HAVE_TOUCHSCREEN=1 + </pre><p> + </p></td></tr><tr class="question" title="12.19."><td align="left" valign="top"><a id="idp3244640"></a><a id="idp3244768"></a><p><strong>12.19.</strong></p></td><td align="left" valign="top"><p> + How do I make sure connected network interfaces are brought up by default? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The default interfaces file provided by the netbase recipe does not + automatically bring up network interfaces. + Therefore, you will need to add a BSP-specific netbase that includes an interfaces + file. + See the "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>" + section for information on creating these types of miscellaneous recipe files. + </p><p> + For example, add the following files to your layer: + </p><pre class="literallayout"> + meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces + meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend + </pre><p> + </p></td></tr><tr class="question" title="12.20."><td align="left" valign="top"><a id="idp3248256"></a><a id="idp3248384"></a><p><strong>12.20.</strong></p></td><td align="left" valign="top"><p> + How do I create images with more free space? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Images are created to be 1.2 times the size of the populated root filesystem. + To modify this ratio so that there is more free space available, you need to + set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>. + For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets + the image size ratio to one and a half times the size of the populated + root filesystem. + </p><pre class="literallayout"> + IMAGE_OVERHEAD_FACTOR = "1.5" + </pre><p> + </p></td></tr><tr class="question" title="12.21."><td align="left" valign="top"><a id="idp348464"></a><a id="idp348592"></a><p><strong>12.21.</strong></p></td><td align="left" valign="top"><p> + Why don't you support directories with spaces in the pathnames? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The Yocto Project team has tried to do this before but too many of the tools + the OpenEmbedded build system depends on such as <code class="filename">autoconf</code> + break when they find spaces in pathnames. + Until that situation changes, the team will not support spaces in pathnames. + </p></td></tr><tr class="question" title="12.22."><td align="left" valign="top"><a id="idp350512"></a><a id="idp350640"></a><p><strong>12.22.</strong></p></td><td align="left" valign="top"><p> + How do I use an external toolchain? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The toolchain configuration is very flexible and customizable. + It is primarily controlled with the + <code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> variable. + This variable controls which <code class="filename">tcmode-*.inc</code> file to include + from the <code class="filename">meta/conf/distro/include</code> directory within the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a>. + </p><p> + The default value of <code class="filename">TCMODE</code> is "default" + (i.e. <code class="filename">tcmode-default.inc</code>). + However, other patterns are accepted. + In particular, "external-*" refers to external toolchains of which there are some + basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>). + You can use your own custom toolchain definition in your own layer + (or as defined in the <code class="filename">local.conf</code> file) at the location + <code class="filename">conf/distro/include/tcmode-*.inc</code>. + </p><p> + In addition to the toolchain configuration, you also need a corresponding toolchain recipe file. + This recipe file needs to package up any pre-built objects in the toolchain such as + <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>, + any locales, and <code class="filename">libc</code>. + An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located + in <code class="filename">meta/recipes-core/meta/</code> within the source directory. + </p></td></tr><tr class="question" title="12.23."><td align="left" valign="top"><a id="idm184288"></a><a id="idm1835680"></a><p><strong>12.23.</strong></p></td><td align="left" valign="top"><p><a id="how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server"></a> + How does the OpenEmbedded build system obtain source code and will it work behind my + firewall or proxy server? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + The way the build system obtains source code is highly configurable. + You can setup the build system to get source code in most environments if + HTTP transport is available. + </p><p> + When the build system searches for source code, it first tries the local download directory. + If that location fails, Poky tries PREMIRRORS, the upstream source, + and then MIRRORS in that order. + </p><p> + By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS + for SCM-based sources, + upstreams for normal tarballs, and then falls back to a number of other mirrors + including the Yocto Project source mirror if those fail. + </p><p> + As an example, you could add a specific server for Poky to attempt before any + others by adding something like the following to the <code class="filename">local.conf</code> + configuration file: + </p><pre class="literallayout"> + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + </pre><p> + </p><p> + These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS + requests and direct them to the <code class="filename">http://</code> sources mirror. + You can use <code class="filename">file://</code> URLs to point to local directories + or network shares as well. + </p><p> + Aside from the previous technique, these options also exist: + </p><pre class="literallayout"> + BB_NO_NETWORK = "1" + </pre><p> + This statement tells BitBake to throw an error instead of trying to access the + Internet. + This technique is useful if you want to ensure code builds only from local sources. + </p><p> + Here is another technique: + </p><pre class="literallayout"> + BB_FETCH_PREMIRRORONLY = "1" + </pre><p> + This statement limits Poky to pulling source from the PREMIRRORS only. + Again, this technique is useful for reproducing builds. + </p><p> + Here is another technique: + </p><pre class="literallayout"> + BB_GENERATE_MIRROR_TARBALLS = "1" + </pre><p> + This statement tells Poky to generate mirror tarballs. + This technique is useful if you want to create a mirror server. + If not, however, the technique can simply waste time during the build. + </p><p> + Finally, consider an example where you are behind an HTTP-only firewall. + You could make the following changes to the <code class="filename">local.conf</code> + configuration file as long as the PREMIRROR server is up to date: + </p><pre class="literallayout"> + PREMIRRORS_prepend = "\ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + BB_FETCH_PREMIRRORONLY = "1" + </pre><p> + These changes would cause Poky to successfully fetch source over HTTP and + any network accesses to anything other than the PREMIRROR would fail. + </p><p> + The build system also honors the standard shell environment variables + <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>, + <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code> + to redirect requests through proxy servers. + </p></td></tr><tr class="question" title="12.24."><td align="left" valign="top"><a id="idm1036560"></a><a id="idm1036432"></a><p><strong>12.24.</strong></p></td><td align="left" valign="top"><p> + Can I get rid of build output so I can start over? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Yes - you can easily do this. + When you use BitBake to build an image, all the build output goes into the + directory created when you source the <code class="filename">oe-init-build-env</code> + setup file. + By default, this <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">build directory</a> + is named <code class="filename">build</code> but can be named + anything you want. + </p><p> + Within the build directory is the <code class="filename">tmp</code> directory. + To remove all the build output yet preserve any source code or downloaded files + from previous builds, simply remove the <code class="filename">tmp</code> directory. + </p></td></tr></tbody></table></div></div> + + <div class="chapter" title="Chapter 13. Contributing to the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="resources"></a>Chapter 13. Contributing to the Yocto Project</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#resources-intro">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">13.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">13.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">13.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">13.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">13.6. Contributions</a></span></dt></dl></div><div class="section" title="13.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-intro"></a>13.1. Introduction</h2></div></div></div><p> + The Yocto Project team is happy for people to experiment with the Yocto Project. + A number of places exist to find help if you run into difficulties or find bugs. + To find out how to download source code, + see the "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#local-yp-release" target="_top">Yocto Project Release</a>" + list item in the Yocto Project Development Manual. + </p></div><div class="section" title="13.2. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-bugtracker"></a>13.2. Tracking Bugs</h2></div></div></div><p> + If you find problems with the Yocto Project, you should report them using the + Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>. + </p></div><div class="section" title="13.3. Mailing lists"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-mailinglist"></a>13.3. Mailing lists</h2></div></div></div><p> + There are a number of mailing lists maintained by the Yocto Project as well as + related OpenEmbedded mailing lists for discussion, patch submission and announcements. + To subscribe to one of the following mailing lists, click on the appropriate URL + in the following list and follow the instructions: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> - + General Yocto Project discussion mailing list. </p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core</a> - + Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel</a> - + Discussion mailing list about OpenEmbedded.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel</a> - + Discussion mailing list about the BitBake build tool.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> - + Discussion mailing list about Poky.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> - + Mailing list to receive official Yocto Project release and milestone + announcements.</p></li></ul></div><p> + </p></div><div class="section" title="13.4. Internet Relay Chat (IRC)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-irc"></a>13.4. Internet Relay Chat (IRC)</h2></div></div></div><p> + Two IRC channels on freenode are available for the Yocto Project and Poky discussions: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">#yocto</code></p></li><li class="listitem"><p><code class="filename">#poky</code></p></li></ul></div><p> + </p></div><div class="section" title="13.5. Links"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-links"></a>13.5. Links</h2></div></div></div><p> + Following is a list of resources you will find helpful: + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_top">The Yocto Project website</a>: + </em></span> The home site for the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span> + The company who acquired OpenedHand in 2008 and began development on the + Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span> + The upstream, generic, embedded distribution used as the basis for the build system in the + Yocto Project. + Poky derives from and contributes back to the OpenEmbedded project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top"> + BitBake</a>:</em></span> The tool used to process metadata.</p></li><li class="listitem"><p><span class="emphasis"><em>BitBake User Manual:</em></span> + A comprehensive guide to the BitBake tool. + You can find the BitBake User Manual in the <code class="filename">bitbake/doc/manual</code> + directory, which is found in the + <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>. + </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>: + </em></span> An open source machine emulator and virtualizer.</p></li></ul></div><p> + </p></div><div class="section" title="13.6. Contributions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-contributions"></a>13.6. Contributions</h2></div></div></div><p> + The Yocto Project gladly accepts contributions. + You can submit changes to the project either by creating and sending pull requests, + or by submitting patches through email. + For information on how to do both, see the + "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">How to Submit a Change</a>" + section in the Yocto Project Development Manual. + </p></div></div> + + + +</div></body></html> diff --git a/documentation/ref-manual/ref-manual.pdf b/documentation/ref-manual/ref-manual.pdf Binary files differnew file mode 100644 index 0000000000..4dd9f7a25f --- /dev/null +++ b/documentation/ref-manual/ref-manual.pdf diff --git a/documentation/ref-manual/ref-manual.tgz b/documentation/ref-manual/ref-manual.tgz Binary files differnew file mode 100644 index 0000000000..e4a17c884f --- /dev/null +++ b/documentation/ref-manual/ref-manual.tgz diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml new file mode 100644 index 0000000000..eeba91c775 --- /dev/null +++ b/documentation/ref-manual/ref-manual.xml @@ -0,0 +1,125 @@ +<!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='ref-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/poky-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title></title> + + <authorgroup> + <author> + <firstname>Richard</firstname> <surname>Purdie</surname> + <affiliation> + <orgname>Linux Foundation</orgname> + </affiliation> + <email>richard.purdie@linuxfoundation.org</email> + </author> + + </authorgroup> + + <revhistory> + <revision> + <revnumber>4.0+git</revnumber> + <date>24 November 2010</date> + <revremark>Released with the Yocto Project 0.9 Release</revremark> + </revision> + <revision> + <revnumber>1.0</revnumber> + <date>6 April 2011</date> + <revremark>Released with the Yocto Project 1.0 Release.</revremark> + </revision> + <revision> + <revnumber>1.0.1</revnumber> + <date>23 May 2011</date> + <revremark>Released with the Yocto Project 1.0.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.1</revnumber> + <date>6 October 2011</date> + <revremark>Released with the Yocto Project 1.1 Release.</revremark> + </revision> + <revision> + <revnumber>1.2</revnumber> + <date>April 2012</date> + <revremark>Released with the Yocto Project 1.2 Release.</revremark> + </revision> + <revision> + <revnumber>1.3</revnumber> + <date>October 2012</date> + <revremark>Released with the Yocto Project 1.3 Release.</revremark> + </revision> + <revision> + <revnumber>1.4</revnumber> + <date>Sometime in 2013</date> + <revremark>Released with the Yocto Project 1.4 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> + Due to production processes, there could be differences between the Yocto Project + documentation bundled in the release tarball and the + <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink> on + the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. + For the latest version of this manual, see the manual on the website. + </note> + </legalnotice> + + </bookinfo> + + <xi:include href="introduction.xml"/> + + <xi:include href="usingpoky.xml"/> + + <xi:include href="technical-details.xml"/> + + <xi:include href="migration.xml"/> + + <xi:include href="ref-structure.xml"/> + + <xi:include href="ref-bitbake.xml"/> + + <xi:include href="ref-classes.xml"/> + + <xi:include href="ref-images.xml"/> + + <xi:include href="ref-features.xml"/> + + <xi:include href="ref-variables.xml"/> + + <xi:include href="ref-varlocality.xml"/> + + <xi:include href="faq.xml"/> + + <xi:include href="resources.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml new file mode 100644 index 0000000000..2fa3341e61 --- /dev/null +++ b/documentation/ref-manual/ref-structure.xml @@ -0,0 +1,709 @@ +<!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-structure'> + +<title>Source Directory Structure</title> + +<para> + The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components. + Understanding them and knowing where they are located is key to using the Yocto Project well. + This chapter describes the Source Directory and gives information about the various + files and directories. +</para> + +<para> + For information on how to establish a local Source Directory on your development system, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>" + section in the Yocto Project Development Manual. +</para> + +<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> + +<section id='structure-core'> + <title>Top level core components</title> + + <section id='structure-core-bitbake'> + <title><filename>bitbake/</filename></title> + + <para> + The <ulink url='source-directory'>Source Directory</ulink> + includes a copy of BitBake for ease of use. + The copy usually matches the current stable BitBake release from the BitBake project. + BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks + defined by that data. + Failures are usually from the metadata and not from BitBake itself. + Consequently, most users do not need to worry about BitBake. + </para> + + <para> + When you run the <filename>bitbake</filename> command, the wrapper script in + <filename>scripts/</filename> is executed to run the main BitBake executable, + which resides in the <filename>bitbake/bin/</filename> directory. + Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link> + script places the <filename>scripts</filename> and <filename>bitbake/bin</filename> + directories (in that order) into the shell's <filename>PATH</filename> environment + variable. + </para> + + <para> + For more information on BitBake, see the BitBake documentation + inculded in the <filename>bitbake/doc/manual</filename> directory of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para> + </section> + + <section id='structure-core-build'> + <title><filename>build/</filename></title> + + <para> + This directory contains user configuration files and the output + generated by the OpenEmbedded build system in its standard configuration where + the source tree is combined with the output. + The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + is created initially when you <filename>source</filename> + the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>. + </para> + + <para> + It is also possible to place output and configuration + files in a directory separate from the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + by providing a directory name when you <filename>source</filename> + the setup script. + For information on separating output from your local Source Directory files, see <link + linkend='structure-core-script'>&OE_INIT_FILE;</link>. + </para> + </section> + + <section id='handbook'> + <title><filename>documentation</filename></title> + + <para> + This directory holds the source for the Yocto Project documentation + as well as templates and tools that allow you to generate PDF and HTML + versions of the manuals. + Each manual is contained in a sub-folder. + For example, the files for this manual reside in + <filename>ref-manual</filename>. + </para> + </section> + + <section id='structure-core-meta'> + <title><filename>meta/</filename></title> + + <para> + This directory contains the OpenEmbedded Core metadata. + The directory holds recipes, common classes, and machine + configuration for emulated targets (qemux86, qemuarm, + and so on.) + </para> + </section> + + <section id='structure-core-meta-yocto'> + <title><filename>meta-yocto/</filename></title> + + <para> + This directory contains the configuration for the Poky + reference distribution. + </para> + </section> + + <section id='structure-core-meta-yocto-bsp'> + <title><filename>meta-yocto-bsp/</filename></title> + + <para> + This directory contains the Yocto Project reference + hardware BSPs. + </para> + </section> + + <section id='structure-meta-hob'> + <title><filename>meta-hob/</filename></title> + + <para> + This directory contains template recipes used by the + <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> + build UI. + </para> + </section> + + <section id='structure-meta-skeleton'> + <title><filename>meta-skeleton/</filename></title> + + <para> + This directory contains template recipes for BSP and kernel development. + </para> + </section> + + <section id='structure-core-scripts'> + <title><filename>scripts/</filename></title> + + <para> + This directory contains various integration scripts that implement + extra functionality in the Yocto Project environment (e.g. QEMU scripts). + The <link linkend="structure-core-script">&OE_INIT_FILE;</link> script appends this + directory to the shell's <filename>PATH</filename> environment variable. + </para> + + <para> + The <filename>scripts</filename> directory has useful scripts that assist contributing + back to the Yocto Project, such as <filename>create_pull_request</filename> and + <filename>send_pull_request</filename>. + </para> + </section> + + <section id='structure-core-script'> + <title><filename>&OE_INIT_FILE;</filename></title> + + <para> + This script sets up the OpenEmbedded build environment. + Running this script with the <filename>source</filename> command in + a shell makes changes to <filename>PATH</filename> and sets other core BitBake variables based on the + current working directory. + You need to run this script before running BitBake commands. + The script uses other scripts within the <filename>scripts</filename> directory to do + the bulk of the work. + </para> + + <para> + By default, running this script without a Build Directory argument creates the + <filename>build</filename> directory. + If you provide a Build Directory argument when you <filename>source</filename> + the script, you direct OpenEmbedded build system to create a + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> of your choice. + For example, the following command creates a Build Directory named + <filename>mybuilds</filename> that is outside of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: + <literallayout class='monospaced'> + $ source &OE_INIT_FILE; ~/mybuilds + </literallayout> + <note> + The OpenEmbedded build system does not support file or directory names that + contain spaces. + If you attempt to run the <filename>&OE_INIT_FILE;</filename> script + from a Source Directory that contains spaces in either the filenames + or directory names, the script returns an error indicating no such + file or directory. + Be sure to use a Source Directory free of names containing spaces. + </note> + </para> + </section> + + <section id='structure-basic-top-level'> + <title><filename>LICENSE, README, and README.hardware</filename></title> + + <para> + These files are standard top-level files. + </para> + </section> +</section> + +<section id='structure-build'> + <title>The Build Directory - <filename>build/</filename></title> + + <section id='structure-build-pseudodone'> + <title><filename>build/pseudodone</filename></title> + + <para> + This tag file indicates that the initial pseudo binary was created. + The file is built the first time BitBake is invoked. + </para> + </section> + + <section id='structure-build-conf-local.conf'> + <title><filename>build/conf/local.conf</filename></title> + + <para> + This file contains all the local user configuration for your build environment. + If there is no <filename>local.conf</filename> present, it is created from + <filename>local.conf.sample</filename>. + The <filename>local.conf</filename> file contains documentation on the various configuration options. + Any variable set here overrides any variable set elsewhere within the environment unless + that variable is hard-coded within a file (e.g. by using '=' instead of '?='). + Some variables are hard-coded for various reasons but these variables are + relatively rare. + </para> + + <para> + Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename> + for which you want to build, which package types you wish to use + (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), + where you want to downloaded files + (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>), + and how you want your host machine to use resources + (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>). + </para> + </section> + + <section id='structure-build-conf-bblayers.conf'> + <title><filename>build/conf/bblayers.conf</filename></title> + + <para> + This file defines layers, which are directory trees, traversed (or walked) by BitBake. + If <filename>bblayers.conf</filename> + is not present, it is created from <filename>bblayers.conf.sample</filename> when + you <filename>source</filename> the environment setup script. + </para> + + <para> + The <filename>bblayers.conf</filename> file uses the + <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable to + list the layers BitBake tries to find. + The file uses the + <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link> + variable to list layers that must not be removed. + </para> + </section> + + <section id='structure-build-conf-sanity_info'> + <title><filename>build/conf/sanity_info</filename></title> + + <para> + This file is created during the build to indicate the state of the sanity checks. + </para> + </section> + + <section id='structure-build-downloads'> + <title><filename>build/downloads/</filename></title> + + <para> + This directory is used for the upstream source tarballs. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable. + </para> + </section> + + <section id='structure-build-sstate-cache'> + <title><filename>build/sstate-cache/</filename></title> + + <para> + This directory is used for the shared state cache. + The directory can be reused by multiple builds or moved to another location. + You can control the location of this directory through the + <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable. + </para> + </section> + + <section id='structure-build-tmp'> + <title><filename>build/tmp/</filename></title> + + <para> + This directory receives all the OpenEmbedded build system's output. + BitBake creates this directory if it does not exist. + As a last resort, to clean up a build and start it from scratch (other than the downloads), + you can remove everything in the <filename>tmp</filename> directory or get rid of the + directory completely. + If you do, you should also completely remove the <filename>build/sstate-cache</filename> + directory as well. + </para> + </section> + + <section id='structure-build-tmp-buildstats'> + <title><filename>build/tmp/buildstats/</filename></title> + + <para> + This directory stores the build statistics. + </para> + </section> + + <section id='structure-build-tmp-cache'> + <title><filename>build/tmp/cache/</filename></title> + + <para> + When BitBake parses the metadata, it creates a cache file of the result that can + be used when subsequently running commands. + These results are stored here on a per-machine basis. + </para> + </section> + + <section id='structure-build-tmp-deploy'> + <title><filename>build/tmp/deploy/</filename></title> + + <para> + This directory contains any 'end result' output from the OpenEmbedded build process. + </para> + </section> + + <section id='structure-build-tmp-deploy-deb'> + <title><filename>build/tmp/deploy/deb/</filename></title> + + <para> + This directory receives any <filename>.deb</filename> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </para> + </section> + + <section id='structure-build-tmp-deploy-rpm'> + <title><filename>build/tmp/deploy/rpm/</filename></title> + + <para> + This directory receives any <filename>.rpm</filename> packages produced by + the build process. + The packages are sorted into feeds for different architecture types. + </para> + </section> + + <section id='structure-build-tmp-deploy-licenses'> + <title><filename>build/tmp/deploy/licenses/</filename></title> + + <para> + This directory receives package licensing information. + For example, the directory contains sub-directories for <filename>bash</filename>, + <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn + contain appropriate <filename>COPYING</filename> license files with other licensing information. + </para> + </section> + + <section id='structure-build-tmp-deploy-images'> + <title><filename>build/tmp/deploy/images/</filename></title> + + <para> + This directory receives complete filesystem images. + If you want to flash the resulting image from a build onto a device, look here for the image. + </para> + + <para> + Be careful when deleting files in this directory. + You can safely delete old images from this directory (e.g. + <filename>core-image-*</filename>, <filename>hob-image-*</filename>, + etc.). + However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.), + bootloader and other supplementary files might be deployed here prior to building an + image. + Because these files, however, are not directly produced from the image, if you + delete them they will not be automatically re-created when you build the image again. + </para> + + <para> + If you do accidentally delete files here, you will need to force them to be + re-created. + In order to do that, you will need to know the target that produced them. + For example, these commands rebuild and re-create the kernel files: + <literallayout class='monospaced'> + $ bitbake -c clean virtual/kernel + $ bitbake virtual/kernel + </literallayout> + </para> + </section> + + <section id='structure-build-tmp-deploy-ipk'> + <title><filename>build/tmp/deploy/ipk/</filename></title> + + <para> + This directory receives <filename>.ipk</filename> packages produced by + the build process.</para> + </section> + + <section id='structure-build-tmp-sysroots'> + <title><filename>build/tmp/sysroots/</filename></title> + + <para> + This directory contains shared header files and libraries as well as other shared + data. + Packages that need to share output with other packages do so within this directory. + The directory is subdivided by architecture so multiple builds can run within + the one Build Directory. + </para> + </section> + + <section id='structure-build-tmp-stamps'> + <title><filename>build/tmp/stamps/</filename></title> + + <para> + This directory holds information that BitBake uses for accounting purposes + to track what tasks have run and when they have run. + The directory is sub-divided by architecture, package name, and + version. + Following is an example: + <literallayout class='monospaced'> + stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do + </literallayout> + Although the files in the directory are empty of data, + BitBake uses the filenames and timestamps for tracking purposes. + </para> + </section> + + <section id='structure-build-tmp-log'> + <title><filename>build/tmp/log/</filename></title> + + <para> + This directory contains general logs that are not otherwise placed using the + package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. + Examples of logs are the output from the <filename>check_pkg</filename> or + <filename>distro_check</filename> tasks. + Running a build does not necessarily mean this directory is created. + </para> + </section> + + <section id='structure-build-tmp-pkgdata'> + <title><filename>build/tmp/pkgdata/</filename></title> + + <para> + This directory contains intermediate packaging data that is used later in the packaging process. + For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section. + </para> + </section> + + <section id='structure-build-tmp-work'> + <title><filename>build/tmp/work/</filename></title> + + <para> + This directory contains architecture-specific work sub-directories + for packages built by BitBake. + All tasks execute from the appropriate work directory. + For example, the source for a particular package is unpacked, + patched, configured and compiled all within its own work directory. + Within the work directory, organization is based on the package group + and version for which the source is being compiled + as defined by the + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. + </para> + + <para> + It is worth considering the structure of a typical work directory. + As an example, consider the <filename>linux-yocto-kernel-3.0</filename> + on the machine <filename>qemux86</filename> + 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. + Within this directory, the source is unpacked to + <filename>linux-qemux86-standard-build</filename> and then patched by Quilt + (see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package + Source Code with Quilt</ulink>" section in the Yocto Project Development Manual. + Within the <filename>linux-qemux86-standard-build</filename> directory, + standard Quilt directories <filename>linux-3.0/patches</filename> + and <filename>linux-3.0/.pc</filename> are created, + and standard Quilt commands can be used. + </para> + + <para> + There are other directories generated within <filename>WORKDIR</filename>. + The most important directory is <filename>WORKDIR/temp/</filename>, + which has log files for each task (<filename>log.do_*.pid</filename>) + and contains the scripts BitBake runs for each task + (<filename>run.do_*.pid</filename>). + The <filename>WORKDIR/image/</filename> directory is where "make + install" places its output that is then split into sub-packages + within <filename>WORKDIR/packages-split/</filename>. + </para> + </section> +</section> + +<section id='structure-meta'> + <title>The Metadata - <filename>meta/</filename></title> + + <para> + As mentioned previously, metadata is the core of the Yocto Project. + Metadata has several important subdivisions: + </para> + + <section id='structure-meta-classes'> + <title><filename>meta/classes/</filename></title> + + <para> + This directory contains the <filename>*.bbclass</filename> files. + Class files are used to abstract common code so it can be reused by multiple + packages. + Every package inherits the <filename>base.bbclass</filename> file. + Examples of other important classes are <filename>autotools.bbclass</filename>, which + in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort. + Another example is <filename>kernel.bbclass</filename> that contains common code and functions + for working with the Linux kernel. + Functions like image generation or packaging also have their specific class files + such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and + <filename>package*.bbclass</filename>. + </para> + </section> + + <section id='structure-meta-conf'> + <title><filename>meta/conf/</filename></title> + + <para> + This directory contains the core set of configuration files that start from + <filename>bitbake.conf</filename> and from which all other configuration + files are included. + See the include statements at the end of the file and you will note that even + <filename>local.conf</filename> is loaded from there. + While <filename>bitbake.conf</filename> sets up the defaults, you can often override + these by using the (<filename>local.conf</filename>) file, machine file or + the distribution configuration file. + </para> + </section> + + <section id='structure-meta-conf-machine'> + <title><filename>meta/conf/machine/</filename></title> + + <para> + This directory contains all the machine configuration files. + If you set <filename>MACHINE="qemux86"</filename>, + the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this + directory. + The <filename>include</filename> directory contains various data common to multiple machines. + If you want to add support for a new machine to the Yocto Project, look in this directory. + </para> + </section> + + <section id='structure-meta-conf-distro'> + <title><filename>meta/conf/distro/</filename></title> + + <para> + Any distribution-specific configuration is controlled from this directory. + For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here. + This directory includes the versions and the + <filename>SRCDATE</filename> definitions for applications that are configured here. + An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>. + Although this file mainly inherits its configuration from Poky. + </para> + </section> + + <section id='structure-meta-recipes-bsp'> + <title><filename>meta/recipes-bsp/</filename></title> + + <para> + This directory contains anything linking to specific hardware or hardware + configuration information such as "u-boot" and "grub". + </para> + </section> + + <section id='structure-meta-recipes-connectivity'> + <title><filename>meta/recipes-connectivity/</filename></title> + + <para> + This directory contains libraries and applications related to communication with other devices. + </para> + </section> + + <section id='structure-meta-recipes-core'> + <title><filename>meta/recipes-core/</filename></title> + + <para> + This directory contains what is needed to build a basic working Linux image + including commonly used dependencies. + </para> + </section> + + <section id='structure-meta-recipes-devtools'> + <title><filename>meta/recipes-devtools/</filename></title> + + <para> + This directory contains tools that are primarily used by the build system. + The tools, however, can also be used on targets. + </para> + </section> + + <section id='structure-meta-recipes-extended'> + <title><filename>meta/recipes-extended/</filename></title> + + <para> + This directory contains non-essential applications that add features compared to the + alternatives in core. + You might need this directory for full tool functionality or for Linux Standard Base (LSB) + compliance. + </para> + </section> + + <section id='structure-meta-recipes-gnome'> + <title><filename>meta/recipes-gnome/</filename></title> + + <para> + This directory contains all things related to the GTK+ application framework. + </para> + </section> + + <section id='structure-meta-recipes-graphics'> + <title><filename>meta/recipes-graphics/</filename></title> + + <para> + This directory contains X and other graphically related system libraries + </para> + </section> + + <section id='structure-meta-recipes-kernel'> + <title><filename>meta/recipes-kernel/</filename></title> + + <para> + This directory contains the kernel and generic applications and libraries that + have strong kernel dependencies. + </para> + </section> + + <section id='structure-meta-recipes-multimedia'> + <title><filename>meta/recipes-multimedia/</filename></title> + + <para> + This directory contains codecs and support utilities for audio, images and video. + </para> + </section> + + <section id='structure-meta-recipes-qt'> + <title><filename>meta/recipes-qt/</filename></title> + + <para> + This directory contains all things related to the Qt application framework. + </para> + </section> + + <section id='structure-meta-recipes-rt'> + <title><filename>meta/recipes-rt/</filename></title> + + <para> + This directory contains package and image recipes for using and testing + the <filename>PREEMPT_RT</filename> kernel. + </para> + </section> + + <section id='structure-meta-recipes-sato'> + <title><filename>meta/recipes-sato/</filename></title> + + <para> + This directory contains the Sato demo/reference UI/UX and its associated applications + and configuration data. + </para> + </section> + + <section id='structure-meta-recipes-support'> + <title><filename>meta/recipes-support/</filename></title> + + <para> + This directory contains recipes that used by other recipes, but that are not directly + included in images (i.e. dependencies of other recipes). + </para> + </section> + + <section id='structure-meta-site'> + <title><filename>meta/site/</filename></title> + + <para> + This directory contains a list of cached results for various architectures. + Because certain "autoconf" test results cannot be determined when cross-compiling due to + the tests not able to run on a live system, the information in this directory is + passed to "autoconf" for the various architectures. + </para> + </section> + + <section id='structure-meta-recipes-txt'> + <title><filename>meta/recipes.txt</filename></title> + + <para> + This file is a description of the contents of <filename>recipes-*</filename>. + </para> + </section> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css new file mode 100644 index 0000000000..e896a39d33 --- /dev/null +++ b/documentation/ref-manual/ref-style.css @@ -0,0 +1,979 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/poky-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-image: url("figures/poky-title.png"); + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} + diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml new file mode 100644 index 0000000000..c490fc360d --- /dev/null +++ b/documentation/ref-manual/ref-variables.xml @@ -0,0 +1,3018 @@ +<!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; ] > + +<!-- Dummy chapter --> +<chapter id='ref-variables-glos'> + +<title>Variables Glossary</title> + +<para> + This chapter lists common variables used in the OpenEmbedded build system and gives an overview + of their function and contents. +</para> + +<glossary id='ref-variables-glossary'> + + + <para> + <link linkend='var-ALLOW_EMPTY'>A</link> + <link linkend='var-B'>B</link> + <link linkend='var-CFLAGS'>C</link> + <link linkend='var-D'>D</link> + <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link> + <link linkend='var-FILES'>F</link> +<!-- <link linkend='var-glossary-g'>G</link> --> + <link linkend='var-HOMEPAGE'>H</link> + <link linkend='var-IMAGE_FEATURES'>I</link> +<!-- <link linkend='var-glossary-j'>J</link> --> + <link linkend='var-KBRANCH'>K</link> + <link linkend='var-LAYERDIR'>L</link> + <link linkend='var-MACHINE'>M</link> +<!-- <link linkend='var-glossary-n'>N</link> --> + <link linkend='var-OE_TERMINAL'>O</link> + <link linkend='var-P'>P</link> +<!-- <link linkend='var-glossary-q'>Q</link> --> + <link linkend='var-RCONFLICTS'>R</link> + <link linkend='var-S'>S</link> + <link linkend='var-T'>T</link> +<!-- <link linkend='var-glossary-u'>U</link> --> +<!-- <link linkend='var-glossary-v'>V</link> --> + <link linkend='var-WORKDIR'>W</link> +<!-- <link linkend='var-glossary-x'>X</link> --> +<!-- <link linkend='var-glossary-y'>Y</link> --> +<!-- <link linkend='var-glossary-z'>Z</link>--> + </para> + + <glossdiv id='var-glossary-a'><title>A</title> + + <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> + <glossdef> + <para> + Specifies if an output package should still be produced 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 + some other runtime hard-requirement on the existence of the package. + </para> + + <para> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + <literallayout class='monospaced'> + ALLOW_EMPTY_${PN} = "1" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> + <glossdef> + <para>The email address used to contact the original author or authors in + order to send patches, forward bugs, etc.</para> + </glossdef> + </glossentry> + + <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm> + <glossdef> + <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename> + is set to the value of this variable, it specifies that the latest + source revision in the repository should be used. Here is an example: + <literallayout class='monospaced'> + SRCREV = "${AUTOREV}" + </literallayout> + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-b'><title>B</title> + + <glossentry id='var-B'><glossterm>B</glossterm> + <glossdef> + <para> + The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + The OpenEmbedded build system places generated objects into the Build Directory + during a recipe's build process. + By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link> + directory: + <literallayout class='monospaced'> + B = ${WORKDIR}/${BPN}/{PV}/ + </literallayout> + You can separate the (<filename>S</filename>) directory and the directory pointed to + by the <filename>B</filename> variable. + Most autotools-based recipes support separating these directories. + The build system defaults to using separate directories for <filename>gcc</filename> + and some kernel recipes. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm> + <glossdef> + <para> + A list of packages not to install despite being recommended by a recipe. + Support for this variable exists only when using the + <filename>ipk</filename> packaging backend. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm> + <glossdef> + <para> + Monitors disk space and available inodes during the build + and allows you to control the build based on these + parameters. + </para> + + <para> + Disk space monitoring is disabled by default. + To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename> + variable to your <filename>conf/local.conf</filename> file found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + Use the following form: + <literallayout class='monospaced'> + BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" + + where: + + <action> is: + ABORT: Immediately abort the build when + a threshold is broken. + STOPTASKS: Stop the build after the currently + executing tasks have finished when + a threshold is broken. + 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. + + <dir> is: + Any directory you choose. You can specify one or + more directories to monitor by separating the + groupings with a space. If two directories are + on the same device, only the first directory + is monitored. + + <threshold> is: + Either the minimum available disk space, + the minimum number of free inodes, or + both. You must specify at least one. To + omit one or the other, simply omit the value. + Specify the threshold using G, M, K for Gbytes, + Mbytes, and Kbytes, respectively. If you do + not specify G, M, or K, Kbytes is assumed by + default. Do not use GB, MB, or KB. + </literallayout> + </para> + + <para> + Here are some examples: + <literallayout class='monospaced'> + BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" + BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + </literallayout> + The first example works only if you also provide + the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable + in the <filename>conf/local.conf</filename>. + This example causes the build system to immediately + abort when either the disk space in <filename>${TMPDIR}</filename> drops + below 1 Gbyte or the available free inodes drops below + 100 Kbytes. + Because two directories are provided with the variable, the + build system also issue a + warning when the disk space in the + <filename>${SSTATE_DIR}</filename> directory drops + below 1 Gbyte or the number of free inodes drops + below 100 Kbytes. + Subsequent warnings are issued during intervals as + defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> + variable. + </para> + + <para> + The second example stops the build after all currently + executing tasks complete when the minimum disk space + in the <filename>${TMPDIR}</filename> directory drops + below 1 Gbyte. + No disk monitoring occurs for the free inodes in this case. + </para> + + <para> + The final example immediately aborts the build when the + number of free inodes in the <filename>${TMPDIR}</filename> directory + drops below 100 Kbytes. + No disk space monitoring for the directory itself occurs + in this case. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm> + <glossdef> + <para> + Defines the disk space and free inode warning intervals. + To set these intervals, define the variable in your + <filename>conf/local.conf</filename> file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + </para> + + <para> + If you are going to use the + <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must + also use the + <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable + and define its action as "WARN". + During the build, subsequent warnings are issued each time + disk space or number of free inodes further reduces by + the respective interval. + </para> + + <para> + If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> + variable and you do use <filename>BB_DISKMON_DIRS</filename> with + the "WARN" action, the disk monitoring interval defaults to + the following: + <literallayout class='monospaced'> + BB_DISKMON_WARNINTERVAL = "50M,5K" + </literallayout> + </para> + + <para> + When specifying the variable in your configuration file, + use the following form: + <literallayout class='monospaced'> + BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" + + where: + + <disk_space_interval> is: + An interval of memory expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + <disk_inode_interval> is: + An interval of free inodes expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + </literallayout> + </para> + + <para> + Here is an example: + <literallayout class='monospaced'> + BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_WARNINTERVAL = "50M,5K" + </literallayout> + These variables cause the OpenEmbedded build system to + issue subsequent warnings each time the available + disk space further reduces by 50 Mbytes or the number + of free inodes further reduces by 5 Kbytes in the + <filename>${SSTATE_DIR}</filename> directory. + Subsequent warnings based on the interval occur each time + a respective interval is reached beyond the intial warning + (i.e. 1 Gbytes and 100 Kbytes). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm> + <glossdef> + <para> + Allows you to extend a recipe so that it builds variants of the software. + Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>, + which is a copy of quilt built to run on the build system; + "crosses" such as <filename>gcc-cross</filename>, + which is a compiler built to run on the build machine but produces binaries + that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>; + "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>; + and "mulitlibs" in the form "<filename>multilib:<multilib_name></filename>". + </para> + + <para> + To build a different variant of the recipe with a minimal amount of code, it usually + is as simple as adding the following to your recipe: + <literallayout class='monospaced'> + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:<multilib_name>" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> + <glossdef> + <para>Prevents BitBake from processing recipes and recipe append files. + You can use the <filename>BBMASK</filename> variable to "hide" + these <filename>.bb</filename> and <filename>.bbappend</filename> files. + BitBake ignores any recipe or recipe append files that match the expression. + It is as if BitBake does not see them at all. + Consequently, matching files are not parsed or otherwise used by + BitBake.</para> + <para>The value you provide is passed to python's regular expression compiler. + For complete syntax information, see python's documentation at + <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>. + The expression is compared against the full paths to the files. + For example, the following uses a complete regular expression to tell + BitBake to ignore all recipe and recipe append files in the + <filename>.*/meta-ti/recipes-misc/</filename> directory: + <literallayout class='monospaced'> + BBMASK = ".*/meta-ti/recipes-misc/" + </literallayout></para> + <para>Use the <filename>BBMASK</filename> variable from within the + <filename>conf/local.conf</filename> file found + in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm> + <glossdef> + <para>The maximum number of tasks BitBake should run in parallel at any one time. + If your host development system supports multiple cores a good rule of thumb + is to set this variable to twice the number of cores.</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> + <glossdef> + <para>Lists the names of configured layers. + These names are used to find the other <filename>BBFILE_*</filename> + variables. + Typically, each layer will append its name to this variable in its + <filename>conf/layer.conf</filename> file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> + <glossdef> + <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer. + This variable is used in the <filename>conf/layer.conf</filename> file and must + be suffixed with the name of the specific layer (e.g. + <filename>BBFILE_PATTERN_emenlow</filename>).</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm> + <glossdef> + <para>Assigns the priority for recipe files in each layer.</para> + <para>This variable is useful in situations where the same recipe appears in + more than one layer. + Setting this variable allows you to prioritize a + layer against other layers that contain the same recipe - effectively + letting you control the precedence for the multiple layers. + The precedence established through this variable stands regardless of a + recipe's version (<filename>PV</filename> variable). + For example, a layer that has a recipe with a higher <filename>PV</filename> value but for + which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a + lower precedence.</para> + <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher + precedence. + For example, the value 6 has a higher precedence than the value 5. + If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer + dependencies (see the + <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for + more information. + The default priority, if unspecified + for a layer with no dependencies, is the lowest defined priority + 1 + (or 1 if no priorities are defined).</para> + <tip> + You can use the command <filename>bitbake-layers show_layers</filename> to list + all configured layers along with their priorities. + </tip> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm> + <glossdef> + <para>List of recipe files used by BitBake to build software</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> + <glossdef> + <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files. + This variable is analogous to the <filename>PATH</filename> variable.</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm> + <glossdef> + <para>Variable that controls how BitBake displays logs on build failure.</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> + <glossdef> + <para>Lists the layers to enable during the build. + This variable is defined in the <filename>bblayers.conf</filename> configuration + file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + Here is an example: + <literallayout class='monospaced'> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + " + </literallayout> + This example enables four layers, one of which is a custom, user-defined layer + named <filename>meta-mykernel</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm> + <glossdef> +Core layer for images cannot be removed + <para>Lists core layers that cannot be removed from the + <filename>bblayers.conf</filename> file. + In order for BitBake to build your image, your + <filename>bblayers.conf</filename> file must include the + <filename>meta</filename> and <filename>meta-yocto</filename> + core layers. + Here is an example that shows these two layers listed in + the <filename>BBLAYERS_NON_REMOVABLE</filename> statement: + <literallayout class='monospaced'> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + + BBLAYERS_NON_REMOVABLE ?= " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + " + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BP'><glossterm>BP</glossterm> + <glossdef> + <para>The base recipe name and version but without any special + recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, + and so forth). + <filename>BP</filename> is comprised of the following: + <literallayout class="monospaced"> + ${BPN}-${PV} + </literallayout></para> + </glossdef> + </glossentry> + + <glossentry id='var-BPN'><glossterm>BPN</glossterm> + <glossdef> + <para>The bare name of the recipe. + This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable + but removes common suffixes such as "-native" and "-cross" as well + as removes common prefixes such as multilib's "lib64-" and "lib32-". + The exact list of suffixes removed is specified by the + <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable. + The exact list of prefixes removed is specified by the + <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable. + Prefixes are removed for multilib and nativesdk cases.</para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-c'><title>C</title> + + <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm> + <glossdef> + <para> + Flags passed to C compiler for the target system. + This variable evaluates to the same as + <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> + <glossdef> + <para>A set of features common between + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> + and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + See the glossary descriptions for these variables for more information.</para> + </glossdef> + </glossentry> + + <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm> + <glossdef> + <para>A regular expression which evaluates to match the machines the recipe + works with. + It stops recipes being run on machines for which they are not compatible. + This is particularly useful with kernels. + It also helps to increase parsing speed as further parsing of the recipe is skipped + if it is found the current machine is not compatible.</para> + </glossdef> + </glossentry> + + <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm> + <glossdef> + <para> + Identifies editable or configurable files that are part of a package. + If the Package Management System (PMS) is being used to update + packages on the target system, it is possible that + configuration files you have changed after the original installation + and that you now want to remain unchanged are overwritten. + In other words, editable files might exist in the package that you do not + want reset as part of the package update process. + You can use the <filename>CONFFILES</filename> variable to list the files in the + package that you wish to prevent the PMS from overwriting during this update process. + </para> + + <para> + To use the <filename>CONFFILES</filename> variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files. + Here is an example: + <literallayout class='monospaced'> + CONFFILES_${PN} += "${sysconfdir}/file1 \ + ${sysconfdir}/file2 ${sysconfdir}/file3" + </literallayout> + </para> + + <para> + A relationship exists between the <filename>CONFFILES</filename> and + <filename><link linkend='var-FILES'>FILES</link></filename> variables. + The files listed within <filename>CONFFILES</filename> must be a subset of + the files listed within <filename>FILES</filename>. + Because the configuration files you provide with <filename>CONFFILES</filename> + are simply being identified so that the PMS will not overwrite them, + it makes sense that + the files must already be included as part of the package through the + <filename>FILES</filename> variable. + </para> + + <note> + When specifying paths as part of the <filename>CONFFILES</filename> variable, + it is good practice to use appropriate path variables. + For example, <filename>${sysconfdir}</filename> rather than + <filename>/etc</filename> or <filename>${bindir}</filename> rather + than <filename>/usr/bin</filename>. + You can find a list of these variables at the top of the + <filename>/meta/conf/bitbake.conf</filename> file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </note> + </glossdef> + </glossentry> + + <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm> + <glossdef> + <para> + A list of files that contains <filename>autoconf</filename> test results relevant + to the current build. + This variable is used by the Autotools utilities when running + <filename>configure</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm> + <glossdef> + <para> + Specifies the list of packages to be added to the image. + This variable should only be set in the <filename>local.conf</filename> + configuration file found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + </para> + + <para> + This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-d'><title>D</title> + + <glossentry id='var-D'><glossterm>D</glossterm> + <glossdef> + <para>The destination directory.</para> + </glossdef> + </glossentry> + + <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm> + <glossdef> + <para> + Specifies to build packages with debugging information. + This influences the value of the + <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm> + <glossdef> + <para> + The options to pass in + <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> + and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling + a system for debugging. + This variable defaults to "-O -fno-omit-frame-pointer -g". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm> + <glossdef> + <para>Specifies the priority of recipes.</para> + </glossdef> + </glossentry> + + <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm> + <glossdef> + <para> + Lists a recipe's build-time dependencies + (i.e. other recipe files). + The system ensures that all the dependencies listed + have been built and have their contents in the appropriate + sysroots before the recipe's configure task is executed. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> + <glossdef> + <para>The package description used by package managers. + If not set, <filename>DESCRIPTION</filename> takes + the value of the + <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm> + <glossdef> + <para>the destination directory.</para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm> + <glossdef> + <para> + The short name of the distribution. + This variable corresponds to a file with the + extension <filename>.conf</filename> + located in a <filename>conf/distro</filename> directory + within the metadata that contains the distribution configuration. + The + value must not contain spaces, and is typically all lower-case. + </para> + <para> + If the variable is blank, a set of default configuration + will be used, which is specified + within <filename>meta/conf/distro/defaultsetup.conf</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm> + <glossdef> + <para> + Specifies a list of distro-specific packages to add to all images. + This variable takes affect through + <filename>packagegroup-base</filename> so the + variable only really applies to the more full-featured + images that include <filename>packagegroup-base</filename>. + You can use this variable to keep distro policy out of + generic images. + As with all other distro variables, you set this variable + in the distro <filename>.conf</filename> file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm> + <glossdef> + <para> + Specifies a list of distro-specific packages to add to all images + if the packages exist. + The packages might not exist or be empty (e.g. kernel modules). + The list of packages are automatically installed but can be + removed by the user. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm> + <glossdef> + <para>The features enabled for the distribution. + For a list of features supported by the Yocto Project as shipped, + see the "<link linkend='ref-features-distro'>Distro</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> + <glossdef> + <para>Features to be added to + <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> + if not also present in + <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. + </para> + + <para> + This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. + 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 + more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm> + <glossdef> + <para>Features from + <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> + that should not backfilled (i.e. added to + <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>) + during the build. + See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for + more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> + <glossdef> + <para>The long name of the distribution.</para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> + <glossdef> + <para>Alias names used for the recipe in various Linux distributions.</para> + <para>See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling + a Package Name Alias</ulink>" section in the Yocto Project Development + Manual for more information.</para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm> + <glossdef> + <para>the version of the distribution.</para> + </glossdef> + </glossentry> + + <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm> + <glossdef> + <para> + The central download directory used by the build process to store downloads. + You can set this directory by defining the <filename>DL_DIR</filename> + variable in the <filename>/conf/local.conf</filename> file. + This directory is self-maintaining and you should not have + to touch it. + By default, the directory is <filename>downloads</filename> in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + <literallayout class='monospaced'> + #DL_DIR ?= "${TOPDIR}/downloads" + </literallayout> + To specify a different download directory, simply uncomment the line + and provide your directory. + </para> + + <para> + During a first build, the system downloads many different source code + tarballs from various upstream projects. + Downloading can take a while, particularly if your network + connection is slow. + Tarballs are all stored in the directory defined by + <filename>DL_DIR</filename> and the build system looks there first + to find source tarballs. + <note> + When wiping and rebuilding, you can preserve this directory to speed + up this part of subsequent builds. + </note> + </para> + + <para> + You can safely share this directory between multiple builds on the + same development machine. + For additional information on how the build process gets source files + when working behind a firewall or proxy server, see the + "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>" + chapter. + </para> + </glossdef> + + </glossentry> + </glossdiv> + + <glossdiv id='var-glossary-e'><title>E</title> + + <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm> + <glossdef> + <para></para> + <para>Variable that controls which locales for <filename>eglibc</filename> are + to be generated during the build (useful if the target device has 64Mbytes + of RAM or less).</para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm> + <glossdef> + <para> + Used with file and pathnames to create a prefix for a recipe's + version based on the recipe's + <link linkend='var-PE'><filename>PE</filename></link> value. + If <filename>PE</filename> is set and greater than zero for a recipe, + <filename>EXTENDPE</filename> becomes that value (e.g if + <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename> + becomes "1_"). + If a recipe's <filename>PE</filename> is not set (the default) or is equal to + zero, <filename>EXTENDPE</filename> becomes "".</para> + <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link> + variable for an example. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm> + <glossdef> + <para>Allows extra packages to be added to the generated images. + You set this variable in the <filename>local.conf</filename> + configuration file. + Note that some image features are also added using the + <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> + variable generally configured in image recipes. + You can use this variable to add more features in addition to those. + Here are some examples of features you can add:</para> + <literallayout class='monospaced'> +"dbg-pkgs" - Adds -dbg packages for all installed packages + including symbol information for debugging and + profiling. + +"dev-pkgs" - Adds -dev packages for all installed packages. + This is useful if you want to develop against + the libraries in the image. + +"tools-sdk" - Adds development tools such as gcc, make, + pkgconfig and so forth. + +"tools-debug" - Adds debugging tools such as gdb and + strace. + +"tools-profile" - Adds profiling tools such as oprofile, + exmap, lttng and valgrind (x86 only). + +"tools-testapps" - Adds useful testing tools such as + ts_print, aplay, arecord and so + forth. + +"debug-tweaks" - Makes an image suitable for development. + For example, ssh root access has a blank + password. You should remove this feature + before you produce a production image. + </literallayout> + + <para>There are other valid features too, see the + <link linkend='ref-features-image'>Images</link> + section for more details.</para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm> + <glossdef> + <para>A list of recipes to be built that do not provide packages to be installed in + the root filesystem. + </para> + <para>Sometimes a recipe is required to build the final image but is not + needed in the root filesystem. + You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to + list these recipes and thus, specify the dependencies. + A typical example is a required bootloader in a machine configuration. + </para> + <note> + To add packages to the root filesystem, see the various + <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename> + variables. + </note> + </glossdef> + </glossentry> + + <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm> + <glossdef> + <para>Additional <filename>cmake</filename> options.</para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm> + <glossdef> + <para>Additional <filename>configure</filename> script options.</para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm> + <glossdef> + <para>Additional GNU <filename>make</filename> options.</para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-f'><title>F</title> + + <glossentry id='var-FILES'><glossterm>FILES</glossterm> + <glossdef> + <para> + The list of directories or files that are placed in packages. + </para> + + <para> + To use the <filename>FILES</filename> variable, provide a package name + override that identifies the resulting package. + Then, provide a space-separated list of files or paths that identifies the + files you want included as part of the resulting package. + Here is an example: + <literallayout class='monospaced'> + FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + </literallayout> + </para> + + <note> + When specifying paths as part of the <filename>FILES</filename> variable, + it is good practice to use appropriate path variables. + For example, <filename>${sysconfdir}</filename> rather than + <filename>/etc</filename> or <filename>${bindir}</filename> rather + than <filename>/usr/bin</filename>. + You can find a list of these variables at the top of the + <filename>/meta/conf/bitbake.conf</filename> file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </note> + + <para> + If some of the files you provide with the <filename>FILES</filename> variable + are editable and you know they should not be + overwritten during the package update process by the Package Management + System (PMS), you can identify these files so that the PMS will not + overwrite them. + See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> + variable for information on how to identify these files to the PMS. + </para> + + </glossdef> + </glossentry> + + <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> + <glossdef> + <para> + Extends the search path the OpenEmbedded build system uses when + looking for files and patches as it processes recipes. + The directories BitBake uses when it processes recipes is defined by the + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable. + You can add directories to the search path by defining the + <filename>FILESEXTRAPATHS</filename> variable. + </para> + + <para> + To add paths to the search order, provide a list of directories and separate + each path using a colon character as follows: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" + </literallayout> + Typically, you want your directories searched first. + To make sure that happens, use <filename>_prepend</filename> and + the immediate expansion (<filename>:=</filename>) operator as shown in the + previous example. + Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable, + you must include the appropriate beginning or ending (as needed) colon character. + </para> + + <para> + The <filename>FILESEXTRAPATHS</filename> variable is intended for use in + <filename>.bbappend</filename> files to include any additional files provided in that layer. + You typically accomplish this with the following: + <literallayout class='monospaced'> + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm> + <glossdef> + <para> + The default set of directories the OpenEmbedded build system uses + when searching for patches and files. + 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. + </para> + + <para> + The default value for the <filename>FILESPATH</filename> variable is defined + in the <filename>base.bbclass</filename> class found in + <filename>meta/classes</filename> in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: + <literallayout class='monospaced'> +FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ + "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \ + "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \ + "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}" + </literallayout> + Do not hand-edit the <filename>FILESPATH</filename> variable. + If you want to extend the set of pathnames that BitBake uses when searching for + files and patches, use the + <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm> + <glossdef> + <para>Allows you to define your own file permissions settings table as part of + your configuration for the packaging process. + For example, suppose you need a consistent set of custom permissions for + a set of groups and users across an entire work project. + It is best to do this in the packages themselves but this is not always + possible. + </para> + <para> + By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which + is located in the <filename>meta/files</filename> folder in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + If you create your own file permissions setting table, you should place it in your + layer or the distros layer. + </para> + <para> + You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the + <filename>conf/local.conf</filename> file, which is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to + point to your custom <filename>fs-perms.txt</filename>. + You can specify more than a single file permissions setting table. + The paths you specify to these files must be defined within the + <filename>BBPATH</filename> variable. + </para> + <para> + For guidance on how to create your own file permissions settings table file, + examine the existing <filename>fs-perms.txt</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> + <glossdef> + <para> + The options to pass in + <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> + and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> + when compiling an optimized system. + This variable defaults to + "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2". + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- <glossdiv id='var-glossary-g'><title>G</title>--> +<!-- </glossdiv>--> + + <glossdiv id='var-glossary-h'><title>H</title> + + <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm> + <glossdef> + <para>Website where more information about the software the recipe is building + can be found.</para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-i'><title>I</title> + + <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm> + <glossdef> + <para>The list of features to include in an image. + Typically, you configure this variable in an image recipe. + Note that you can also add extra features to the image by using the + <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable. + See the "<link linkend="ref-features-image">Images</link>" section for the + full list of features that can be included in images built by the + OpenEmbedded build system.</para> + </glossdef> + </glossentry> + + <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm> + <glossdef> + <para>Formats of root filesystem images that you want to have created.</para> + </glossdef> + </glossentry> + + <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm> + <glossdef> + <para> + 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. + </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 + <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists + and turn these 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 with 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 = " package-name" + </literallayout> + Be sure to include the space between the quotation character and the start of the + package name. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm> + <glossdef> + <para> + Defines a multiplier that the build system applies to the initial image + size for cases when the multiplier times the returned disk usage value + for the image is greater than the sum of + <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> + and + <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>. + The result of the multiplier applied to the initial image size creates + free disk space in the image as overhead. + By default, the build process uses a multiplier of 1.3 for this variable. + This default value results in 30% free disk space added to the image when this + method is used to determine the final generated image size. + You should be aware that post install scripts and the package management + system uses disk space inside this overhead area. + Consequently, the multiplier does not produce an image with + all the theoretical free disk space. + See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> + for information on how the build system determines the overall image size. + </para> + + <para> + The default 30% free disk space typically gives the image enough room to boot + and allows for basic post installs while still leaving a small amount of + free disk space. + If 30% free space is inadequate, you can increase the default value. + For example, the following setting gives you 50% free space added to the image: + <literallayout class='monospaced'> + IMAGE_OVERHEAD_FACTOR = "1.5" + </literallayout> + </para> + + <para> + Alternatively, you can ensure a specific amount of free disk space is added + to the image by using + <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> + the variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm> + <glossdef> + <para> + Defines additional free disk space created in the image in Kbytes. + By default, this variable is set to "0". + This free disk space is added to the image after the build system determines + the image size as described in + <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>. + </para> + + <para> + This variable is particularly useful when you want to ensure that a + specific amount of free disk space is available on a device after an image + is installed and running. + For example, to be sure 5 Gbytes of free disk space is available, set the + variable as follows: + <literallayout class='monospaced'> + IMAGE_ROOTFS_EXTRA_SPACE = "5242880" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> + <glossdef> + <para> + Defines the size in Kbytes for the generated image. + The OpenEmbedded build system determines the final size for the generated + image using an algorithm that takes into account the initial disk space used + for the generated image, a requested size for the image, and requested + additional free disk space to be added to the image. + Programatically, the build system determines the final size of the + generated image as follows: + <literallayout class='monospaced'> + if (image-du * overhead) < rootfs-size: + internal-rootfs-size = rootfs-size + xspace + else: + internal-rootfs-size = (image-du * overhead) + xspace + + where: + + image-du = Returned value of the du command on + the image. + + overhead = IMAGE_OVERHEAD_FACTOR + + rootfs-size = IMAGE_ROOTFS_SIZE + + internal-rootfs-size = Initial root filesystem + size before any modifications. + + xspace = IMAGE_ROOTFS_EXTRA_SPACE + </literallayout> +<!-- In the above example, <filename>overhead</filename> is defined by the + <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename> + variable, <filename>xspace</filename> is defined by the + <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> + variable, and <filename>du</filename> is the results of the disk usage command + on the initially generated image. --> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm> + <glossdef> + <para>Helps define the recipe revision for recipes that share + a common <filename>include</filename> file. + You can think of this variable as part of the recipe revision + as set from within an include file.</para> + <para>Suppose, for example, you have a set of recipes that + are used across several projects. + And, within each of those recipes the revision + (its <filename>PR</filename> value) is set accordingly. + In this case, when the revision of those recipes changes + the burden is on you to find all those recipes and + be sure that they get changed to reflect the updated + version of the recipe. + In this scenario, it can get complicated when recipes + used in many places and that provide common functionality + are upgraded to a new revision.</para> + <para>A more efficient way of dealing with this situation is + to set the <filename>INC_PR</filename> variable inside + the <filename>include</filename> files that the recipes + share and then expand the <filename>INC_PR</filename> + variable within the recipes to help + define the recipe revision. + </para> + <para> + The following provides an example that shows how to use + the <filename>INC_PR</filename> variable + given a common <filename>include</filename> file that + defines the variable. + Once the variable is defined in the + <filename>include</filename> file, you can use the + variable to set the <filename>PR</filename> values in + each recipe. + You will notice that when you set a recipe's + <filename>PR</filename> you can provide more granular + revisioning by appending values to the + <filename>INC_PR</filename> variable: + <literallayout class='monospaced'> +recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" +recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" +recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" +recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + </literallayout> + The first line of the example establishes the baseline + revision to be used for all recipes that use the + <filename>include</filename> file. + The remaining lines in the example are from individual + recipes and show how the <filename>PR</filename> value + is set.</para> + </glossdef> + </glossentry> + + <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm> + <glossdef> + <para> + Causes the build to not strip binaries in resulting packages. + </para> + </glossdef> + </glossentry> + + + <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> + <glossdef> + <para> + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + </para> + </glossdef> + </glossentry> + + + <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm> + <glossdef> + <para> + A list of the packages that contain initscripts. + If multiple packages are specified, you need to append the package name + to the other <filename>INITSCRIPT_*</filename> as an override.</para> + <para> + This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. + The variable is optional and defaults to the <filename>PN</filename> variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm> + <glossdef> + <para> + The filename of the initscript (as installed to <filename>${etcdir}/init.d)</filename>. + </para> + <para> + This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. + The variable is Mandatory. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm> + <glossdef> + <para> + Specifies the options to pass to <filename>update-rc.d</filename>. + An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a + runlevel of 99, starts the script in initlevels 2 and 5, and + stops the script in levels 0, 1 and 6. + </para> + <para> + The variable is mandatory and is used in recipes when using + <filename>update-rc.d.bbclass</filename>. + </para> + </glossdef> + </glossentry> + + + </glossdiv> + +<!-- <glossdiv id='var-glossary-j'><title>J</title>--> +<!-- </glossdiv>--> + + <glossdiv id='var-glossary-k'><title>K</title> + + <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm> + <glossdef> + <para> + A regular expression used by the build process to explicitly identify the kernel + branch that is validated, patched and configured during a build. + The <filename>KBRANCH</filename> variable is optional. + You can use it to trigger checks to ensure the exact kernel branch you want is + being used by the build process. + </para> + + <para> + Values for this variable are set in the kernel's recipe file and the kernel's + append file. + For example, if you are using the Yocto Project kernel that is based on the + Linux 3.4 kernel, the kernel recipe file is the + <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file. + Following is the default value for <filename>KBRANCH</filename> and the default + override for the architectures the Yocto Project supports: + <literallayout class='monospaced'> + KBRANCH_DEFAULT = "standard/base" + KBRANCH = "${KBRANCH_DEFAULT}" + </literallayout> + This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git + repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>. + </para> + + <para> + This variable is also used from the kernel's append file to identify the kernel + branch specific to a particular machine or target hardware. + The kernel's append file is located in the BSP layer for a given machine. + For example, the kernel append file for the Crown Bay BSP is in the + <filename>meta-intel</filename> Git repository and is named + <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>. + Here are the related statements from the append file: + <literallayout class='monospaced'> + COMPATIBLE_MACHINE_crownbay = "crownbay" + KMACHINE_crownbay = "crownbay" + KBRANCH_crownbay = "standard/crownbay" + + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" + KMACHINE_crownbay-noemgd = "crownbay" + KBRANCH_crownbay-noemgd = "standard/crownbay" + </literallayout> + The <filename>KBRANCH_*</filename> statements identify the kernel branch to + use when building for the Crown Bay BSP. + In this case there are two identical statements: one for each type of + Crown Bay machine. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm> + <glossdef> + <para>Includes additional metadata from the Yocto Project kernel Git repository. + In the OpenEmbedded build system, the default Board Support Packages (BSPs) + metadata is provided through + the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables. + You can use the <filename>KERNEL_FEATURES</filename> variable to further + add metadata for all BSPs.</para> + <para>The metadata you add through this variable includes config fragments and + features descriptions, + which usually includes patches as well as config fragments. + You typically override the <filename>KERNEL_FEATURES</filename> variable + for a specific machine. + In this way, you can provide validated, but optional, sets of kernel + configurations and features.</para> + <para>For example, the following adds <filename>netfilter</filename> to all + the Yocto Project kernels and adds sound support to the <filename>qemux86</filename> + machine: + <literallayout class='monospaced'> + # Add netfilter to all linux-yocto kernels + KERNEL_FEATURES="features/netfilter" + + # Add sound support to the qemux86 machine + KERNEL_FEATURES_append_qemux86=" cfg/sound" + </literallayout></para> + </glossdef> + </glossentry> + + <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm> + <glossdef> + <para>The type of kernel to build for a device, usually set by the + machine configuration files and defaults to "zImage". + This variable is used + when building the kernel and is passed to <filename>make</filename> as the target to + build.</para> + </glossdef> + </glossentry> + + <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm> + <glossdef> + <para> + The machine as known by the kernel. + Sometimes the machine name used by the kernel does not match the machine name + used by the OpenEmbedded build system. + For example, the machine name that the OpenEmbedded build system understands as + <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel. + The kernel understands that machine as <filename>arm_versatile926ejs</filename>. + For cases like these, the <filename>KMACHINE</filename> variable maps the + kernel machine name to the OpenEmbedded build system machine name. + </para> + + <para> + Kernel machine names are initially defined in the + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in + the <filename>meta</filename> branch. + From the <filename>meta</filename> branch, look in + the <filename>meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</filename> file. + For example, from the <filename>meta</filename> branch in the + <filename>linux-yocto-3.0</filename> kernel, the + <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file + has the following: + <literallayout class='monospaced'> + define KMACHINE cedartrail + define KTYPE standard + define KARCH i386 + + include ktypes/standard + branch cedartrail + + include cedartrail.scc + </literallayout> + You can see that the kernel understands the machine name for the Cedar Trail BSP as + <filename>cedartrail</filename>. + </para> + + <para> + If you look in the Cedar Trail BSP layer in the <filename>meta-intel</filename> source + repository at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>, + you will find the following statements among others: + <literallayout class='monospaced'> + COMPATIBLE_MACHINE_cedartrail = "cedartrail" + KMACHINE_cedartrail = "cedartrail" + KBRANCH_cedartrail = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" + KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" + + COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" + KMACHINE_cedartrail-nopvr = "cedartrail" + KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" + KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" + </literallayout> + The <filename>KMACHINE</filename> statements in the kernel's append file make sure that + the OpenEmbedded build system and the Yocto Linux kernel understand the same machine + names. + </para> + + <para> + This append file uses two <filename>KMACHINE</filename> statements. + The first is not really necessary but does ensure that the machine known to the + OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine + in the kernel also known as <filename>cedartrail</filename>: + <literallayout class='monospaced'> + KMACHINE_cedartrail = "cedartrail" + </literallayout> + </para> + + <para> + The second statement is a good example of why the <filename>KMACHINE</filename> variable + is needed. + In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename> + machine name to refer to the Cedar Trail BSP that does not support the propriatory + PowerVR driver. + The kernel, however, uses the machine name <filename>cedartrail</filename>. + Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to + the kernel's <filename>cedartrail</filename> name: + <literallayout class='monospaced'> + KMACHINE_cedartrail-nopvr = "cedartrail" + </literallayout> + </para> + + <para> + BSPs that ship with the Yocto Project release provide all mappings between the Yocto + Project kernel machine names and the OpenEmbedded machine names. + Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine + name you use is different than that used in the kernel. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-l'><title>L</title> + + <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> + <glossdef> + <para>Lists the layers that this recipe depends upon, separated by spaces. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" + to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case). + An error will be produced if any dependency is missing or + the version numbers do not match exactly (if specified). + This variable is used in the <filename>conf/layer.conf</filename> file + and must be suffixed with the name of the specific layer (e.g. + <filename>LAYERDEPENDS_mylayer</filename>).</para> + </glossdef> + </glossentry> + + <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> + <glossdef> + <para>When used inside the <filename>layer.conf</filename> configuration + file, this variable provides the path of the current layer. + This variable requires immediate expansion + (see the BitBake manual) as lazy expansion can result in + the expansion happening in the wrong directory and therefore + giving the wrong value.</para> + </glossdef> + </glossentry> + + <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> + <glossdef> + <para>Optionally specifies the version of a layer as a single number. + You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to + depend on a specific version of the layer. + This variable is used in the <filename>conf/layer.conf</filename> file + and must be suffixed with the name of the specific layer (e.g. + <filename>LAYERVERSION_mylayer</filename>).</para> + </glossdef> + </glossentry> + + <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm> + <glossdef> + <para>Checksums of the license text in the recipe source code.</para> + <para>This variable tracks changes in license text of the source + code files. + If the license text is changed, it will trigger a build + failure, which gives the developer an opportunity to review any + license change.</para> + <para> + This variable must be defined for all recipes (unless <filename>LICENSE</filename> + is set to "CLOSED")</para> + <para>For more information, see the + <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> + Tracking License Changes</link> section</para> + </glossdef> + </glossentry> + + <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm> + <glossdef> + <para> + The list of source licenses for the recipe. + Follow these rules: + <itemizedlist> + <listitem><para>Do not use spaces within individual + license names.</para></listitem> + <listitem><para>Separate license names using + | (pipe) when there is a choice between licenses. + </para></listitem> + <listitem><para>Separate license names using + & (ampersand) when multiple licenses exist + that cover different parts of the source. + </para></listitem> + <listitem><para>You can use spaces between license + names.</para></listitem> + </itemizedlist> + </para> + + <para> + Here are some examples: + <literallayout class='monospaced'> + LICENSE = "LGPLv2.1 | GPLv3" + LICENSE = "MPL-1 & LGPLv2.1" + LICENSE = "GPLv2+" + </literallayout> + The first example is from the recipes for Qt, which the user + may choose to distribute under either the LGPL version + 2.1 or GPL version 3. + The second example is from Cairo where two licenses cover + different parts of the source code. + The final example is from <filename>sysstat</filename>, + which presents a single license. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm> + <glossdef> + <para>Path to additional licenses used during the build. + By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> + to define the directory that holds common license text used during the build. + The <filename>LICENSE_PATH</filename> variable allows you to extend that + location to other areas that have additional licenses: + <literallayout class='monospaced'> + LICENSE_PATH += "/path/to/additional/common/licenses" + </literallayout></para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-m'><title>M</title> + + <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm> + <glossdef> + <para> + Specifies the target device for which the image is built. + You define <filename>MACHINE</filename> in the + <filename>local.conf</filename> file found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + By default, <filename>MACHINE</filename> is set to + "qemux86", which is an x86-based architecture machine to + be emulated using QEMU: + <literallayout class='monospaced'> + MACHINE ?= "qemux86" + </literallayout> + The variable corresponds to a machine configuration file of the + same name, through which machine-specific configurations are set. + Thus, when <filename>MACHINE</filename> is set to "qemux86" there + exists the corresponding <filename>qemux86.conf</filename> machine + configuration file, which can be found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + in <filename>meta/conf/machine</filename>. + </para> + + <para> + The list of machines supported by the Yocto Project as + shipped include the following: + <literallayout class='monospaced'> + MACHINE ?= "qemuarm" + MACHINE ?= "qemumips" + MACHINE ?= "qemuppc" + MACHINE ?= "qemux86" + MACHINE ?= "qemux86-64" + MACHINE ?= "atom-pc" + MACHINE ?= "beagleboard" + MACHINE ?= "mpc8315e-rdb" + MACHINE ?= "routerstationpro" + </literallayout> + The last four are Yocto Project reference hardware boards, which + are provided in the <filename>meta-yocto-bsp</filename> layer. + <note>Adding additional Board Support Package (BSP) layers + to your configuration adds new possible settings for + <filename>MACHINE</filename>. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm> + <glossdef> + <para></para> + <para> + 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 + packages are essential for the machine to boot. + The impact of this variable affects images based on + <filename>packagegroup-core-boot</filename>, + including the <filename>core-image-minimal</filename> image. + </para> + <para> + This variable is similar to the + <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </para> + <para> + As an example, suppose the machine for which you are building requires + <filename>example-init</filename> to be run during boot to initialize the hardware. + In this case, you would use the following in the machine's + <filename>.conf</filename> configuration file: + <literallayout class='monospaced'> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm> + <glossdef> + <para></para> + <para> + 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 + packages are essential for the machine to boot. + The impact of this variable affects images based on + <filename>packagegroup-core-boot</filename>, + including the <filename>core-image-minimal</filename> image. + </para> + <para> + This variable is similar to the + <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will still build if a package in this list is not found. + Typically, this variable is used to handle essential kernel modules, whose + functionality may be selected to be built into the kernel rather than as a module, + in which case a package will not be produced. + </para> + <para> + Consider an example where you have a custom kernel where a specific touchscreen + driver is required for the machine to be usable. + However, the driver can be built as a module or + into the kernel depending on the kernel configuration. + If the driver is built as a module, you want it to be installed. + But, when the driver is built into the kernel, you still want the + build to succeed. + This variable sets up a "recommends" relationship so that in the latter case, + the build will not fail due to the missing package. + To accomplish this, assuming the package for the module was called + <filename>kernel-module-ab123</filename>, you would use the + following in the machine's <filename>.conf</filename> configuration + file: + <literallayout class='monospaced'> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" + </literallayout> + </para> + <para> + Some examples of these machine essentials are flash, screen, keyboard, mouse, + or touchscreen drivers (depending on the machine). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> + <glossdef> + <para> + A list of machine-specific packages to install as part of the + image being built that are not essential for the machine to boot. + However, the build process for more fully-featured images + depends on the packages being present. + </para> + <para> + This variable affects all images based on + <filename>packagegroup-base</filename>, which does not include the + <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> + images. + </para> + <para> + The variable is similar to the + <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> + variable with the exception that the image being built has a build + dependency on the variable's list of packages. + In other words, the image will not build if a file in this list is not found. + </para> + <para> + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + the WiFi. + The package containing the firmware for the WiFi hardware is always + expected to exist, so it is acceptable for the build process to depend upon + finding the package. + In this case, assuming the package for the firmware was called + <filename>wifidriver-firmware</filename>, you would use the following in the + <filename>.conf</filename> file for the machine: + <literallayout class='monospaced'> + MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm> + <glossdef> + <para></para> + <para> + A list of machine-specific packages to install as part of the + image being built that are not essential for booting the machine. + The image being built has no build dependency on this list of packages. + </para> + <para> + This variable affects only images based on + <filename>packagegroup-base</filename>, which does not include the + <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> + images. + </para> + <para> + This variable is similar to the + <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> + variable with the exception that the image being built does not have a build + dependency on the variable's list of packages. + In other words, the image will build if a file in this list is not found. + </para> + <para> + An example is a machine that has WiFi capability but is not essential + For the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + WiFi. + In this case, the package containing the WiFi kernel module will not be produced + if the WiFi driver is built into the kernel, in which case you still want the + build to succeed instead of failing as a result of the package not being found. + To accomplish this, assuming the package for the module was called + <filename>kernel-module-examplewifi</filename>, you would use the + following in the <filename>.conf</filename> file for the machine: + <literallayout class='monospaced'> + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> + <glossdef> + <para>Specifies the list of hardware features the + <link linkend='var-MACHINE'>MACHINE</link> supports. + For example, including the "bluetooth" feature causes the + <filename>bluez</filename> bluetooth daemon to be built and + added to the image. + It also causes the <filename>connman</filename> recipe + to look at <filename>MACHINE_FEATURES</filename> and when it + finds "bluetooth" there it enables the bluetooth + support in ConnMan. + </para> + + <para> + For a list of features supported by the Yocto Project as shipped, + see the "<link linkend='ref-features-machine'>Machine</link>" section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> + <glossdef> + <para>Features to be added to + <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> + if not also present in + <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. + </para> + + <para> + This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. + 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 + more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm> + <glossdef> + <para>Features from + <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> + 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 + more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm> + <glossdef> + <para>The email address of the distribution maintainer.</para> + </glossdef> + </glossentry> + + <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm> + <glossdef> + <para> + 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. + 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). + <filename>MLPREFIX</filename> gets set when a prefix has been + added to <filename>PN</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> + <glossdef> + <para> + Separates files for different machines such that you can build + for multiple target machines using the same output directories. + See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable + for an example. + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- <glossdiv id='var-glossary-n'><title>N</title>--> +<!-- </glossdiv>--> + + <glossdiv id='var-glossary-o'><title>O</title> + + <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> + <glossdef> + <para> + Controls how the OpenEmbedded build system spawns + interactive terminals on the host development system + (e.g. using the BitBake command with the + <filename>-c devshell</filename> command-line option). + For more information, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section + in the Yocto Project Development Manual. + </para> + + <para> + You can use the following values for the + <filename>OE_TERMINAL</filename> variable: + <literallayout class='monospaced'> + auto + gnome + xfce + rxvt + screen + konsole + none + </literallayout> + <note>Konsole support only works for KDE 3.x. + Also, "auto" is the default behavior for + <filename>OE_TERMINAL</filename></note> + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id='var-glossary-p'><title>P</title> + + <glossentry id='var-P'><glossterm>P</glossterm> + <glossdef> + <para>The recipe name and version. + <filename>P</filename> is comprised of the following: + <literallayout class='monospaced'> + ${PN}-${PV} + </literallayout></para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm> + <glossdef> + <para>The architecture of the resulting package or packages.</para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm> + <glossdef> + <para>Enables easily adding packages to + <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> + before <filename>${PN}</filename> so that the packages can pick + up files that would normally be included in the default package.</para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm> + <glossdef> + <para>This variable, which is set in the <filename>local.conf</filename> configuration + file found in the <filename>conf</filename> folder of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, + specifies the package manager to use when packaging data. + You can provide one or more arguments for the variable with the first + argument being the package manager used to create images: + <literallayout class='monospaced'> + PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" + </literallayout> + For information on build performance effects as a result of the + package manager use, see + <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link> + in this manual. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm> + <glossdef> + <para>Specifies the list of architectures compatible with the device CPU. + This variable is useful when you build for several different devices that use + miscellaneous processors such as XScale and ARM926-EJS).</para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> + <glossdef> + <para> + This variable provides a means of enabling or disabling + features of a recipe on a per-recipe basis. + The <filename>PACKAGECONFIG</filename> + variable itself specifies a space-separated list of the + features to enable. + The features themselves are specified as flags on the + <filename>PACKAGECONFIG</filename> variable. + You can provide up to four arguments, which are separated by + commas, to determine the behavior of each feature + when it is enabled or disabled. + You can omit any argument you like but must retain the + separating commas. + The arguments specify the following: + <orderedlist> + <listitem><para>Extra arguments + that should be added to the configure script argument list + (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) + if the feature is enabled.</para></listitem> + <listitem><para>Extra arguments + that should be added to <filename>EXTRA_OECONF</filename> + if the feature is disabled. + </para></listitem> + <listitem><para>Additional build dependencies + (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>) + that should be added if the feature is enabled. + </para></listitem> + <listitem><para>Additional runtime dependencies + (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) + that should be added if the feature is enabled. + </para></listitem> + </orderedlist> + </para> + + <para> + Consider the following example taken from the + <filename>librsvg</filename> recipe. + In this example the feature is <filename>croco</filename>, which + has three arguments that determine the feature's behavior. + <literallayout class='monospaced'> + PACKAGECONFIG ??= "croco" + PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" + </literallayout> + The <filename>--with-croco</filename> and + <filename>libcroco</filename> arguments apply only if + the feature is enabled. + 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>. + 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 + added to the configure script rather than + <filename>--with-croco</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> + <glossdef> + <para>The list of packages to be created from the recipe. + The default value is the following: + <literallayout class='monospaced'> + ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + </literallayout></para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> + <glossdef> + <para> + A promise that your recipe satisfies runtime dependencies + for optional modules that are found in other recipes. + <filename>PACKAGES_DYNAMIC</filename> + does not actually satisfy the dependencies, it only states that + they should be satisfied. + For example, if a hard, runtime dependency + (<filename>RDEPENDS</filename>) of another package is satisfied + at build time through the <filename>PACKAGES_DYNAMIC</filename> + variable, but a package with the module name is never actually + produced, then the other package will be broken. + Thus, if you attempt to include that package in an image, + you will get a dependency failure from the packaging system + during <filename>do_rootfs</filename>. + Typically, if there is a chance that such a situation can + occur and the package that is not created is valid + without the dependency being satisfied, then you should use + <filename>RRECOMMENDS</filename> (a soft runtime dependency) + instead of <filename>RDEPENDS</filename>. + </para> + + <para> + For an example of how to use the <filename>PACKAGES_DYNAMIC</filename> + variable when you are splitting packages, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section + in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> + <glossdef> + <para>Specifies extra options that are passed to the <filename>make</filename> command during the + compile tasks. + This variable is usually in the form <filename>-j 4</filename>, where the number + represents the maximum number of parallel threads make can run. + If you development host supports multiple cores a good rule of thumb is to set + this variable to twice the number of cores on the host.</para> + </glossdef> + </glossentry> + + <glossentry id='var-PF'><glossterm>PF</glossterm> + <glossdef> + <para>Specifies the recipe or package name and includes all version and revision + numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and + <filename>bash-4.2-r1/</filename>). + This variable is comprised of the following: + <literallayout class='monospaced'> + ${PN}-${EXTENDPE}${PV}-${PR} + </literallayout></para> + </glossdef> + </glossentry> + + <glossentry id='var-PN'><glossterm>PN</glossterm> + <glossdef> + <para>This variable can have two separate functions depending on the context: a recipe + name or a resulting package name.</para> + <para><filename>PN</filename> refers to a recipe name in the context of a file used + by the OpenEmbedded build system as input to create a package. + The name is normally extracted from the recipe file name. + For example, if the recipe is named + <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename> + will be "expat".</para> + <para> + The variable refers to a package name in the context of a file created or produced by the + OpenEmbedded build system.</para> + <para>If applicable, the <filename>PN</filename> variable also contains any special + suffix or prefix. + For example, using <filename>bash</filename> to build packages for the native + machine, <filename>PN</filename> is <filename>bash-native</filename>. + Using <filename>bash</filename> to build packages for the target and for Multilib, + <filename>PN</filename> would be <filename>bash</filename> and + <filename>lib64-bash</filename>, respectively. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PR'><glossterm>PR</glossterm> + <glossdef> + <para>The revision of the recipe. + The default value for this variable is "r0". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PRINC'><glossterm>PRINC</glossterm> + <glossdef> + <para>Causes the <filename>PR</filename> variable of + <filename>.bbappend</filename> files to dynamically increment. + This increment minimizes the impact of layer ordering.</para> + <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist, + <filename>PRINC</filename> should be self referencing. + This variable defaults to 0.</para> + <para>Following is an example that increments <filename>PR</filename> by two: + <literallayout class='monospaced'> + PRINC := "${@int(PRINC) + 2}" + </literallayout> + It is adviseable not to use strings such as ".= '.1'" with the variable because + this usage is very sensitive to layer ordering. + Explicit assignments should be avoided as they cannot adequately represent multiple + <filename>.bbappend</filename> files.</para> + </glossdef> + </glossentry> + + <glossentry id='var-PV'><glossterm>PV</glossterm> + <glossdef> + <para>The version of the recipe. + The version is normally extracted from the recipe filename. + For example, if the recipe is named + <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> + will be "2.0.1". + <filename>PV</filename> is generally not overridden within + a recipe unless it is building an unstable (i.e. development) version from a source code repository + (e.g. Git or Subversion). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PE'><glossterm>PE</glossterm> + <glossdef> + <para> + the epoch of the recipe. + The default value is "0". + The field is used to make upgrades possible when the versioning scheme changes in + some backwards incompatible way. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm> + <glossdef> + <para> + If multiple recipes provide an item, this variable + determines which recipe should be given preference. + The variable must always be suffixed with the name of the + provided item, and should be set to the + <filename>PN</filename> of the recipe + to which you want to give precedence. + Here is an example: + <literallayout class='monospaced'> + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm> + <glossdef> + <para> + If there are multiple versions of recipes available, this + variable determines which recipe should be given preference. + The variable must always be suffixed with the <filename>PN</filename> + for which to select, and should be set to the + <filename>PV</filename> to which you want to give precedence. + You can use the "<filename>%</filename>" character as a wildcard + to match any number of characters, which can be useful when + specifying versions that contain long revision number that could + potentially change. + Here are two examples: + <literallayout class='monospaced'> + PREFERRED_VERSION_python = "2.6.6" + PREFERRED_VERSION_linux-yocto = "3.0+git%" + </literallayout> + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- <glossdiv id='var-glossary-q'><title>Q</title>--> +<!-- </glossdiv>--> + + <glossdiv id='var-glossary-r'><title>R</title> + + <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm> + <glossdef> + <para>The list of packages that conflict with a package. + Note that the package will not be installed if the conflicting packages are not + first removed.</para> + <para> + Like all package-controlling variables, you must always use them in + conjunction with a package name override. + Here is an example: + <literallayout class='monospaced'> + RCONFLICTS_${PN} = "another-conflicting-package-name" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> + <glossdef> + <para> + Lists a package's run-time dependencies (i.e. other packages) + that must be installed for the package to be built. + In other words, in order for the package to be built and + run correctly, it depends on the listed packages. + If a package in this list cannot be found, it is probable + that a dependency error would occur before the build. + </para> + + <para> + The names of the variables you list with + <filename>RDEPENDS</filename> must be the names of other + packages as listed in the + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + variable. + You should not list recipe names (<filename>PN</filename>). + </para> + + <para> + Because the <filename>RDEPENDS</filename> variable applies + to packages being built, you should + always attach a package name to the variable to specify the + particular run-time package that has the dependency. + For example, suppose you are building a development package + that depends on the <filename>perl</filename> package. + In this case, you would use the following + <filename>RDEPENDS</filename> statement: + <literallayout class='monospaced'> + RDEPENDS_${PN}-dev += "perl" + </literallayout> + In the example, the package name + (<filename>${PN}-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 like <filename>debian.bbclass</filename>. + </para> + + <para> + In many cases you do not need to explicitly add dependencies + to <filename>RDEPENDS</filename> since some automatic + handling occurs: + <itemizedlist> + <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If + a run-time package contains a shared library + (<filename>.so</filename>), the build + processes the library in order to determine other + libraries to which it is dynamically linked. + The build process adds these libraries to + <filename>RDEPENDS</filename> when creating the run-time + package.</para></listitem> + <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If + the package ships a <filename>pkg-config</filename> + information file, the build process uses this file + to add items to the <filename>RDEPENDS</filename> + variable to create the run-time packages. + </para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> + <glossdef> + <para> + A list of packages that extend the usability of a package being + built. + The package being built does not depend on this list of packages in + order to successfully build, but needs them for the extended usability. + To specify runtime dependencies for packages, see the + <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable. + </para> + <para> + The OpenEmbedded build process automatically installs the list of packages + as part of the built package. + However, you can remove them later if you want. + If, during the build, a package from the list cannot be found, the build + process continues without an error. + </para> + <para> + Because the <filename>RRECOMMENDS</filename> variable applies to packages + being built, you should + always attach an override to the variable to specify the particular package + whose usability is being extended. + For example, suppose you are building a development package that is extended + to support wireless functionality. + In this case, you would use the following: + <literallayout class='monospaced'> + RRECOMMENDS_${PN}-dev += "<wireless_package_name>" + </literallayout> + In the example, the package name (<filename>${PN}-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 like <filename>debian.bbclass</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm> + <glossdef> + <para>The list of packages that are replaced with this package.</para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-s'><title>S</title> + + <glossentry id='var-S'><glossterm>S</glossterm> + <glossdef> + <para> + The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + where unpacked package source code resides. + This location is within the working directory + (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which + is not static. + The unpacked source location depends on the package name + (<filename><link linkend='var-PN'>PN</link></filename>) and + package version (<filename><link linkend='var-PV'>PV</link></filename>) as + follows: + <literallayout class='monospaced'> + ${WORKDIR}/${PN}/${PV} + </literallayout> + As an example, assume a + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level + folder named <filename>poky</filename> + and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + at <filename>poky/build</filename>. + In this case, the working directory the build system uses to build + the <filename>db</filename> package is the following: + <literallayout class='monospaced'> + ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm> + <glossdef> + <para>Equivalent to + <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>. + However, this variable applies to the SDK generated from an image using + <filename>bitbake -c populate_sdk imagename</filename>). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SECTION'><glossterm>SECTION</glossterm> + <glossdef> + <para>The section in which packages should be categorized. + Package management utilities can make use of this variable.</para> + </glossdef> + </glossentry> + + <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm> + <glossdef> + <para> + The variable takes the value of + <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename> + unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1". + In this case the value of + <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used. + </para> + </glossdef> + </glossentry> + + + <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm> + <glossdef> + <para>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 and after booting occurs <filename>getty</filename> is started on that port + so remote login is possible.</para> + </glossdef> + </glossentry> + + <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm> + <glossdef> + <para> + Specifies the endian byte order of the target system. + The value should be either "le" for little-endian or "be" for big-endian. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm> + <glossdef> + <para> + Specifies the number of bits for the target system CPU. + The value should be either "32" or "64". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm> + <glossdef> + <para> + A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the + OpenEmbedded build system to create variants of recipes or packages. + The list specifies the prefixes to strip off during certain circumstances + such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm> + <glossdef> + <para>The list of source files - local or remote. + This variable tells the OpenEmbedded build system which bits to pull + in for the build and how to pull them in. + For example, if the recipe only needs to fetch a tarball from the + internet, the recipe uses a single <filename>SRC_URI</filename> entry. + On the other hand, if the recipe needs to fetch a tarball, apply + two patches, and include a custom file, the recipe would include four + instances of the variable.</para> + <para>The following list explains the available URI protocols: + <itemizedlist> + <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually + a file shipped with the metadata, from the local machine. + The path is relative to the + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> + variable. + Thus, the build system searches, in order, from the following directories, + which are assumed to be a subdirectories of the directory in which the + recipe file resides: + <itemizedlist> + <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name + with any special suffix or prefix, if applicable. + For example, using <filename>bash</filename> to build for the native + machine, <filename>PN</filename> is <filename>bash-native</filename>. + Using <filename>bash</filename> to build for the target and for Multilib, + <filename>PN</filename> would be <filename>bash</filename> and + <filename>lib64-bash</filename>, respectively. + </para></listitem> + <listitem><para><emphasis><filename>${PF}</filename> - </emphasis> + <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>. + The recipe name including all version and revision numbers + (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and + <filename>bash-4.2-r1/</filename>).</para></listitem> + <listitem><para><emphasis><filename>${P}</filename> -</emphasis> + <filename>${PN}-${PV}</filename>. + The recipe name and version (i.e. <filename>bash-4.2</filename>). + </para></listitem> + <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The + base recipe name without any special suffix or version numbers. + </para></listitem> + <listitem><para><emphasis><filename>${BP}</filename> -</emphasis> + <filename>${BPN}-${PV}</filename>. + The base recipe name and version but without any special + package name suffix.</para></listitem> + <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe + resides.</para></listitem> + <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe + resides.</para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a + Bazaar revision control repository.</para></listitem> + <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a + Git revision control repository.</para></listitem> + <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from + an OSC (OpenSuse Build service) revision control repository.</para></listitem> + <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from + a repo (Git) repository.</para></listitem> + <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from + an SVK revision control repository.</para></listitem> + <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from + the Internet using <filename>http</filename>.</para></listitem> + <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files + from the Internet using <filename>https</filename>.</para></listitem> + <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files + from the Internet using <filename>ftp</filename>.</para></listitem> + <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from + a CVS revision control repository.</para></listitem> + <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from + a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> + <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from + a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> + <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from + a secure shell.</para></listitem> + <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from + a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> + </itemizedlist> + </para> + <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist. + Here are standard options: + <itemizedlist> + <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply + the patch or not. + The default action is to apply the patch.</para></listitem> + <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which + striplevel to use when applying the patch. + The default level is 1.</para></listitem> + </itemizedlist> + </para> + <para>Here are options specific to recipes building code from a revision control system: + <itemizedlist> + <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies + the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> + is equal to or greater than <filename>mindate</filename>.</para></listitem> + <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies + the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> + is not later than <filename>mindate</filename>.</para></listitem> + <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies + the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + is equal to or greater than <filename>minrev</filename>.</para></listitem> + <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies + the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + is not later than <filename>maxrev</filename>.</para></listitem> + <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the + patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + is equal to <filename>rev</filename>.</para></listitem> + <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies + the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + is not equal to <filename>rev</filename>.</para></listitem> + </itemizedlist> + </para> + <para>Here are some additional options worth mentioning: + <itemizedlist> + <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls + whether or not to unpack the file if it is an archive. + The default action is to upack the file.</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>. + This option is useful for unusual tarballs or other archives that + don't have their files already in a subdirectory within the archive. + </para></listitem> + <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a + name to be used for association with <filename>SRC_URI</filename> checksums + when you have more than one file specified in <filename>SRC_URI</filename>. + </para></listitem> + <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies + the filename used when storing the downloaded file.</para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm> + <glossdef> + <para></para> + <para> + By default, the OpenEmbedded build system automatically detects whether + <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> + contains files that are machine-specific. + If so, the build system automatically changes + <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>. + Setting this variable to "0" disables this behavior. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm> + <glossdef> + <para> + The date of the source code used to build the package. + This variable applies only if the source was fetched from a Source Code Manager (SCM). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm> + <glossdef> + <para> + The revision of the source code used to build the package. + This variable applies to Subversion, Git, Mercurial and Bazaar + only. + Note that if you wish to build a fixed revision and you wish + to avoid performing a query on the remote repository every time + BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a + full revision identifier and not just a tag. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm> + <glossdef> + <para>The directory for the shared state.</para> + </glossdef> + </glossentry> + + <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm> + <glossdef> + <para> + Configures the OpenEmbedded build system to search other + mirror locations for prebuilt cache data objects before + building out the data. + This variable works like fetcher + <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename> + and points to the cache locations to check for the shared + objects. + </para> + + <para> + You can specify a filesystem directory or a remote URL such + as HTTP or FTP. + The locations you specify need to contain the shared state + cache (sstate-cache) results from previous builds. + The sstate-cache you point to can also be from builds on + other machines. + </para> + + <para> + If a mirror uses the same structure as + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, + you need to add + "PATH" at the end as shown in the examples below. + The build system substitues the correct path within the + directory structure. + <literallayout class='monospaced'> + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm> + <glossdef> + <para> + The directory with kernel headers that are required to build out-of-tree + modules. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-STAMP'><glossterm>STAMP</glossterm> + <glossdef> + <para> + Specifies the base path used to create recipe stamp files. + The path to an actual stamp file is constructed by evaluating this + string and then appending additional information. + Currently, the default assignment for <filename>STAMP</filename> + as set in the <filename>meta/conf/bitbake.conf</filename> file + is: + <literallayout class='monospaced'> + STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" + </literallayout> + See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, + <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, + <link linkend='var-PN'><filename>PN</filename></link>, + <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>, + <link linkend='var-PV'><filename>PV</filename></link>, and + <link linkend='var-PR'><filename>PR</filename></link> for related variable + information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> + <glossdef> + <para>The short (72 characters or less) summary of the binary package for packaging + 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> + variable if <filename>DESCRIPTION</filename> is not set + in the recipe. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-t'><title>T</title> + + <glossentry id='var-T'><glossterm>T</glossterm> + <glossdef> + <para>This variable points to a directory were Bitbake places temporary + files when building a particular package. + It is typically set as follows: + <literallayout class='monospaced'> + T = ${WORKDIR}/temp + </literallayout> + The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + is the directory into which Bitbake unpacks and builds the package. + The default <filename>bitbake.conf</filename> file sets this variable.</para> + <para>The <filename>T</filename> variable is not to be confused with + the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable, + which points to the root of the directory tree where Bitbake + places the output of an entire build. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm> + <glossdef> + <para>The architecture of the device being built. + While a number of values are possible, the OpenEmbedded build system primarily supports + <filename>arm</filename> and <filename>i586</filename>.</para> + </glossdef> + </glossentry> + + <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm> + <glossdef> + <para> + Flags passed to the C compiler for the target system. + This variable evaluates to the same as + <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>. + </para> + </glossdef> + </glossentry> + + + <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm> + <glossdef> + <para>Specifies the method for handling FPU code. + For FPU-less targets, which include most ARM CPUs, the variable must be + set to "soft". + If not, the kernel emulation gets used, which results in a performance penalty.</para> + </glossdef> + </glossentry> + + <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> + <glossdef> + <para>Specifies the target's operating system. + The variable can be set to "linux" for <filename>eglibc</filename>-based systems and + to "linux-uclibc" for <filename>uclibc</filename>. + For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-uclibc-gnueabi" values possible.</para> + </glossdef> + </glossentry> + + <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm> + <glossdef> + <para> + Specifies which variant of the GNU standard C library (<filename>libc</filename>) + to use during the build process. + This variable replaces <filename>POKYLIBC</filename>, which is no longer + supported. + </para> + <para> + You can select <filename>eglibc</filename> or <filename>uclibc</filename>. + <note> + This release of the Yocto Project does not support the + <filename>glibc</filename> implementation of <filename>libc</filename>. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm> + <glossdef> + <para> + The toolchain selector. + This variable replaces <filename>POKYMODE</filename>, which is no longer + supported. + </para> + <para> + The <filename>TCMODE</filename> variable selects the external toolchain + built using the OpenEmbedded build system or a few supported combinations of + the upstream GCC or CodeSourcery Labs toolchain. + The variable identifies the <filename>tcmode-*</filename> files used in + the <filename>meta/conf/distro/include</filename> directory, which is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para> + <para> + By default, <filename>TCMODE</filename> is set to "default", which + chooses the <filename>tcmode-default.inc</filename> file. + The variable is similar to + <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls + the variant of the GNU standard C library (<filename>libc</filename>) + used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm> + <glossdef> + <para> + This variable is the temporary directory the OpenEmbedded build system + uses when it does its work building images. + By default, the <filename>TMPDIR</filename> variable is named + <filename>tmp</filename> within the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + </para> + + <para> + If you want to establish this directory in a location other than the + default, you can uncomment the following statement in the + <filename>conf/local.conf</filename> file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: + <literallayout class='monospaced'> + #TMPDIR = "${TOPDIR}/tmp" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> + <glossdef> + <para> + This variable is the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + BitBake automatically sets this variable. + The OpenEmbedded build system uses the Build Directory when building images. + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- <glossdiv id='var-glossary-u'><title>U</title>--> +<!-- </glossdiv>--> + +<!-- <glossdiv id='var-glossary-v'><title>V</title>--> +<!-- </glossdiv>--> + + <glossdiv id='var-glossary-w'><title>W</title> + + <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm> + <glossdef> + <para> + The pathname of the working directory in which the OpenEmbedded build system + builds a recipe. + This directory is located within the + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes + as different packages are built. + </para> + + <para> + The actual <filename>WORKDIR</filename> directory depends on several things: + <itemizedlist> + <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem> + <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem> + <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem> + <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem> + <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem> + <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem> + <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem> + </itemizedlist> + </para> + + <para> + For packages that are not dependent on a particular machine, + <filename>WORKDIR</filename> is defined as follows: + <literallayout class='monospaced'> + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR} + </literallayout> + As an example, assume a + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level + folder name <filename>poky</filename> and a default + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + at <filename>poky/build</filename>. + In this case, the working directory the build system uses to build + the <filename>v86d</filename> package is the following: + <literallayout class='monospaced'> + ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0 + </literallayout> + </para> + + <para> + For packages that are dependent on a particular machine, <filename>WORKDIR</filename> + is defined slightly different: + <literallayout class='monospaced'> + ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR} + </literallayout> + As an example, again assume a Source Directory top-level folder + named <filename>poky</filename> and a default Build Directory + at <filename>poky/build</filename>. + In this case, the working directory the build system uses to build + the <filename>acl</filename> recipe, which is being built for a + MIPS-based device, is the following: + <literallayout class='monospaced'> + ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2 + </literallayout> + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- <glossdiv id='var-glossary-x'><title>X</title>--> +<!-- </glossdiv>--> + +<!-- <glossdiv id='var-glossary-y'><title>Y</title>--> +<!-- </glossdiv>--> + +<!-- <glossdiv id='var-glossary-z'><title>Z</title>--> +<!-- </glossdiv>--> + +</glossary> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml new file mode 100644 index 0000000000..ae8f75c2f5 --- /dev/null +++ b/documentation/ref-manual/ref-varlocality.xml @@ -0,0 +1,193 @@ +<!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-varlocality'> + <title>Variable Context</title> + + <para> + While most variables can be used in almost any context such as + <filename>.conf</filename>, <filename>.bbclass</filename>, + <filename>.inc</filename>, and <filename>.bb</filename> files, + some variables are often associated with a particular locality or context. + This chapter describes some common associations. + </para> + + <section id='ref-varlocality-configuration'> + <title>Configuration</title> + + <para> + The following subsections provide lists of variables whose context is + configuration: distribution, machine, and local. + </para> + + <section id='ref-varlocality-config-distro'> + <title>Distribution (Distro)</title> + + <para> + This section lists variables whose context is the distribution, or distro. + <itemizedlist> + <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename></para></listitem> + <listitem><para><filename><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-MAINTAINER'>MAINTAINER</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-TARGET_OS'>TARGET_OS</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-TARGET_FPU'>TARGET_FPU</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-TCMODE'>TCMODE</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-TCLIBC'>TCLIBC</link></filename> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-varlocality-config-machine'> + <title>Machine</title> + + <para> + This section lists variables whose context is the machine. + <itemizedlist> + <listitem><para><filename><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS + </link></filename></para></listitem> + <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS + </link></filename></para></listitem> + <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS + </link></filename></para></listitem> + <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename></para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-varlocality-config-local'> + <title>Local</title> + + <para> + This section lists variables whose context is the local configuration through the + <filename>local.conf</filename> file. + <itemizedlist> + <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-MACHINE'>MACHINE</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-BBFILES'>BBFILES</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES + </link></filename></para></listitem> + <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'> + ENABLE_BINARY_LOCALE_GENERATION</link></filename></para></listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id='ref-varlocality-recipes'> + <title>Recipes</title> + + <para> + The following subsections provide lists of variables whose context is + recipes: required, dependencies, path, and extra build information. + </para> + + <section id='ref-varlocality-recipe-required'> + <title>Required</title> + + <para> + This section lists variables that are required for recipes. + <itemizedlist> + <listitem><para><filename><link linkend='var-LICENSE'>LICENSE</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> - used + in recipes that fetch local or remote files. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-varlocality-recipe-dependencies'> + <title>Dependencies</title> + + <para> + This section lists variables that define recipe dependencies. + <itemizedlist> + <listitem><para><filename><link linkend='var-DEPENDS'>DEPENDS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-RDEPENDS'>RDEPENDS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-RREPLACES'>RREPLACES</link> + </filename></para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-varlocality-recipe-paths'> + <title>Paths</title> + + <para> + This section lists variables that define recipe paths. + <itemizedlist> + <listitem><para><filename><link linkend='var-WORKDIR'>WORKDIR</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-S'>S</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-FILES'>FILES</link> + </filename></para></listitem> + </itemizedlist> + </para> + </section> + + <section id='ref-varlocality-recipe-build'> + <title>Extra Build Information</title> + + <para> + This section lists variables that define extra build information for recipes. + <itemizedlist> + <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link> + </filename></para></listitem> + <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> + </para></listitem> + <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE + </link></filename></para></listitem> + </itemizedlist> + </para> + </section> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 spell spelllang=en_gb +--> diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml new file mode 100644 index 0000000000..a6916064f6 --- /dev/null +++ b/documentation/ref-manual/resources.xml @@ -0,0 +1,114 @@ +<!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='resources'> +<title>Contributing to the Yocto Project</title> + +<section id='resources-intro'> + <title>Introduction</title> + <para> + The Yocto Project team is happy for people to experiment with the Yocto Project. + A number of places exist to find help if you run into difficulties or find bugs. + To find out how to download source code, + see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>" + list item in the Yocto Project Development Manual. + </para> +</section> + +<section id='resources-bugtracker'> + <title>Tracking Bugs</title> + + <para> + If you find problems with the Yocto Project, you should report them using the + Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>. + </para> +</section> + +<section id='resources-mailinglist'> + <title>Mailing lists</title> + + <para> + There are a number of mailing lists maintained by the Yocto Project as well as + related OpenEmbedded mailing lists for discussion, patch submission and announcements. + To subscribe to one of the following mailing lists, click on the appropriate URL + in the following list and follow the instructions: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> - + General Yocto Project discussion mailing list. </para></listitem> + <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> - + Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem> + <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> - + Discussion mailing list about OpenEmbedded.</para></listitem> + <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> - + Discussion mailing list about the BitBake build tool.</para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> - + Discussion mailing list about Poky.</para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> - + Mailing list to receive official Yocto Project release and milestone + announcements.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='resources-irc'> + <title>Internet Relay Chat (IRC)</title> + + <para> + Two IRC channels on freenode are available for the Yocto Project and Poky discussions: + <itemizedlist> + <listitem><para><filename>#yocto</filename></para></listitem> + <listitem><para><filename>#poky</filename></para></listitem> + </itemizedlist> + </para> +</section> + +<section id='resources-links'> + <title>Links</title> + + <para> + Following is a list of resources you will find helpful: + <itemizedlist> + <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>: + </emphasis> The home site for the Yocto Project.</para></listitem> +<!-- <listitem><para><emphasis><ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis> + The company where the Yocto Project build system Poky was first developed. + OpenedHand has since been acquired by Intel Corporation.</para></listitem> --> + <listitem><para><emphasis><ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> + The company who acquired OpenedHand in 2008 and began development on the + Yocto Project.</para></listitem> + <listitem><para><emphasis><ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> + The upstream, generic, embedded distribution used as the basis for the build system in the + Yocto Project. + Poky derives from and contributes back to the OpenEmbedded project.</para></listitem> + <listitem><para><emphasis><ulink url='http://developer.berlios.de/projects/bitbake/'> + BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem> + <listitem><para><emphasis>BitBake User Manual:</emphasis> + A comprehensive guide to the BitBake tool. + You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename> + directory, which is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para></listitem> + <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>: + </emphasis> An open source machine emulator and virtualizer.</para></listitem> + </itemizedlist> + </para> +</section> + +<section id='resources-contributions'> + <title>Contributions</title> + + <para> + The Yocto Project gladly accepts contributions. + You can submit changes to the project either by creating and sending pull requests, + or by submitting patches through email. + For information on how to do both, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml new file mode 100644 index 0000000000..b1d7c40799 --- /dev/null +++ b/documentation/ref-manual/technical-details.xml @@ -0,0 +1,1011 @@ +<!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 and shared state (sstate) cache. + </para> + +<section id='usingpoky-components'> + <title>Yocto Project Components</title> + + <para> + The BitBake task executor together with various types of configuration files form the + OpenEmbedded Core. + This section overviews the BitBake task executor and the + configuration files by describing what they are used for 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> An abstraction of 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, etc. + Configuration data acts as the glue to bind everything together.</para></listitem> + </itemizedlist> + For more information on data, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-terms'>Yocto Project Terms</ulink>" + section in the Yocto Project Development Manual. + </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 Manual. + </para> + + <para> + Following are some brief details on these core components. + For more detailed information on these components see the + "<link linkend='ref-structure'>Directory Structure</link>" chapter. + </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 metadata, generating a list of tasks from it, + and then executing those tasks. + To see a list of the options BitBake supports, use the following help command: + <literallayout class='monospaced'> + $ bitbake --help + </literallayout> + </para> + + <para> + The most common usage for BitBake is <filename>bitbake <packagename></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 <filename>.bb</filename> filename. + So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> 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 + "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section. + </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>eglibc</filename> if they had not already + been built. + <note>This release of the Yocto Project does not support the <filename>glibc</filename> + GNU version of the Unix standard C library. By default, the OpenEmbedded build system + builds with <filename>eglibc</filename>.</note> + </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 much + 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> + The <filename>.bb</filename> files are usually referred to as "recipes." + In general, a recipe contains information about a single piece of software. + The information includes the location from which to download the source patches + (if any are 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" can also be used to describe recipes. + However, since the same word 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='usingpoky-components-classes'> + <title>Classes</title> + + <para> + Class files (<filename>.bbclass</filename>) contain information that is useful to share + between metadata files. + An example is the Autotools class, which contains + common settings for any application that Autotools uses. + The "<link linkend='ref-classes'>Classes</link>" chapter provides details + about common 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 (<filename>local.conf</filename>, which is found + in the <ulink url='build-directory'>Build Directory</ulink>). + </para> + </section> +</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 don't 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 don't necessarily need 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>What pieces of the system have changed and what pieces have not changed?</listitem> + <listitem>How are changed pieces of software removed and replaced?</listitem> + <listitem>How are pre-built components that don't need to be rebuilt from scratch + used when they are available?</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> + + <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 + uses a per-task basis and does not use 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, <filename>do_install</filename> and <filename>do_package</filename> + output 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 situation. + 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 working directory changes because it should not + affect the output for target packages. + Also, the build process has the objective of making native/cross packages relocatable. + The checksum therefore needs to exclude <filename>WORKDIR</filename>. + The simplistic approach for excluding the working 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 <filename>PACKAGE_ARCHS</filename> variable does not + depend on the value of <filename>MACHINE</filename>, 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 inline 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 Build Directory. + 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 statements effectively result 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" + BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" + BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" + BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" + </literallayout> + The previous example actually excludes + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + since it 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 <filename>OE-Core</filename> + 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. + <filename>OE-Core</filename> uses the "OEBasic" signature handler by default + through this setting in the <filename>bitbake.conf</filename> file: + <literallayout class='monospaced'> + BB_SIGNATURE_HANDLER ?= "OEBasic" + </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 metadata 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. + Currently, this behavior is not the default behavior for <filename>OE-Core</filename> + but is the default in <filename>poky</filename>. + </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: + <literallayout class='monospaced'> + BB_BASEHASH_task-<taskname> - the base hashes for each task in the recipe + BB_BASEHASH_<filename:taskname> - the base hashes for each dependent task + BBHASHDEPS_<filename:taskname> - The task dependencies for each task + BB_TASKHASH - the hash of the currently running task + </literallayout> + </para> + </section> + + <section id='shared-state'> + <title>Shared State</title> + + <para> + Checksums and dependencies, as discussed in the previous section, solve half the + problem. + 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 shared state class (<filename>sstate.bbclass</filename>) + 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 doesn't need to worry about its source. + </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 <filename>do_install</filename> or + <filename>do_package</filename>. + 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.bbclass</filename>. + From a user's perspective, adding shared state wrapping to a task + is as simple as this <filename>do_deploy</filename> example taken from + <filename>do_deploy.bbclass</filename>: + <literallayout class='monospaced'> + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-name] = "deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + </literallayout> + In the 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 \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 uses 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 <filename>do_package_write_ipk</filename> 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> + When things go wrong, debugging needs to be straightforward. + Because of this, the Yocto Project team included strong debugging + tools: + <itemizedlist> + <listitem><para>Whenever a shared state package is written out, so is a + corresponding <filename>.siginfo</filename> file. + This practice results in a pickled python database of all + the metadata that went into creating the hash for a given shared state + package.</para></listitem> + <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename> + (or <filename>-S</filename>) option, BitBake dumps out + <filename>.siginfo</filename> files in + the stamp directory for every task it would have executed instead of + building the specified target package.</para></listitem> + <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that + can process these <filename>.siginfo</filename> files. + If one file is specified, it will dump out the dependency + information in the file. + If two files are specified, it will compare the two files and dump out + the differences between the two. + This allows the question of "What changed between X and Y?" to be + answered easily.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='invalidating-shared-state'> + <title>Invalidating Shared State</title> + + <para> + The shared state code uses checksums and shared state + cache to avoid unnecessarily rebuilding tasks. + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes that are not factored + into the checksum calculation, but do affect a task's output. + A good example is perhaps when a tool changes its output. + Let's say that the output of <filename>rpmdeps</filename> needed to change. + The result of the change should be that all the "package", "package_write_rpm", + and "package_deploy-rpm" shared state cache items would become invalid. + But, because this is a change that is external to the code and therefore implicit, + the associated shared state cache items do not become invalidated. + In this case, the build process would use 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 + change you make. + Note that any changes you make directly to a function automatically are factored into + the checksum calculation and thus, will invalidate the associated area of sstate cache. + 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. + Once you are aware of such a change, you can take steps to invalidate the cache + and force the task to run. + The step to take is 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 <filename>do_package</filename> or the comments of one of the functions it calls. + The change is purely cosmetic, but it causes the checksum to be recalculated and + forces the task to be run again. + </para> + + <note> + For an example of a commit that makes a cosmetic change to invalidate + a 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='x32'> + <title>x32</title> + + <para> + x32 is a new 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> + While the x32 psABI specifications are not fully finalized, this Yocto Project + release supports current development specifications of x32 psABI. + As of this release of the Yocto Project, x32 psABI support 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 use the x32 psABI support through the <filename>meta-x32</filename> + layer on top of the OE-core/Yocto layer.</para></listitem> + <listitem><para>The toolchain from the <filename>experimental/meta-x32</filename> layer + is used for building x32 psABI program binaries.</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='future-development-and-limitations'> + <title>Future Development and Limitations</title> + + <para> + As of this Yocto Project release, the x32 psABI kernel and library interfaces + specifications are not finalized. + </para> + + <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> + <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from + <filename>experimental/meta-x32</filename> into OE-core.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='using-x32-right-now'> + <title>Using x32 Right Now</title> + + <para> + Despite the fact the x32 psABI support is in development state for this release of the + Yocto Project, you can follow these steps to use the x32 spABI: + <itemizedlist> + <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + You can find the <filename>experimental/meta-x32</filename> source repository at + <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem> + <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes + the <filename>meta-x32</filename>. + Here is an example: + <literallayout class='monospaced'> + BBLAYERS ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + /home/nitin/prj/poky.git/meta-yocto-bsp \ + /home/nitin/prj/meta-x32.git \ + " + BBLAYERS_NON_REMOVABLE ?= " \ + /home/nitin/prj/poky.git/meta \ + /home/nitin/prj/poky.git/meta-yocto \ + " + </literallayout></para></listitem> + <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 = "atom-pc" + #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'> + $ bitake 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="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 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> + </para> + + <para> + The build system uses the + <filename><link linkend='var-S'>S</link></filename> variable as the + default directory used when searching files listed in + <filename>LIC_FILES_CHKSUM</filename>. + The previous example employs the default directory. + </para> + + <para> + You can also use relative paths as shown in the following example: + <literallayout class='monospaced'> + LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + </literallayout> + </para> + + <para> + In this example, the first line locates a file in + <filename>${S}/src/ls.c</filename>. + The second line refers to a file in + <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent + of <filename><link linkend='var-S'>S</link></filename>. + </para> + <para> + Note that this 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 <filename>LICENSE_FLAGS</filename> variable + definition in the affected recipe. + For instance, the + <filename>$HOME/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 + <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable + typically defined in your <filename>local.conf</filename> file. + For example, to enable + the <filename>$HOME/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> + The definition of 'matching' in reference to a + recipe's <filename>LICENSE_FLAGS</filename> setting is simple. + However, some things exist that you should know about in order to + correctly and effectively use it. + </para> + + <para> + Before a flag + defined by a particular recipe is tested against the + contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the + string <filename>_${PN}</filename> (with + <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is + appended to the flag, thus automatically making each + <filename>LICENSE_FLAGS</filename> value recipe-specific. + That string is + then matched against the whitelist. + So if you specify <filename>LICENSE_FLAGS = "commercial"</filename> in recipe + "foo" for example, the string <filename>"commercial_foo"</filename> + would normally be what is specified in the whitelist in order for it to + match. + </para> + + <para> + You can broaden the match by + putting any "_"-separated beginning subset of a + <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also + match. + For example, simply specifying "commercial" in + the whitelist would match any expanded <filename>LICENSE_FLAGS</filename> + definition starting with "commercial" such as + "commercial_foo" and "commercial_bar", which are the + strings that would be automatically generated for + hypothetical "foo" and "bar" recipes assuming those + recipes had simply specified the following: + <literallayout class='monospaced'> + LICENSE_FLAGS = "commercial" + </literallayout> + </para> + + <para> + Broadening the match allows for a range of specificity for the items + in the whitelist, from more general to perfectly + specific. + So you have the choice of exhaustively + enumerating each license flag in the whitelist to + allow only those specific recipes into the image, or + of using a more general string to pick up anything + matching just the first component or components of the specified + string. + </para> + + <para> + This scheme works even if the flag already + has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is + redundant, but does not affect the outcome. + For example, a license flag of "commercial_1.2_foo" would + turn into "commercial_1.2_foo_foo" and would match + both the general "commercial" and the specific + "commercial_1.2_foo", as expected. + The flag would also match + "commercial_1.2_foo_foo" and "commercial_1.2", which + does not make much sense regarding use in the whitelist. + </para> + + <para> + For a versioned string, you could instead specify + "commercial_foo_1.2", which would turn into + "commercial_foo_1.2_foo". + And, as expected, this flag allows + you to pick up this package along with + anything else "commercial" when you specify "commercial" + in the whitelist. + Or, the flag allows you to pick up this package along with anything "commercial_foo" + regardless of version when you use "commercial_foo" in the whitelist. + Finally, you can be completely specific about the package and version and specify + "commercial_foo_1.2" package and version. + </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>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file: + <literallayout class='monospaced'> + COMMERCIAL_AUDIO_PLUGINS ?= "" + COMMERCIAL_VIDEO_PLUGINS ?= "" + COMMERCIAL_QT = "" + </literallayout> + If you want to enable these components, you can do so by making sure you have + the following statements 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" + COMMERCIAL_QT ?= "qmmp" + 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 + or commercial qt components as part of + the <filename>COMMERCIAL_QT</filename> statement (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/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml new file mode 100644 index 0000000000..149490969a --- /dev/null +++ b/documentation/ref-manual/usingpoky.xml @@ -0,0 +1,651 @@ +<!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;#building-image'>Building an Image</ulink>" + section of the Yocto Project Quick Start. + </para> + + <section id='build-overview'> + <title>Build Overview</title> + + <para> + The first thing you need to do is set up the OpenEmbedded build environment by sourcing + the <link linkend='structure-core-script'>environment setup script</link> as follows: + <literallayout class='monospaced'> + $ source &OE_INIT_FILE; [build_dir] + </literallayout> + </para> + + <para> + The <filename>build_dir</filename> is optional and specifies the directory the + OpenEmbedded build system uses for the build - + the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + If you do not specify a Build Directory it defaults to <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. + See <link linkend="structure-core-script">&OE_INIT_FILE;</link> + for more information on this script. + </para> + + <para> + Once the build environment is set up, you can build a target using: + <literallayout class='monospaced'> + $ bitbake <target> + </literallayout> + </para> + + <para> + The <filename>target</filename> 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 + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + Or, the target can be the name of a recipe for a specific piece of software such as + <application>busybox</application>. + 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) components + is only supported for 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 + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> 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_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" + section in the Yocto Project Quick Start. + For information about how to install these images, see the documentation for your + particular board/machine. + </para> +</section> + +<section id='usingpoky-debugging'> + <title>Debugging Build Failures</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> + + <section id='usingpoky-debugging-taskfailures'> + <title>Task Failures</title> + + <para>The log file for shell tasks is available in + <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. + For example, the <filename>compile</filename> task for the QEMU minimal image for the x86 + machine (<filename>qemux86</filename>) might be + <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>. + To see what BitBake runs to generate that log, look at the corresponding + <filename>run.do_taskname.pid</filename> file located in the same directory. + </para> + + <para> + Presently, the output from Python tasks is sent directly to the console. + </para> + </section> + + <section id='usingpoky-debugging-taskrunning'> + <title>Running Specific Tasks</title> + + <para> + Any given package consists of a set of tasks. + The standard BitBake behavior in most cases is: <filename>fetch</filename>, + <filename>unpack</filename>, + <filename>patch</filename>, <filename>configure</filename>, + <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>, + <filename>package_write</filename>, and <filename>build</filename>. + The default task is <filename>build</filename> and any tasks on which it depends + build first. + Some tasks exist, such as <filename>devshell</filename>, that 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 as follows: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c devshell + </literallayout> + </para> + + <para> + If you wish to rerun a task, use the <filename>-f</filename> force option. + For example, the following sequence forces recompilation after changing files in the + working directory. + <literallayout class='monospaced'> + $ bitbake matchbox-desktop + . + . + [make some changes to the source code in the working directory] + . + . + $ bitbake matchbox-desktop -c compile -f + $ bitbake matchbox-desktop + </literallayout> + </para> + + <para> + This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it. + The last command reruns all tasks (basically the packaging tasks) after the compile. + BitBake recognizes that the <filename>compile</filename> task was rerun and therefore + understands that the other tasks also need to be run again. + </para> + + <para> + You can view a list of tasks in a given package by running the + <filename>listtasks</filename> task as follows: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c listtasks + </literallayout> + The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>. + </para> + </section> + + <section id='usingpoky-debugging-dependencies'> + <title>Dependency Graphs</title> + + <para> + Sometimes it can be hard to see why BitBake wants to build some other packages before a given + package you have specified. + The <filename>bitbake -g targetname</filename> command creates the + <filename>depends.dot</filename>, <filename>package-depends.dot</filename>, + and <filename>task-depends.dot</filename> files in the current directory. + These files show the package and task dependencies and are useful for debugging problems. + You can use the <filename>bitbake -g -u depexp targetname</filename> command to + display the results in a more human-readable form. + </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 targetname</filename> 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='usingpoky-debugging-buildfile'> + <title>Building with No Dependencies</title> + <para> + If you really want to build a specific <filename>.bb</filename> file, you can use + the command form <filename>bitbake -b <somepath/somefile.bb></filename>. + This command form does not check for dependencies so you should use it + only when you know its dependencies already exist. + You can also specify fragments of the filename. + In this case, BitBake checks for a unique match. + </para> + </section> + + <section id='usingpoky-debugging-variables'> + <title>Variables</title> + <para> + The <filename>-e</filename> option dumps the resulting environment for + either the configuration (no package specified) or for a + specific package when specified; or <filename>-b recipename</filename> + to show the environment from parsing a single recipe file only. + </para> + </section> + + <section id='recipe-logging-mechanisms'> + <title>Recipe Logging Mechanisms</title> + <para> + Best practices exist while writing recipes that both log build progress and + act on build conditions such as warnings and errors. + Both Python and Bash language bindings exist for the logging mechanism: + <itemizedlist> + <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake + supports several loglevels: <filename>bb.fatal</filename>, + <filename>bb.error</filename>, <filename>bb.warn</filename>, + <filename>bb.note</filename>, <filename>bb.plain</filename>, + and <filename>bb.debug</filename>.</para></listitem> + <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set + of loglevels exist and are accessed with a similar syntax: + <filename>bbfatal</filename>, <filename>bberror</filename>, + <filename>bbwarn</filename>, <filename>bbnote</filename>, + <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> + </itemizedlist> + </para> + + <para> + For guidance on how logging is handled in both Python and Bash recipes, see the + <filename>logging.bbclass</filename> file in the + <filename>meta/classes</filename> folder of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </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: + <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 psplash boot splashscreen, + add <filename>psplash=false</filename> to the kernel command line. + Doing so prevents psplash 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> + </itemizedlist> + </para> + </section> +</section> + +<section id='maintaining-build-output-quality'> + <title>Maintaining Build Output Quality</title> + + <para> + A build's quality can be influenced by many things. + 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, + then 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 <filename>buildhistory</filename> 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 statements to the end of your + <filename>conf/local.conf</filename> file found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: + <literallayout class='monospaced'> + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "1" + </literallayout> + Enabling build history as previously described + causes the build process to collect build + output information and commit it to a local + <ulink url='&YOCTO_DOCS_DEV_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. + However, you should realize that enabling and disabling + build history in this manner can change the + <filename>do_package</filename> task checksums, which if you + are using the OEBasicHash signature generator (the default + for many current distro configurations including + <filename>DISTRO = "poky"</filename> and + <filename>DISTRO = ""</filename>) will result in the packaging + tasks being re-run during the subsequent build. + </para> + + <para> + To disable the build history functionality without causing the + packaging tasks to be re-run, add just this statement to your + <filename>conf/local.conf</filename> file: + <literallayout class='monospaced'> + BUILDHISTORY_FEATURES = "" + </literallayout> + </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 + <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename> + in the Build Directory. + The following is an example abbreviated listing: + <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" /> + </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/core2-poky-linux/busybox/busybox/latest</filename> + contains the following: + <literallayout class='monospaced'> + PV = 1.19.3 + PR = r3 + RDEPENDS = update-rc.d eglibc (>= 2.13) + RRECOMMENDS = busybox-syslog busybox-udhcpc + PKGSIZE = 564701 + FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ + /etc /com /var /bin/* /sbin/* /lib/*.so.* /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 = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh + </literallayout> + Most of these name-value pairs corresponds 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/core2-poky-linux/busybox/latest</filename>): + <literallayout class='monospaced'> + PV = 1.19.3 + PR = r3 + DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ + virtual/libc update-rc.d-native + PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ + busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ + busybox-staticdev busybox-locale + </literallayout> + </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><emphasis>build-id:</emphasis> + Human-readable information about the build configuration + and metadata source revisions.</para></listitem> + <listitem><para><emphasis>*.dot:</emphasis> + Dependency graphs for the image that are + compatible with <filename>graphviz</filename>. + </para></listitem> + <listitem><para><emphasis>files-in-image.txt:</emphasis> + A list of files in the image with permissions, + owner, group, size, and symlink information. + </para></listitem> + <listitem><para><emphasis>image-info.txt:</emphasis> + A text file containing name-value pairs with information + about the image. + See the following listing example for more information. + </para></listitem> + <listitem><para><emphasis>installed-package-names.txt:</emphasis> + A list of installed packages by name only.</para></listitem> + <listitem><para><emphasis>installed-package-sizes.txt:</emphasis> + A list of installed packages ordered by size. + </para></listitem> + <listitem><para><emphasis>installed-packages.txt:</emphasis> + A list of installed packages with fuill 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.1+snapshot-20120207 + USER_CLASSES = image-mklibs image-prelink + IMAGE_CLASSES = image_types + IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ + package-management ssh-server-dropbear package-management + IMAGE_LINGUAS = en-us en-gb + IMAGE_INSTALL = task-core-boot task-base-extended + BAD_RECOMMENDATIONS = + ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + IMAGESIZE = 171816 + </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 history or any package 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_DEV_URL;#build-directory'>Build Directory</ulink>: + <literallayout class='monospaced'> + INHERIT += "buildhistory" + BUILDHISTORY_COMMIT = "0" + BUILDHISTORY_FEATURES = "image" + </literallayout> + </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 + <filename>BUILDHISTORY_COMMIT = "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/eglibc/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/eglibc/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> + </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> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
